The data passed over APIs / transport layers are always JSON formatted objects. No delimiters are used between the objects.
The cmd field is present in all messages and indicates the message type.
JSON format for data sent from the device to the network (“uplink”)
Every uplink JSON message corresponds to one frame produced by your device. It contains not only the raw application payload, but also additional meta-data.
KotahiNet can provide either basic or extended verbosity messages.
Uplink Message- Basic Verbosity
{
cmd : 'rx'; // identifies type of message, rx = uplink message
EUI : string; // device EUI, 16 hex digits (without dashes)
ts : number; // server timestamp as number (milliseconds from Linux epoch)
ack : boolean; // acknowledgement flag as set by device
fcnt : number; // frame counter, a 32-bit number
port : number; // port as sent by the end device
data : string; // data payload (decrypted, plaintext hex string)
}
Uplink Message- Extended Verbosity
{
cmd : 'rx'; // identifies type of message, rx = uplink message
EUI : string; // device EUI, 16 hex digits (without dashes)
ts : number; // server timestamp as number (milliseconds from Linux epoch)
ack : boolean; // acknowledgement flag as set by device
fcnt : number; // frame counter, a 32-bit number
port : number; // port as sent by the end device
data : string; // data payload (decrypted, plaintext hex string)
// extended radio information
freq : number; // radio frequency at which the frame was received, in Hz
dr : string; // radio data rate - spreading factor, bandwidth and coding rate
rssi : number; // frame rssi, in dBm, as integer number
snr : number; // frame snr, in dB, one decimal place
}
JSON format for optional gateway information
KotahiNet can optionally deliver detailed radio information from all gateways that received a given frame. These messages have higher latency than the standard data ‘rx’ message as the network has to wait for all the gateways to report the status.
If gateway information is enabled, verbosity levels reported per gateway can be set as Radio Data, Gateway ID, or Location Data.
In all three options, the cmd value in the JSON object will be ‘gw’. They all follow the common structure below with “gws” being an array of gateway information objects based on the chosen verbosity level.
Gateway Message- Common Structure
{
cmd : 'gw'; // identifies type of message, gw = gateway information
EUI : string; // device EUI, 16 hex digits (without dashes)
ts : number; // server timestamp as number (milliseconds from Linux epoch)
ack : boolean; // acknowledgement flag as set by device
fcnt : number; // frame counter, a 32-bit number
port : number; // port as sent by the end device
data : string; // data payload (decrypted, plaintext hex string)
// extended radio information
freq : number; // radio frequency at which the frame was received, in Hz
dr : string; // radio data rate - spreading factor, bandwidth and coding rate
gws : array; // array of gateway information objects
}
gws Array for Radio Data
{
rssi : number; // radio rssi, in dBm
snr : number; // radio snr, in dB, single decimal digit precision
ts : number; // timestamp (gateway internal counter)
}
gws Array for Gateway ID
{
rssi : number; // radio rssi
snr : number; // radio snr
ts : number; // timestamp (gateway internal counter)
gweui : string; // gateway EUI as 16 hex digits
}
gws Array for Location Data
{
rssi : number; // radio rssi
snr : number; // radio snr
ts : number; // timestamp (gateway internal counter)
gweui : string; // gateway EUI as 16 hex digits
lat : number; // gateway latitude
lon : number; // gateway longitude
}
Examples
Data Uplink Message- Extended Verbosity
{
"cmd" : "rx",
"EUI" : "0102030405060708",
"ts" : 1470850675433,
"ack" : false,
"fcnt" : 1,
"port" : 1,
"data" : "0102AABB",
"freq" : 868500000,
"dr" : "SF12 BW125 4/5",
"rssi" : -130,
"snr" : 1.2
}
Gateway Uplink Message- Location ID
{
"cmd" : "gw",
"EUI" : "0102030405060708",
"ts" : 1470850675433,
"ack" : false,
"fcnt" : 1,
"port" : 1,
"data" : "0102AABB",
"freq" : 868500000,
"dr" : "SF12 BW125 4/5",
"gws" : [
{
"rssi" : -130,
"snr" : 1.2,
"ts" : 43424140,
"gweui" : "1122334455667788.0",
"lat" : -36.848448,
"lon" : 174.762191
}
]
}