Skip to content

Device messages

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, contact Nordic Semiconductor Sales.

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

Access

Device messages retrieved through the APIs are not filtered according to a user's group access or role. This means a user can view messages for devices they do not otherwise have access to.

If you want to keep device messages more secure within your teams, set up a new team for those devices and invite only those team members you want to give message access to.

This also applies to device alerts in the nRF Cloud portal and APIs.

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 the nRF Cloud portal, 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.

The benefit of setting a ts in your device messages is that the timestamp shows when the messages were recorded on the device, not when nRF Cloud received them. This can be beneficial 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.

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.

Single or bulk messages

Devices typically send messages one at a time. nRF Cloud also supports sending messages in bulk. This is particularly useful in low-power, low-connectivity or constrained device scenarios. For more information, see the /d2c/bulk topic in the MQTT API.

Note

Messages bundled under the bulk topic are still counted individually toward your service limits.

MQTT API

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

REST API

You or your devices can call the SendDeviceMessage endpoint to send a message on behalf of the IP device specified by the deviceId. Compare this with the specified device sending the message itself, directly over MQTT. This allows for one-way MQTT messaging through a REST proxy, which is useful for devices that are not running an MQTT client.

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 MQTT topic to which the message is published depends on the type of IP device specified by the deviceId:

  • Non-gateway: the user-specified topic value is appended to the main device message topic prefix (see the nRF Cloud MQTT API). For example, if you set topic to warehouse1/temperature, the message is published over {mqttTopicPrefix}/m/warehouse1/temperature. If you want to use the bulk messaging feature, set the topic to /d/{deviceId}/d2c/bulk.

  • Gateway: the topic parameter is disregarded because all gateway messages are sent over /gateways/{gatewayId}/g2c.

Retrieving device messages

You can retrieve your device messages using either the 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 the open-source mqtt-bridge-mosquitto project.

REST API

You can retrieve device messages through the ListMessages endpoint.

Note

If data messages are not shown in the ListMessages response, and you know they 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. For more information, see Message timestamps.