Device Communication API
These calls relate to the communication with devices, the manipulation of device states, and the signaling of downlink messages.
The most important API calls, /uplink/send
and /device/send
, take uplinks received by devices, update the internal devices states and return device information and any completed files, streaming records or resolved positions. /uplink/send
accepts multiple device uplinks in a single request, /device/send
accepts a single uplink.
Deliver Uplink Messages
- POST /api/v1/uplink/send
The uplink/send API is the entry point for all uplink messages originating from devices to drive the Modem Service protocols. Messages must be submitted in the order in which they were transmitted by the devices. uplink/send allows to specify messages from multiple devices at once whereas device/send accepts a single uplink message (device/send). Each uplink message may encapsulate a LoRa Cloud Protocol message of a certain type (Format specification). A LoRaWAN transport message for instance is signaled by a field msgtype with value updf and carries LoRaWAN destination port and payload. Each incoming message is validated and the associated protocol performed leading to state transitions of the internal device representation. The responses contains new device state, as well as the following:
The file data, if the uplink message led to the completion of a “file upload” session.
Data stream records, if the uplink message led to the re-assembly of stream records.
The next downlink message required to be transmitted to the device
All pending requests which have been completed with the uplink
Any new log messages issued by actions that occurred during the handling of the uplink
Position solutions resulting from the message payload
The “operation” field which signals whether the message was handled by the Modem Service or not
By default, the application should also submit all other uplinks, irrespective of the port. The advantage of this strategy is twofold:
It informs the Modem Service about application-level downlink opportunities, which the Modem Service can use to schedule modem specific downlinks. This helps to drive the Modem Service protocol with lower latency, resulting in faster response times and higher performance over all.
The metadata supplied to the Modem Service with such an uplink will be updated in the device state and will be made available to the application for further analysis. The payload of messages that do not use relevant ports for the Modem Service may be omitted if the application is intended to preserve data privacy. Additionally, the application does not rely on the most recent payload to be accessible in the device state object.
- Request Headers
Authorization – Required. Access token
Request Body:
The request body contains a mapping from device EUI to UplinkMsg objects.
{ DEVEUI: UPLINK_MSG, .. }
DEVEUI: Required. Valid device EUI.
Response:
- Status Codes
200 OK – OK
401 Unauthorized – Authentication failed
- Response Headers
Content-Type – ‘application/json’
Response JSON:
The invocation returns a mapping of EUIs to response objects.
If successful, each EUI response returns an UplinkResponse object in the result field. If errors were encountered, they are signaled in the error field of the response object.
{ DEVEUI: { "result": UPLINK_RESPONSE, // Uplink response object for this EUI "error": STRING // Error message in case of error }
DEVEUI: Required. A valid device EUI.
result: UplinkResponse instance which details the current device state, and which may also include information such as completed requests, files, stream records, and pending downlink messages.
error: The error message to be displayed if an error is encountered.
Deliver Uplink Message
- POST /api/v1/device/send
Similar to the uplink/send API endpoint, but accepting a single uplink message of a device. The source device is denoted by the deveui field, the message by the uplink field.
- Request Headers
Authorization – Required. Access token
Request Body:
The request body must contain the deveui and uplink fields.
{ "deveui": DEVEUI, // Required. Source device EUI. "uplink": UPLINK_MSG // Required. .. }
deveui: Required, a valid device EUI.
uplink: Required, UplinkMsg object.
Response:
- Status Codes
200 OK – OK
401 Unauthorized – Authentication failed
- Response Headers
Content-Type – ‘application/json’
Response JSON:
The response adheres to the Base Response Format. If successful, the result field keeps an UplinkResponse object. If errors were encountered, they are signaled in the errors field.
{ "result": UPLINK_RESPONSE, // Uplink response object for this EUI "errors": [ STRING, .. ] // Error messages in case of error }
result: UplinkResponse instance detailing device state including information such as completed requests, files, stream records, and pending downlink messages.
errors: If set and non-empty, error message in case the operation did not succeed.
Full Almanac Image
- GET /api/v1/almanac/full
LoRa Edge™ devices require a list of coarse orbital parameters for GNSS constellations: the Almanac. The quality of the orbital parameters degrades over time. Therefore, updates of the Almanac image inside the device are necessary. The update period depends on the application’s requirements with respect to downlink capacity and energy efficiency.
This API serves full Almanac images on a bi-weekly basis.
- Query Parameters
toa (integer) – Optional. TOA (time of almanac) in GPST. If present, returns the almanac that was served at the specified time. Warning: The use of old almanacs is not recommended except for testing purposes. The TOA parameter is an experimental feature without any guarantees. When in doubt, don’t use it.
- Request Headers
Accept – application/json
Authorization – Required. Access token
Response:
- Status Codes
200 OK – OK
401 Unauthorized – Authentication failed :statuscode 429: Rate limit exceeded
- Response Headers
Content-Type – ‘application/json’
Response JSON:
{ "almanac_image": STRING, // Required. Base64-encoded string containing current Almanac image "this_gpst": INT, // Required. Time at which the Almanac parameters are valid in GPST "backoff": INT, // Required. Backoff in seconds until the next update of the Almanac image can be expected }
almanac_image: Required. Base64-encoded string containing current Almanac image. The device-level SPI API expects this binary image in the Almanac load command payload.
this_gpst: Required. Time at which the Almanac parameters are valid in GPST
backoff: Required. Backoff, in seconds, until the next update of the Almanac image can be expected.