Application integration

This section describes the needed interaction between the LwM2M carrier library and the user application.

Interaction between the LwM2M carrier library and the user application

Interaction between the LwM2M carrier library and the user application

The LwM2M carrier library has an OS abstraction layer. This abstraction layer makes the LwM2M carrier library independent of the nRF Connect SDK modules and underlying implementation of primitives such as timers, non-volatile storage, and heap allocation. For more information, see the lwm2m_os.h file or the OS abstraction layer section for available APIs.

LwM2M library OS abstraction overview

LwM2M library OS abstraction overview

It provides an abstraction of the following modules:

The OS abstraction layer is fully implemented for the nRF Connect SDK, and it needs to be ported if used with other RTOS or on other systems.

When the LwM2M carrier library is enabled in your application, it includes the file nrf/lib/bin/lwm2m_carrier/os/lwm2m_carrier.c. This automatically runs the library’s main function (lwm2m_carrier_main()).

Configuration

To run the library in an application, you must implement the application with the API of the library. Enable the library by setting the CONFIG_LWM2M_CARRIER Kconfig option to y.

The Cellular: LwM2M carrier sample project configuration (nrf/samples/cellular/lwm2m_carrier/prj.conf) contains all the configurations that are needed by the LwM2M carrier library.

To overwrite the carrier default settings, you can provide the initialization parameter lwm2m_carrier_config_t with the Kconfig options specified in the following sections. You can also use the provided LwM2M carrier shell configuration to quickly get started and experiment with the API.

General options

Following are some of the general Kconfig options that you can configure:

  • CONFIG_LWM2M_CARRIER_SESSION_IDLE_TIMEOUT:

    • This configuration specifies the session idle timeout (inactivity). Upon timeout, the LwM2M carrier library disconnects from one or more device management servers.

    • The timeout closes the DTLS session. A new DTLS session will be created on the next activity (for example, lifetime trigger).

    • Leaving this configuration empty (0) sets it to a default of 60 seconds.

    • Setting this configuration to -1 disables the session idle timeout.

    • This configuration does not apply when the DTLS session is using Connection ID.

  • CONFIG_LWM2M_CARRIER_COAP_CON_INTERVAL:

    • This configuration specifies how often to send a Confirmable message instead of a Non-Confirmable message, according to RFC 7641 section 4.5.

    • Leaving this configuration empty (0) sets it to a default of 24 hours.

    • Setting this to -1 will always use Confirmable notifications.

  • CONFIG_LWM2M_CARRIER_CUSTOM_APN:

    • This configuration produces different results depending on normal or generic mode of operation.

    • If the connected device management server does not support the APN Connection Profile object, this configuration is ignored.

    • If CONFIG_LWM2M_CARRIER_CUSTOM_URI is not set (normal), this configuration provides a fallback APN. This might be required in your application, depending on the requirements from the carrier.

    • If CONFIG_LWM2M_CARRIER_CUSTOM_URI is set (generic), CONFIG_LWM2M_CARRIER_CUSTOM_APN is used instead of the default APN. The default APN becomes the fallback APN.

  • CONFIG_LWM2M_CARRIER_PDN_TYPE:

Server options

Following are some of the server Kconfig options that you can configure. See the enabled carriers under General options for when the option is relevant.

For CONFIG_LWM2M_CARRIER_GENERIC, no valid factory configuration has been set. At a minimum, a URI must be set, unless the CONFIG_LWM2M_SERVER_BINDING_CHOICE Kconfig option value is non-IP.

Note

Changing one or more server options will trigger a factory reset (resulting in a new bootstrap sequence).

Device options

These values are reported in the Device Object and are not expected to change during run time. These configurations can be left empty unless otherwise stated by your operator. The library will automatically set the values according to the detected operator.

Following are the device Kconfig options:

LwM2M carrier library events

The lwm2m_carrier_event_handler() function can be implemented by your application. This is shown in the Cellular: LwM2M carrier sample. A __weak implementation is included in nrf/lib/bin/lwm2m_carrier/os/lwm2m_carrier.c.

The __weak implementation acts as default handling and should be sufficient for most needs, but certain events could need handling specific to your application.

For example:

  • LWM2M_CARRIER_EVENT_REBOOT- This event indicates that the LwM2M carrier library will reboot the device. Your application might want to do some bookkeeping before rebooting.

  • LWM2M_CARRIER_EVENT_LTE_LINK_DOWN- This event indicates that the device must disconnect from the LTE network. Your application might want to do some bookkeeping before disconnecting.

  • LWM2M_CARRIER_EVENT_ERROR_CODE_RESET- This event indicates that the server has reset the “Error Code” resource (3/0/11) of the LwM2M carrier library. When received, the application should re-evaluate the errors and signal relevant errors again using the lwm2m_carrier_error_code_add() function. This is not handled in the __weak implementation since the applicable errors to report is application dependent.

See the LwM2M carrier library events section of the API documentation for a complete overview over the events, which are defined in the nrf/lib/bin/lwm2m_carrier/include/lwm2m_carrier.h file.

LwM2M carrier shell configuration

The LwM2M carrier shell allows you to interact with the carrier library through the shell command line. This allows you to overwrite initialization parameters and call the different runtime APIs of the library. This can be useful for getting started and debugging. See Shell for more information.

To enable and configure the LwM2M carrier shell, set the CONFIG_LWM2M_CARRIER_SHELL Kconfig option to y. The CONFIG_LWM2M_CARRIER_SHELL Kconfig option has the following dependencies:

In the Cellular: LwM2M carrier sample, you can enable the LwM2M carrier shell by building with the overlay file overlay-shell.conf.

LwM2M carrier shell

LwM2M carrier shell

carrier_config

The initialization parameter lwm2m_carrier_config_t can be overwritten with custom settings through the LwM2M carrier shell command group carrier_config. Use the print command to display the configurations that are written with carrier_config:

uart:~$ carrier_config print
Automatic startup                No

Custom carrier settings          Yes
  Carriers enabled               Verizon (1), T-Mobile (3), SoftBank (4), Bell Canada (5)
  Server settings
    Server URI
      Is bootstrap server        No  (Not used without server URI)
    PSK security tag             0
    Server lifetime              0
    Server binding               Not set
  Auto register                  Yes
  Bootstrap from smartcard       Yes
  Queue mode                     Yes
  Session idle timeout           60
  CoAP confirmable interval      86400
  APN
    PDN type                     IPv4v6
  Service code
  Device Serial Number type      1
  Firmware download timeout      0 (disabled)

Custom carrier device settings   No
  Manufacturer
  Model number
  Device type
  Hardware version
  Software version

To allow time to change configurations before the library applies them, the application waits in the initialization phase (lwm2m_carrier_custom_init()) until auto_startup is set.

uart:~$ carrier_config auto_startup y
Set auto startup: Yes

The settings are applied by the function lwm2m_carrier_custom_init().

This function is implemented in nrf/lib/bin/lwm2m_carrier/os/lwm2m_settings.c that is included in the project when you enable the LwM2M carrier shell. The library thread calls the lwm2m_carrier_custom_init() function before calling the lwm2m_carrier_main() function.

carrier_api

The LwM2M carrier shell command group carrier_api allows you to access the public LwM2M API as shown in nrf/lib/bin/lwm2m_carrier/include/lwm2m_carrier.h.

For example, to indicate the battery level of the device to the carrier, the function lwm2m_carrier_battery_level_set() is used. This can also be done through the carrier_api command:

> carrier_api device battery_level 20
Battery level updated successfully

help

To display help for all available shell commands, pass the following command to shell:

> [group] help

If the optional argument is not provided, the command displays help for all command groups.

If the optional argument is provided, it displays help for subcommands of the specified command group. For example, carrier_config help displays help for all carrier_config commands.

Objects

The objects enabled depend on the carrier network. When connecting to a generic LwM2M Server, the following objects are enabled:

ID

Name

0

Security

1

Server

2

Access Control

3

Device

4

Connectivity Monitoring

5

Firmware Update

6

Location

7

Connectivity Statistics

10

Cellular Connectivity

11

APN Connection Profile

19

Binary App Data Container

20

Event Log

Resources

Reading and writing to the resources of the prior listed objects are the LwM2M Server’s interface to your device. Many of these resources have no application API, and the reporting is automatically handled by the LwM2M carrier library. An example is the Network Bearer or Radio Signal Strength resources in the Connectivity Monitoring object are simply read from the modem directly by the library.

Every resource, which is not automatically managed by the library, can be set using the resource APIs. See the LwM2M carrier library objects section for more details on the resource APIs, which are defined in the nrf/lib/bin/lwm2m_carrier/include/lwm2m_carrier.h file.

For example, your operator’s LwM2M Server might observe the battery level of your device. The battery level is not automatically known to the LwM2M carrier library, (or if there is no battery at all). So it provides the default (0%) to the server. The application can use the lwm2m_carrier_avail_power_sources_set() function to select LWM2M_CARRIER_POWER_SOURCE_INTERNAL_BATTERY as the power source, and then call the lwm2m_carrier_battery_level_set() function to indicate the current battery level of the device to the operator’s server.

Note

Some Device Resources are not expected to change during runtime and are set at start-up using the lwm2m_carrier_config_t struct See Device options for the corresponding Kconfig options for the following events:

DFU interface

The LwM2M carrier library makes use of the DFU target library to manage the DFU process, providing a single interface to support different types of firmware upgrades. Currently, the following types of firmware upgrades are supported:

The type of upgrade is determined when the library calls the lwm2m_os_dfu_img_type() function in the abstraction layer upon receiving a new firmware image.

If MCUboot-style upgrades are enabled, the LwM2M carrier library uses the function lwm2m_os_dfu_application_update_validate() to validate the application image update. A __weak implementation of the function is included, which checks if the currently running image is not yet confirmed as valid (which is the case after an upgrade) and marks it appropriately.

The proprietary application upgrades over multiple files are currently only supported if the CONFIG_LWM2M_CARRIER_SOFTBANK_DIVIDED_FOTA Kconfig option is enabled. This allows the library to perform the non-standard divided FOTA procedure in the SoftBank network. The application update files required for this type of firmware upgrade can be generated during the building process by enabling the SB_CONFIG_LWM2M_CARRIER_DIVIDED_DFU sysbuild Kconfig option.