Subscribing to Resource changes from a web application

Device Management Connect provides connectivity to devices running Device Management Client. In addition to read and write operations towards devices, it offers a subscribe method to observe changes in device Resources.

To minimize the network traffic, the client does not start sending notifications of Resource changes automatically. Instead, the web application needs to subscribe to the device Resources.

You can also reduce the network traffic by using the Auto-observation feature.

Presubscriptions

A presubscription automatically subscribes to Resources based on given rules. Rather than constantly listening to registered device 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 with Resources match the set rules, the Device management Connect service sends a subscription (observe) request to the device on behalf of your application.

See also Notification rules for optimizing the data sent by the device.

The diagram below shows notifications for presubscribed Resources:

1. The web application sets a presubscription to receive notifications of all changes under Object 3303, 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 '[
            {
              "resource-path": ["/3303/*"]
            }     
         ]'
   

2. Device Management Connect responds with a success message.

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

4. Device Management Connect notifies the web application of the registered device.

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

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

7. Device Management Connect notifies the web application of the new value. The event format is defined in Connect API models NotificationMessage.

Note: Presubscription changes are not deployed to the device immediately. The presubscription rules for a device are checked and updated when the device updates its registration. If you need immediate notifications, you can use Resource-specific subscriptions.

Resource-specific subscriptions

To subscribe to individual Resources, you can use PUT /v2/subscriptions/{device-id}/{resourcePath}. If the device makes a full registration (and restarts), the Resource-specific subscription data is lost and the call is considered invalid.

When a value of an observed Resource changes, the device send event is delivered to your web-application through the event notification channel.

The diagram below illustrates the notification process of a Resource-specific subscription:

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 Connect responds with the async-id.

3. Device Management Connect sets the subscription on the device.

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

5. Device Management Connect notifies the web application of a successful subscription through the event notification channel.

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

7. Device Management Connect sends a notification to the web application's event notification channel with the new value. The event format is defined in Connect API models NotificationMessage

Subscribe only to what you need

You should avoid large wildcard subscriptions, as they will generate unwanted traffic. If you have, for example, an Object 1234 with 25 resources:

1234/0/1
       .
       .
       .
       25

If you are only interested in 1234/0/6 and 1234/0/21, then you should subscribe only to 1234/0/6 and 1234/0/21, instead of 1234/*.

If any of the 25 Resources of 1234 changes value, you will get the full Object 1234 in TLV format every time. This creates unnecessary load and traffic.

Notification rules

Device Management Client supports periodic and event-triggered reporting of Resource values. The web application can set a rule-based subscription to an Object, an Object Instance or a Resource, which then results in asynchronous notifications when an Object Instance changes. You can do this for each Resource that you have specified to be observable.

Device Management does not store or validate rules when delivering to Device Management Client. Whenever the device reregisters, the web 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 goes above the limit. 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 goes below the limit. 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 Resource level.

Read more about the write attributes in OMA LwM2M/Write-Attributes.

Examples

• The web application is interested in the temperature sensor, but does not want to cause traffic on every minor temperature change. One degree accuracy is enough. The application sets the alert Step to one degree for the client:

  PUT 	https://api.us-east-1.mbedcloud.com/v2/endpoints/<device-id>/3303/0/5700?st=1
  

  The client sends notifications of the temperature change when the temperature changes more than one degrees.

• The web application is interested in a temperature reading only if it is below 10 degrees or above 60 degrees. The application specifies the alert levels (min 10, max 60) and the alert interval (120 seconds) for the client:

  PUT 	https://api.us-east-1.mbedcloud.com/v2/endpoints/<device-id>/3303/0/5700?lt=10&gt=60&pmax=120
  

  The client sends notifications of the temperature every 120 seconds even if the temperature value does not change. If the temperature is below 10 or above 60 degrees, the notification is sent immediately.