LWM2M

Overview

Lightweight M2M (LWM2M) is a traffic and resource-optimized protocol to remotely manage IoT devices. The protocol is standardized by the Open Mobile Alliance. For more information, see http://openmobilealliance.org/iot/lightweight-m2m-lwm2m.

Important
Cumulocity IoT currently supports LWM2M 1.0.
Info
You can connect any device supporting LWM2M 1.0 to Cumulocity IoT without programming. We expect the device and its capabilities (such as firmware update) to be compliant to the LWM2M specification. The device must support the UDP binding of the LWM2M standard.

Our LWM2M solution allows any LWM2M object to be easily interfaced with the platform. For the sake of convenience, we provide out-of-the-box integration for the following LWM2M objects:

Our LWM2M solution supports the following measurement types:

Important
If a string is mapped into a measurement and the string value does not follow any of the notations above, it cannot be parsed. As a result, an alarm will be created.

To use these integrations, upload the corresponding DDF XML to your tenant. For arbitrary protocols, you can configure how LWM2M devices are mapped to Cumulocity IoT using device protocols. See Cloud Fieldbus > Configuring fieldbus device protocols for more information.

Device protocols

Registering LWM2M devices

To register a LWM2M device in Cumulocity IoT, upload a CSV file with registration data in the bulk registration dialog in Devices > Registration > Register device > Bulk device registration in the Device Management application, see Device Management > Connecting devices > To bulk-register devices in the User guide. This data is required to enable LWM2M communication. The CSV file holds all information for factory bootstrap and client-initiated bootstrap. In the factory bootstrap mode, the LWM2M client has been configured with the necessary bootstrap information prior to the deployment of the device. The client-initiated bootstrap mode requires a LWM2M bootstrap-server account pre-loaded in the LWM2M client. Cumulocity IoT supports registration for unsecured and PSK-secured LWM2M devices allowing connection with NO_SEC and PSK mode respectively.

Registration of unsecured devices

Unsecured devices connect during bootstrap connection and server connection through unsecured ports:

Below you can see an example CSV file for an unsecured device:

NO_SEC device csv

The CSV file must at least contain the following fields to be able to establish a connection:

Field Description
ID Unique ID of the device, such as an IMEI or a serial number. The ID field must be unique as it uniquely identifies a LWM2M device.
IDTYPE The type of the external ID. This type must be "c8y_Id" to allow Cumulocity IoT to create an external ID for the LWM2M device.
CREDENTIALS The device credentials. The content of this field is not used by the LWM2M feature. However, this field is still mandatory. Accessing Cumulocity IoT devices usually requires a password (the value of the "Credentials" field in the CSV file) by the inventory. However, the LWM2M agent has its own way of authenticating devices and hence the "Credentials" field is not used by the LWM2M agent but is used by the platform as a mandatory parameter. The credentials must contain a minimum of 12 characters with an uppercase letter, a lowercase letter, a digit and a special character.
NAME The name of the device. In this case the name of the device is the same as the device ID.
TYPE This field needs to have the value "c8y_lwm2m" to mark the device as a LWM2M device.
SHELL To enable "Shell", the value of this field must be "1". If you want to disable "Shell" the value must be "0". For more info about the shell commands, see Shell commands.
com_cumulocity_model_Agent This field needs to have the value "1" to forward all commands to the LWM2M agent.
endpoint id Indicates the LWM2M client's "endpoint ID" in order to allow the LwM2M bootstrap to provision the bootstrap information for the LWM2M client. The endpoint ID has be to be unique across all tenants and must have the same value as the ID.
lwm2m server uri The URI the server is using for bootstrap. The LWM2M bootstrap server is used to provision the LWM2M client with the information required to contact the LWM2M servers. If you are using the Cumulocity IoT service the hostname of the LWM2M server is "lwm2m.cumulocity.com". The bootstrap ports are "5683" for unsecure bootstrap connections and "5684" for secure bootstrap connections. The LWM2M server ports are "5783" for unsecure server connections and "5784" for secure server connections. Note that these values can be different for other services.
securityMode Determines the type of connection used by the LWM2M device. "NO_SEC" is used for unsecure connections which means that there is no security. It is highly recommended to always protect the LWM2M protocol. However, there are scenarios in which the LWM2M protocol is deployed in environments where the lower layer security mechanisms are provided. "PSK" is used for secure connections. With "PSK", the client and server have a common secret symmetric cryptography. Currently Cumulocity IoT supports only "NO_SEC" and "PSK".
Info
The Cumulocity IoT platform stores the credentials for a device owner associated with a particular device. Hence, if you delete a device while the device owner is not deleted and the same CSV file is used again for bulk registration, then the platform no longer considers it as a unique credential and throws an error. To resolve this either use new credentials or a new ID for the device. The other way to resolve this is to delete the credentials from the device credentials options under management.

Upon upload of the CSV file in Cumulocity IoT we should see that our “nosec_device” device has been created.

Unsecure device created

The table below reflects the full set of possible fields that can be added:

Field Type Description Mandatory
endpoint id String Indicates the LWM2M client's "endpoint ID" in order to allow the LwM2M bootstrap to provision the bootstrap information for the LWM2M client. The endpoint ID has be to be unique across all tenants and must have the same value as the ID. Yes
lwm2m server uri String The URI the server is using for bootstrap. The LWM2M bootstrap server is used to provision the LWM2M client with the information required to contact the LWM2M servers. If you are using the Cumulocity IoT service the hostname of the LWM2M server is "lwm2m.cumulocity.com". The bootstrap ports are "5683" for unsecure bootstrap connections and "5684" for secure bootstrap connections. The LWM2M server ports are "5783" for unsecure server connections and "5784" for secure server connections. Note that these values can be different for other services. Yes, for LWM2M bootstrap
securityMode String Determines the type of connection used by the LWM2M device. "NO_SEC" is used for unsecure connections which means that there is no security. It is highly recommended to always protect the LWM2M protocol. However, there are scenarios in which the LWM2M protocol is deployed in environments where the lower layer security mechanisms are provided. "PSK" is used for secure connections. With "PSK", the client and server have a common secret symmetric cryptography. Currently Cumulocity IoT supports only "NO_SEC" and "PSK". Yes
awakeTimeRegistrationParameter Integer Specifies a time interval in milliseconds for which a device is awake and accepting network traffic after sending a LWM2M registration or a registration update to Cumulocity IoT. If set to 0, the device will be considered as always online. If the value is not set, the awake time is determined by the LWM2M client's registration awake time attribute “at” or, if this attribute is also not found, then by the global setting that is defined in the LWM2M microservice. Optional
serverPublicKey String The public key of the server. Optional
generateBootstrapServerConfig Boolean In order to establish a connection between the LWM2M client and the LWM2M bootstrap server on the bootstrap interface, the client requires a pre-loaded LWM2M bootstrap server account. This property enables Cumulocity IoT to generate a bootstrap server configuration (for example, the security information like server URI, server ID, or security mode) for the LWM2M bootstrap server and writes it back to the client during bootstrap. Default is false. Refer to the OMA LWM2M 1.0 technical specification for more details. Optional
securityInstanceOffset Integer The first instance to be used during bootstrap to which entries are written. Default is "0". If set, for example, to "3", the first instance will be three. Optional
bootstrapShortServerId Integer The short server ID to be used for the bootstrap server. Default is "0". Optional
lwm2mShortServerId Integer The short server ID to be used for LWM2M server. Default is "1". Optional
registrationLifetime Integer The registration lifetime that is sent to the device during bootstrap. Overrides global agent configuration. The value must be specified in seconds. Optional
defaultMinimumPeriod Integer The default minimum period to configure during bootstrap. See LWM2M Spec for explanation. Optional
defaultMaximumPeriod Integer The default max period to configure during bootstrap. See LWM2M Spec for explanation. Optional
bindingMode String The LWM2M binding mode to be reported to the device. Supported are “UQ” (default, queuing) and “U” (unqueued). Note, that Cumulocity IoT will always queue operations. Optional
notificationIfDisabled (true/false) Boolean See LWM2M spec. Default: Not configured. Optional, defaults to Leshan default behavior.
disableTimeout (true/false) Boolean See LWM2M spec. Default: Not configured. Optional, defaults to Leshan default behavior.
binaryDeliveryEncoding String Indicates the encoding format for writing binaries to a LWM2M device. The encoding format can be either "OPAQUE" or "TLV" or "JSON" or "TEXT". In case of empty or invalid entries, the default format is considered as "OPAQUE". Optional
lwm2mRequestTimeout Integer The timeout used for shell operation requests such as read, write, execute done by the LWM2M microservice to the LWM2M device. The value is in milliseconds and can be given to override the default value that is provided in the LWM2M microservice property file with “C8Y.lwm2mRequestTimeout” property. The value must not exceed the maximum request timeout limit given in the LWM2M microservice property file with “C8Y.lwm2mMaxRequestTimeout” property. Optional

Registration of PSK-secured devices

PSK-secured devices connect during a bootstrap connection and a server connection using a pre-shared key through secured ports:

PSK keys must be provided during the device registration in the CSV file. The file must contain the fields defined in Registration of unsecured device. PSK registration requires additional fields to be filled (see the example CSV file for a PSK-secured device below).

PSK device csv

The table below lists the information of the additional fields:

Field Type Description Mandatory
lwm2m psk_key String The hex-encoded pre-shared key used by the device for server connections in PSK mode. Mandatory for PSK. Should not be set for NO_SEC.
lwm2m psk_id String The ID used by the device for server connections in PSK mode. Mandatory for PSK. Should not be set for NO_SEC.
bootstrap psk_id String The ID used by the device for bootstrap connections in PSK mode. Yes for PSK
bootstrap psk_key String The hex-encoded key used by the device for bootstrap connections in PSK mode. Yes for PSK
external-c8y_Lwm2mPskId String This field has the same value as the "lwm2m psk_id" field. The ID is used to create an additional external ID of type "c8y_Lwm2mPskId" in the registered device. Optional
external-c8y_BootstrapPskId String This field has the same value as the "bootstrap psk_id" field. This mandatory ID is used to create an additional external ID of type "c8y_BootstrapPskId" in the registered device which will be used to find the device during bootstrap. Mandatory

Upon upload of the CSV file in Cumulocity IoT we should see that our “psk_device” device has been created with the appropriate external IDs.

PSK device created PSK device external ids

Info
Firmware updates are also supported for registration of unsecured devices as well as PSK-secured devices. For more information, see Device Management > Managing device data > Managing device firmware in the User guide.

The following table explains several optional parameters related to firmware update which help in tuning the Firmware Over The Air (FOTA) parameters on a device level.

Field Type Description
fwUpdateDeliveryMethod String Explains the firmware update delivery method. Can be either "PUSH" or "PULL" or "BOTH".
fwUpdateSupportedDeviceProtocol String Indicates the device protocol to be used for the firmware update. Can be either "COAP" or "COAPS" or "HTTP" or "HTTPS".
fwUpdateResetMechanism String Indicates the mechanism used to reset the firmware update state machine. Can be either "PACKAGE" or "PACKAGE_URI". And as per the given option, the LWM2M agent either writes an empty string to package URI resource or sets the package resource to NULL ('\0'). If this field is not used the default reset state machine mechanism is used in which for PUSH reset is done via package resource and for PULL reset is done via package URI.
fwUpdateURL String Indicates the firmware update URL from where the LWM2M device can download the firmware package.

After creation, the bootstrap parameters can be viewed and changed in the LWM2M bootstrap parameters tab in the Device details page, see LWM2M bootstrap parameters.

Duplicate LWM2M devices

If a LWM2M device is registered with the same endpoint ID in multiple tenants, the device will be binded only to the tenant in which the device was first registered and the devices in the other tenants will be considered as duplicates. As notification, a MAJOR alarm is created stating that the device with this endpoint already exists.

Alarm for duplicated device with endpoint

LWM2M device protocols

To process data from LWM2M devices, Cumulocity IoT uses device protocols. Device protocols are accessible through the Devices Types menu in the Device Management application. For details on the general usage, see Device Management > Managing device types in the User guide.

Creating LWM2M device protocols

Once you have registered a device with the proper CSV file, you can manage LWM2M device protocols. Each piece of information available by the LWM2M client is a resource. The resources are further logically organized into objects. The LWM2M client can have any number of resources, each of which belongs to an object. In the device protocols you can observe your resources. Furthermore, you can choose whether to create measurements, events or alarms out of those resources.

To add a new LWM2M device protocol follow these steps:

  1. In the Device Management application, move to the Device protocol page.
  2. Click Add device protocol in the top menu bar.
  3. In the upcoming dialog select LWM2M as device protocol type.

Add new protocol

  1. Next, upload an appropriate DDF or XML file. DDF or XML files describe the data provided by your device. They are typically provided by the manufacturer or by standards bodies such as IPSO. There are also 3 “special” device protocols (DDF files) for standard OMA objects: 6 (location tracking), 5 (firmware update) and 3 (device information). If these files are not uploaded, then neither location tracking nor firmware updates will work. By default, the LWM2M agent adds mappings to these objects and knows how to “handle” their information without any additional configuration. The XML schema used by LWM2M can be found at http://www.openmobilealliance.org/tech/profiles/LWM2M.xsd.
    If the DDF files for the default mappings are uploaded in the Management tenant, all subscribed user tenants will inherit this behavior.

Upload DDF file

  1. In the next dialog, you can see the name and description of the protocol. Click Complete to create the new device protocol.

Upload DDF file

The device protocol will open in a new page.

Example protocol

In the device protocol page, you will see the description at the top left and the ID, the creation date and date of the last update at the top right.

Below, a list of resources configured for the device will be listed (which is empty when creating a new protocol), showing the ID, name and potentially configured functionalities for each resource.

Info
LWM2M protocol resources cannot be edited.

Example: In the following screenshot you can see an example device protocol. This object should be used with a temperature sensor to report a temperature measurement. It also provides resources for minimum/maximum measured values and the minimum/maximum range that can be measured by the temperature sensor. An example measurement unit is “degrees Celsius”.

Example protocol2

Adding additional functionalities to a resource

The functionalities that you may enable are the following:

Resource functionalities

Send measurement

Turn on Send measurement to specify a measurement.

Create alarm

Turn on Create alarm if you want to create an alarm out of the resource. Specify the following parameters (all mandatory):

Send Event

Turn on Send event to send an event each time you receive a resource value. Specify the following parameters:

Custom Actions

Turn on Custom Actions to map LWM2M data into Cumulocity IoT using custom data processing actions. For specialized integration use cases, it is required to perform customized data processing on LWM2M data. One example are LWM2M resources of the OPAQUE data type that contain proprietary, binary data, CBOR, XML or alike.

Custom actions

Cumulocity IoT LWM2M allows the set of custom actions to be extended using decoder microservices. A decoder microservice is an ordinary Cumulocity IoT microservice that implements a simple decoder interface. The LWM2M agent calls this microservice for decoding data in a customer-specific way. We are providing an according example how to write such a decoder microservice in our public GitHub repository.

Predefined custom actions

There are several predefined custom actions which can be selected to apply actions to the relevant resources. Predefined custom actions

Actions that are relevant for Device (/3):

Actions that are relevant for connectivity monitoring (/4):

Below is an example where the “connectivity:updateRssi” custom action is selected for the Connectivity monitoring (/4) radio signal strength in order to create the signal measurement for the device. Custom actions for connectivity signal strength

Auto observe

If Auto-Observe is turned on for a resource, the LWM2M server observes a specific resource for changes.

Info
At least one functionality must be set to enable “Auto observe”.

Resource

Alarms on device protocol mapping failures

There are 2 types of alarms raised related to device protocol mapping failures.

Alarms on mapping failures

LWM2M device details

Info
In the Device management application, you can view all details of a device. The following details are specific to LWM2M devices. For information on general details refer to Device details in the Device management section.

Objects

In the Objects tab of a LWM2M device, you can view all objects, resources and instances of the device. Additionally, you can create new operations, see all currently pending operations and view the history of all previous operations.

Objects view

Info
In order to see resources in the Objects tab, the resources first must be added in the Device Protocols page.

The following operations may be available in each instance:

Info
Some instances do not have all of the listed operations.

Some object cards show additional operations which can be performed. These operations become available after reading the object/instance, for example, device Update. In order to perform the operation without parameters, click Execute. To perform an operation with parameters click Execute with parameters and enter a value.

Execute operation

More information can be acquired for each resource by hovering over the tooltip icon.

Tooltip

Additional information on recent operations can be viewed by clicking the operations button located at the right side of an instance card. The button is only visible if any operation has been performed. The number of unread operations can be seen on the top right of the button. In the example below there is only one.

Recent operations Recent operations 2

To view the history of all operations, simply click View history. Note, that you will be redirected to the Control tab.

View History control tab

If enabled, the agent will periodically look for starved operations of a tenant and fail them automatically. Starved operations are device operations which have had a status of EXECUTING and have not been updated for a long time. Platform administrators can configure how long such operations stay alive (described in the LWM2M agent installation & operations guide).

Audit Configuration

In the Audit configuration page you can audit the current device by comparing it to a selected reference device. It is also possible to sync properties to the values of the referenced device.

Click Audit configuration in the right of the top menu bar to navigate to the Audit configuration page.

Audit configuration

To sync properties, select the desired reference device from the dropdown list. Check the properties that you wish to sync and click Sync selected properties.

Info
The numbers in the green circles represent the number of properties in the instance which have the same value in both devices. Respectively, the numbers in the red circles represent the number of properties which have different values compared to the values of the referenced device. If an instance is expanded, you can select only specific properties which can be synced.

Sync properties

LWM2M bootstrap parameters

In the LWM2M bootstrap parameters tab, bootstrap parameters of the current device can be viewed and changed. To modify a parameter, enter the desired value in a field of your choice and click Save.

Bootstrap customization

Important
Currently only the “NO_SEC” and “PSK” security modes are supported.

For further information on the fields in the LWM2M bootstrap parameters tab, see Registering LWM2M devices.

LWM2M client awake time

LWM2M client awake time specifies how long a device can be expected to be listening for incoming traffic before it goes back to sleep. The LWM2M server uses the client awake time to determine if the operations are passed down to a device. The operations are sent during the awake time after the registration or after the registration update request is received by the LWM2M server. After the awake time has passed, the operations are being queued and will be sent to the device on the next registration or registration update. This applies to all operations that can be applied to the device.

LWM2M client awake time is determined based on the following priority:

  1. (If provided) Device managed object “awakeTimeRegistrationParameter” fragment.
  2. (If provided) Registration awake time attribute “at” in the registration request by the LWM2M client.
  3. Global setting of the LWM2M microservice.

Device managed object “awakeTimeRegistrationParameter” fragment can be provided during the device registration as explained in Registering LWM2M devices or set with the managed object update request as in the example:

PUT /inventory/managedObjects/<device-managed-object-id>

{
    "awakeTimeRegistrationParameter": 180000
}

The value is in milliseconds. If set to 0, the device will be considered as always online.

Handling LWM2M shell commands

In the Shell tab of a device, LWM2M shell commands can be performed. Each command has a different functionality. Find all available placeholders (for example “objectID”, “instanceID”) and commands with their respective descriptions below:

Placeholder Description
objectID The ID of the object.
instanceID The ID of the instance. Some objects can have multiple instances. For example, "3300" is a temperature sensor object. Each device can have up to 10 sensors. In this case the instance ID would be 3300/1…10 depending on the sensor that you would like to focus.
resourceID The ID of the desired resource. The resources describe the characteristics of each object. All instances of a given object have the same resources, but the value of the resources may be different.
value The value to be written to the resource. Must be given using the type of the resource.
parameters The optional parameters of the "execute" operation. Must be expressed in plain text and follow the ABNF grammar rule.
Firmware version The current version of the firmware.
Firmware url The URL from which the new version of the firmware will be downloaded.
SER The supported data formats are TLV, TEXT, JSON and OPAQUE.

In the next table you will see all available commands and a brief description of their functionality.

Command Description
read /<objectID>/<instanceID>/<resourceID> Reads a resource path.
observe /<objectID>/<instanceID>/<resourceID> Enables the observe functionality.
execute /<objectID>/<instanceID>/<resourceID> [<parameters>] Executes a resource on the device with optional parameters.
write /<objectID>/<instanceID>/<resourceID> <value> Writes value to a resource on the device.
cancelobservation /<objectID>/<instanceID>/<resourceID> Cancels the observation functionality from the desired resource.
delete /<objectID>/<instanceID>[/<resourceID>] Deletes a given object/instance/resource.
discover /<objectID>/<instanceID>/<resourceID> Shows all resources of the given object.
create /<objectID> [JSON] Creates a new object. The JSON argument is optional.
writeattr /<objectID>/<instanceID>/<resourceID> pmin=<sec>&pmax=<sec>&gt=<num>&lt=<num>&st=<num>&cancel Writes additional attributes to the object. Typically used for conditional observes.
fwupdate <Firmware name>;<firmware version>;<firmware_url> Updates the firmware of the agent.
serialization <SER> Sets the data format.
Info
A shell command can also be used to send multiple operations to a LWM2M device at once. To do that, simply enter all instructions with a line break between them. Make sure that the shell command does not carry any leading or trailing white spaces. The LWM2M agent then uses the line break to split a multi-line operation into separate LWM2M shell operations.

Adding validation rules to resources

Validation rules are used to verify that the data a user enters in a resource meets the constraints you specify before the user can save the resource.

Validation rules can only be added to resources which have “write” permissions. Resources which can have validation rules are marked by the following icon:

Validation rule icon

When hovering over the icon, you can see whether there are defined validation rules.

Add a new validation rule by clicking on the desired resource and then click Add validation rule.

Add validation rule

Validation rules can have the following types:

After selecting a type, the following rules can be selected:

Info
Not all rules are available to each type.

To delete a rule, simply click on the delete icon:

Remove lwm2m rule

Click Save to save your settings.

Complex rulesets

In order to enable more complex conditions, multiple validation rules can be defined for a resource:

The screenshot above provides an example for the use of validation rule groups: User input is valid if the given string does not match “test” (equals not). It is also valid if it ends with “asd” and it matches the contents of the LWM2M resource /3/0/15.

Complex rulesets are based on Boolean Disjunctive Normal Form, which allows arbitrary complex rules to be defined.

Device lifecycle events

The LWM2M agent creates events of device lifecycle in Cumulocity IoT. Following are the specific event types for device bootstrap and registration process. The LWM2M agent creates the events with the specific event type during the device bootstrap and registration process.

Handling LWM2M post registration actions

The LWM2M shell commands can be performed in the Shell tab of each device. It is also possible to execute some common operations when a device sends a full registration request. This can be done in the LWM2M post-operations page accessible from the Device types menu in the navigator. A set of shell commands can be saved in the Commands section, which will be performed on each device on registration.

Post operations example

The above image shows the LWM2M post-operations page with a set of sample shell commands. More information on shell commands can be found in LightweightM2M > Handling LWM2M shell commands in the Protocols integration guide.

Device operations handling

If the operations are created while the device is offline, all the operations will be executed when the device comes online as those operations will be delivered through the real-time channel. A configurable property can limit the number of operations to be executed as part of the post-registration process, for example, the operations which were already delivered to the device once via the real-time channel, but they still have a status of PENDING.

Info
The default maximum limit of the pending operations is 10, which is a configurable value for the agent. In case this limit is not sufficient for your use case please contact product support.

LWM2M device firmware update (FOTA)

Cumulocity IoT LWM2M agent supports FOTA (Firmware update Over The Air) using a firmware binary that is uploaded to the Cumulocity IoT platform. To upload a firmware, go to Device Management > Management > Firmware repository > Add firmware

Add new firmware

Select the firmware binary to upload, either from your local computer or from a URL. The device type filter must be left empty or filled with a value of c8y_lwm2m.

Assuming that you have already registered and connected your device, go to the device page to trigger a firmware update like this:

Trigger firmware update

Once the firmware update has been triggered, the LWM2M agent creates and queues up a PENDING firmware update operation for execution.

Info
This document is not supposed to cover every detail of firmware update process because they are already specified in the LWM2M specification. This instead summaries the process, highlights the key points and possible customizations of the firmware update process in Cumulocity IoT LWM2M.

Firmware update state machine

The firmware update procedure is well standardized within the LWM2M specification, and a standard Firmware Update Object (/5) is used to perform the process. Let’s have a quick glance at the firmware update state machine as defined by the LWM2M specification:

Firmware update state machine (Source: openmobilealliance.org)

Basically the whole update process contains different phases of interactions between the LWM2M server and the device. The above diagram consists of the possible states and transitions that could be introduced during the firmware update process.

If the device goes offline or is considered offline by the LWM2M agent, the firmware update operation is left IN_PROGRESS and the agent will try to resume the firmware update process if possible when the device connects again via a registration or registration update.

Resetting the state machine

When the firmware operation is being executed, the LWM2M agent first of all tries to reset the firmware state machine to the original state to avoid any leftover downloaded firmware that has not been installed or failures of the previous firmware update attempts on the device. Cumulocity IoT LWM2M agent supports the following mechanisms of resetting the firmware update state machine:

If resetting the state machine has failed because the device is not reachable, the firmware update operation stays in PENDING status and will be executed when the device connects. If it’s failed by any other reason, the firmware update operation set to FAILED. If the state machine is reset successfully, the firmware update operation is marked as IN_PROGRESS and the process continues to the next steps.

Querying the device configuration

In order to determine what is the best way to deliver the firmware to the device, the LWM2M agent tries to read the device configuration by executing a read request on the firmware update object on the device: read /5/0. In this step, the agent will learn:

Supported firmware delivery methods and delivery protocols can also be specified in the device managed object by setting these fragments:

If they are specified in the device managed object, the values sent by the device are ignored.

Firmware delivery

As the first step of the delivery, the agent tries to establish the observations on two resources to monitor the firmware delivery transitions on the device:

Depending on the supported delivery protocols and methods by the device, the agent now delivers the firmware to the device.

When PULL is selected as the delivery method, the agent will try to write the firmware URI to the device firmware package URI: write /5/0/1 . The agent constructs the firmware URI according to the selected delivery protocol.

When PUSH is selected as the deliver method, the agent will try to write the firmware binary to the device firmware package: write /5/0/0 .

In both cases, if the firmware binary cannot be delivered as one single message, the agent delivers the firmware using so-called block-wise transfer. The preferred size of each block can be specified by the device in the negotiation phase with the LWM2M agent. If the device does not specify it, the agent uses its default block size of 512 bytes.

When the delivery is completed on the device (no matter if it’s successful or failed, for example, because the device runs out of storage, or due to network issues) the device must inform the agent by updating the value of the firmware update state (/5/0/3) and/or firmware update result (/5/0/5). Practically, the device can keep sending the value periodically for the firmware update state resource even if the firmware is still being transferred, with the value 1 (Downloading) or 2 (Downloaded).

Triggering the firmware update on the device

When the firmware delivery is completed successfully and the agent is informed, it will trigger the firmware update on the device by sending an execute request to the update resource: execute /5/0/2. Note that the observations on the update state and update result are still being maintained. When the update process is completed on the device, it must communicate to the agent by updating the value of firmware update result (and firmware update state).

Completing of the firmware update process

When the firmware update is completed (no matter if it’s successful or failed) on the device and the agent is informed, the agent completes the firmware update process.

Canceling the firmware update process

In practice, the communications between the device and the agent are not always smooth, for example in the case of network failures or the device is not able to report to the agent about its status, or in case of other failures, you might want to cancel the firmware update process entirely and start a new one. To do that, send an HTTP request as the following: PUT .../service/lwm2m-agent/shell/{tenantId}/{deviceId}/cancelFirmwareUpdate in which tenantId is the ID of your tenant, deviceId is your device managed object ID. The ongoing firmware update process will be canceled by the agent. Alternatively, the firmware update process is also canceled if you delete the firmware update operation.