LightweightM2M

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.

Info: You can connect any device supporting LWM2M 1.0 to Cumulocity IoT without programming. We expect the device and its capabilities (e.g. 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:

To make use of 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.

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. For example, the ID could be an IMEI, serial number, etc. The ID field has to 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.
c8y_GenericUi In order to enable the Objects tab for LWM2M devices, the value of this field has to be set to "{}".
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 Toggles if Cumulocity IoT generates a server config for the LWM2M bootstrap server and writes that back during bootstrap. Default is false. Optional
securityInstanceOffset Integer The first instance to be used during bootstrap to which entries are written. Default is "0". If set e.g. 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. 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 need to 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. The 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. Optional

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

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

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 have to 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, click Execute.

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

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 (e.g. “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.
Firmware version The current version of the firmware.
Firmware url The URL from which the new version of the firmware will be downloaded.

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> Executes a resource on the device.
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.

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 chosen:

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.