LoRaWAN Integration

One unified webhook endpoint

HydroNode exposes a single webhook URL that auto-detects whether the incoming uplink is from TTN (v3) or ChirpStack (v4/v3). There are no separate endpoints and no per-network configuration.

Before you start

1. 1
   A sensor exists in HydroNode

   Create the sensor via the dashboard or API first.
2. 2
   The sensor is saved as Outdoor

   Open General settings, select Outdoor, and save. A LoRaWAN binding creates a Station Interface automatically, and only outdoor sensors can be stations.
3. 3
   The physical DevEUI is at hand

   16 hex characters printed on the device, e.g. a840411b2182cd44.
4. 4
   You know your payload layout

   Which fPort carries which channels and at which byte offsets (configured in Step 4).

Register your device on the network server

This is the one step that differs between networks.

Bind the device to your sensor

Done entirely in the HydroNode web app. Open your sensor and go to its Settings page, then use the LoRaWAN Binding card.

1. 1
   Confirm the sensor is Outdoor

   If it is still Indoor, change it under General settings and save before continuing.
2. 2
   Enter the DevEUI

   The 16 lowercase hex characters from your device (and noted in Step 02).
3. 3
   Enter the LoRaWAN Application ID (optional)

   The Application ID from TTN or ChirpStack. Only needed if several applications share a DevEUI range; otherwise leave it blank.
4. 4
   Click Save LoRaWAN Binding

   HydroNode creates the Station Interface automatically, generates your personal Webhook URL, and shows it in the same connection card.
5. 5
   Reveal and copy the Webhook URL

   Click the eye icon to reveal it, then Copy. You paste this into the network server in Step 04.

Point the network server at your URL

Configure fPort decoding

Each fPort carries a fixed set of channels packed into the payload bytes. You tell HydroNode how to decode them in the web app: on the same sensor Settings page, scroll to fPort Configurations. See Sensor Types for the supported types and encodings.

1. 1
   Click Add fPort

   Set the fPort number (1–223) your firmware sends on, and an optional description.
2. 2
   Add one channel per value

   Pick a Sensor Type (presets fill in bytes, encoding, scale and unit), then adjust Bytes (1, 2, 3 or 4), Encoding (signed or unsigned), Byte Order, Scale Factor, Offset, Channel Name and Unit if needed. Choose Custom for a type not in the list.
3. 3
   Order the channels

   Channels decode top to bottom with no gaps. Use the up and down arrows so the order matches the byte layout your device transmits.
4. 4
   Click Create

   Repeat for every fPort your device uses. Existing configs can be edited or deleted from the same list.

How a channel is decoded

Every channel reads a fixed number of bytes and turns them into one physical value:

value = raw × scaleFactor + offset

Native payload formats (auto-detected)

No transformation needed. HydroNode reads each network's native JSON and picks the format from its shape: end_device_ids means The Things Stack v3, deviceInfo or a top level devEui means ChirpStack v4. Helium is not a third format; its console runs on ChirpStack and sends the ChirpStack event. Anything else is rejected with 400 rather than guessed at.

Repeat deliveries are recognised by deduplicationId when the network server sends one, and by the frame counter otherwise. If a payload carries neither, deduplication is skipped for that uplink: a duplicate reading can be removed later, a dropped one cannot be recovered.

{
  "end_device_ids": {
    "dev_eui": "a840411b2182cd44",
    "application_ids": {
      "application_id": "my-app"
    }
  },
  "uplink_message": {
    "f_port": 1,
    "f_cnt": 9846,
    "frm_payload": "AQH0AgBk",
    "rx_metadata": [
      { "rssi": -85, "snr": 7.2 }
    ],
    "received_at": "2026-07-21T11:24:34.027Z"
  },
  "received_at": "2026-07-21T11:24:39.500Z"
}

{
  "deduplicationId": "f2b0b8ec-1d5a-4c1f-9d0e-2f2f7d3a1b22",
  "time": "2026-07-21T11:24:34.027+00:00",
  "deviceInfo": {
    "devEui": "a840411b2182cd44",
    "applicationId": "abc123"
  },
  "fPort": 1,
  "fCnt": 9846,
  "data": "AQH0AgBk",
  "rxInfo": [
    { "rssi": -85, "snr": 7.2 }
  ]
}

Confirm it works

Trigger a test uplink (TTN's Simulate uplink or a real transmission). On success, the server logs LoRaWAN uplink processed: network=… devEui=… fPort=… and the value appears under the sensor.

A 202 means the values are stored, not merely received. HydroNode waits for its own storage to confirm them before answering, so a 202 is a real delivery receipt. If storage is unavailable you get 503 instead and your network server should redeliver. Repeated deliveries of the same frame are recognised and stored once, so retrying is always safe.