Sending Alarms to Device Cloud in C

A client application can send alarms to indicate an occurrence on the device to Device Cloud using the alarm APIs.

You can publish the alarm state or the alarm state and a message.

Alarms appear on the thing definition page. Click the View icon of the alarm to view the alarm details and history in chart, graph, and table format. You can also overlay alarm data on the property data in the property graph view. For more information about viewing alarms, see the following:

  • Device Cloud Management Portal User's Guide: Viewing and Updating the Alarms of a Thing
  • Device Cloud Management Portal User's Guide: Viewing the Properties of a Thing

In the options parameter of the API, you can specify additional, optional information, including the following:

  • location (latitude and longitude) where the alarm occurred, specified as a location object

  • maximum time to wait for the publish operation to complete

  • timestamp of the alarm

  • whether to publish the alarm value even if the value has not changed since the alarm was published previously

The function parameter txn is for future use.

You must have initialized your application (see Initializing Your C Application).

The thing definition that corresponds to your application must have the alarm defined and you must know the numeric values of the alarm states defined. For more information about defining alarms, see Device Cloud Management Portal User's Guide: Defining Alarms.

To send alarms to Device Cloud, your application must be connected to Device Cloud.

  1. Register the alarm object with the agent.

    For the handle parameter, specify the value returned from the iot_initialize function, which you called when you registered your application.

    For the name parameter, specify the alarm key defined in the thing definition.

    iot_alarm_t* temp_too_high;
temp_too_high = iot_alarm_register(agentLib, "temp_too_high");
  2. Write the code to determine the alarm state.
  3. (Optional) Specify the alarm options.

    In the following example, the collection time is two minutes earlier than the current time.

    iot_options_t *alarm_options = iot_options_allocate( agentLib );
iot_timestamp_t tstamp;

tstamp = iot_timestamp_now() - 120000;
iot_options_set(alarm_options, "time_stamp", IOT_TYPE_UINT64, tstamp); 
iot_options_set(alarm_options, "republish", IOT_TYPE_BOOL, IOT_TRUE);
  4. Send the alarm to Device Cloud.

    For the alarm_state parameter, specify a state defined in the alarm definition.

    For the txn parameter, specify NULL

    If you do not want to publish any optional information, specify NULL for the options parameter.

    For the severity parameter, specify an alarm state defined for the alarm.

    OptionDescription

    Publish the alarm without a message

    		 
    result = iot_alarm_publish(temp_too_high, 
                           NULL, 
                           alarm_options, 
                           5);

    Publish the alarm with a message

    		 
    result = iot_alarm_publish_string(temp_too_high, 
                                  NULL, 
                                  alarm_options, 
                                  5, 
                                  "temperature is too high");

    When your application runs, the application transmits the alarm to Device Cloud, and it appears on the thing details page.

When you no longer need to send the alarm, call the iot_alarm_deregister function and if applicable, the iot_option_free function, to free the associated memory.