Getting started with LwM2M
Introduction
Cumulocity IoT offers multiple different options to integrate devices allowing to cope with heterogeneous device fleets accommodating changing requirements as IoT projects scale and evolve.
There are different IoT use-cases like metering and asset tracking that require the deployment of dispersed and energy-constrained devices running on batteries in cellular and sensor networks. For such cases LwM2M stands out particularly, as it is very efficient regarding both power consumption as well as data usage. It thereby also recognizes that the average size of the data plan for some IoT devices is limited. Its lightweight design, however, does not change the fact that the protocol still works very efficiently on bigger IoT assets such as business routers or gateways.
Furthermore, it defines an extensible resource and data model, that can be extended and is able to support applications for various kinds of industries. Its service and device management enablement capabilities include for example sensor and meter readings, remote actuation as well as troubleshooting and performing remote firmware updates.
If you are interested to explore how LwM2M devices interact with Cumulocity, you can quickly start by using the LwM2M demo client. We will now go through the different steps required to get it up and running.
The LwM2M demo implementation is based on the eclipse Leshan client . The leshan client demo sends temperature values and supports location tracking and device controls.
Prerequisites
To follow this guide, you only need the following:
Steps to follow
1. Getting Started
In the context of LwM2M, bootstrap servers are used to provision the LwM2M client with the information required to contact the LwM2M servers. It is therefore necessary to prepare the registration and docker-compose file for the bootstrap server configuration:
registration.csv
In the registration.csv file, the fields for endpoint ID and LwM2M server URI must be checked. The endpoint ID is required by the bootstrap process in order to provision the LwM2M client with the bootstrap information. Make sure that the endpoint ID is unique and hasn’t been used before to register a device. Otherwise this will result in an error. Additionally, the LwM2M server URI needs to contain the right hosting environment that you or rather your company is using. This should be one of the following public cloud instances:
coap://lwm2m.eu-latest.cumulocity.com:5783
The bootstrap ports are “5683” for unsecure bootstrap connections which we are using for this demo 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.
Your individual tenant prefix is not required since there is only one LwM2M server for each public cloud instance. Please note that this registration file is only applicable for the dedicated LwM2M bulk registration process that has been introduced with version 10.15. If you are still using an older version of Cumulocity IoT, use the template for the general bulk registration you can find in the documentation.
docker-compose.yaml
Edit the docker-compose.yaml and change the endpoint ID and URI in the environment variables for all containers so that they match the entries in the registration file.
version: "4.3"
services:
lwm2m_client_1:
build:
context: leshan-demo-client
args:
ENDPOINT: "lwm2m_device01"
URI: "lwm2m.eu-latest.cumulocity.com"
...
2. Upload device protocols to Cumulocity IoT
LwM2M’s advantage is not only it’s resource efficiency but also that it provides a predefined and extensible data model. Each piece of information made available by the LwM2M Client is represented as a resource with multiple resources being logically organized into objects. There are multiple predefined objects available e.g. for updating firmware or reporting the state of an analog input. The data model can also be extended by defining additional objects to meet specific needs.
This demo client uses the following LWM2M objects:
3 (device)
6 (location),
3303 (temperature sensor)
3441 (lwm2m test object)
Cumulocity allows any LwM2M objects to be easily interfaced with the platform and supports out-of-the-box integration for the standard LwM2M objects 3(device), 4(connectivity), 5(firmware) and 6(location).
In order to make use of the objects, a protocol definition for each object is required. You can find the protocol definitions as xml files in the resource folder. These need to be uploaded to your Cumulocity IoT tenant in the Device Management → Device types → Device protocols tab.
The demo client sends a random temperature measurement at 3303/5700 (object/resource). To activate the functionality, open the LwM2M Device Protocol with the name “3303 Temperature” and turn on Send measurement for the Sensor Value. Do also enable on Auto observe for at least one functionality per protocol. This will instruct the LwM2M device to periodically report data to Cumulocity IoT.
The LwM2M objects 3 (device) and 6 (location) are supported out-of-the-box and do not need a mapping configuration.
3. Define LwM2M post-registration actions
LwM2M shell commands can be performed in the Shell tab of each device. In addition to this, there is an option to define tenant wide post-operations. Each LwM2M device will execute these after sending a full registration request.
In this example the LwM2M post operations will be used the read the current device info (3) and location (6) from the device, if the devices sends a registration request. To do this go to the tab Device Management → Device types → LwM2M post-operations and add the following:
read /3
read /6
4. Device Registration
To register the LwM2M devices in Cumulocity IoT, upload the CSV file that you prepared in step 1 in the LwM2M bulk registration dialog in Device Management → Devices → Registration → Register device → LWM2M (Bulk Registration) .
After the registration process was successful, the new LwM2M demo devices will be shown in the all device list in Device Management → Devices → All devices. The devices won’t show any incoming measurement values yet. First the demo client needs to be started. Do so by opening the folder in the Terminal and run the following command:
docker-compose up
Further information on how to read and send events, alarms or custom actions from LWM2M devices or how to write to LWM2M objects can be found in the Cumulocity IoT documentation.