Sample description

The LwM2M Client sample demonstrates the usage of the Lightweight Machine to Machine (LwM2M) protocol to connect a Thingy:91 or an nRF91 Series 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

Board target

Thingy:91

PCA20035

thingy91

thingy91/nrf9160/ns

nRF9161 DK

PCA10153

nrf9161dk

nrf9161dk/nrf9161/ns

nRF9160 DK

PCA10090

nrf9160dk

nrf9160dk/nrf9160/ns

nRF9151 DK

PCA10171

nrf9151dk

nrf9151dk/nrf9151/ns

When built for a board target with the */ns variant, 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 AVSystem’s Coiote Device Management server. To know more about the AVSystem integration with nRF Connect SDK, see AVSystem integration.

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

nRF91 Series 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

Advanced Firmware Update

33629

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.

Optional configuration:

  • DTLS Connection Identifier, requires modem version 1.3.5 or newer.

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.

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 an nRF91 Series DK, where only simulated sensor data is available, as it does not have any of the external sensors needed for actual measurements.

Configuration

See Configuring and building an application for information about how to permanently or temporarily change the configuration. You can configure the sample either by editing the prj.conf file and the relevant overlay files, or through menuconfig or guiconfig.

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. To add the device to the LwM2M Server, complete the following steps:

    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)

  2. To register 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.

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.

See the Configuration files section for overlays that set the mentioned options.

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.

Avoiding re-writing credentials to modem

Every time the sample starts, it provisions the keys to the modem and this is only needed once. To speed up the start up, you can prevent the provisioning by completing the following steps using Visual Studio Code:

  1. In nRF Connect for VS Code extension, build the sample.

  2. Under Actions, click Kconfig.

  3. Click Application sample.

  4. Under LwM2M objects, remove the key value next to LwM2M pre-shared key for communication.

  5. Save and close the configuration.

The provisioning can also be prevented by setting the CONFIG_APP_LWM2M_PSK Kconfig option to an empty string in the prj.conf file. You can also edit this configuration using menuconfig. See Configuring and building an application for information about how to permanently or temporarily change the configuration.

For the changes to be added, rebuild the sample.

Configuration options

Check and configure the following configuration options for the sample:

Server options

CONFIG_APP_LWM2M_PSK - Configuration for the PSK

The sample configuration sets the hexadecimal representation of the PSK used when registering the device with the server. To prevent provisioning of the key to the modem, set this option to an empty string.

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.

CONFIG_SENSOR_MODULE_ACCEL - Configuration to enable accelerometer

This configuration option enables the accelerometer.

CONFIG_SENSOR_MODULE_PRESS - Configuration for pressure reading

This configuration option enables the reading of pressure values.

CONFIG_SENSOR_MODULE_HUMID - Configuration for humidity reading

This configuration option enables the reading of humidity values.

CONFIG_SENSOR_MODULE_GAS_RES - Configuration for gas resistance reading

This configuration option enables the reading of gas resistance values.

CONFIG_SENSOR_MODULE_LIGHT - Configuration for light reading

This configuration option enables the reading of light values.

CONFIG_SENSOR_MODULE_COLOR - Configuration for color

This configuration option enables the reading of color values.

Additional configuration

Check also the default configurations and any additional configurations of the sample listed in this section.

Default configuration

The sample use the following default configurations.

LwM2M configuration:

  • Protocol version: 1.0

  • Binding mode: Queue

  • Device Management server: Leshan Demo server

  • Security: Enabled with PSK, DTLS Connection Identifier, and DTLS session caching

  • Registration life time: 12 hours

  • Coap ACK initial timeout: 4 seconds

  • Enable LwM2M tickless mode power optimization

  • LwM2M shell

Modem configurations:

  • Network Mode: LTE-M with GNSS.

  • PSM: Enabled TAU 12 hours, RAT 30 seconds

  • Paging window: LTE 1.28 seconds and NB-IoT 2.56 seconds

  • eDRX: Enabled, with request of 5.12 seconds on LTE and 20.48 seconds on NB-IoT.

  • TAU pre-warning enabled, notification triggers registration update and TAU will be sent with the update which decreases power consumption.

Modem proprietary PSM

Add the overlay-aggressive-psm.conf overlay file to enable optimized PSM setup and proprietary PSM mode. This configuration disables eDRX, because it will request 10 seconds RAT and 12 hours TAU period. Proprietary PSM enables power saving when network does not allow PSM. The modem enters the PSM state after the configured RAT period when the connection is released.

Note

Proprietary PSM is only supported with modem firmware v2.x. Enabling this file for an older modem version generates the following error message:

<err> lte_lc: Failed to configure proprietary PSM, err -14

Configuration for external FOTA

The sample supports UART2 connection on the nRF9160 SiP to onboard an nRF52840 SiP with or without MCUboot recovery mode. The nRF9160 SiP needs to enable UART2 on the devicetree using the following configuration files and recovery mode overlay files:

  • overlay-mcumgr_client.conf - Defines the configuration for external FOTA client. This requires an additional devicetree overlay file nrf9160dk_mcumgr_client_uart2.overlay.

  • overlay-mcumgr_reset.conf - Enables MCUboot recovery mode. This requires an additional devicetree overlay file nrf9160dk_recovery.overlay.

To enable the experimental Advanced Firmware Update object for the external FOTA, use the following overlay configuration files:

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

  • overlay-lwm2m-1.1.conf - Enables the LwM2M version 1.1.

You also need one of the following Coiote Device Management server configurations:

  • overlay-avsystem.conf - For the Coiote Device Management server.

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

Sending traces over UART on an nRF91 Series DK

To send modem traces over UART on an nRF91 Series DK, configuration must be added for the UART device in the devicetree and Kconfig. This is done by adding the modem trace UART snippet when building and programming.

Use the Cellular Monitor app for capturing and analyzing modem traces.

TF-M logging must use the same UART as the application. For more details, see shared TF-M logging.

Various library options

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

Note

The nRF91 Series modem negotiates PSM and eDRX modes with the network it is trying to connect. The network can either accept the values, assign different values or reject them.

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.

  • prj.conf - Default configuration file.

LwM2M Device management server:

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

NB-IoT:

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

LwM2M v1.1:

  • overlay-lwm2m-1.1.conf - Enables LwM2M v1.1 protocol version.

Firmware update:

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

  • overlay-fota_helper.conf - Enables faster response for evaluating FOTA.

Location assistance:

  • overlay-assist-agnss.conf - Enables A-GNSS assistance.

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

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

Location service requires Coiote Device Management server and LwM2M v1.1.

Power savings:

  • overlay-aggressive-psm.conf - Enables optimized PSM setup and proprietary PSM mode.

  • overlay-lowpower.conf - Disables serial console to bring the power consumption down.

LwM2M v1.1 conformance testing:

  • overlay-lwm2m-1.1-core-interop.conf - Allows running of Core Specific Objects Test cases.

  • overlay-lwm2m-1.1-object-interop.conf - Allows running of Additional Objects Test cases.

Building and running

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

When built as firmware image for a board target with the */ns variant, 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, follow the instructions in Configuring and building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

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

The sample uses LwM2M queue mode by default. In this mode, the device need not actively listen for incoming packets and the client can reduce power consumption by being in the sleep state for longer duration.

Queue mode is suitable for LTE connection where devices are not continuously reachable from the network. Both network and the modem try to release any resources as soon as possible. In LTE, the Radio Resource Control (RRC) protocol sometimes causes the close of idle connections as early as 10 seconds of idle time. This depends on the network operator. Another network dependent feature is the NAT timeout. Some networks drop unused UDP mappings after 30 seconds even if the RFC recommendation is 2 minutes. Therefore, after a short sleeping period, the device would not be addressable from the network as the mapping would not exist. Hence, by default, after contacting the LwM2M Server, the device is configured to listen for 10 seconds after receiving the last packet. After that idle period, the device enables eDRX and PSM power saving modes if those are supported by the network. The device wakes up from sleep mode when it needs to send data.

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 Bootstrap Server for instructions.

To build the LwM2M Client with LwM2M bootstrap support, use the overlay-avsystem-bootstrap.conf or overlay-leshan-bootstrap.conf configuration overlay. For example:

west build -b board_target -- -DEXTRA_CONF_FILE=overlay-leshan-bootstrap.conf

Replace the board_target with the board target of the nRF91 Series device you are using (see the Requirements section).

In bootstrap mode, application does not overwrite the PSK key from the modem so CONFIG_APP_LWM2M_PSK is not used. Please refer to Preparing for production for instructions how to provision bootstrap keys.

MCUmgr client for external FOTA

Use one of the following build commands to evaluate external FOTA:

To build for MCUboot recovery mode with bootstrap, use the following command:

west build  --pristine -b nrf9160dk/nrf9160/ns --  -DEXTRA_CONF_FILE="overlay-adv-firmware.conf;overlay-fota_helper.conf;overlay-avsystem-bootstrap.conf;overlay-lwm2m-1.1.conf;overlay-mcumgr_client.conf; overlay-mcumgr_reset.conf" -DEXTRA_DTC_OVERLAY_FILE="nrf9160dk_mcumgr_client_uart2.overlay;nrf9160dk_recovery.overlay"

See Evaluating LwM2M Advanced Firmware Update for external MCU for details.

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, nRF Connect Serial Terminal). See Testing and optimization for the required settings and steps.

  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 nRF91 Series 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.

The client supports Push and Pull modes for image delivery. Recommend transport types are CoAP or HTTP for Pull mode. Coiote Device Management server also supports Multi component FOTA object, which allows updating multiple instances at the same time.

Use overlay-adv-firmware.conf overlay file to enable the experimental Advanced Firmware Update object. Advanced firmware requires Coiote Device Management server that supports it. Refer to Evaluating LwM2M Advanced Firmware Update for more details.

Note

You can use the overlay-fota_helper.conf configuration file to enable faster responses when using queue mode binding. This configuration uses an update period of 60 seconds.

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 updates for more information.

  2. Open Coiote Device Management server and click Firmware update.

  3. Click Update Firmware.

  4. Click Basic Firmware update.

  5. Click Upload Firmware.

  6. Select or upload the binary under Upload New or from Resources and click Save.

  7. Click Next.

  8. Set the image delivery mode, transport type, and timeout values. Coiote Device Management server recommends to use the Pull delivery mode because it is fail safe operation. Select the transport type (CoAP or HTTP) for the pull operation.

  9. Click Next to continue.

  10. Click Schedule Update after checking that the update process summary is correct.

  11. The firmware update starts at next registration update.

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: