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
,warning
andinfo
. 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 |
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_request
withpacket_hash
= 1 and wait for the response - AS process this message and send a response with
packet_hash
= 1 - NS match
downlink_request
anddownlink_response
and 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.