nRF Cloud application protocols for long-range devices

Contains the application protocol definitions for long-range devices connecting to nRF Cloud.

Devices that send messages to nRFCloud can optionally have data displayed on cards. Cards will be shown only if the device shadow includes valid service ui and messages transmitted from the device use the correct protocols described in this repo.

General Message Schema

{
   appId: AppId;
   messageType: MessageType;
   data?: any;
   time | ts ?: number;
}

appId: The application identifier associated with a running application on a IoT device. For example a device may be running an application sampling temperature and sending messages. Messages would include the appId TEMP.

messageType: Below is a table of valid message types depending on the asset tracker version:

Asset Tracker v2

MessageType	Description	deviceToCloud or cloudToDevice
DATA	Message contains sensor or other data	D2C

Asset Tracker v1 (legacy)

MessageType	Description	deviceToCloud or cloudToDevice
START	Tells application to start sending data to cloud	C2D
STOP	Tells device to stop sending data	C2D
INIT	Tells the application to initialize or reset	C2D
GET	Tell application to send a single data point	C2D
STATUS	Status message to device or cloud	Both
DATA	Message contains sensor or other data	D2C
OK	Confirmation message	Both
CFG_GET	Gets configuration	Both
CFG_SET	Sets configuration	C2D
CMD	Command and response	Both

data: Raw data from the application. See below under cloudToDevice and deviceToCloud for details.

time | ts: Timestamp parameter given by the device when the sample was taken (see caveats).

Message Topics

To learn more about the topics on which these messages are broadcast, check out our MQTT API Guide.

Supported Schemas

The schemas are divided into three folders:

• cloudToDevice - Supported messages sent from nRF Cloud to the device. These messages apply to IP devices only. On nRF Cloud these messages can be sent using the terminal card or using the REST API SendDeviceMessage

• deviceShadow - Supported device shadow that stores the current state of the device. A device has full privilege to write to the shadow. However conforming to the schema ensures that the UI on nRF Cloud will operate as expected.

  For example, an ip device reports a ServiceInfo field to the shadow. nRF Cloud uses the information (contained in ui field) to display the correct cards.

• deviceToCloud - Supports messages sent from the device to nRF Cloud. nRF Cloud supports message from both IP and BLE devices. The current schemas only apply to IP devices. BLE documentation will be released in the future.

Custom Schemas

Messages that do not conform to the schemas are still processed and stored. However, it is not guaranteed that nRF Cloud will display your data on a card. Instead you will have to view the data using the terminal card.

Caveats

• A successful AGPS response does not have an entry in the deviceToCloud directory because it returns a raw binary response (not JSON). In event of an error, AGPS will return JSON, which is documented.
• ts should be used instead of time. The time property is included to be backwards compatible with certain versions of asset tracker version 2 firmware. Future versions will use the ts property instead.
• The Location Service deviceToCloud endpoints (AGPS, PGPS, CELL_POS, SCELL, and WIFI) will return a standardized JSON response in event of an error, all include an err property with an error code, which are documented in the REST API error code docs.
• All GNSS deviceToCloud examples also work with the appId = GPS. Although the GPS appId is deprecated.