Messages
Once you are connected to Data API you have a capability to receive and send different messages: uplink messages from the device, debug messages, and so on...
All messages that are received or transmitted through Data API interface are JSON objects with the following format:
| Name | Type | Description |
|---|---|---|
| type | string | Message type is used to divide messages by it's functionality: information messages, uplink messages, error messages and so on. |
| meta | object | Metadata is a common structure for all message types and contain such kind of information like: device identifier, message identifier and so on... |
| params | object | Contains specific parameters for the particular type of a message. For example, uplink messages cointain "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 better understanding you could divide messages into two groups:
LoRaWAN - messages that are generated because of device actions or to perform any actions on the devices.
These messages have the following types:uplink,downlink_request,downlink_response,downlink,join_request,join_response,status_request,status_response,downlink_claim.Service messages that have types:
error,warningandinfo. These messages are generated by NS in 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 NS in case it has an opportunity to send downlink message to a device. In case of AS has any downlinks it will send it to the NS. More information could be found here. | From NS to AS |
| downlink_response | Response message generated by AS as a response to downlink_request message |
from AS to NS |
| downlink | Message generated by 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 downlink to a device. Please use downlink_request / downlink_response sequence instead. |
from NS to AS |
| join_request | Join request message is generated in case of device is using OTAA on the application side. | from NS to AS |
| join_response | Join accept message should be emitted by AS after a succesfull join procedure | from AS to NS |
| status_request | This message is generated by 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 NS to inform AS about critical errors thathappened during LoRaWAN message processing and NS to AS interactions. For example: MIC is incorrect. | from NS to AS |
| warning | Message of these type are generated in case of error occurred during message processing, but NS was able to finish processing. For example: 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: message was successfully delivered to 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 sets 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 messages hashes for bidirectional interaction. More information is available here. |
| packet_id | string | Message identifier. Each message has unique identifier. It is possible to use it to identify duplicates. |
| version | integer | Current version of everynet network server protocol, default: 1 |
| outdated | bool | Optional field, can only be in uplink messages, this flag sets for uplinks that were received too late, for which it is impossible to initiate a downlink sending |
Bidirectionals messages
Data API supports bidirectional messaging using request-response model.
For example messages downlink_request, downlink_response are used to get a downlink data from AS and send it to the device.
Here is a diagram that describes a message flow between NS and AS to send a downlink message to a device:
In other words the sequence is the following:
- NS sends AS
downlink_requestwithpacket_hash= 1 and wait for the response - AS process this message and send a response with
packet_hash= 1 - NS match
downlink_requestanddownlink_responseand send message to the end device
Params
Field params is specific for each type of message and described in corresponding section dedicated to the message type.