Connection

Connection to Data API is performed through WebSocket.

Please note that Websocket protocol implements so called PING/PONG messages to keep Websockets alive (https://tools.ietf.org/html/rfc6455#section-5.5.2\), even behind proxies, firewalls and load-balancers. Network server sends a PONG message to client every 25 seconds. This message does not require a response. Receiving of this message indicates that connection is active. To check connection client can send PING message, in response NS send a PONG message.

It is possible to specify the following parameters in query string of request:

• access_token - this is a mandatory field that is used to authenticate connection request. This token could be generated using Management API or network server GUI in a tab Keys. This is the only mandatory field you need to specify to establish a connection.

• lora=1 - enables connection to receive not only application data, but also all MAC command generated by network server. MAC commands will be included into uplink and downlink messages. Default value is 0.

• radio=1 - force NS to include radio metadata into each uplink message. Default value is 0 (no radio metadata).

• duplicate=1 - force NS to stream all uplink message duplicates from all gateways that was capable to receive a message. Default value is 0: no duplicates will be delivered to AS.

• last_messages= - retrieve up to N last historical messages. Maximum value is 1000.

• from_unixtime - retrieve historical messages from a specific moment of time. Unix timestamp format.

• types - tells NS to filter messages according to provide list of message types. Accepts a comma separated list of message types. For example if it is necessary to receive only uplink and join_request messages you should use: types=uplink,join_request. Default value is:types=uplink, downlink, downlink_request, join_request, status_response.

  Read more about message types here.

• gateways - tells NS that you want to receive messages if they receive only by closed list of gateways. Accepts a comma separated list of gateway identifiers. By default this option is disabled (accepts data from any gateway).

• applications - tells NS that you want to receive messages if they receive only by closed list of applications (APP_EUI_). _Accepts a comma separated list of APP_EUI identifiers. By default this option is disabled (accepts data from any application).

• devices - tells NS that you want to receive messages if they receive only by closed list of devices (dev_eui). Accepts a comma separated list of device identifiers. By default this option is disabled (accepts data from any device).

• tags - tells NS that you want to receive messages if they receive only by closed list of tags. Accepts a comma separated list of dtags. By default this option is disabled (accepts data from device with any tag).

• filter - tells NS that you want to receive message that was passed through a specific filter. Accepts a filter ID as a value. You can read more about filters here. You should create filter prior using this field. It is possible to do that through GUI or Management API.

All described parameters are passed through connection query string.
Parameter filter and parameters types, gateways, applications, tags and devices are mutually exclusive. It means that you should specify or filter or any of the other parameters, but not together.

All filtering performed on NS side.

History retrieval

For your convenience we store data for some amount of time.

• uplink, downlink - 48 hours
• other messages - 1 hour

Upon connection you can retrieve the old messages, that you may miss.
To do that you have to specify from_unixtime and/or last_messages parameters.

All the retrieved messages will come with flag meta.history = true.

We don't want to disturb your current realtime traffic and communication, so all the historical messages will come in asynchronous manner.

You may receive current stream messages between the historical ones. It helps to keep latency-sensitive traffic up to date.

Example of reconnection with history retrieval

The best way to use the history feature is to store meta.time of the last received message and later use that unixtime on the reconnect in the from_unixtime parameter.

But you have to keep in mind, that it may request quite a lot messages. To limit amount of them, use last_messages parameter.

Examples

Connect to Data API without any filtering:

wss://ns.us.everynet.io/api/v1.0/data?access_token=89058167bcf482071da1a88036ca9aaf

Connect to Data API and getting message only from device with dev_eui=ef7bc2134bfa6ab0

wss://ns.us.everynet.io/api/v1.0/data?access_token=89058167bcf482071da1a88036ca9aaf&devices=ef7bc2134bfa6ab0