Subscribing to resource change notifications

In addition to sending commands to device resources, you can:

• Subscribe to specific resources to receive notification of resource value changes based on events or thresholds.

• Set presubscription rules to create automatic subscriptions whenever devices register, based on device name, device type or resource path, thus avoiding the need for manual subscription.

Note: You must set up an event notification channel to receive the results of your command executions.

Subscribing to a resource

Use the /v2/subscriptions/{device-id}/{resourcePath} PUT API to subscribe to specific resources.

Note: If the device makes a full registration (and restarts), the resource-specific subscription data is lost and the call is considered invalid.

This diagram illustrates the resource subscription and notification flow:

1. The web application subscribes to a resource using an HTTPS request with the device ID and resource path:

   PUT /v2/subscriptions/{device-id}/{resourcePath}.

2. Device Management responds with the async-id.

3. Device Management sets the subscription on the device.

4. The device notifies Device Management of a successful subscription.

5. Device Management notifies your application that the subscription was created successfully through the event notification channel.

6. When the value of the subscribed resource changes, the device notifies Device Management of the new value.

7. Device Management sends a notification to your application's event notification channel with the new value. You define the event format in the Notifications API NotificationMessage model.

Note: Avoid large wildcard subscriptions because they generate unwanted traffic. For example, if object 1234 has 25 resources and you subscribe to 1234/*, when any of the 25 resources changes value, you get the full 1234 object in type-length-value (TLV) format, (chapter 6.4.3) every time. This creates unnecessary load and traffic. If you are only interested in 1234/0/6 and 1234/0/21, subscribe only to 1234/0/6 and 1234/0/21, rather than 1234/*. Also, use the endpoint-type field to restrict the subscription to a specific set of devices.

Presubscribing to resources based on rules

A presubscription automatically subscribes to resources based on given rules. Rather than constantly listening to device registration events and subscribing, your application sends a single presubscription request, detailing the resources it's interested in (by device name, device type or resource path). When a device and its resources match the set rules, Device Management sends a subscription (observe) request to the device on behalf of your application.

This diagram below illustrates the presubscription and notification flow for presubscribed resources:

1. Your application sets a presubscription to receive notifications from devices of type sensor, for all changes under object 3303, which is an ID reserved for temperature sensors (using /3303/ with the wildcard *: /3303/*):

   PUT  https://api.us-east-1.mbedcloud.com/v2/subscriptions \
     -H 'authorization: Bearer {api-key}' \
     -H 'content-type: application/json' \
     -d '[
            {
              "endpoint-type": "sensor",
              "resource-path": ["/3303/*"]
            }     
         ]'
   

2. Device Management responds with a success message.

3. A device containing resources /3303/0/5602 and /3303/0/5700 registers to Device Management.

4. Device Management notifies your application of the newly registered device.

5. (steps 5-8) Device Management sets subscriptions for both resources.

6. The device notifies Device Management of a new value in resource /3303/0/5700.

7. Device Management sends a notification to your application's event notification channel with the new value. You define the event format in the Notifications API NotificationMessage model.

Note: Device Management does not deploy presubscription changes to the device immediately. When the device updates its registration, Device Management checks the presubscription rules and updates the device, if necessary. For immediate notifications, you can use resource-specific subscriptions.

Configuring notifications

Device Management Client, which runs on the device, supports periodic and event-triggered reporting of resource values. Your application can set a rule-based subscription to an object, an object instance or a resource. When an object instance change meets the rules you define, the device sends notifications to Device Management. You can do this for each resource you define as observable.

Device Management does not store or validate rules it delivers to Device Management Client. Whenever the device re-registers, your application must set the rules again.

You can fine-tune your subscription by using the write attributes. The supported attributes are:

• Minimum period (pmin) specifies the minimum notification interval in seconds. This is the minimum quiet period the client waits between two notifications. The client delays any new notifications that happen before the minimum period is up, even when triggered by other attributes.
• Maximum period (pmax) specifies the maximum time in seconds the client waits between two notifications. When the maximum period expires after the last notification, Device Management Client sends a new notification.
• Step (st) controls how much the value needs to change from the previous notification before a new notification is triggered. Valid only for numeric (integer or float) resource types.
• Greater Than (gt) specifies threshold high value. Device Management Client notifies the server if the value crosses the limit in either direction. Valid only for numeric (integer or float) resource types.
• Less Than (lt) specifies threshold low value. The Device Management Client notifies the server if the value crosses the limit in either direction. Valid only for numeric (integer or float) resource types.

Note: You can use pmin and pmax on object, object instance and resource level, whereas st, gt and lt only on the resource level.

Note: End-to-end accuracy of the time periods pmin and pmax depends highly on your device and connectivity technology. There can be ±5 second variation in event receiving intervals.

For more information about Write attributes, please see OMA LwM2M/Write-Attributes.

Examples

• Your application is interested in the temperature sensor resource (/3303/0/5700), but does not want to cause unnecessary traffic for every minor temperature change. One degree accuracy is sufficient. The application sets the alert step (st) attribute to one degree for this resource:

  POST 	https://api.us-east-1.mbedcloud.com/v2/endpoints//device-requests/{device_id}?async-id={async-response-id}
  -H 'Authorization: Bearer {access_key}' \
  -H 'content-type: application/json' \
  -d '{"method": "PUT", "uri": "/3303/0/5700?st=1"}'
  

  The device sends notifications of the temperature change when the temperature changes by more than one degree.

• Your application is interested in a temperature reading only when the temperature is below 10 degrees or above 60 degrees. The application specifies the alert levels (lt=10, gt=60) and the alert interval (pmax=3600) for this resource:

  POST https://api.us-east-1.mbedcloud.com/v2/endpoints//device-requests/{device_id}?async-id={async-response-id}
  -H 'Authorization: Bearer {access_key}' \
  -H 'content-type: application/json' \
  -d '{"method": "PUT", "uri": "/3303/0/5700?lt=10&gt=60&pmax=3600"}'
  

  The device sends temperature notifications every 3600 seconds even if the temperature value does not change. When the temperature crosses the 10 or 60 degree thresholds, the device sends notification immediately.