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 lwm2m_os.h.

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.


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 nRF9160: LwM2M carrier sample project configuration (nrf/samples/nrf9160/lwm2m_carrier/prj.conf) contains all the configurations that are needed by the LwM2M carrier library.

You can provide the initialization parameter lwm2m_carrier_config_t to overwrite the carrier default settings with the following Kconfig options:

  • This configuration allows the LwM2M carrier library to use a URI stored in the SIM card. 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 CONFIG_LWM2M_CARRIER_IS_SERVER_BOOTSTRAP configuration is ignored. If a production server URI is fetched from the SIM, the CONFIG_LWM2M_CARRIER_CERTIFICATION_MODE configuration is ignored.

Note that these settings can put the LwM2M carrier library either in the normal mode where it connects to the applicable carriers, or in the generic mode where it can connect to any bootstrap server.


A change of the bootstrap server URI between builds does not trigger a new bootstrap. The bootstrap process is intended to happen only once unless it is initiated from the server. To redo the bootstrap process, you must erase the flash and then load your application again.

After calling the lwm2m_carrier_init() function, your application can call the non-returning function lwm2m_carrier_run() in its own thread. Both these functions are called in nrf/lib/bin/lwm2m_carrier/os/lwm2m_carrier.c, which is included into the project when you enable the LwM2M carrier library.

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

See nrf/lib/bin/lwm2m_carrier/include/lwm2m_carrier.h for all the events and API.

LwM2M carrier library events

Following are the various LwM2M carrier library events:


    • This event indicates that the carrier library has been successfully initialized. Modem library is initialized and can be used. See Requirements and application limitations). The application can now attach to the network.

    • If CA certificates are not already present in the modem, they can be written when receiving this event (and before attaching to the network). The CA certificates needed for your device depends on your network operator. The LwM2M carrier library will apply these certificates during certain out-of-band FOTA operations. See nRF9160: LwM2M carrier sample for an example of how these certificates are written to the modem using Modem key management library.


    • These events indicate that the device must connect to, or disconnect from the LTE network. They occur during the bootstrapping process, startup, and during FOTA.


    • This event indicates that the bootstrap sequence is complete, and that the device is ready to be registered.

    • This event is typically seen during the first boot-up.


    • This event indicates that the device has registered successfully to the carrier’s device management servers.




    • This event indicates that the LwM2M carrier library will reboot the device.

    • If the application is not ready to reboot, it must return non-zero and then reboot at the earliest convenient time.


    • This event indicates an error.

    • The event data struct lwm2m_carrier_event_error_t contains the information about the error (code and value).

    • Following are the valid error codes:

      • LWM2M_CARRIER_ERROR_CONNECT_FAIL - This error is generated from the lte_lc_init_and_connect() function. It indicates possible problems with the SIM card, or insufficient network coverage. See value field of the event.

      • LWM2M_CARRIER_ERROR_DISCONNECT_FAIL - This error is generated from the lte_lc_offline() function. See value field of the event.

      • LWM2M_CARRIER_ERROR_BOOTSTRAP - This error is generated during the bootstrap procedure.


        More information


        Retry limit for connecting to the bootstrap server has been reached (-ETIMEDOUT).

        Common reason for this failure can be incorrect URI or PSK, or the server is unavailable (for example, temporary network issues). If this error persists, contact your carrier.

        Library retries after next device reboot.

        Failure to provision the PSK needed for the bootstrap procedure.

        If the LTE link is up while the modem attempts to write keys to the modem, the error will be -EACCES. Verify that the application prioritizes the LWM2M_CARRIER_EVENT_LTE_LINK_UP and LWM2M_CARRIER_EVENT_LTE_LINK_DOWN events.

        Library retries after 24 hours.

        Failure to read MSISDN or ICCID values (-EFAULT).

        ICCID is fetched from SIM, while MSISDN is received from the network for some carriers. If it has not been issued yet, the bootstrap process cannot proceed.

        Library retries upon next network connection.

      • LWM2M_CARRIER_ERROR_FOTA_PKG - This error indicates that the update package has been rejected. The integrity check has failed because of a wrong package sent from the server, or a wrong package received by client. The value field will have an error of type nrf_dfu_err_t from the file nrfxlib/nrf_modem/include/nrf_socket.h.

      • LWM2M_CARRIER_ERROR_FOTA_PROTO - This error indicates a protocol error. There might be unexpected HTTP header contents. The server might not support partial content requests.

      • LWM2M_CARRIER_ERROR_FOTA_CONN - This error indicates a connection problem. Either the server host name could not be resolved, or the remote server refused the connection.

      • LWM2M_CARRIER_ERROR_FOTA_CONN_LOST - This error indicates a loss of connection, or an unexpected closure of connection by the server.

      • LWM2M_CARRIER_ERROR_FOTA_FAIL - This error indicates a failure in applying a valid update. If this error persists, create a ticket in DevZone with the modem trace.

      • LWM2M_CARRIER_ERROR_CONFIGURATION - This error indicates that an illegal object configuration was detected.

      • LWM2M_CARRIER_ERROR_INTERNAL - This error indicates an irrecoverable error between the modem and carrier library. The LwM2M carrier library recovers only upon reboot.

Device objects

The following values that reflect the state of the device must be kept up to date by the application:

  • Available Power Sources

  • Power Source Voltage

  • Power Source Current

  • Battery Level

  • Battery Status

  • Memory Total

  • Error Code

  • Device Type (Defaults to Smart Device if not set)

  • Software Version (Defaults to LwM2M <libversion>. For example, LwM2M 0.21.0 for release 0.21.0.)

  • Hardware Version (Defaults to 1.0 if not set)

  • Location

For example, the carrier device management platform can observe the battery level of your device. The application uses the lwm2m_carrier_battery_level_set() function to indicate the current battery level of the device to the carrier.