nRF Cloud Alert

This library is an enhancement to the nRF Cloud library. It enables applications to generate and transmit messages that comply with the Alerts feature of nRF Cloud. Alert messages are compact JSON documents that indicate a critical event, such as low battery or unexpected reset.

Overview

This library provides an API for MQTT-, REST-, or CoAP-based applications to send alerts to nRF Cloud. For MQTT-based applications, you can enable or disable alerts remotely using the nRF Cloud portal or nRF Cloud REST API.

Each alert contains the following elements, as defined in the nrf_cloud_alert_info structure :

  • type - A value of the nrf_cloud_alert_type enum.

  • value - Use 0 if not otherwise needed.

  • description - Use NULL to suppress transmission of this field.

  • sequence - Sequence number used when no timestamp is available.

  • ts_ms - Timestamp if accurate time is known.

The range of the alert type enumeration is split into two parts:

  • Values less than ALERT_TYPE_CUSTOM are predefined.

  • Values greater or equal to that are for application-specific use.

Use the alert value to indicate more information about an alert. For example, for ALERT_TYPE_TEMPERATURE, the alert value could be the temperature in degrees Celsius.

Use the description string to give more detail about a specific alert, if required.

The library sets the sequence number and timestamp automatically. The nRF Cloud Alert service uses these values to present the alerts in the actual sequence they were generated on the device.

Supported features

If the Date-Time library is enabled, and the current date and time are known, the timestamp field of the alert will be automatically set accordingly. Otherwise, the sequence number will be set to a monotonically-increasing value.

Requirements

The device must be connected to nRF Cloud before calling the nrf_cloud_alert_send() function. The nrf_cloud_rest_alert_send() function initiates the connection as needed.

Configuration

Configure the following Kconfig options to enable or disable the library and to select the data transport method:

See Configuring and building for information on how to change configuration options.

Usage

To use this library, complete the following steps:

  1. Include the nrf_cloud_alert.h file.

  2. Define a local variable of type nrf_cloud_alert_info.

  3. Initialize the structure members:

    • type - A value of the nrf_cloud_alert_type enum.

    • value - Use 0 if not otherwise needed.

    • description - Use NULL to suppress transmission of this field.

  4. Call the nrf_cloud_alert_send() function when connected to nRF Cloud using MQTT or CoAP.

  5. Call the nrf_cloud_rest_alert_send() when using REST.

Samples using the library

The following nRF Connect SDK samples use this library:

Limitations

For REST-based applications, you can enable or disable alerts only at compile time.

Dependencies

This library uses the following nRF Connect SDK libraries:

API documentation

Header file: include/net/nrf_cloud_alert.h
Source files: subsys/net/lib/nrf_cloud/src/nrf_cloud_alert.c
nRF Cloud Alert