Sample description

The LwM2M carrier sample demonstrates how to run the LwM2M carrier library in an application in order to connect to the operator LwM2M device management.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Board target

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.

Overview

LwM2M is an application layer protocol for IoT device management and service enablement. It is designed to expose various resources for reading, writing, and executing through an LwM2M Server in a lightweight environment.

The LwM2M carrier library is needed for certification in certain operator networks. The LwM2M carrier sample shows how to integrate the LwM2M carrier library. This sample is primarily meant to be run in the applicable networks where the certification applies. It will automatically connect to the correct device management servers, depending on which network operator is detected.

Some of the configurations of the library must be changed according to your specific operator requirements. For example, at some point during certification, you might have to connect to one or more of an operator’s test (certification) servers, by overwriting the library’s automatic URI and PSK selection. When CONFIG_LWM2M_CARRIER_CUSTOM_URI is empty, the library connects to live (production) servers.

The sections below explain how you can configure the library in different ways to connect to Leshan and AVSystem’s Coiote LwM2M Servers. To know more about the AVSystem integration with nRF Connect SDK, see AVSystem integration. Configuring your application to connect to other servers (such as your operator’s test servers) might look different, depending on the operator’s device management framework.

Configuration

See Configuring and building 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 that 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.

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

    10. Click ADD.

Set the server address and PSK

  1. Open prj.conf (see Configuration files for more information).

  2. Set CONFIG_LWM2M_CARRIER_CUSTOM_URI to the correct server URL:

  3. Set CONFIG_LWM2M_CARRIER_IS_BOOTSTRAP_SERVER if bootstrap is used. If bootstrap is not used, set CONFIG_LWM2M_CARRIER_SERVER_LIFETIME to specify the lifetime of the LwM2M Server.

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

  5. Specify a CONFIG_LWM2M_CARRIER_SERVER_SEC_TAG to store the PSK. Alternatively, you could only specify a security tag if a PSK is previously stored to the security tag as shown in LwM2M Client provisioning documentation.

Configuration options

Check and configure the following configuration options for the sample:

Server options

CONFIG_CARRIER_APP_PSK - Configuration for a pre-shared key (PSK)

The sample configuration is used to set the hexadecimal representation of the PSK used when registering the device with the server. The PSK is stored in the security tag specified in CONFIG_LWM2M_CARRIER_SERVER_SEC_TAG.

Configuration files

The sample provides predefined configuration files for typical use cases.

The following files are available:

The sample can either be configured by editing the prj.conf file and the relevant overlay files, or through menuconfig or guiconfig.

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.

Building and running

This sample can be found under samples/cellular/lwm2m_carrier 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 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.

Building with overlay

To build with a Kconfig overlay, set EXTRA_CONF_FILE to the overlay-shell.conf file using the respective CMake option, as shown in the following example:

west build -b board_target -- -DEXTRA_CONF_FILE=overlay-shell.conf

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

This command builds for your nRF91 Series DK using the configurations found in the overlay-shell.conf file, in addition to the configurations found in the prj.conf file. If some options are defined in both files, the options set in the overlay take precedence.

For more information about configuration files in the nRF Connect SDK, see Build and configuration system.

Testing

After programming the sample and all prerequisites to the development kit, test it by performing the following steps:

  1. Connect the USB cable and power on or reset your nRF91 Series DK.

  2. Use a terminal emulator, like nRF Connect Serial Terminal, to connect to the serial port. See Testing and optimization for the required settings and steps.

  3. Observe that the kit prints the following information:

    LWM2M Carrier library sample.

  4. Observe that the application receives events from the LwM2M carrier library using the registered event handler. If the client and server configuration is correct, the initial output looks similar to the following output:

    LWM2M_CARRIER_EVENT_LTE_LINK_DOWN
LWM2M_CARRIER_EVENT_LTE_LINK_UP
LWM2M_CARRIER_EVENT_LTE_LINK_DOWN
LWM2M_CARRIER_EVENT_BOOTSTRAPPED
LWM2M_CARRIER_EVENT_LTE_LINK_UP
LWM2M_CARRIER_EVENT_REGISTERED

Once bootstrap has been done, subsequent reconnects will not contain the bootstrap sequence. The output looks similar to the following output:

LWM2M Carrier library sample.
LWM2M_CARRIER_EVENT_REGISTERED

The device is now registered to an LwM2M Server, and the server can interact with it. If you used your own custom server as described in Server setup, you can try reading and observing the available resources.

If you connected to the carrier (test) servers or live (production) servers, reach out to your mobile network operator to learn about how to proceed with certification tests or normal operation, respectively.

Testing with the LwM2M shell

See LwM2M carrier shell configuration for more information about the LwM2M carrier shell and shell commands. To test with the sample, complete the following steps:

  1. Make sure the sample was built with the shell overlay as described in Building with overlay.

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

  3. Verify that the shell inputs are working correctly by running few commands. Example commands can be to set the Server URI and PSK to match the description in Server setup.

    1. Store a PSK:

      $ at AT+CFUN=4
OK
$ at AT%CMNG=0,450,3,\"000102030405060708090a0b0c0d0e0f\"
OK
$ at AT+CFUN=1
OK

    2. Set the URI and security tag (containing the PSK that was stored):

      $ carrier_config server uri coaps://leshan.eclipseprojects.io:5784
Set server URI: coaps://leshan.eclipseprojects.io:5784
$ carrier_config server sec_tag 450
Set security tag: 450

    3. Apply the server config. After rebooting, the sample loads these settings (instead of using the static Kconfig options).

      $ carrier_config server enable
Enabled custom server config

    4. Finally, as described in ref:lwm2m_carrier_shell, set auto_startup (or else the sample will wait indefinitely for you to configure all the settings).

      $ carrier_config auto_startup y
Set auto startup: Yes

    Once the device is registered to a device management server, you can experiment by setting some of the resources. For example, you can set the Location object (/6) resources for Latitude (/6/0/0) and Longitude (/6/0/1):

    $ carrier_api location position 63.43049 10.39506

Troubleshooting

Bootstrapping can take several minutes. This is expected and dependent on the availability of the LTE link. During bootstrap, the application will receive the LWM2M_CARRIER_EVENT_LTE_LINK_UP and LWM2M_CARRIER_EVENT_LTE_LINK_DOWN events. This is expected and is part of the bootstrapping procedure.

You might encounter deferred events, as shown in the following output:

LWM2M Carrier library sample.
LWM2M_CARRIER_EVENT_LTE_LINK_DOWN
LWM2M_CARRIER_EVENT_LTE_LINK_UP
LWM2M_CARRIER_EVENT_DEFERRED
Reason: Failed to connect to bootstrap server, timeout: 60 seconds
LWM2M_CARRIER_EVENT_DEFERRED
...

There are many scenarios which can lead to a deferred event. Following are some of the common scenarios:

  • A mismatch in the provisioning of the device (wrong PSK).

  • A DTLS session is already in use.

  • Temporary networking issues when connecting to the bootstrap or device management servers.

For more information, see the LwM2M carrier library events and Message sequence charts sections in the LwM2M carrier library documentation.

To completely restart and trigger a new bootstrap, the device must be erased and re-programmed, as mentioned in Application integration.

Dependencies

This sample uses the following nRF Connect SDK libraries:

  • nRF Connect SDK modules abstracted by the LwM2M carrier OS abstraction layer (lwm2m_os.h)

    The inclusion of the UICC LwM2M library is optional and is added using the CONFIG_UICC_LWM2M Kconfig option. This module allows the LwM2M carrier library to use the bootstrap information stored on the SIM card. If present, the configuration in the SIM will take precedence over any other configuration. For example, if a bootstrap server URI is fetched from the SIM, the configuration set by the CONFIG_LWM2M_CARRIER_CUSTOM_URI Kconfig option is ignored.

It uses the following sdk-nrfxlib library:

In addition, it uses the following secure firmware component: