Skip to content

Latest commit

 

History

History
73 lines (50 loc) · 5 KB

README.md

File metadata and controls

73 lines (50 loc) · 5 KB
Raw

nRF Cloud application protocols for long-range devices Version 1.1.0

Build Status Commitizen friendly

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.