The data passed over APIs / transport layers are always JSON formatted objects. No delimiters are used between the objects.
You can send messages to your device (“downlink”) using either plaintext (we encrypt the data in the server prior to wireless delivery) or ciphertext (you encrypt the data end-to-end).
Messages will be enqueued and delivered based on target device class- after the next transmission from the device (Class A) or immediately (Class C).
JSON format for downlink send request
If downlink data is being sent by https push, see the specific instructions for that API.
Sending plaintext
{
cmd : 'tx'; // must always have the value 'tx'
EUI : string; // device EUI, 16 hex digits (without dashes)
port : number; // port to be used (1..223)
confirmed? : boolean; // (optional) request confirmation (ACK) from end-device
data : string; // data payload (to be encrypted by our server)
}
Example
{
"cmd" : "tx",
"EUI" : "0102030405060708",
"port" : 1,
"confirmed" : true,
"data" : "0102AABB"
}
Sending ciphertext
The payload has to be encrypted using the latest downlink sequence number and the appropriate APPSKEY (Application Session Key).
The downlink sequence number (seqdn) must correspond to the latest downlink sequence number reported by the ‘txd’ message. If sequence number doesn’t match, an error will be returned with the current seqdn.
{
cmd : 'tx'; // must always have the value 'tx'
EUI : string; // device EUI, 16 hex digits (without dashes)
port : number; // port to be used (1..223)
confirmed? : boolean; // (optional) request confirmation (ACK) from end-device
encdata : string; // data payload (already APPSKEY encrypted)
seqno : number; // must correspond to the latest seqdn reported by the 'txd' message
}
Example
{
"cmd" : "tx",
"EUI" : "0102030405060708",
"port" : 1,
"confirmed" : true,
"encdata" : "0102AABB"
"seqno" : 1,
}
Acknowledgement of send request
Acknowledgement is returned immediately by our server after your issuing the ‘tx’ command.
{
cmd : 'tx'; // always has the value 'tx'
EUI : string; // device EUI, 16 hex digits (without dashes)
success? : string; // on success, will contain a confirmation message
// only present if the command succeeded
error? : string; // string describing the encountered error
// only present if the command failed
data? : string; // data that was enqueued (either plaintext or ciphertext)
// only present if the command succeeded
}
Example
{
"cmd" : "tx",
"EUI" : "0102030405060708",
"success" : "Downlink message enqueued.",
"data" : "0102AABB"
}
Delivery confirmation
Confirmation is sent by our server once the packet has been sent to a gateway for delivery.
{
cmd : 'txd'; // always has the value 'txd'
EUI : string; // device EUI, 16 hex digits (without dashes)
seqdn : number; // sequence number used for the downlink
ts : number; // unix timestamp, moment of the transfer to gateway
}
Example
{
"cmd" : "txd",
"EUI" : "0102030405060708",
"seqdn" : 1,
"ts" : 1470850675434
}