LWM2M

Overview

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

Important: Cumulocity IoT currently supports LWM2M 1.0.

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

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

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.

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:

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

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

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

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.

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

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:

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

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

The table below lists the information of the additional fields:

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.

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.

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.

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.
   
   

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.
   
   

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

The device protocol will open in a new page.

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

Adding additional functionalities to a resource

The functionalities that you may enable are the following:

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 - one of CRITICAL, MAJOR, MINOR, WARNING.
• Type.
• Status - one of 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.

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 Device (/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 (/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.

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

Alarms on device protocol mapping failures

There are 2 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

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.

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:

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

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

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

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

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.

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

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

Audit Configuration

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

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

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.

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:

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

Info: A shell command can also be used to send multiple operations to a LWM2M device at once. To do that, simply enter all instructions with a line break between them. Make sure that the shell command does not carry any leading or trailing white spaces. The LWM2M agent then uses the line break to split a multi-line operation into separate LWM2M shell operations.

Adding validation rules to resources

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

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

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.

Validation rules can have the following types:

• Date: Simply enter a date and choose 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 chosen:

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

Info: Not all rules are available to each type.

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

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 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 like this:

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:

(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), 1 (CoAPs), etc. 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 chosen 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 chosen delivery protocol.

When PUSH is chosen 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, e.g. because the device runs out of storage, or network issues, etc.) 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, etc. 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.