Skip to main content

JSON Schema

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

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

FieldTypeDescription
app_euiStringLoRaWAN 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_euiStringLoRaWAN 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
devaddrStringUpon 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
fcntNumberLoRaWAN FCnt for uplink packets; this increments with every uplink packet and can be useful for surmising whether an uplink was missed
hotspotsArray(hotspot)Array of hotspots which received the same packet (schema description in a following table)
idStringUUID 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
metadataObject("label": Array(label))A nested JSON object with a single field, "labels", which is an array of label Objects, described in the next table
nameStringName assigned to the device by Console user
payloadStringData 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_sizeNumberSize of the payload in bytes; you can use this to verify your libraries parsing output
portNumberLoRaWAN FPort on which the data was transmitted; this can be useful for routing data within the application
reported_atNumberTimestamp in milliseconds

Hotspot

FieldTypeDescription
frequencyNumberIn MHz, the frequency which the packet was received upon
idStringA base58 encoding of the hotspot's public key; this may serve as a concise unique identifier
nameStringA human-friendly three-word encoding of the hotspot's public key; link to JavaScript and Erlang implementations
reported_atNumberTimestamp in milliseconds
rssiNumberReceived 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
snrNumberIn 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
spreadingStringLoRa 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

FieldTypeDescription
labelsStringA list of Labels attached to the device

Here is an example of data received:

{
    "payload_raw": "SGVsbG8sIHdvcmxkIQ==",
    "port": 1,
    "confirmed": false
}
FieldDescription
payload_rawStringData transmitted to your device as a base64 encoded String. Most computer languages will have some built-in libraries for parsing this (e.g. base64.encode(payload))
portNumberLoRaWAN FPort on which the data was transmitted; this can be useful for routing data within the application
confirmedBoolWhether or not a device acknowledgement is required

Clearing a Device Queue

If the payload_raw field is the base64 encoded value '__clear_downlink_queue__' any downlinks queued for that device will be removed.