RESTful interface. It is a real-time interface but at the moment in a read-only, uni-directional mode.
We send data by HTTPS POST requests to a target HTTPS URL. There needs a properly configured HTTPS server on the customer side. Using plain HTTP is not usually supported so as to secure the privacy and authenticity of your data.
This method has larger overhead compared to WebSocket or TLS socket.
Getting Your Device Data
- Run a web server that accepts POST requests on the URL you provide to KotahiNet.
- Your server needs to present a valid, not self-signed, certificate.
- Currently, we don’t attempt re-deliveries of transmitted data JSON objects (frames). Any frame not handled by your HTTP server will be lost. You can however query our data cache and retrieve the missed messages at a later point.
Sending Data/Commands To Your Device
Since the POST only works one way, you will need to generate separate POST requests to our server to send data/commands to your device (“downlink” messages).
The URL is https://au1.loriot.io/1/rest.
The authentication token needs to be provided in the Authorization header as ‘Bearer YOUR_TOKEN’, so for example ‘Authorization: Bearer YOUR_TOKEN’. The value of YOUR_TOKEN will be provided to you by KotahiNet as will be the “appid” below to be included.
The JSON object you need to send needs to have the structure below, depending on whether you are sending plaintext (we encrypt the data in the server) or ciphertext (you encrypt the data). The acknowledgement and confirmation JSON messages you will receive are the same as the general send case.
Sending plaintext
{
cmd : 'tx'; // must always have the value 'tx'
appid : string; // application ID provided by KotahiNet, 8 hex digits
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",
"appid" : "BE7A00AA"
"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'
appid : string; // application ID provided by KotahiNet, 8 hex digits
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",
"appid" : "BE7A00AA"
"EUI" : "0102030405060708",
"port" : 1,
"confirmed" : true,
"encdata" : "0102AABB"
"seqno" : 1,
}