Uplink
Uplink - these are messages received from end devices.
The NS is capable of optionally adding the following additional parameters to the uplink messages:
radio - an object that contains information about RF properties like RSSI, SNR and so on...
You should useradio = 1
parameter during connection procedure in order to receive this data from the NS.For example:
wss://ns.eu.everynet.io/api/v1.0/data?access_token=9ec85978f3fa1ab6f953406269f69a95&radio=1
mac_commands - a list of MAC commands that was received in this uplink message.
Please use thelora = 1
parameter in a query string in order to receive this information from the NS.For example:
wss://ns.eu.everynet.io/api/v1.0/data?access_token=9ec85978f3fa1ab6f953406269f69a95&lora=1
Another functionality of the NS is the ability to receive or discard duplicate messages.
In order to receive all message duplicates, use duplicate=1
in query string.
For example:
wss://ns.eu.everynet.io/api/v1.0/data?access_token=9ec85978f3fa1ab6f953406269f69a95&duplicate=1
Review this diagram for a better understanding on how uplink messages work:
On this diagram, you can see how uplink messages are delivered to the AS:
- The Device sends a message to the Gateway.
- The Gateway processes the message and adds some additional information to it (for example RF parameters) and sends to the NS.
- The NS receives an uplink message from the gateway, processes it (decrypt, deserialize, ...) and sends it to the AS through the Data API.
- The AS receives a message with type=uplink
Params
Name | Description |
---|---|
rx_time | float, time in unixtime, when gateway received this packet, required |
counter_up | integer, uplink counter from LoraWAN packet, required |
port | integer, FPort from LoraWAN packet, required |
payload | string, optional |
encrypted_payload | string, required |
duplicate | boolean, if the message is duplicate then this flag is true, required |
radio | object, radio data, required |
radio.freq | float, central frequency in MHz (unsigned float, Hz precision), required |
radio.time | float, unixtime, time of receiving the message at the gateway, optional |
radio.modulation | object, information about modulation, required |
radio.modulation.type | string, enum: LORA, FSK, required |
radio.modulation.coderate | string, LoRa ECC coding rate identifier, required |
radio.modulation.spreading | integer, required |
radio.modulation.bandwidth | integer, required |
radio.hardware | object, information about hardware, required |
radio.hardware.tmst | integer, send packet on a certain timestamp value (will ignore time), required |
radio.hardware.channel | integer, concentrator IF channel used for RX (unsigned integer), required |
radio.hardware.chain | integer, concentrator 'RF chain', required |
radio.hardware.status | integer, CRC status: 1 = OK, -1 = fail, 0 = no CRC, required |
radio.hardware.rssi | float, RSSI in dBm (signed integer, 1 dB precision), required |
radio.hardware.snr | float, lora SNR ratio in dB (signed float, 0.1 dB precision), required |
radio.hardware.gps | Coordinates of gateway that was used to receive this particular message: string, enum: LORA, FSK, requiredobject, geodata, optional |
radio.hardware.gps.lat | float, latitude, optional |
radio.hardware.gps.lng | float, longitude, optional |
radio.hardware.gps.alt | float, altitude, optional |
Example
The first example shows how to receive an uplink message without radio information.
Let's use a WebSocket client called wscat
.
To connect to the server and start receiving messages, you should run this command (do not forget to use your own access_token):
wscat -c "wss://ns.eu.everynet.io/api/v1.0/data?types=uplink&access_token=89058167bcf482071da1a88036ca9aaf"
You should get something like this after your client is connected to the Data API:
{
"meta": {
"network": "75697b95",
"packet_hash": "889a72ab34a647f504ef37d598589431",
"application": "70b3d54b17db0106",
"device_addr": "36c365b4",
"time": 1504806725.252493,
"device": "faa73111a2aead2c",
"packet_id": "bfa4be139911fe8ff80bc0afbf110fa3",
"gateway": "7c95bd79864622a4"
},
"params": {
"rx_time": 1504806725.245682,
"port": 55,
"counter_up": 118,
"payload": "MjRjZjA4YWQyZGE5NGZlZDlkNmRiY2VkOTMwYWMzZjM=",
"encrypted_payload": "ehMceJ/3W3itJE8rwwvL3y0yu485QMHpLCa4km/TZYM="
},
"type": "uplink"
}
Second example shows how to receive uplink messages with RF details in each message.
Let's use wscat
again, but you should add radio=1
to the query string:
wscat -c "wss://ns.eu.everynet.io/api/v1.0/data?types=uplink&access_token=89058167bcf482071da1a88036ca9aaf&radio=1"
Just after Data API connection is established, you should start to receive messages like:
{
"meta": {
"network": "75697b95",
"packet_hash": "79f664df2c2073af798fa87497305d8d",
"application": "70b3d54b17db0106",
"device_addr": "36c365b4",
"time": 1504806731.256388,
"device": "faa73111a2aead2c",
"packet_id": "fdbb09021c4523d9f28bb815ca872c70",
"gateway": "7c95bd79864622a4"
},
"params": {
"rx_time": 1504806731.249041,
"port": 27,
"radio": {
"modulation": {
"bandwidth": 125000,
"type": 0,
"spreading": 12,
"coderate": "4/7"
},
"hardware": {
"status": 1,
"chain": 0,
"tmst": 514586002,
"snr": 5.0,
"rssi": -100.0,
"channel": 0,
"gps": {
"lat": 59.890445709228516,
"lng": 30.258167266845703
}
},
"freq": 868.1,
"datarate": 0,
"time": 1504806731.249041
},
"counter_up": 120,
"payload": "ZGEwOTg3MmI4NmU4NGI4MDg4YzZmMWU4ZjM5NmViODU=",
"encrypted_payload": "aiN3/x3Z7wz7NMPq+qoWf/17pq2J3Cx/p1kjvarfLEE="
},
"type": "uplink"
}