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 intouplink
anddownlink
messages. Default value is 0.radio=1
- force NS to include radio metadata into eachuplink
message. Default value is 0 (no radio metadata).duplicate=1
- force NS to stream alluplink
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 toN
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 onlyuplink
andjoin_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 hoursother 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