Messages
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:
| Name | Type | Description |
|---|---|---|
| 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. |
Types
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 params structure.
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:
uplink,downlink_request,downlink_response,downlink,join_request,join_response,status_request,status_response,downlink_claim. - Thse are service messages that have types:
error,warningandinfo. 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:
| Name | Description | Direction |
|---|---|---|
| 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 downlink_request message |
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 downlink_request / downlink_response sequence instead. |
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 |
Metadata
Each message contains the following metadata structure (this structure is common for all message types):
| Name | Type | Description |
|---|---|---|
| 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 |
Bidirectionals messages
The Data API supports bidirectional messaging using the request-response model.
For example messages like downlink_request, 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
downlink_requestwithpacket_hash= 1 and wait for the response - The AS processes this message and sends a response with
packet_hash= 1 - The NS matches a
downlink_requestanddownlink_responseand sends a message to the end device
Params
The field params is specific for each type of message and described in corresponding section dedicated to the message type.