JSON Schema

This page has not been fully updated to represent the latest state of the Helium Network following the migration to Solana on April 18, 2023.

When receiving or transmitting data with an integration, there is a consistent JSON Schema for the data.

Uplink: Receiving Data from a Device

Here is an example of data received:

{
    "app_eui": "6948A4B59F4666AD",
    "dev_eui": "1C29FBD1D2084E21",
    "devaddr": "B5A44869",
    "fcnt": 19,
    "hotspots": [
        {
            "frequency": 912.2999877929688,
            "id": "11KHJW1ePkfhLYptMwKyDzn4opLc62daahbi35uxhH3wwi7p6xr",
            "name": "icy-fiery-hippo",
            "reported_at": 15868685461234,
            "rssi": -54,
            "snr": 9.800000190734863,
            "spreading": "SF9BW125",
            "status": "success"
        },
        {
            "frequency": 912.2999877929688,
            "id": "11ni2CACdVUAshDvXif2pYUduAsvoawoxvVub6aqgHjSNsPEapZ",
            "name": "cool-chiffon-hornet",
            "reported_at": 15868685461235,
            "rssi": -51,
            "snr": 9,
            "spreading": "SF9BW125",
            "status": "success"
        }
    ],
    "id": "7c523974-4ce7-4a92-948b-55171a6e4d77",
    "metadata": {
        "labels": [
            {
                "id": "7d11aef4-4daf-4caf-b72a-f789b191ebe4",
                "name": "DontLabelMe",
                "organization_id": "d724b93a-895a-4175-9852-8738ae31050b"
            }
        ]
    },
    "name": "Test Me",
    "payload": "SGVsbG8sIHdvcmxkIQ==",
    "port": 1,
    "reported_at": 15868685461234
}

Root

Field	Type	Description
app_eui	String	LoRaWAN 64-bit Application Identifier (AppEUI) in MSB hex; conventionally this is used to identify a type of sensor or actuator, e.g. "temperature sensor" or "valve controller"
dev_eui	String	LoRaWAN 64-bit Device Identifier (DevEUI) in MSB hex; conventionally this is used to identify a unique device within a specific application (AppEUI) or even within an entire organization
devaddr	String	Upon a successful Join, the device is allocated a LoRaWAN 64-bit DevAddr which is unique across the entire Helium Network as long the session is active; the data is represented here in MSB hex
fcnt	Number	LoRaWAN FCnt for uplink packets; this increments with every uplink packet and can be useful for surmising whether an uplink was missed
hotspots	Array(hotspot)	Array of hotspots which received the same packet (schema description in a following table)
id	String	UUID used to identify the device within Helium Console; this is assigned during device creation and maps to a unique set of AppEui, DevEui, and AppKey
metadata	Object("label": Array(label))	A nested JSON object with a single field, "labels", which is an array of label Objects, described in the next table
name	String	Name assigned to the device by Console user
payload	String	Data transmitted by your device as a base64 encoded String. Most computer languages will have some built-in libraries for parsing this (e.g. base64.decode(payload))
payload_size	Number	Size of the payload in bytes; you can use this to verify your libraries parsing output
port	Number	LoRaWAN FPort on which the data was transmitted; this can be useful for routing data within the application
reported_at	Number	Timestamp in milliseconds

Hotspot

Field	Type	Description
frequency	Number	In MHz, the frequency which the packet was received upon
id	String	A base58 encoding of the hotspot's public key; this may serve as a concise unique identifier
name	String	A human-friendly three-word encoding of the hotspot's public key; link to JavaScript and Erlang implementations
reported_at	Number	Timestamp in milliseconds
rssi	Number	Received Signal Strength Indicator is reported by the hotspot and indicates how strong the signal device's radio signal was; the larger the number (closer to 0), the better the signal
snr	Number	In dB, Signal to Noise Ratio is reported by the hotspot to indicate how clear the signal was relative to environmental noise; this generally ranges between -20 and +10 and the larger the number (closer to 10 dB) the better
spreading	String	LoRa Spreading Factor and Bandwidth used for the radio transmission. In the US, spreading factor ranges from 7 to 10 and bandwidth is always 125 kHz. For example, "SF7BW125" means a Spreading Factor of 7 was used and a channel width of 125 kHz.

Metadata

Field	Type	Description
labels	String	A list of Labels attached to the device

Downlink: Transmitting Data to a Device

Here is an example of data received:

{
    "payload_raw": "SGVsbG8sIHdvcmxkIQ==",
    "port": 1,
    "confirmed": false
}

Field	Description
payload_raw	String	Data transmitted to your device as a base64 encoded String. Most programming languages will have some built-in libraries for parsing/encoding this (e.g., Python's payload = base64.b64encode(payload_str.encode('utf-8')).decode('ascii'))
port	Number	LoRaWAN FPort on which the data is to be transmitted; this can be useful for routing data within the application
confirmed	Bool	Whether a device acknowledgement (ACK) is required

Note that many devices will show the downlinked payload (submitted as base64 in the JSON schema) as hex (base-16).

Clearing a Device Queue

If the payload_raw field is set to the base64 encoded value '__clear_downlink_queue__', all downlinks queued for that device will be removed.