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 either REST-based or MQTT-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 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 options to enable or disable the library and to select the data transport method:

See Configuring your application 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 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
group nrf_cloud_alert

Enums

enum nrf_cloud_alert_type

Alert type.

Values:

enumerator ALERT_TYPE_NONE

Placeholder; not meant to be sent.

enumerator ALERT_TYPE_DEVICE_NOW_ONLINE

Device finished booting.

enumerator ALERT_TYPE_DEVICE_NOW_ONLINE_WDT

Device finished rebooting from a watchdog timeout.

enumerator ALERT_TYPE_DEVICE_GOING_OFFLINE

Device is shutting down.

enumerator ALERT_TYPE_MSG

Generic message (see description field).

enumerator ALERT_TYPE_TEMPERATURE

Operating temperature outside of limits. Value is in degrees Celsius.

enumerator ALERT_TYPE_HUMIDITY

Operating humidity outside of limits. Value is in percent relative humidity.

enumerator ALERT_TYPE_BATTERY

Battery level too low. Value is in volts.

enumerator ALERT_TYPE_SHOCK

Shock and vibration limits exceeded. Value is in m/s^2.

enumerator ALERT_TYPE_CUSTOM

User-specific alerts start here.

Functions

int nrf_cloud_alert_send(enum nrf_cloud_alert_type type, float value, const char *description)

Transmit the specified alert to nRF Cloud using MQTT.

Parameters:

  • type – [in] The type of alert.

  • value – [in] Optional numeric value associated with the alert. If set to NRF_CLOUD_ALERT_UNUSED_VALUE, the library will not send this field to nRF Cloud.

  • description – [in] Optional text describing the alert.

Returns:

0 if alert is successfully sent, otherwise, a negative error number.

int nrf_cloud_rest_alert_send(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, enum nrf_cloud_alert_type type, float value, const char *description)

Transmit the specified alert to nRF Cloud using REST.

Parameters:

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • type – [in] The type of alert.

  • value – [in] Optional numeric value associated with the alert. If set to NRF_CLOUD_ALERT_UNUSED_VALUE, the library will not send this field to nRF Cloud.

  • description – [in] Optional text describing the alert.

Returns:

0 if alert is successfully sent, otherwise, a negative error number.

void nrf_cloud_alert_control_set(bool alerts_enable)

Enable or disable use of alerts.

Parameters:

  • alerts_enable – [in] Value for alerts enabled.

bool nrf_cloud_alert_control_get(void)

Find out if alerts are enabled.

Returns:

current alert enablement status.

struct nrf_cloud_alert_info
#include <nrf_cloud_alert.h>

Alert data.

Public Members

enum nrf_cloud_alert_type type

The type of alert this represents.

float value

A value associated with this alert.

const char *description

An optional human-readable description.

unsigned int sequence

A monotonically increasing alert counter used when current time not available.

int64_t ts_ms

UNIX epoch timestamp (in milliseconds) of the data. If a value <= NRF_CLOUD_NO_TIMESTAMP (0) is provided, the timestamp will be ignored.