Once you are connected to the Data API, you have the ability to receive and send different messages: uplink messages from the device, debug messages, and so on...
All messages that are received or transmitted through the Data API interface are JSON objects with the following format:
|type||string||This message type is used to divide messages by its functionality: information messages, uplink messages, error messages and so on.|
|meta||object||Metadata is a common structure for all message types and contains such information as: device identifier, message identifier and so on...|
|params||object||Contains specific parameters for the particular type of message. For example, uplink messages contain the "payload" field, but it is missed in join requests.|
Each message contains a
type field that is included to divide messages by it's functionality: uplinks, downlinks, join, errors.
Each message type has a corresponding
For a better understanding, you could divide messages into two groups:
- LoRaWAN - These messages are generated because of device actions or to perform any actions on the device side. These messages have the following types:
- Thse are service messages that have types:
info. These messages are generated by the NS in the process of LoRaWAN message processing. This group has more informational/debug purpose that the first one.
Here is a list of message types:
|uplink||Uplink messages from devices. Contains payload, radio information, mac commands and so on...||from NS to AS|
|downlink_request||Request message generated by the NS in case it has an opportunity to send downlink message to a device. In case the AS has any downlinks, it will send it to the NS. More information can be found here.||From NS to AS|
|downlink_response||Response message generated by the AS as a response to
||from AS to NS|
|downlink||Message generated by the NS just after a downlink message was actually sent to a device. Note that it is not possible to use this type of message to actually send a downlink to a device. Please use the
||from NS to AS|
|join_request||Join request message generated in case the device is using OTAA on the application side.||from NS to AS|
|join_response||Join accept message should be emitted by the AS after a successful join procedure||from AS to NS|
|status_request||This message is generated by the AS to request device status according to LoRaWAN specification. See DevStatusReq MAC command for details.||from AS to NS|
|status_response||Message with device status according to LoRaWAN specification.||fron NS to AS|
|downlink_claim||This type is used for Class C devices only and notifies the Network Server about a new, available uplink packet.||from AS to NS|
|error||These messages are generated by the NS to inform the AS about critical errors that happened during LoRaWAN message processing and NS to AS interactions. For example: MIC is incorrect.||from NS to AS|
|warning||Messages of this type are generated in case of errors encountered during message processing, but the NS was able to finish processing. For example: the AS is not available.||from NS to AS|
|info||This is an auxiliary message type that could be used to understand all processing steps in details. For example: the message was successfully delivered to the AS.||from NS to AS|
Each message contains the following metadata structure (this structure is common for all message types):
|application||string||The application identifier (app_eui by LoraWAN specification)|
|device||string||The device identifier (dev_eui by LoraWAN specification)|
|device_addr||string||The device address (dev_addr by LoraWAN specification)|
|gateway||string||The gateway mac address|
|history||bool||This flag is set for saving the messages in Everynet Network Server History|
|network||string||The network of gateways identifier|
|packet_hash||string||Message hash. It is very important to understand message hashes for bidirectional interaction. More information is available here.|
|packet_id||string||Message identifier. Each message has a unique identifier. It is possible to use it to identify duplicates.|
|version||integer||Current version of the Everynet network server protocol, default: 1|
|outdated||bool||Optional field, can only be in uplink messages, this flag is set for uplinks that were received too late, for which it is impossible to initiate downlink sending|
The Data API supports bidirectional messaging using the request-response model.
For example messages like
downlink_response are used to get downlink data from the AS and send it to the device.
Here is a diagram that describes a message flow between the NS and the AS to send a downlink message to a device:
In other words the sequence is the following:
- The NS sends the AS a
packet_hash= 1 and wait for the response
- The AS processes this message and sends a response with
- The NS matches a
downlink_responseand sends a message to the end device
params is specific for each type of message and described in corresponding section dedicated to the message type.