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

Hardware platforms

PCA

Board name

Build target

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.

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 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 Coiote LwM2M servers. 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 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 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. 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.

    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 Pre-Shared Key

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.

Building and running

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

Building with overlay

To build with a Kconfig overlay, pass it to the build system using the OVERLAY_CONFIG CMake variable, as shown in the following example:

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

This command builds for the nRF9160 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.

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 nRF9160 DK.

  2. Open a terminal emulator and observe that the kit prints the following information:

    LWM2M Carrier library sample.

  3. 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_INIT
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_INIT
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
$
$ carrier_config server sec_tag 450
$
$ carrier_config

    3. Save the settings. Resetting the device will load them.

      $ Enable custom server settings  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_INIT
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:

It uses the following sdk-nrfxlib library:

In addition, it uses the following secure firmware component: