--- name: cumulocity-lwm2m-shell-observe description: "Set notification attributes, start and stop observations of LWM2M resources on a device with shell commands, and check that measurements arrive. Use when the user wants to observe the resources of an LWM2M device or set its notification attributes." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Observe LWM2M resources with shell commands Source: https://cumulocity.com/docs/skills/device-management/lwm2m-shell-observe/ Sector: Skills, Device management & connectivity Release: Latest Description: Set notification attributes, start and stop observations of LWM2M resources on a device with shell commands, and check that measurements arrive. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) When the LWM2M agent observes a resource, the device sends a notification with the value of the resource instead of waiting for a read request. Notification attributes control how often the device sends notifications. From the values, the agent creates measurements, events, or alarms as the object mapping of the resource defines, see [LWM2M device protocols](https://cumulocity.com/docs/device-integration/lwm2m/#device-protocols). You start and stop observations with shell commands. A shell command is the text of a `c8y_Command` operation, see [Read and write LWM2M resources with shell commands](https://cumulocity.com/docs/skills/device-management/lwm2m-shell-resources/). Before you send a command, follow these steps of that skill: * [To check that the device accepts shell commands](https://cumulocity.com/docs/skills/device-management/lwm2m-shell-resources/#to-check-that-the-device-accepts-shell-commands) * [To find the LWM2M version of the device](https://cumulocity.com/docs/skills/device-management/lwm2m-shell-resources/#to-find-the-lwm2m-version-of-the-device) Write the command text as described in [Rules for the command text](https://cumulocity.com/docs/skills/device-management/lwm2m-shell-resources/#rules-for-the-command-text). Use the commands in the following order: 1. Set the notification attributes with `writeattr`. Attributes that you set on an active observation only take effect when the observation is renewed. 2. Start the observation with `observe` or `cobserve`. 3. Check that measurements arrive. 4. Stop the observation with `cancelobservation`, `cancelobserve`, or `cancelCompositeObserve`. > **Requirements:** > ROLES & PERMISSIONS: > > * To send shell commands: ROLE_DEVICE_CONTROL_ADMIN > * To read the results: ROLE_DEVICE_CONTROL_READ > * To read measurements: ROLE_MEASUREMENT_READ The examples use `` for the ID of the LWM2M device, `` for the ID of an operation, and `` for an LWM2M path, for example `/3/0/13`. ### Observation commands {#observation-commands} | Command | Task | LWM2M version | Result on success | |---|---|---|---| | `writeattr ` | Set the notification attributes of a path | 1.0, 1.1 | `CHANGED(204)` | | `observe ` | Observe one path | 1.0, 1.1 | A JSON map with the first value | | `cobserve ` | Observe several paths in one request | 1.1 | A JSON map with the first values | | `cancelobservation ` | Cancel a single or a composite observation with a reset message | 1.0, 1.1 | `OBSERVATION CANCELLED` | | `cancelobserve ` | Cancel the observation of one path with a request to the device | 1.1 | `Observation was successfully cancelled` | | `cancelCompositeObserve ` | Cancel a composite observation with a request to the device | 1.1 | `Observation was successfully cancelled` | On an LWM2M 1.0 device, the agent or the device rejects the commands that need 1.1. Do not send them. ### To set the notification attributes {#to-set-the-notification-attributes} Write the attributes as one argument: `key=value` pairs, joined with `&`, without spaces. A space splits the argument, and the agent rejects the command. The agent uses the following attributes: * `pmin`: The minimum time in seconds between two notifications. * `pmax`: The maximum time in seconds between two notifications. * `gt` and `lt`: Thresholds for the value: greater than and less than. * `st`: The minimum change of the value, the step. Send a [Create an operation](https://cumulocity.com/api/core/#operation/postOperationCollectionResource) request with the `writeattr` command. The example sets a minimum of 5 seconds and a maximum of 30 seconds between notifications: ```http POST /devicecontrol/operations Content-Type: application/json Accept: application/json { "deviceId": "", "description": "writeattr /3/0/13 pmin=5&pmax=30", "c8y_Command": { "text": "writeattr /3/0/13 pmin=5&pmax=30" } } ``` The platform returns HTTP 201 and the operation with its `id` and `"status": "PENDING"`. Note the `id` as `` and read the result, see [To read the result of a command](https://cumulocity.com/docs/skills/device-management/lwm2m-shell-observe/#to-read-the-result-of-a-command). ### To start an observation {#to-start-an-observation} Send a [Create an operation](https://cumulocity.com/api/core/#operation/postOperationCollectionResource) request with the `observe` command: ```http POST /devicecontrol/operations Content-Type: application/json Accept: application/json { "deviceId": "", "description": "observe /3/0/13", "c8y_Command": { "text": "observe /3/0/13" } } ``` To observe several paths in one request on an LWM2M 1.1 device, use `cobserve` with the paths separated by single spaces, for example `cobserve /3/0/13 /3/0/9`. The platform returns HTTP 201 and the operation with its `id`. Note the `id` as `` and the `creationTime` as ``, and read the result. ### To read the result of a command {#to-read-the-result-of-a-command} Send a [Retrieve a specific operation](https://cumulocity.com/api/core/#operation/getOperationResource) request: ```http GET /devicecontrol/operations/ ``` Repeat the request until the status is SUCCESSFUL or FAILED, as described in [Send an operation to a device](https://cumulocity.com/docs/skills/device-management/send-operation/#to-follow-the-status-of-the-operation). If the status is SUCCESSFUL, `c8y_Command.result` contains the result that the table in [Observation commands](https://cumulocity.com/docs/skills/device-management/lwm2m-shell-observe/#observation-commands) shows. If the status is FAILED, the `failureReason` property describes the cause. In addition to the reasons in [To read the result](https://cumulocity.com/docs/skills/device-management/lwm2m-shell-resources/#to-read-the-result), the following reasons apply to observations: * **Contains `Missing attribute(s)`**: The `writeattr` command has no attributes. * **Contains `Invalid write attributes:`**: The agent does not accept a key or a value in the attributes. Check the attributes, and do not use spaces. * **Contains `This device doesn't support composite command operations`**: The device uses LWM2M 1.0. Send `observe` for each path instead of `cobserve`. If the status changes from EXECUTING back to PENDING, the device is not connected. The agent sends the command again when the device registers again. Do not create the command again. ### To check that measurements arrive {#to-check-that-measurements-arrive} After an `observe` or `cobserve` command is SUCCESSFUL, send a [Retrieve all measurements](https://cumulocity.com/api/core/#operation/getMeasurementCollectionResource) request for the measurements since ``: ```http GET /measurement/measurements?source=&dateFrom=&revert=true&pageSize=1 ``` With `dateFrom` and `revert=true`, the platform returns the newest measurement first. If the `measurements` array contains a measurement, the observation works. New measurements arrive at least every `pmax` seconds. If the array is empty, the value has not changed yet, or the object mapping of the resource does not create measurements, see [Send measurement](https://cumulocity.com/docs/device-integration/lwm2m/#send-measurement) and [Manage LWM2M object mappings](https://cumulocity.com/docs/skills/device-management/manage-object-mappings/). Wait `pmax` seconds and send the request again. If measurements stop arriving, the device dropped the observation, often after it registered again. Start the observation again. ### To stop an observation {#to-stop-an-observation} Select the cancel command: * `cancelobservation`: Cancels a single or a composite observation with a reset message. It works with LWM2M 1.0 and 1.1, and you can use it when the device is not reachable. To cancel a composite observation, list the same paths as in the `cobserve` command, in any order. * `cancelobserve` and `cancelCompositeObserve`: Cancel the observation with a request to the device, a GET request with the observe option. They need LWM2M 1.1 on the device. Send a [Create an operation](https://cumulocity.com/api/core/#operation/postOperationCollectionResource) request with the cancel command: ```http POST /devicecontrol/operations Content-Type: application/json Accept: application/json { "deviceId": "", "description": "cancelobservation /3/0/13", "c8y_Command": { "text": "cancelobservation /3/0/13" } } ``` The platform returns HTTP 201. Read the result of the command. After the command is SUCCESSFUL with its fixed result text, no further measurements arrive for the path. ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [POST /devicecontrol/operations](https://cumulocity.com/api/core/#operation/postOperationCollectionResource): Create an operation - [GET /devicecontrol/operations/{id}](https://cumulocity.com/api/core/#operation/getOperationResource): Retrieve a specific operation - [GET /measurement/measurements](https://cumulocity.com/api/core/#operation/getMeasurementCollectionResource): Retrieve all measurements ## Linked from the documentation - [LWM2M > Handling LWM2M shell commands](https://cumulocity.com/docs/device-integration/lwm2m/#handling-shell-commands)