Helium & TTN (LoRaWAN) Gateway - projecthorus/sondehub-infra GitHub Wiki

As of October 2023, SondeHub runs an API suitable for handling traffic from Helium Network and TheThingsNetwork (TTN) trackers, using each networks HTTP integration functionality. Received ('uplinked') telemetry will be reformatted and passed onto the SondeHub-Amateur database for display on the SondeHub-Amateur Tracker.

Users with Helium/TTN trackers must ensure that they provide decoded payload data in a format suitable for us to parse, details on how to do this is provided further below.

Adding the SondeHub API

The following APIs are available:

In both cases, the API requires a POST request be sent.

Setting up a LoRaWAN Tracker

TODO

  • Ideally link out to other guides for this.
  • Known-working boards
  • Code that runs on them
  • How to set up payload decoding in Helium / TTN.

There is some very preliminary and unfinished information on setting up written by Steve Randall available here. Please contact Steve for more information...

Payload Decoder Requirements

SondeHub will extract payload telemetry and other metadata from the JSON structure provided via the Helium/TTN integrations. We use the name field (Helium), or application_id (TTN) as the payload callsign shown on the tracker, so ensure you set this appropriately, and try and not make it too long! We also use the reported or received_at time as the date/time for the uploaded packet.

Any binary payload in use must be decoded to individual fields and available in the following location within the structure:

  • Helium - decoded -> payload
  • TTN - uplink_message -> decoded_payload

Decoding of the binary telemetry can be accomplished by including a Decoder Function (Helium) or Payload Formatter (TTN) in the data processing chain.

The decoded payload telemetry fields must include:

  • latitude - as Decimal Degrees
  • longitude - as Decimal Degrees
  • altitude - in metres (usually above-sea-level)

We will also extract the following fields and convert them for use on SondeHub-Amateur:

Field Name SondeHub Field Name Description
sats sats Number of GNSS satellites used in the position fix. (If set to 0, the position will be hidden on the tracker map.)
battery batt Battery voltage (V)
speed speed Speed-over-ground (kph)
heading heading Heading-over-ground in degrees True
temperature temp Payload internal temperature (˚C)
ext_temperature ext_temperature Payload external temperature (˚C)
ext_pressure or pressure ext_pressure Atmospheric Pressure (hPa)
ext_humidity ext_humidity Relative Humidity (%)
accel_x accel_x Accelerometer X reading (G)
accel_y accel_y Accelerometer Y reading (G)
accel_z accel_z Accelerometer Z reading (G)
gyro_x gyro_x Gyroscope X reading (˚/s)
gyro_y gyro_y Gyroscope Y reading (˚/s)
gyro_z gyro_z Gyroscope Z reading (˚/s)
illuminance illuminance Illuminance (lux)

We also store the raw_payload (Helium), frm_payload (TTN) data as raw.

If you want more fields added, please email us at [email protected]!

From the per-hotspot data, we extract and use:

  • name - as the uploader callsign value.
  • reported at - as the per-receiver time received value.
  • latitude and longitude - as the uploader position.
  • Modulation metadata, including spreading factor, bandwidth, and code rate.
  • snr, rssi, frequency - For additional receiver metadata

All other data sent to the API is discarded (e.g. account balance information, downlink URL).