--- name: cumulocity-manage-lwm2m-configuration description: "Read and replace the LWM2M configuration of a device on the LWM2M agent, section by section, for the basic settings, the servers, the connectivity, the bootstrap, and the firmware update. Use when the user wants to read or replace the LWM2M configuration of a device, such as its servers, connectivity, bootstrap, or firmware update settings." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Manage the LWM2M configuration of a device Source: https://cumulocity.com/docs/skills/device-management/manage-lwm2m-configuration/ Sector: Skills, Device management & connectivity Release: Latest Description: Read and replace the LWM2M configuration of a device on the LWM2M agent, section by section, for the basic settings, the servers, the connectivity, the bootstrap, and the firmware update. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) The LWM2M agent keeps an LWM2M configuration for each registered device. It is the configuration that the **LWM2M configuration** tab in the device details shows, see [LWM2M configuration](https://cumulocity.com/docs/device-integration/lwm2m/#lwm2m-configuration). The configuration has the following sections: * `basic`: General device settings, for example the awake time, the serialization format, and the event log level. * `servers`: The servers that the bootstrap server writes to the device. * `connectivity`: The security settings of the bootstrap connection and of the server connection. * `bootstrap`: The bootstrap settings, for example the bootstrap server ID and the security instance offset. * `firmware`: The firmware update settings. All requests go to the LWM2M agent and start with `/service/lwm2m-agent/v1/device//configuration`, where `` is the managed object ID of the LWM2M device. To register a device, see [Register an LWM2M device](https://cumulocity.com/docs/skills/device-management/register-lwm2m-device/). > **Important:** > A PUT or POST request replaces the stored section with exactly the body that you send. There is no partial update. Always read the section first, change only the fields that you want to change, and send the complete section back. > **Requirements:** > ROLES & PERMISSIONS: > > * To read the configuration: ROLE_INVENTORY_READ or ROLE_LWM2M_READ > * To change the configuration: ROLE_INVENTORY_ADMIN, ROLE_INVENTORY_CREATE, or ROLE_LWM2M_ADMIN ### To read the basic settings {#to-read-the-basic-settings} Send a GET request for the `basic` section to the LWM2M agent: ```http GET /service/lwm2m-agent/v1/device//configuration/basic ``` The agent returns HTTP 200 and the section with the following properties: * `id`: The identity of the device, with `deviceId`, `endpointId`, and `tenantId`. * `endpointId`: The endpoint client ID of the device. * `awakeTime`: The time in milliseconds for which the device is awake after a registration or a registration update. `0` means that the device is always online. See [LWM2M client awake time](https://cumulocity.com/docs/device-integration/lwm2m/#lwm2m-client-awake-time). * `requestTimeout`: The timeout of requests to the device. * `serializationFormat`: TLV, CBOR, TEXT, OPAQUE, JSON, SENML_JSON, SENML_CBOR, or DEFAULT. * `binaryEncoding`: OPAQUE, TLV, JSON, or TEXT. * `logLevel`: NONE, LIFECYCLE, or VERBOSE. * `useTimestampResources`, `keepOldValuesOnOperationFail`, `disableObjectInstanceActions`, `autoManageAvailabilityRequiredInterval`, and `useLegacyEventDateFormat`: Boolean switches. The response leaves out fields without a value. For the meaning of the settings, see [Advanced settings](https://cumulocity.com/docs/device-integration/lwm2m/#advanced-settings). If the agent returns HTTP 404, no device with this ID exists, or the device is not an LWM2M device. If it returns HTTP 400, the ID is malformed. ### To change the basic settings {#to-change-the-basic-settings} Send a PUT request with the complete section that you read, with your changes. The example sets the awake time to 2 minutes and the event log level to VERBOSE: ```http PUT /service/lwm2m-agent/v1/device//configuration/basic Content-Type: application/json Accept: application/json { "endpointId": "", "awakeTime": 120000, "useTimestampResources": false, "keepOldValuesOnOperationFail": true, "serializationFormat": "DEFAULT", "binaryEncoding": "OPAQUE", "disableObjectInstanceActions": false, "autoManageAvailabilityRequiredInterval": true, "logLevel": "VERBOSE", "useLegacyEventDateFormat": false } ``` The agent ignores an `id` in the body and keeps the identity of the device. The agent returns HTTP 200 and the stored section with your values. To verify the change, read the section again. It contains exactly the values that you sent. If the agent returns HTTP 400, a value is invalid, for example a `logLevel` that is not NONE, LIFECYCLE, or VERBOSE. The error response names the field. ### To read the other sections {#to-read-the-other-sections} Send a GET request for the section, where `
` is `servers`, `connectivity`, `bootstrap`, or `firmware`: ```http GET /service/lwm2m-agent/v1/device//configuration/
``` The agent returns HTTP 200 and the section. As for the basic settings, the response leaves out fields without a value: * `servers`: An array of server entries. Each entry has an `id` (a UUID), `uri`, `bootstrap`, `shortServerId`, `security`, `registrationLifetime`, `defaultMinPeriod`, `defaultMaxPeriod`, `bindingMode` (U or UQ), `storeNotifications`, `disableTimeout`, and `acl`. The `security` object contains the security `mode` and, depending on the mode, the PSK or X.509 settings. * `connectivity`: An object with `bootstrapConnectivity` and `serverConnectivity`. Both have the same structure as the `security` object of a server entry. * `bootstrap`: An object with `bootstrapServerId`, `securityInstanceOffset`, `useDiscoverToVerifyConfiguration`, `bootstrapSerializationFormat`, and the arrays of LWM2M paths `bootstrapDelete` and `bootstrapRead`. * `firmware`: An object with `firmwareDeliveryMethod` (PUSH, PULL, or BOTH), `supportedDeviceProtocol` (COAP, COAPS, HTTP, or HTTPS), `resetMethod` (PACKAGE or PACKAGE_URI), `resetStateMachineOnStart`, `disableFirmwareStateMachine`, and `failOnStateAndResultIncompatibility`. If the agent returns HTTP 404, the device does not exist. ### To replace the connectivity, bootstrap, or firmware section {#to-replace-the-connectivity-bootstrap-or-firmware-section} Send a PUT request with the complete section to `/service/lwm2m-agent/v1/device//configuration/
`, where `
` is `connectivity`, `bootstrap`, or `firmware`. The example makes the device download new firmware itself over CoAP: ```http PUT /service/lwm2m-agent/v1/device//configuration/firmware Content-Type: application/json Accept: application/json { "firmwareDeliveryMethod": "PULL", "supportedDeviceProtocol": "COAP", "resetMethod": "PACKAGE_URI", "resetStateMachineOnStart": true, "disableFirmwareStateMachine": false, "failOnStateAndResultIncompatibility": false } ``` If the section that you read contains an `id`, send it back unchanged. The agent returns HTTP 200 and the stored section. For the meaning of the firmware settings, see [LWM2M device firmware update](https://cumulocity.com/docs/device-integration/lwm2m/#firmware-update). To delete the connectivity section, send a DELETE request: ```http DELETE /service/lwm2m-agent/v1/device//configuration/connectivity ``` The agent returns HTTP 200. If the agent returns HTTP 400, the validation of the section failed. The error response names the field. If it returns HTTP 404, the device does not exist. ### To add, replace, or delete a server {#to-add-replace-or-delete-a-server} The `servers` section is a list. You change it one entry at a time. The examples use `` for the `id` of a server entry and `` for the URI of the server. * To add a server, send a POST request with one complete server entry without `id`: ```http POST /service/lwm2m-agent/v1/device//configuration/servers Content-Type: application/json Accept: application/json { "uri": "", "bootstrap": false, "shortServerId": 2, "security": { "mode": "NO_SEC" }, "registrationLifetime": 3600, "bindingMode": "U" } ``` * To replace a server, read the `servers` section, change the entry, and send the complete entry in a PUT request to `/service/lwm2m-agent/v1/device//configuration/servers/`. * To delete a server, send a DELETE request: ```http DELETE /service/lwm2m-agent/v1/device//configuration/servers/ ``` The agent returns HTTP 200. For POST and PUT requests, the response contains the stored server entry. If the agent returns HTTP 400, the validation failed, and the error response names the field. If it returns HTTP 404, the device or the server entry with `` does not exist. The configuration belongs to the device registration. When you delete the device registration, the agent deletes the configuration too. ## Linked from the documentation - [LWM2M > LWM2M device details](https://cumulocity.com/docs/device-integration/lwm2m/#device-details)