Skip to main content

Device Messages

Overview#

Device messages are stored on nRF Cloud for 30 days if they are sent over supported message topics or through the SendDeviceMessage endpoint.

If you need longer term storage, you can create your own storage mechanism. See the message bridge guide for details. Otherwise, please contact Nordic Sales.

Messages sent using MQTT over unsupported message topics are not stored.

Message schemas#

You can send device messages using any schema. However, if you want full support of nRF Cloud for parsing and viewing messages on nRFCloud.com, your device messages should conform to nRF Cloud's published schemas. See the nRF Cloud application-protocols project for more information.

Message timestamps#

nRF Cloud stores device messages with some metadata, including a ReceivedAt timestamp. This is the timestamp used by the data range that you must set when calling the ListMessages endpoint.

ReceivedAt is a Unix timestamp in milliseconds according to the Unix epoch. You can use the EpochConverter if you need to verify some timestamps in a human readable format.

The value of ReceivedAt is set in one of two ways:

  • To the same value as the device message's ts field, if present. Values set in the ts field undergo basic validation. If the value is not a Unix timestamp, or if the value is older than 90 days, nRF Cloud does not use it.
  • Otherwise, it is set to the current timestamp, the Unix time in milliseconds when the message was received by nRF Cloud.

When storing device messages, nRF Cloud does not alter the message payload. For example, if you send ts: 0 in your device message, it is stored with that value, but ReceivedAt shows the current timestamp because nRF Cloud does not consider it valid.

info

The benefit of setting a ts in your device messages is that for certain real-world scenarios, such as an ultra-low power scenario where devices stay offline for extended periods then send a batch of messages, the timestamp shows when the messages were recorded on the device, not when nRF Cloud received them.

Sending device messages#

You can send device messages using either the nRF Cloud MQTT or REST APIs.

caution

Data loss can occur under two conditions:

  • If you send more than 3000 messages in one second from an account, such as sending messages across all your devices. If this limit is an issue for you, set up an MQTT bridge to send messages directly to your own storage mechanism.

  • If you send a message larger than 390 KB.

MQTT API#

For storage in nRF Cloud, devices should send messages over the MQTT messaging topics.

REST API#

You can use the SendDeviceMessage endpoint to send a message on behalf of a device as if it sent the message itself.

Additionally, if the message is sent to a topic to which another device is subscribed, you can send a message to a device, as long as both devices are currently connected to the nRF Cloud platform.

The message is published on a user-specified MQTT topic under the {mqttTopicPrefix}/m topic (see The nRF Cloud MQTT API). If you set the topic to warehouse1/temperature, for example, the message is published over {mqttTopicPrefix}/m/warehouse1/temperature.

Retrieving device messages#

You can retrieve your device messages using either our MQTT or REST APIs.

MQTT API#

Using an account device, meaning a device running a special device certificate that grants MQTT permissions for all devices in your account, you can subscribe to your device's message topics and send or store the messages wherever you want.

For an example of this, see our open-source mqtt-bridge-mosquitto project.

REST API#

You can retrieve device messages through the ListMessages endpoint.

info

If you are not seeing data messages in the ListMessages response that you know were sent by your device(s), make sure you are sending a proper Unix timestamp in your device message's ts field, or do not use that field at all. See "Message Timestamps", above.