--- name: cumulocity-read-write-device-parameters description: "Read a device parameter from the device managed object, send a new value to the device with a c8y_ParameterUpdate operation, and check the value that the device reports back. Use when the user wants to read a device parameter or change its value on the device." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Read and write device parameters Source: https://cumulocity.com/docs/skills/device-management/read-write-device-parameters/ Sector: Skills, Device management & connectivity Release: Latest Description: Read a device parameter from the device managed object, send a new value to the device with a c8y_ParameterUpdate operation, and check the value that the device reports back. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) A device parameter is a fragment on the device managed object, for example `"reportingInterval": 60`. You read a parameter from the managed object. To change it, you create a `c8y_ParameterUpdate` operation: 1. The device picks up the operation and applies the new value. 2. The device reports the value with an event of the type `c8y_ParameterUpdate`, see [Device parameter](https://cumulocity.com/docs/device-integration/fragment-library/#parameter-status). 3. The device-parameter microservice copies the reported value to the device managed object. The device-parameter microservice only copies the value if the property definition of the parameter in the Digital Twin Manager allows the asset context, or if the parameter has no property definition. To check the definition, see [Inspect the definition of a device parameter](https://cumulocity.com/docs/skills/device-management/inspect-parameter-definitions/). > **Requirements:** > ROLES & PERMISSIONS: > > * To read the device: ROLE_INVENTORY_READ > * To create the operation: ROLE_DEVICE_CONTROL_ADMIN > * To read the operation: ROLE_DEVICE_CONTROL_READ > * To read the parameter update events: ROLE_EVENT_READ > > Your tenant is subscribed to the microservices `device-parameter` and `dtm`. The **Parameters** tab of the device needs both. The examples use `` for the ID of the device and `` for the ID of the operation. They set the parameter `reportingInterval` to 60. ### To read a parameter {#to-read-a-parameter} Send a [Retrieve a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectResource) request: ```http GET /inventory/managedObjects/ ``` The platform returns HTTP 200 and the device. Check the following properties in the response: * The fragment `reportingInterval` contains the current value of the parameter. If the fragment is missing, the device never reported this parameter. You can still set it. * The array `c8y_SupportedOperations` contains `"c8y_ParameterUpdate"`. If it is missing, do not create the operation. No agent picks it up. If the platform returns HTTP 404, the device does not exist. ### To send a new value to the device {#to-send-a-new-value-to-the-device} Send a [Create an operation](https://cumulocity.com/api/core/#operation/postOperationCollectionResource) request: ```http POST /devicecontrol/operations Content-Type: application/json Accept: application/json { "deviceId": "", "description": "Update parameter 'reportingInterval'", "c8y_ParameterUpdate": {}, "c8y_ParameterUpdate_reportingInterval": {}, "reportingInterval": 60 } ``` The operation has three fragments. In the list, `` stands for the fragment name of the parameter, here `reportingInterval`: * `c8y_ParameterUpdate`: An empty marker fragment for parameter updates. * `c8y_ParameterUpdate_`: An empty marker fragment for the parameter. * ``: The new value. Use any JSON value that the device accepts for this parameter, for example a number or an object. Do not send a `status`. The platform sets it. The platform returns HTTP 201 and the operation with its `id` and `"status": "PENDING"`. Note the `id` as ``. If the platform returns HTTP 422, the device is not an agent, and none of its parent devices is an agent. The platform cannot deliver operations to it. ### To follow the operation {#to-follow-the-operation} Send a [Retrieve a specific operation](https://cumulocity.com/api/core/#operation/getOperationResource) request: ```http GET /devicecontrol/operations/ ``` Repeat the request every 5 seconds until the `status` is SUCCESSFUL or FAILED, for at most 2 minutes: * **SUCCESSFUL**: The device applied the value. It reports the value with a `c8y_ParameterUpdate` event. * **FAILED**: The `failureReason` property describes why the device did not apply the value. * **Still PENDING after 2 minutes**: No agent picked up the operation. The device is offline, or it does not listen for parameter updates. Cancel the operation, see [To cancel a pending operation](https://cumulocity.com/docs/skills/device-management/send-operation/#to-cancel-a-pending-operation). For details on the statuses of an operation, see [Send an operation to a device](https://cumulocity.com/docs/skills/device-management/send-operation/#how-an-operation-moves-through-its-statuses). ### To check the reported value {#to-check-the-reported-value} The device-parameter microservice writes the reported value to the managed object asynchronously, after the device sends its event. Send the [Retrieve a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectResource) request again: ```http GET /inventory/managedObjects/ ``` Repeat the request every 10 seconds, for at most 2 minutes, until the fragment `reportingInterval` contains the new value. If the value does not change, check the property definition of the parameter, see [Inspect the definition of a device parameter](https://cumulocity.com/docs/skills/device-management/inspect-parameter-definitions/): * **The definition does not allow the asset context**: The device-parameter microservice does not write this parameter to the managed object. Read the value from the latest parameter update event instead, as described below. * **The definition allows the asset context, or no definition exists**: The device did not send a `c8y_ParameterUpdate` event, or its event is not the latest one for this parameter. To read the latest value that the device reported, send a [Retrieve all events](https://cumulocity.com/api/core/#operation/getEventCollectionResource) request: ```http GET /event/events?source=&type=c8y_ParameterUpdate&fragmentType=reportingInterval&pageSize=1 ``` The platform returns HTTP 200 and the newest matching event in the `events` array. The fragment `reportingInterval` of the event contains the reported value. ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [GET /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/getManagedObjectResource): Retrieve a specific managed object - [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 /event/events](https://cumulocity.com/api/core/#operation/getEventCollectionResource): Retrieve all events ## Linked from the documentation - [Fragment library > Device parameter](https://cumulocity.com/docs/device-integration/fragment-library/#device-parameter) - [Managing parameters](https://cumulocity.com/docs/device-management-application/managing-device-parameters/)