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:

LwM2M client state diagram

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:

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 resource values if it detects a sufficiently large change in one of the values. The threshold for a sufficiently large change can be configured. For example, a change in temperature of one degree Celsius.

Each sensor can be enabled separately. The sampling period and change threshold of a sensor can also be configured independently of all the other sensors.

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 only when that value changes significantly (as specified by the change threshold). Thus, the bandwidth usage can be significantly limited, while simultaneously registering important changes in sensor values.

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:

    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:

    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:

  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:

  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:

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

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:

Location assistance options

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

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 carrier shell configuration, 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:

It uses the following sdk-nrfxlib library:

It uses the following Zephyr libraries:

In addition, it uses the following secure firmware component: