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.1 over CoAP and UDP.
Info

Cumulocity IoT LWM2M 1.1 introduces a composite operation and a client-side “send” operation. If a sensor or a number of sensors want to send measurements to the server, they can use the “send” operation to send single or composite measurement data. The LWM2M 1.1 “send” operation makes this simple on protocol level. Cumulocity IoT also allows a timestamp-based operation. If a sensor reports a timestamp resource object in parallel with its data from the same object, the timestamp will be used.

Cumulocity IoT LWM2M 1.1 is backward compatible. What has worked on Cumulocity IoT LWM2M 1.0 will also work on Cumulocity IoT LWM2M 1.1. However, Cumulocity IoT LWM2M 1.1 introduces some new features which are not compatible with LWM2M 1.0 devices. If you try to run some of these features with LWM2M 1.0 devices, you may receive an error message response.

You can connect any device supporting LWM2M 1.1 or LWM2M 1.0 to Cumulocity IoT without programming. Cumulocity IoT expects 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.

Requirements
In order to use LWM2M, you must be subscribed to the LWM2M-agent application. If the LWM2M-agent is not available in your tenant, contact product support.
Info
The LWM2M agent supports DTLS Connection ID. Contact your platform administrator if you use LWM2M devices that support connection IDs and if you are unsure if this feature is enabled.

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

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

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

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 three steps:

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 Required settings, Bootstrap settings and Advanced settings below for details about the fields.

Info
The maximum size allowed for the CSV file is 10 MB.

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 registration settings

Required settings

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

Field CSV field name Type Description Mandatory
Endpoint client ID 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. Registering a device using an endpoint ID already used will result in an error. Mandatory
Security mode 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. If PSK is selected, devices need to connect to the LWM2M server using DTLS with the given pre-shared key (PSK). With "PSK", the client and server have a common secret symmetric cryptography. Currently Cumulocity IoT supports only "NO_SEC" and "PSK". Mandatory
LWM2M PSK ID lwm2m psk_id String The ID used by the device for server connections in PSK mode. The LWM2M PSK ID has be to be unique across all tenants. Registering a device using an LWM2M PSK ID already used will result in an error. Mandatory for PSK. Don't set it for NO_SEC
LWM2M PSK key lwm2m psk_key String The hex-encoded pre-shared key used by the device for server connections in PSK mode. Mandatory for PSK. Don't set it for NO_SEC
Bootstrap PSK ID bootstrap psk_id String The ID used by the device for bootstrap connections in PSK mode. The bootstrap PSK ID has be to be unique across all tenants. Registering a device using an bootstrap PSK ID already used will result in an error. Mandatory for PSK
Bootstrap PSK key bootstrap psk_key String The hex-encoded key used by the device for bootstrap connections in PSK mode. Mandatory for PSK

Bootstrap settings

Registration of NO_SEC devices

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

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. The file must contain the fields defined in Required settings. PSK registration requires additional fields to be filled.

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

Field CSV field name Type Description Mandatory
LWM2M server URI lwm2m server uri String The URI the server uses for bootstrap. The LWM2M bootstrap server is used to provision the LWM2M client with the information required to contact the LWM2M servers. If you use 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. Mandatory for LWM2M bootstrap
Generate bootstrap server config 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
LWM2M bootstrap short server ID bootstrapShortServerId Integer The short server ID to be used for the bootstrap server. Default is "0". Optional
Registration lifetime 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
Default minimum period defaultMinimumPeriod Integer The default minimum period to configure during bootstrap. See the LWM2M specification for explanation. Optional
Default maximum period defaultMaximumPeriod Integer The default max period to configure during bootstrap. See LWM2M specification for explanation. Optional
Info
After creation, you can view and change the bootstrap parameters in the LWM2M bootstrap parameters tab in the Device details page, see LWM2M bootstrap parameters.

Advanced settings

See the table below for information on additional fields:

Field CSV field name Type Description Mandatory
LWM2M device type type String Type to set for the device managed object on creation. Default is "c8y_lwm2m". Optional
Server public key serverPublicKey String The public key of the server. Optional
LWM2M short server ID lwm2mShortServerId Integer The short server ID to be used for LWM2M server. Default is "1". Optional
Security instance offset 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
Binding mode bindingMode String The LWM2M binding mode to be reported to the device. For LWM2M 1.0 devices the supported modes are "UQ" (default, queuing) and "U" (unqueued). Note that since Cumulocity IoT LWM2M 1.1, the "Q" (queue) mode is not supported, and the default mode will be "U" (unqueued). Cumulocity IoT will always queue operations, regardless of whether the device is connected or not. This means that the setting has no effect on the behavior of Cumulocity IoT. Optional
Awake time registration parameter 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
Notification storing when disabled or offline / notificationIfDisabled notificationIfDisabled Boolean See the LWM2M specification. Allowed values are true or false. Default: Not configured. Optional, defaults to Leshan default behavior
Disable timeout disableTimeout Boolean See the LWM2M specification. Allowed values are true or false. Default: Not configured. Optional, defaults to Leshan default behavior
LWM2M request timeout 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 the "C8Y.lwm2mRequestTimeout" property. The value must not exceed the maximum request timeout limit given in the LWM2M microservice property file with the "C8Y.lwm2mMaxRequestTimeout" property. Optional
Binary delivery encoding binaryDeliveryEncoding String Indicates the encoding format for writing binaries to a LWM2M device. The encoding format can be OPAQUE, TLV, JSON or TEXT. In case of empty or invalid entries, the default format is OPAQUE. Optional
Use common timestamp resources 5518 and 6050 or object specific timestamp for object 6 reported by the device if available enableResourceLevelTimestamp Boolean If this device property is enabled Cumulocity IoT uses time stamps reported by the device for constructing measurements, events and alarms. This is possible if the device reports multiple resources at the same time. For example, this may be done using observes on entire object instances or composite reads and observes. Time stamp data needs to be reported as part of the same object: Either via the common timestamp resources 5518 and 6050 or the specific timestamp resource for object 6. If this feature is disabled or no timestamp information is reported, Cumulocity IoT will use its local date and time. Default: false Optional, defaults to false
Keep old values in the objects tab if an operation fails c8y_GenericUI_retainOldValuesIfError Boolean Controls if stale values are kept in the Objects tab. If this flag is set to true (default) the agent never removes a value. If set to false the agent will remove values in two cases:
  1. A failed read or write operation will lead to removal if the device answers with one of the following CoAP response codes: 4.01 (Unauthorized), 4.03 (Forbidden), 4.04 (Not found), 5.00 (Internal Server Error) and 5.01 (not implemented).
  2. Resources not contained in a discover response will be removed. This allows a discover operation to be used for purging resources that do not exist on the device any longer.
Optional

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.

Field CSV field name Type Description Mandatory
Firmware update delivery method fwUpdateDeliveryMethod String Explains the firmware update delivery method. Allowed values are PUSH, PULL or BOTH. Optional
Firmware update supported device protocol fwUpdateSupportedDeviceProtocol String Indicates the device protocol to be used for the firmware update. Allowed values are COAP, COAPS, HTTP or HTTPS. Optional
Firmware update reset mechanism fwUpdateResetMechanism String Indicates the mechanism used to reset the firmware update state machine. Allowed values are PACKAGE or PACKAGE_URI. Depending on the value, 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 where a reset is done via package resource for PUSH and via package URI for PULL. Optional
Firmware update URL fwUpdateURL String Indicates the firmware update URL from where the LWM2M device can download the firmware package. Optional
Info
Firmware updates are also supported for the 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.

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. In order to remove the device, besides deleting the device from the list in Device Management > All Devices in the User Guide, a connector operation also needs to be executed to remove tenant route information from the cluster tenant. See cleanup cluster tenant objects for endpoint for more information.

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.

LWM2M connector bulk device registration result

Caution
We recommend you to never delete the connector 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:

Cleanup cluster tenant objects for endpoint

Info
Endpoint refers to the endpoint client ID listed under Registering LWM2M devices > Mandatory settings.

During LWM2M device registration the tenant route information is stored in the cluster tenant. If the LWM2M device is only deleted from the tenant, the tenant route information will not be deleted automatically. This operation can be used for triggering the cleanup of the managed objects in the cluster tenant associated with the device with the endpoint and has to be executed from the tenant that owned the device with the endpoint.

Additionally, the operation can be executed regardless of the existence of the device in the tenant. Therefore, it is also possible to use it to remove the link between the device and the tenant but still keep the device’s history.

Example usage: cleanupClusterTenantObjectsForEndpoint urn:imei:012345678901234

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 Device Management > Managing device types in the User guide.

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.

Protocol example

Info
LWM2M protocol resources cannot be edited.

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.

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.

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.

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

Actions that are relevant for connectivity monitoring (object ID /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 action example

Auto observe

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

Auto-observe example

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

Alarms on device protocol mapping failures

There are two types of alarms raised related to device protocol 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 after clicking the menu icon ( ⋮ ) at the end of each object row:

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. 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 tooltip icon (Tooltip 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.

Operations view

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.

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.

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.
executeparameters The execute parameters have to conform to arglist ANBF syntax as described in the OMA Lightweight M2M specification (Section 6.3.5).
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.
requestJson The raw CoAP request can be specified using the following JSON syntax.
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.

Command Supported version Description
read /<objectID>/<instanceID>/<resourceID> 1.0, 1.1 Reads a resource path.
cread /<objectID>/<instanceID>/<resourceID> [/<objectID>/<instanceID>/<resourceID>] 1.1 Composite reads of one or more resource paths. The resource data from all listed resource paths will be read in a single client response.
observe /<objectID>/<instanceID>/<resourceID> 1.0, 1.1 Enables the observe functionality.
cobserve /<objectID>/<instanceID>/<resourceID> [/<objectID>/<instanceID>/<resourceID>] 1.1 Enables composite observe functionality for one or more resource paths. The resource data from all listed resource paths will be sent to the Cumulocity IoT's LWM2M agent in a single client request.
execute /<objectID>/<instanceID>/<resourceID> [<executeparameters>] 1.0, 1.1 Executes a resource on the device with optional parameters.
executelegacy /<objectID>/<instanceID>/<resourceID> [<STRING>] 1.0, 1.1 Executes a resource on the device and sends the parameters as TEXT/PLAIN string. This was the behavior of the execute command in Cumulocity IoT until version 10.15. In contrast to the regular execute command, executelegacy allows execute parameters not in line with the Lightweight M2M standard to be sent to the device.
write /<objectID>/<instanceID>/<resourceID> <value> 1.0, 1.1 Writes value to a resource on the device.
cwrite /<objectID>/<instanceID>/<resourceID> <value> [/<objectID>/<instanceID>/<resourceID> <value>] 1.1 Composite writes of one or more values to a resource on the device. The data will be written to the listed resource paths in a single request
writeb /<objectID>/<instanceID>/<resourceID> <hexadecimal-string>
OR
writeb /<objectID>/<instanceID>/<resourceID> binary:<binary-file-id>
1.0,1.1 Writes binary data represented as a hex string to a resource on the device. The representation must be an even number of characters. For example: writeb /3442/0/150 010A0B020F.

Writes binary data to a resource on the device from a file uploaded to the Cumulocity IoT platform. The 'binary-file-id' is the object ID that has already been uploaded to the Cumulocity IoT platform. Adding the prefix 'binary:' lets the agent read the file's data and write it to the device. For example: writeb /3442/0/150 binary:12345.
cancelobservation /<objectID>/<instanceID>/<resourceID> [/<objectID>/<instanceID>/<resourceID>] 1.0, 1.1 Cancels either a single or a composite observation functionality from the desired resource. To cancel a composite observation the same list of paths must be mentioned as the composite observation was created. The list of paths is not required to be in the same order as the composite observation that was created.
delete /<objectID>/<instanceID>[/<resourceID>] 1.0, 1.1 Deletes a given object/instance/resource.
discover /<objectID>/<instanceID>/<resourceID> 1.0, 1.1 Shows all resources of the given object.
create /<objectID> [JSON] 1.0, 1.1 Creates a new object. The JSON argument is optional.
writeattr /<objectID>/<instanceID>/<resourceID> pmin=<sec>&pmax=<sec>&gt=<num>&lt=<num>&st=<num>&cancel 1.0, 1.1 Writes additional attributes to the object. Typically used for conditional observes.
fwupdate <Firmware name>;<firmware version>;<firmware_url> 1.0, 1.1 Updates the firmware of the agent.
serialization <SER> 1.0, 1.1 Sets the data format.
coap <requestJson> 1.0, 1.1 Allows a raw CoAP request to be sent to a LWM2M device. The command takes a request JSON string as a single argument.

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

The CoAP response data is populated into the operation response. Note that Cumulocity IoT does not further process CoAP responses. We also recommend you to use raw CoAP requests for device interactions only in exceptional cases. Any interaction with an LWM2M device should be carried out using standard LWM2M operations.
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.

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.
Info
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. This is described in the LWM2M agent installation & operations guide, see also Additional resources > Installation and operations documentation. Contact your Operations team for further details.

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

Add a new validation rule by clicking on the desired resource and then click 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, click on the red delete 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:

Validation rules example

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

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.

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.