JSON Schema

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": 1586868546,
"rssi": -54,
"snr": 9.800000190734863,
"spreading": "SF9BW125",
"status": "success"
},
{
"frequency": 912.2999877929688,
"id": "11ni2CACdVUAshDvXif2pYUduAsvoawoxvVub6aqgHjSNsPEapZ",
"name": "cool-chiffon-hornet",
"reported_at": 1586868546,
"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": 1586868546
}

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, eg: "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 (eg: 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

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

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
}

Type

Description

‚Äč

payload_raw

String

Data transmitted to your device as a base64 encoded String. Most computer languages will have some built-in libraries for parsing this (eg: base64.encode(payload))

port

Number

LoRaWAN FPort on which the data was transmitted; this can be useful for routing data within the application

confirmed

Bool

Whether or not a device acknowledgement is required