LWM2M

Introduction

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.

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:

• Device (/3)
• Connectivity monitoring (/4)
• Firmware update (/5)
• Location (/6)

Our LWM2M solution supports the following measurement types:

• Boolean - represented as “true” or “false” and mapped in Cumulocity IoT LWM2M solution respectively as “0” or “1”
• Float - represented by any float numeric values and mapped in Cumulocity IoT LWM2M solution as is
• Integer - represented by any integer numeric values and mapped in Cumulocity IoT LWM2M solution as is
• Time - represented by any integer or a date format that can be converted to an integer and also mapped in the Cumulocity IoT LWM2M solution as an integer
• String - represented by:
  • Any numeric values in a string format (for example integer and float)
  • Numeric values in scientific format in a positive or negative exponential notation (for example 1.23E10 or 3.57e+5 or 9.8e-4)
  • Any positive or negative numeric values starting with leading zero will be interpreted as a positive or negative octal value (for example -029 or 010) and will be stored in Cumulocity IoT as its decimal representation
  • Any positive or negative value starting with 0x or 0X followed by any number or letter from A to F (case insensitive) will be interpreted as a positive or negative hexadecimal value (for example 0x23F3D5C1 or -0x42a3b3d1) and will be stored in Cumulocity IoT as its decimal representation

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 Configuring fieldbus device protocols for more information.

Registering LWM2M devices

The data provided during registration must enable LWM2M communication and holds 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 preloaded in the LWM2M client. Cumulocity IoT supports registration for unsecured and secured LWM2M devices allowing connection with NO_SEC, PSK and X.509 security modes respectively.

You can register a LWM2M device in Cumulocity IoT in two ways:

• Single device registration
• Bulk device registration

Single device registration

To register a LWM2M device in Cumulocity IoT navigate to Devices > Registration in the Device management application, click Register device at the top right and select Single device registration > LWM2M from the dropdown.

The LWM2M device registration wizard has four steps:

• Device - configuration of globally unique device identifier. Refer to Device settings section below for details about the fields.
• Security - configuration of LWM2M security modes, separate for bootstrap server (“Bootstrap Security Mode”) and regular server (“Server Security Mode”) connections. Refer to Security settings section below for details about the fields.
• Bootstrap settings for enabling the device to connect to the Cumulocity IoT LWM2M bootstrap server. Refer to Bootstrap settings section below for details about the fields.
• Advanced setting for further optional configurations. Refer to Advanced settings section below for details about the fields.

After filling all applicable information for the device, click Register. The UI will display a confirmation message.

Bulk device registration

If there is a number of devices to be registered at the same time, it is more convenient to use bulk device registration.

To register the LWM2M devices in Cumulocity IoT, navigate to Devices > Registration in the Device management application, click Register device at the top right and select Bulk device registration > LWM2M from the dropdown. Upload a CSV file with the registration data in the resulting bulk registration dialog. The dialog also contains CSV template links. Refer to Device settings, Security settings, Bootstrap settings and Advanced settings below for details about the fields.

When you upload the CSV file, the dialog will display a confirmation message that tells you where to find the result. The bulk device registration operation will be displayed in the LWM2M connector device object created for the tenant.

Device settings

The fields below must be contained to be able to establish a connection:

Security settings

We can distinguish 2 types of connectivity:

• bootstrap - connection established to bootstrap server in order to provision device with server configuration.
• server - connection established to regular server to exchange data.

Cumulocity IoT supports different security modes for both connections so device can connect to boostrap server and regular server using different security modes.

Currently Cumulocity IoT supports 3 security modes:

• NO_SEC - Device connects to the platform without any 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 - Device connects to the platform using DTLS with the given pre-shared ID and KEY (PSK).
  • bootstrap connectivity - PSK ID and KEY must be preconfigured on the device by manufacturer and the same credentials must be provided during device registration.
  • server connectivity - PSK ID and KEY must be provided during device registration. The device is expected to use these credentials during regular server connection. Bootstrap server will write these credentials to the device during a LWM2M bootstrap session. There are 2 ways to provide PSK ID and KEY:
    • manual (PSK) - Manually enter both ID and KEY values (useful when device is preconfigured, and it won’t use bootstrap server).
    • generated (PSK_GENERATED) - Server will assume PSK ID is equal to the endpoint ID of the device, and it will generate random secure PSK KEY. This scenario is useful when you want to secure server connectivity without preconfiguring PSK keys on the device. Device can bootstrap with NO_SEC/X509, and it will be provisioned with auto-generated PSK credentials for server connectivity.
• X509 - Device connects to the platform using X.509 certificate.
  • bootstrap connectivity - device must be preconfigured by manufacturer with X.509 certificate, private key and trust store/server certificate. There are no additional settings to provide during device registration.
  • server connectivity - here we can distinguish 2 scenarios:
    • device has all X.509 credentials pre-configured by manufacturer - no additional data is required during device registration.
    • device expects bootstrap server to provision certificates - in this case it’s possible (but not mandatory, when empty it won’t be written to device by bootstrap server) to provide:
      • X.509 Certificate and Private Key in PEM format. Private key will be stored as encrypted data on the platform.
      • Server certificate to use (more on this below).
      • Certificate usage (as defined in LWM2M specification)

More details on X.509 security

Client X.509 certificate must meet the requirements specified in LWM2M specification. For testing purposes, certificate can be generated by a self-signed CA in the following way:

• Creation of self-signed CA:

openssl ecparam -name prime256v1 -genkey -noout -out myCA.key
openssl req -x509 -new -nodes -key myCA.key -days 36500 -out myCA.pem

• Creation of device certificate signed by our CA:

# create and sign certificate
openssl ecparam -name prime256v1 -genkey -noout -out myDevice.key
openssl req -new -key myDevice.key -out myDevice.csr
openssl x509 -req -in myDevice.csr -CA path/to/myCa.pem -CAkey path/to/myCa.key -CAcreateserial -out myDevice.crt -days 36500
# export to PKCS8 PEM format
openssl pkcs8 -topk8 -inform PEM -outform PEM -in myDevice.key -out myDevice.key.pem -nocrypt
# optionally export to DER format if your device needs it
openssl pkcs8 -topk8 -inform PEM -outform DER -in myDevice.key -out myDevice.der -nocrypt

Trusting CA in Cumulocity IoT

Before devices are able to connect to the platform, CA that issued device certificates must be added to trusted certificates. See Managing trusted certificates on how to add and trust CA certificate.

All security field details

The fields below must be contained to configure security modes for bootstrap and regular server connection:

Bootstrap settings

Registration of NO_SEC devices

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

• 5683: unsecure bootstrap connection
• 5783: unsecure direct server connection

Registration of secured devices

Secured devices connect during a bootstrap connection and a server connection through secured ports:

• 5684: secured bootstrap connection
• 5784: secured direct server connection

See the table below for the full set of bootstrap fields you can add:

Advanced settings

See the table below for information on additional fields:

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

Duplicate LWM2M devices

If a LWM2M device has been registered with the same endpoint ID before, the device registration will not register the device, neither for single nor for bulk device registrations. For single device registrations, the duplication error message will be displayed after clicking register. For bulk device registrations, the information about duplicate LWM2M devices will be displayed under the LWM2M connector device’s bulk upload operation result.

Device deletion

During LWM2M device registration the tenant route information is also stored in the cluster tenant. To remove the device, delete it from the All devices list.

LWM2M connector device

The LWM2M connector device is an automatically generated device for the tenants which have a subscription to the LWM2M application. You can use this device to manage tenant-wide LWM2M devices. The help shell command shows the available operations and how to use them.

Additionally, the bulk device registration status and result are shown under this device.

Migration of the LWM2M devices

Starting from version 10.15.0, the new device registration for LWM2M is introduced. LWM2M devices created earlier than version 10.15.0 and new LWM2M devices created via bulk registration must be migrated to the new structure using the migrateLwm2mDevices command for the tenant. It migrates all devices and their existing client registration objects to the new format in the database. It is backwards compatible since it retains old fragments.

The argument -d or --devices followed by a list of managed object IDs can be used to migrate specific device managed objects. To skip the migration of their corresponding client registration objects, use the -sr or --skipRegistrations argument.

Example usages:

• migrateLwm2mDevices: to migrate all devices and client registration objects of the tenant
• migrateLwm2mDevices --skipRegistrations: to migrate all devices without their client registration objects
• migrateLwm2mDevices --devices 1111 2222: to migrate specific devices with their client registration objects
• migrateLwm2mDevices -sr -d 1111 2222: to migrate specific devices without their client registration objects

Invalidate registrations

The LWM2M connector device may be used to invalidate LWM2M registrations. This is sometimes helpful to force a LWM2M device to re-register.

Invalidate registrations by endpoint

This command removes the LWM2M registrations using an endpoint ID.

Syntax: invalidateRegistrationsForEndpoint <endpoint_ID>

Example usage: invalidateRegistrationsForEndpoint urn:imei:012345678901234

This command invalidates all known LWM2M registrations for the endpoint urn:imei:012345678901234.

Invalidate registrations by LWM2M registration ID

Alternatively an LWM2M registration may be invalidated using its ID, using the following command:

Syntax: invalidateRegistrationById <registration_ID>

Example usage: invalidateRegistrationById F7DqjmW3Yy

This command invalidates the LWM2M registration with ID F7DqjmW3Yy.

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 Managing device types.

Creating LWM2M device protocols

Once you have registered a device, 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.

4. 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. In the next dialog, you can see the name and description of the protocol. Click Complete to create the new device protocol.

5. The device protocol opens in a new page that contains the object ID and description and the list of resources that belongs to this object. In this page additional functionalities to a resource can be added.

Adding additional functionalities to a resource

To access resource functionalities proceed to the device protocol page and click one of the resource instances. See below for the functionalities that you may enable:

Send measurement

Turn on Send measurement to specify a measurement.

• Enter the type of the measurement. For example, “c8y_AccelerationMeasurement”.
• Series are any fragments in measurements that contain a “value” property. For example, in the series field you can enter: “c8y_AccelerationMeasurement.acceleration”.
• The “Unit” field specifies the unit of the given measurement. For example, “m/s” for velocity.

Create alarm

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

• Severity: CRITICAL, MAJOR, MINOR, WARNING
• Type
• Status: ACTIVE, ACKNOWLEDGED, CLEARED
• Text

Send Event

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

• Enter the type of the event. For example, “com_cumulocity_model_DoorSensorEvent”.
• Enter the text which will be sent. For example, “Door sensor was triggered”.

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.

We distinguish here between predefined custom actions and decoder microservices.

Predefined custom actions

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

Actions that are relevant for a device object (object ID /3):

• device:updateManufacturer
  • Adds manufacturer information to the name of the device in the following format “LWM2M <manufacturer> <registration endpoint>”
• device:updateModelNumber
  • Stores to the device managed object with the c8y_Hardware fragment “model” property.
• device:updateSerialNumber
  • Stores to the device managed object with the c8y_Hardware fragment “serialNumber” property.
• device:updateFirmwareVersion
  • Stores to the device managed object with the c8y_Hardware fragment “revision” property.

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

• connectivity:updateCellId
  • Stores to the device managed object with the c8y_Mobile fragment “cellId” property.
• connectiviy:updateSmnc
  • Stores to the device managed object with the c8y_Mobile fragment “mnc” property.
• connectivity:updateSmcc
  • Stores to the device managed object with the c8y_Mobile fragment “mcc” property.
• connectivity:updateRssi
  • Stores the value as device measurement with the c8y_SignalStrength type and fragment and “rssi” property.
  • In the same measurement, stores resource path information in “resourcePath” fragment and also in “objectResourcePath_<resource path>” fragment name.
  • In the same measurement, stores device name information in “device!Name” fragment.
  • In the same measurement, stores device mobile information in “device!c8y_Mobile” fragment.

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.

Decoder microservices

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 provide an according example how to write such a decoder microservice in our public GitHub repository.

The LWM2M agent serializes different LWM2M data types to binary data depending on the type of the corresponding resource:

Ignore empty values

If the Ignore empty values option is selected and a device sends empty data, the agent does not perform any action that is configured. If this option is not selected and a device sends empty data, the agent performs the mapped action (default behavior).

Auto observe

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

Alarms on device protocol mapping failures

There are two types of alarms raised related to device protocol mapping failures:

• Alarm for no mapping known: This alarm is raised when value is read or observed but no mapping for this resource is found. This can be resolved by importing device protocol for this resource.

• Alarm due to non-numeric/non-Boolean value received for measurement mapping: This alarm is raised when the resource has a measurement mapping set up but measurement cannot be created because received value is a non-numeric/non-Boolean value.

LWM2M device details

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.

The following operations may be available in each instance after clicking the menu icon at the end of each object row:

• Read Object: Reads all instances for the selected object and lists all available resources for each instance.
• Read Instance: Reads the current instance of the given object and lists all available resources.
• Create Instance: Creates a new instance for the selected object.
• Delete Instance: Deletes the selected instance.

Some object cards show additional operations which can be performed. These operations become available after reading the object/instance. The possible options are Write, Execute and Execute with parameters. For example, after reading device Firmware update in order to perform the operation Execute without parameters, find the Update section on the object card and click Execute. To perform an operation with parameters click Execute with parameters and enter a value.

More information can be acquired for each resource by hovering over the help icon present on the right of the field name.

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 are two.

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

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.

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.

LWM2M configuration

The LWM2M configuration tab displays all LWM2M settings related to the device. These settings are grouped logically by the function they affect.

• Device settings - General device parameters:
  • Endpoint ID
  • Awake time
  • Request timeout
  • Serialization format
  • Binary format
  • Timestamp resources
  • Objects tab behavior (keep old values)
  • Disable the default behavior for object instances of objects 3 (device), 4 (connectivity monitoring) and 6 (location)
• Bootstrap settings - related to LWM2M bootstrap
  • Bootstrap server ID
  • Security instance offset
• Servers to write during bootstrap - list of servers that will be written to the device when it bootstraps. Each server has:
  • Server URI
  • Server ID
  • Registration lifetime
  • Default min period
  • Default max period
  • Binding mode
  • Disable timeout
  • Security mode
    • depending on the selected mode there are additional settings for PSK and X.509
  • Notifications flag
• Connectivity settings - security configuration for bootstrap and regular LWM2M connection.
• Firmware update settings
  • Disable automated firmware update support
  • Firmware URL
  • Delivery method
  • Delivery protocol
  • Reset state machine settings

For a detailed description of the parameters above, 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:

REQUEST_JSON = { 	
	"method": ${METHOD},
	"uri": ${URI},
	"contentFormat" : ${CONTENTFORMAT},
	"accept": ${ACCEPT},
	"payloadHex": ${PAYLOADHEX}
	}
METHOD = "get" | "post" | "put" | "delete" | "fetch" | "ipatch" | "patch"
URI = "/" | "[A-Fa-f0-9]" | uri | null
CONTENTFORMAT = null | "IANA Content Type"
ACCEPT = null | "IANA Content Type"
PAYLOADHEX = null | "^[A-Fa-f0-9]+$"

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

coap {
	"method" : "get",
	"uri" : "/3/0",
	"accept" : "application/vnd.oma.lwm2m+json"}

Shell command lifecycle

The handling of LWM2M shell commands follows the following lifecycle:

1. When a shell command is created the corresponding operation status is set to PENDING. This means that the corresponding CoAP request has not yet been sent to the device.
2. The Cumulocity IoT platform processes the shell command. It sends a corresponding CoAP request to the device and updates the operation status to EXECUTING.
3. The next status update depends on the response of the device.
   • Successful request: In case the device signals a successful operation using a 2.XX CoAP response code, the operation result is updated and the operation status is turned to SUCCESSFUL.
   • Failed requests: If the CoAP request fails with a 4.XX or 5.XX error on the device, the operation is marked as FAILED. The operation result contains a possible response of the device.
   • Not-responding: When sending a LWM2M command to a device the Cumulocity IoT platform is not precisely aware if the device can be reached using a UDP datagram. If the request times out Cumulocity IoT assumes that there is no connectivity. It puts the operation back to PENDING. A redelivery of the operation is triggered as soon as the device sends a registration update or a new LWM2M registration request.
4. To view the history of all operations, click the Control tab.

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:

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

Validation rules can have the following types:

• Date: Simply enter a date and select your desired rule.
• Number: Only values of “Integer” or “Float” type are allowed depending on the resource.
• ObjectLink: Reference to another object using the format “/Object/Instance/Resource”.
• Regex: Add a string which describes the validation pattern. For example, “.*dd” means that the string must end with “dd”.
• String: Enter a string value which can be either “True” or “False”.

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

• Greater than
• Lower than
• Equals
• Equals not
• Greater or equals than
• Lower or equals than

To delete a rule, click on the red remove icon on the right side of that 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:

• Multiple rules can be defined in a validation rule group. A user input is only valid if each of the rules in the validation rule group is satisfied (logical AND).
• It is possible to declare multiple validation rule groups. If multiple validation rule groups are declared, user input is valid if any of the validation rule groups is satisfied (logical OR).

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.

• Bootstrap event types:
  • c8y_LWM2MDeviceBootstrapStart.
  • c8y_LWM2MDeviceBootstrapEnd.
  • c8y_LWM2MDeviceBootstrapFailure.
• Registration event types:
  • c8y_LWM2MDeviceRegistration.
  • c8y_LWM2MDeviceDeRegistration.
  • c8y_LWM2MDeviceRegistrationUpdate.

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.

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 Handling LWM2M shell commands.

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.

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

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. Once the firmware update has been triggered, the LWM2M agent creates and queues up a PENDING firmware update operation for execution.

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:

(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 only PUSH delivery method is supported by the device, the state machine is reset by writing a byte array of a single element (value is 0) to the package resource: write /5/0/0 \0
• If both PUSH and PULL or only PULL delivery method is supported, the state machine is reset by writing a NULL string to the package URI resource: write /5/0/1 \0
• This mechanism can also be specified in the device managed object by using fragment: fwUpdateResetMechanism. When this is set, the delivery method is disregarded. Possible values: ** PACKAGE: This works the same as when only PUSH delivery method is supported, writing a byte array of a single element (value is 0) to the package resource: write /5/0/0 \0 ** PACKAGE_URI: The state machine is reset by writing an empty string ("") to the package URI resource: write /5/0/1 <empty string>

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:

• What the supported delivery methods are on the device specified by the value on resource /5/0/9, for example: 0 (PULL), 1 (PUSH) or 2 (BOTH). If both delivery methods are supported, PULL will be taken.
• What the supported delivery protocols are on the device, specified by the value on resource /5/0/8, for example: 0 (CoAP) or 1 (CoAPs). If this value is not specified by the device, 0 (CoAP) will be taken.
• What the current state of the firmware update is on the device. This value must be 0 (IDLE), otherwise the firmware update process is aborted immediately.

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

• fwUpdateDeliveryMethod. Possible values: PUSH, PULL, BOTH
• fwUpdateSupportedDeviceProtocol. Possible values: COAP, COAPS, HTTP, HTTPS

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:

• observe /5/0/3: Observe the firmware update state
• observe /5/0/5: Observe the firmware update result.

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.

• If the firmware update is successful on the device, the agent sets the firmware information to the device managed object and marks the firmware update operation as completed successfully.
• If the firmware update has failed on the device, the agent marks the firmware update operation as failed.

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.