Sample description

The LwM2M Client sample demonstrates the usage of the Lightweight Machine to Machine (LwM2M) protocol to connect a Thingy:91 or an nRF9160 DK to an LwM2M server through LTE. To achieve this, the sample uses the Zephyr’s Lightweight M2M (LWM2M) client and nRF Connect SDK LwM2M client utils library. The former provides a device vendor agnostic client implementation, whereas the latter includes all the Nordic specific bits and pieces.

The sample also supports a proprietary mechanism to fetch location assistance data from nRF Cloud by proxying it through the LwM2M server. For this, the sample makes use of the LwM2M location assistance library.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Build target
Thingy:91	PCA20035	thingy91_nrf9160	thingy91_nrf9160_ns
nRF9160 DK	PCA10090	nrf9160dk_nrf9160	nrf9160dk_nrf9160_ns

When built for an _ns build target, the sample is configured to compile and run as a non-secure application with Cortex-M Security Extensions enabled. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

Additionally, the sample requires an activated SIM card, and an LwM2M server such as Leshan Demo Server or Coiote Device Management server.

Overview

LwM2M is an application layer protocol based on CoAP over UDP. It is designed to expose various resources for reading, writing, and executing through an LwM2M server in a very lightweight environment. The client sends data such as button and switch states, accelerometer data, temperature, and GNSS position to the LwM2M server. It can also receive activation commands such as buzzer activation and light control.

Note

The GNSS module interferes with the LTE connection. If GNSS is not needed or if the device is in an area with poor connection, disable the GNSS module. You can disable the GNSS module by setting the configuration option CONFIG_APP_GNSS to n.

The sample implements the following LwM2M objects:

LwM2M objects

LwM2M objects	Object ID	Thingy:91	nRF9160 DK
LwM2M Server	1	Yes	Yes
Device	3	Yes	Yes
Connectivity Monitoring	4	Yes	Yes
FOTA	5	Yes	Yes
Location	6	Yes	Yes
Accelerometer	3313	Yes	Simulated
Color	3335	Yes	Simulated
Temperature	3303	Yes	Simulated
Pressure	3323	Yes	Simulated
Humidity	3304	Yes	Simulated
Generic Sensor	3300	Yes	Simulated
Light Control	3311	Yes	Yes
Push Button	3347	Yes	Yes
Buzzer	3338	Yes	No
On/Off Switch	3342	No	Yes
GNSS Assistance	33625	Yes	Yes
Ground Fix	33626	Yes	Yes
Visible Wi-Fi Access Point	33627	Yes	Yes

User interface

Button 1:

Triggers GNSS-based location service

Button 2:

Triggers cell-based location service

State diagram

The following diagram shows states and transitions for the LwM2M Client:

When the device boots up, the sample first connects to the LTE network and initiates the LwM2M connection. If there are errors, in most error cases, the sample tries to reconnect the LwM2M client. In the case of network errors, it tries to reconnect the LTE network. When the number of retries to restore the network connection exceeds three times, the sample falls back to the bootstrap. This enables the recovery in the cases where the LwM2M client credentials are outdated or removed from the server.

DTLS Support

The sample has DTLS security enabled by default. You need to provide the following information to the LwM2M server before you can make a successful connection:

• Client endpoint

• Identity

• Pre-Shared Key (PSK)

See server setup for instructions on providing the information to the server.

Sensor simulation

If a sensor simulator is defined in Devicetree with the sensor_sim node label, it will be used over real devices. This is useful, for example, on the nRF9160 DK, where only simulated sensor data is available, as it does not have any of the external sensors needed for actual measurements.

Notifications

LwM2M specifies the Notify operation, which can be used to notify the server of changes to the value of a resource field, for example, the measured value of a temperature sensor. This allows active monitoring while using minimal bandwidth, as notifications can be sent with the updated values without the need for the server querying the client regularly.

To enable notifications, the server must initiate an observation request on one or more resources of interest. For more information, see Enabling notifications.

Sensor Module

The sample has a sensor module which, if enabled, reads the selected sensors and updates the client’s LwM2M resource values. Each sensor can be enabled separately.

The sensor module is intended to be used together with notifications. If notifications are enabled for a Sensor Value resource and the corresponding sensor is enabled in the sensor module, a notification will be sent when the value changes. The frequency of notification packets is configured by LwM2M attributes set by the server.

See Sensor module options for information on enabling and configuring the sensor module.

Note

When you track several resources and enable sensor module for several sensors , socket errors such as net_lwm2m_engine: Poll reported a socket error, 08 and net_lwm2m_rd_client: RD Client socket error: 5 might occur.

Configuration

See Configuring your application for information about how to permanently or temporarily change the configuration.

Setup

Before building and running the sample, complete the following steps:

1. Select the device you plan to test.

2. Select the LwM2M server for testing.

3. Setup the LwM2M server by completing the steps listed in Server setup. This step retrieves the server address and the security tag that will be needed during the next steps.

4. Set the server address and PSK.

Server setup

The following instructions describe how to register your device to Leshan Demo Server or Coiote Device Management server:

1. For adding the device to the LwM2M server, complete the following steps and for adding the device to an LwM2M bootstrap server, see the procedure in registering the device to an LwM2M bootstrap server:

   Leshan Demo ServerCoiote Device Management

   1. Open the Leshan Demo Server web UI.

   2. Click on SECURITY in the upper right corner in the UI.

   3. Click on ADD SECURITY INFORMATION.

   4. Enter the following data and click ADD:

      • Endpoint - urn:imei:your Device IMEI

      • Security Mode - psk

      • Identity: - urn:imei:your Device IMEI

      • Key - your key (for example, 000102030405060708090a0b0c0d0e0f)

   For registering the device to an LwM2M bootstrap server, complete the following steps:

   Leshan Demo ServerCoiote Device Management

   1. Open the Leshan Bootstrap Server Demo web UI.

   2. Click on BOOTSTRAP in the top right corner.

   3. In the BOOTSTRAP tab, click on ADD CLIENTS CONFIGURATION.

   4. Click on Add clients configuration.

   5. Enter your Client Endpoint name - urn:imei:your device IMEI.

   6. Click NEXT and select Using (D)TLS and enter following data:

      • Identity - urn:imei:your device IMEI

      • Key - your key (for example, 000102030405060708090a0b0c0d0e0f)

   7. Click NEXT and leave default paths to be deleted.

   8. Click NEXT and in the LWM2M Server Configuration section, enter the following data:

      • Server URL - coaps://leshan.eclipseprojects.io:5684

      • Select Pre-shared Key as the Security Mode

      • Identity - urn:imei:your device IMEI

      • Key - your key (for example, 000102030405060708090a0b0c0d0e0f)

      This information is used when your client connects to the server. If you choose Pre-shared Key, you must add the values for Identity and Key fields (the configured Key need not match the Bootstrap Server configuration). The same credentials must be provided in the Leshan Demo Server Security configuration page (see DTLS Support for instructions).

   9. Click NEXT and do not select Add a Bootstrap Server.

   10. Click ADD.

Note

The Client Configuration page of the LwM2M Bootstrap server and the Registered Clients page of the LwM2M server display only a limited number of devices by default. You can increase the number of displayed devices from the drop-down menu associated with Rows per page. In both cases, the menu is displayed at the bottom-right corner of the Client Configuration pages.

Set the server address and PSK

1. Open src/prj.conf.

2. Set CONFIG_LWM2M_CLIENT_UTILS_SERVER to the correct server URL:

   • For Leshan Demo Server - coaps://leshan.eclipseprojects.io:5684 (public Leshan Demo Server).

   • For Coiote Device Management - coaps://eu.iot.avsystem.cloud:5684 (Coiote Device Management server).

   • For Leshan Bootstrap Demo Server - coaps://leshan.eclipseprojects.io:5784

   • For Coiote bootstrap server - coaps://eu.iot.avsystem.cloud:5694

3. Set CONFIG_LWM2M_RD_CLIENT_SUPPORT_BOOTSTRAP if bootstrap is used.

4. Set CONFIG_APP_LWM2M_PSK to the hexadecimal representation of the PSK used when registering the device with the server.

Enabling notifications

Enabling notifications for a resource varies slightly from server to server. The client must be connected to the server to enable notifications. Following are the instructions for enabling notifications in the Leshan Demo server and Coiote Device Management server:

Leshan Demo ServerCoiote Device Management server

1. Open the Leshan Demo Server web UI.

2. Identify your device in the Clients tab and select it.

3. Select the desired object in the menu on the left in the UI.

4. Identify one or more resources you want to track and click OBS next to it.

   • You can track either a single resource or all the resources of an object. It is recommended to track only the resources that are expected to change.

   • If you want to use the Sensor Module, at least the Sensor Value resource must be tracked for all sensors enabled in the Sensor Module.

Configuration options

Check and configure the following configuration options for the sample:

Server options

CONFIG_APP_LWM2M_PSK - Configuration for Pre-Shared Key

The sample configuration sets the hexadecimal representation of the PSK used when registering the device with the server.

CONFIG_APP_ENDPOINT_PREFIX - Configuration for setting prefix for endpoint name

This configuration option changes the prefix of the endpoint name.

LwM2M objects options

CONFIG_APP_TEMP_SENSOR - Configuration for enabling an LwM2M Temperature sensor object

The sample configuration enables an LwM2M Temperature sensor object. All compatible objects are enabled by default. Disabled objects will not be visible in the server. You can use this configuration option for other LwM2M objects also by modifying the option accordingly.

CONFIG_APP_GNSS - Configuration for enabling GNSS functionality

This configuration might interfere with LTE if the GNSS conditions are not optimal. Disable this option if GNSS is not needed.

CONFIG_GNSS_PRIORITY_ON_FIRST_FIX - Configuration for prioritizing GNSS over LTE during the search for first fix

Enabling this option makes it significantly easier for the GNSS module to find a position but will also affect performance for the rest of the application during the search for first fix.

CONFIG_LWM2M_IPSO_APP_COLOUR_SENSOR_VERSION_1_0 - Configuration for selecting the IPSO Color sensor object version

The configuration option sets the version of the OMA IPSO object specification to 1.0. The user-defined Color sensor IPSO object uses this version.

CONFIG_LWM2M_IPSO_APP_COLOUR_SENSOR_VERSION_1_1 - Configuration for selecting the IPSO Color sensor object version

The configuration option sets the version of the OMA IPSO object specification to 1.1. The user-defined Color sensor IPSO object uses this version.

CONFIG_APP_CUSTOM_VERSION - Configuration to set custom application version reported in the Device object

The configuration option allows to specify custom application version to be reported to the LwM2M server. The option has the current nRF Connect SDK version as the default value.

Sensor module options

CONFIG_SENSOR_MODULE - Configuration for periodic sensor reading

This configuration option enables periodic reading of sensors and updating the resource values when the change is sufficiently large. If you enable the option, the sample notifies the server if a change in one or more resources is observed.

CONFIG_SENSOR_MODULE_TEMP - Configuration to enable Temperature sensor

This configuration option enables the Temperature sensor in the Sensor Module.

Note

You can use the configuration options for different sensor types by modifying the configuration options accordingly.

Additional configuration

Check and configure the following LwM2M options that are used by the sample:

• CONFIG_LWM2M_PEER_PORT - LwM2M server port.

• CONFIG_LWM2M_ENGINE_MAX_OBSERVER - Maximum number of resources that can be tracked. You must increase this value if you want to observe more than 10 resources.

• CONFIG_LWM2M_ENGINE_MAX_MESSAGES - Maximum number of LwM2M message objects. You must increase this value if many notifications will be sent at once.

• CONFIG_LWM2M_ENGINE_MAX_PENDING - Maximum number of pending LwM2M message objects. You must increase this value if you want to observe more than 10 resources.

• CONFIG_LWM2M_ENGINE_MAX_REPLIES - Maximum number of LwM2M reply objects. You must increase this value if many notifications will be sent at once.

• CONFIG_LWM2M_COAP_BLOCK_SIZE - Increase if you need to add several new LwM2M objects to the sample, as the registration procedure contains information about all the LwM2M objects in one block.

• CONFIG_LWM2M_ENGINE_DEFAULT_LIFETIME - Set this option to configure how often the client sends I'm alive messages to the server.

• CONFIG_LWM2M_IPSO_TEMP_SENSOR_VERSION_1_0 - Sets the IPSO Temperature sensor object version to 1.0. You can use this configuration option for other IPSO objects also by modifying the option accordingly. See the LwM2M Object and Resource Registry for a list of objects and their available versions.

• CONFIG_LWM2M_IPSO_TEMP_SENSOR_VERSION_1_1 - Sets the IPSO Temperature sensor object version to 1.1. You can use this configuration option for other IPSO objects also by modifying the option accordingly. See the LwM2M Object and Resource Registry for a list of objects and their available versions.

• CONFIG_LWM2M_SHELL - Enables the Zephyr shell and all LwM2M specific commands.

Note

Changing lifetime might not work correctly if you set it to a value beyond 60 seconds. It might cause resending message error and eventually timeout. This is an issue specific for IPV4 when NAT is in use.

For Thingy:91, configure the ADXL362 accelerometer sensor range by choosing one of the following options (default value is ±2 g):

• CONFIG_ADXL362_ACCEL_RANGE_2G - Sensor range of ±2 g.

• CONFIG_ADXL362_ACCEL_RANGE_4G - Sensor range of ±4 g.

• CONFIG_ADXL362_ACCEL_RANGE_8G - Sensor range of ±8 g.

Resolution depends on range: ±2 g has higher resolution than ±4 g, which again has higher resolution than ±8 g.

If you use an external GNSS antenna, add the following configuration:

• CONFIG_MODEM_ANTENNA_GNSS_EXTERNAL - Selects an external GNSS antenna.

Location assistance options

Check and configure the following library options that are used by the sample:

• CONFIG_LWM2M_CLIENT_UTILS_GROUND_FIX_OBJ_SUPPORT - Uses Ground Fix Location object (ID 33626). Used with nRF Cloud to estimate the location of the device based on the cell neighborhood and Wi-Fi AP neighborhood.

• CONFIG_LWM2M_CLIENT_UTILS_GNSS_ASSIST_OBJ_SUPPORT - Uses GNSS Assistance object (ID 33625). Used with nRF Cloud to request assistance data for the GNSS module.

• CONFIG_LWM2M_CLIENT_UTILS_LOCATION_ASSIST_AGPS - nRF Cloud provides A-GPS assistance data and the GNSS-module in the device uses the data for obtaining a GNSS fix, which is reported back to the LwM2M server.

• CONFIG_LWM2M_CLIENT_UTILS_LOCATION_ASSIST_PGPS - nRF Cloud provides P-GPS predictions and the GNSS-module in the device uses the data for obtaining a GNSS fix, which is reported back to the LwM2M server.

• CONFIG_LWM2M_CLIENT_UTILS_NEIGHBOUR_CELL_LISTENER - Disable this option if you provide your own method of populating the LwM2M objects (ID 10256) containing the cell neighborhood information.

Configuration files

The sample provides predefined configuration files for typical use cases.

The following files are available:

• prj.conf - Standard default configuration file.

• overlay-queue.conf - Enables LwM2M Queue Mode support.

• overlay-leshan-bootstrap.conf - Enables LwM2M bootstrap support with Leshan demo server.

• overlay-avsystem.conf - Uses Coiote Device Management server.

• overlay-avsystem-bootstrap.conf - Uses Coiote in bootstrap mode.

• overlay-nbiot.conf - Enables the use of NB-IoT.

• overlay-assist-agps.conf - Enables A-GPS assistance.

• overlay-assist-cell.conf - Enables cell-based location assistance.

• overlay-assist-pgps.conf - Enables P-GPS assistance in the sample.

• overlay-lowpower.conf - Disables certain features to bring the power consumption down.

• overlay-adv-firmware.conf - Enables experimental Advanced Firmware Update object.

Moreover, the sample also provides the following files for LwM2M 1.1 features:

• overlay-lwm2m-1.1.conf - Enables v1.1 and running of Interoperability Test Cases [0-499].

• overlay-lwm2m-1.1-core-interop.conf - Enables v.1.1 and running of Core Specific Objects Test cases [500-999].

• overlay-lwm2m-1.1-object-interop.conf - Enables v.1.1 and running of Additional Objects Test cases [1000-1999].

For further information about the test cases, see Enabler Test Specification (Interoperability) for Lightweight M2M.

You can configure the sample either by editing the prj.conf file and the relevant overlay files, or through menuconfig or guiconfig.

Building and running

This sample can be found under samples/nrf9160/lwm2m_client in the nRF Connect SDK folder structure.

When built as firmware image for the _ns build target, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

After building and running the sample, you can locate your device in the server:

• Leshan - Devices are listed under Clients.

• Coiote - Devices are listed under Device inventory.

You can also optionally enable notifications for the resources so that the server actively monitors the resources.

Queue Mode support

To use the LwM2M Client with LwM2M Queue Mode support, build it with the -DOVERLAY_CONFIG=overlay-queue.conf option:

west build -b nrf9160dk_nrf9160_ns -- -DOVERLAY_CONFIG=overlay-queue.conf

Bootstrap support

To successfully run the bootstrap procedure, you must first register the device in the LwM2M bootstrap server.

See Registering your device to an LwM2M boot strap server for instructions.

To build the LwM2M Client with LwM2M bootstrap support, build it with the -DOVERLAY_CONFIG=overlay-bootstrap.conf option:

west build -b nrf9160dk_nrf9160_ns -- -DOVERLAY_CONFIG=overlay-bootstrap.conf

See Providing CMake options for instructions on how to add this option. Keep in mind that the used bootstrap port is set in the aforementioned configuration file.

Testing

After programming the sample to your development kit, complete the following steps to test it:

1. Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.

2. Connect to the kit with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.

3. Observe that the sample starts in the terminal window.

4. Check that the device is connected to the chosen LwM2M server.

5. Press Button 1 on nRF9160 DK or SW3 on Thingy:91 and confirm that the button event appears in the terminal.

6. Check that the button press event has been registered on the LwM2M server by confirming that the press count has been updated.

7. Retrieve sensor data from various sensors and check if values are reasonable.

8. Test GNSS module:

   1. Ensure that CONFIG_GNSS_PRIORITY_ON_FIRST_FIX is enabled.

   2. Ensure that you are in a location with good GNSS signal, preferably outside.

   3. Wait for the GNSS to receive a fix, which will be displayed in the terminal. It might take several minutes for the first fix.

9. Try to enable or disable some sensors in menuconfig and check if the sensors appear or disappear correspondingly in the LwM2M server.

Testing with the LwM2M shell

To test the sample using LwM2M shell, complete the following steps:

Note

To enable any LwM2M v1.1 specific commands (for example, LwM2M SEND), choose any of the v1.1 overlay files.

1. Open a terminal emulator and observe that the development kit produces an output similar to the above section.

2. Verify that the shell inputs are working correctly by running few commands. You can, for example, run commands to trigger a registration update, pause and start the client.

   1. Registration update:

      uart:~$ lwm2m update
      

   2. Pause the client:

      uart:~$ lwm2m pause
      

   3. Resume the client:

      uart:~$ lwm2m resume
      

Firmware Over-the-Air (FOTA)

You can update the firmware of the device if you are using Coiote Device Management server or Leshan server. Application firmware updates and modem firmware (both full and delta) updates are supported.

To update the firmware, complete the following steps:

1. Identify the firmware image file to be uploaded to the device. See LTE modem and FOTA upgrades for more information.

2. Open Coiote Device Management server and click LwM2M firmware.

3. Click Schedule new firmware upgrade.

4. Click Upload file in the bottom left corner and upload the firmware image file.

5. Configure the necessary firmware update settings in the menu to the right.

6. Click Upgrade.

7. Observe in the terminal window that the image file is being downloaded. The download will take some time. If you do not increase the server lifetime, the Coiote server might drop the connection to the device. The device reconnects later.

8. When the download is complete, the device restarts on its own after installing the firmware. Restart the device manually if it has not started automatically. The device runs the updated firmware and reconnects to Coiote Device Management server automatically.

Dependencies

This sample application uses the following nRF Connect SDK libraries and drivers:

• LwM2M client utils

• LwM2M location assistance

• Modem information

• AT command parser

• DK Buttons and LEDs

• LTE link controller

• Date-Time

• DFU target

• Full modem firmware update from flash device

• FOTA download

• Download client

It uses the following sdk-nrfxlib library:

• Modem library

It uses the following Zephyr libraries:

• GPIO

• Lightweight M2M (LWM2M)

• PWM

• Sensors

In addition, it uses the following secure firmware component:

• Trusted Firmware-M