3.1 Cloud Notifications - About Cloud Notifications

In this chapter we will see how Cloud Notifications make it easy to send messages to the device's user from within firmware.

How Cloud Notifications Work

The Canopy Cloud Service has a fully-featured account and permission system that associates one or more user accounts with each device. Most devices have a primary user, called the "device owner". The device owner may provide an email address, phone number, and other contact information to the Canopy Cloud Service, using our Device Manager or via your application.

Using the libcanopy firmware library, your embedded software can send messages to the registered device owner and/or other users. These messages are first sent to the Canopy Cloud Service, which then uses services such as SendGrid and Twilio to deliver the notification.

Setup

Before using Canopy's Cloud Notification feature, you must have the Embedded Developer Kit (EDK) installed on your device. See Getting Started: Embedded Installation for instructions.

Sending Notifications from C/C++

Initializing libcanopy

The first step is to include and initialize libcanopy.

#include <canopy.h>

int main(void) {
    CanopyContext ctx;
    CanopyResultEnum result;

    ctx = canopy_init_context();
    if (!ctx) {
        canopy_write_error(NULL, stderr, "Failed to create context.");
        return -1;
    }

    result = canopy_set_opt(ctx,
        CANOPY_DEVICE_UUID, "",
        CANOPY_DEVICE_SECRET_KEY, ""
    );
    if (result != CANOPY_SUCCESS) {
        canopy_write_error(ctx, stderr, "Failed to configure context");
        return -1;
    }

This process is discussed in more detail in Cloud Variables - Cloud Variables with libcanopy.

Sending Text Messages

To send a text message to the device owner, use:

    result = canopy_notify_sms(ctx, "Your laundry is done");
    if (result != CANOPY_SUCCESS) {
        canopy_write_error(ctx, stderr, "Failed to queue text message");
        return -1;
    }

The above code simply queues the notification locally. It does not actually send the text message, or interact with the cloud. For that, you need to sync:

    // Synchronize with the cloud (10-second timeout)
    result = canopy_sync_blocking(ctx, 10*CANOPY_SECONDS);
    if (result == CANOPY_ERROR_TIMED_OUT) {
        // Operation timed out
    } else if (result != CANOPY_SUCCESS) {
        // Other error occurred
    }

The synchronization process is discussed in more detail in Cloud Variables - Cloud Variables with libcanopy.

Sending Email

To send an email, use:

    result = canopy_notify_email(ctx, 
        CANOPY_EMAIL_SUBJECT, "Your laundry is finished",
        CANOPY_EMAIL_BODY, "Come and get it!"
    );
    if (result != CANOPY_SUCCESS) {
        canopy_write_error(ctx, stderr, "Failed to queue email message");
        return -1;
    }

Again, be sure to sync:

    result = canopy_sync_blocking(ctx, 10*CANOPY_SECONDS);

Sending a Canopy Message

A Canopy Message is a message that gets stored in the cloud database by the Canopy Cloud Service. Applications can write custom code to deliver these notifications in-app.

To send an Canopy Message, use:

    result = canopy_notify_message(ctx, 
        CANOPY_MESSAGE_SUBJECT, "Your laundry is finished",
        CANOPY_MESSAGE_BODY, "Come and get it!"
    );
    if (result != CANOPY_SUCCESS) {
        canopy_write_error(ctx, stderr, "Failed to queue Canopy message");
        return -1;
    }

Again, be sure to sync:

    result = canopy_sync_blocking(ctx, 10*CANOPY_SECONDS);