Application integration

Configuration
LwM2M carrier library events
LwM2M carrier shell configuration
Objects
- Resources

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

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

It provides an abstraction of the following modules:

nRF Connect SDK modules:
Zephyr modules:
- Kernel Services (include/kernel.h)
- Non-Volatile Storage (NVS)

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 initializes the library (using lwm2m_carrier_init()) and runs the library thread (lwm2m_carrier_run()).

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

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_BOOTSTRAP_SMARTCARD:
- This configuration allows the LwM2M carrier library to use the bootstrap information stored on 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 configuration set by the CONFIG_LWM2M_CARRIER_IS_BOOTSTRAP_SERVER Kconfig option is ignored.
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.
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 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:

This configuration selects the PDN type of the custom APN (CONFIG_LWM2M_CARRIER_CUSTOM_APN).

The default value is IPV4V6.

If CONFIG_LWM2M_CARRIER_CUSTOM_APN is not set, this configuration is ignored.

CONFIG_LWM2M_CARRIER_GENERIC, CONFIG_LWM2M_CARRIER_VERIZON, CONFIG_LWM2M_CARRIER_ATT , CONFIG_LWM2M_CARRIER_LG_UPLUS.
- These configurations allow you to choose the networks in which the carrier library will apply.
- For example, If you are deploying a product in several networks but only need to enable the carrier library within Verizon, you must set CONFIG_LWM2M_CARRIER_VERIZON to y and all the others to n.
- If only one carrier is selected, then the CONFIG_LWM2M_CARRIER_CUSTOM_URI and CONFIG_LWM2M_CARRIER_SERVER_SEC_TAG will be used for this carrier.
  - This will typically have to be done while you are certifying your product, to be able to connect to the carriers certification servers, since they will require a URI different from the default live servers.
  - See Preparing for production for more information on the test configuration.
- If multiple operator networks are selected then the “Custom URI” and “Custom sec_tag” will be used for Generic mode, which is used when not in any of the other selected networks.
CONFIG_LWM2M_CARRIER_LG_UPLUS, CONFIG_LWM2M_CARRIER_LG_UPLUS_SERVICE_CODE:
- The CONFIG_LWM2M_CARRIER_LG_UPLUS_SERVICE_CODE Kconfig option sets the LG U+ service code, which is needed to identify your device in the LG U+ device management.
CONFIG_LWM2M_CARRIER_LG_UPLUS_DEVICE_SERIAL_NUMBER:
- This configuration lets you choose between using the nRF9160 SoC 2DID Serial Number, or the device IMEI as a serial number when connecting to the LG U+ device management server.
Note

Application DFU is needed to enable LG U+ functionality.

Server options 

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

The server 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.

CONFIG_LWM2M_CARRIER_IS_BOOTSTRAP_SERVER:
- This configuration specifies if the custom LwM2M server is an LwM2M Bootstrap Server.
CONFIG_LWM2M_CARRIER_CUSTOM_URI:
- This configuration lets the LwM2M carrier library connect to a custom server other than the normal carrier server and enables the generic mode if used in an operator network that is not supported.
- You must set this option during self-testing, or if the end product is not to be certified with the applicable carriers. For more information, see Certification and version dependencies.
CONFIG_LWM2M_CARRIER_SERVER_SEC_TAG:
- This configuration provides the library with a security tag containing a PSK.
- This configuration should normally be left empty (0) unless stated by the operator, or when connecting to a custom URI. In this case, the library will automatically apply the correct PSK for the different carrier device management.
- The sample allows you to set a PSK that is written to a modem security tag using the CONFIG_CARRIER_APP_PSK and CONFIG_LWM2M_CARRIER_SERVER_SEC_TAG Kconfig options. This is convenient for developing and debugging but must be avoided in the final product. Instead, see Modem key management or nRF9160: AT Client sample for provisioning a PSK.
CONFIG_LWM2M_CARRIER_SERVER_LIFETIME:
- This configuration specifies the lifetime of the custom LwM2M server.
- This configuration is ignored if CONFIG_LWM2M_CARRIER_IS_BOOTSTRAP_SERVER is set.
LWM2M_SERVER_BINDING_CHOICE.

The binding can be either ‘U’ (UDP) or ‘N’ (Non-IP).

Leaving this configuration empty will select the default binding (UDP).

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

Following are the various LwM2M carrier library events that are also listed in nrf/lib/bin/lwm2m_carrier/include/lwm2m_carrier.h.

LWM2M_CARRIER_EVENT_INIT:
- This event indicates that the carrier library has been successfully initialized. Modem library is initialized and can be used. See Requirements and application limitations.
- 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 depend on your network operator. The LwM2M carrier library will apply these certificates during certain out-of-band FOTA updates. See nRF9160: LwM2M carrier sample for an example of how these certificates are written to the modem using Modem key management library.
LWM2M_CARRIER_EVENT_LTE_LINK_DOWN:
- This event indicates that the device must disconnect to the LTE network.
- It occurs during the bootstrapping process and FOTA. It can also be triggered when the application calls lwm2m_carrier_request().
LWM2M_CARRIER_EVENT_LTE_LINK_UP:
- This event indicates that the device must connect from the LTE network.
- It occurs during the bootstrapping process, startup, and FOTA. It can also be triggered when the application calls lwm2m_carrier_request().
LWM2M_CARRIER_EVENT_BOOTSTRAPPED:
- 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.
LWM2M_CARRIER_EVENT_REGISTERED:
- This event indicates that the device has registered successfully to the carrier’s device management servers.
LWM2M_CARRIER_EVENT_DEFERRED:
- This event indicates that the connection to the device management server has failed.
- The LWM2M_CARRIER_EVENT_DEFERRED event appears instead of the LWM2M_CARRIER_EVENT_REGISTERED event.
- The timeout parameter supplied with this event determines when the LwM2M carrier library will retry the connection.
- Following are the various deferred reasons:
  - LWM2M_CARRIER_DEFERRED_NO_REASON - The application need not take any special action. If timeout is 24 hours, the application can proceed with other activities until the retry takes place.
  - LWM2M_CARRIER_DEFERRED_PDN_ACTIVATE - This event indicates problem with the SIM card, or temporary network problems. If this persists, contact your carrier.
  - LWM2M_CARRIER_DEFERRED_BOOTSTRAP_CONNECT - The DTLS handshake with the bootstrap server has failed. If the application is using a custom PSK, verify that the format is correct.
  - LWM2M_CARRIER_DEFERRED_BOOTSTRAP_SEQUENCE - The bootstrap sequence is incomplete. The server failed either to acknowledge the request by the library, or to send objects to the library. Confirm that the carrier is aware of the IMEI.
  - LWM2M_CARRIER_DEFERRED_SERVER_NO_ROUTE, LWM2M_CARRIER_DEFERRED_BOOTSTRAP_NO_ROUTE - There is a routing problem in the carrier network. If this event persists, contact the carrier.
  - LWM2M_CARRIER_DEFERRED_SERVER_CONNECT - This event indicates that the DTLS handshake with the server has failed. This typically happens if the bootstrap sequence has failed on the carrier side.
  - LWM2M_CARRIER_DEFERRED_SERVER_REGISTRATION - The server registration has not completed, and the server does not recognize the connecting device. If this event persists, contact the carrier.
  - LWM2M_CARRIER_DEFERRED_SERVICE_UNAVAILABLE - The server is unavailable due to maintenance.
LWM2M_CARRIER_EVENT_FOTA_START:
- This event indicates that the modem update has started.
- The application must immediately terminate any open TLS and DTLS sessions.
- See Requirements and application limitations.
LWM2M_CARRIER_EVENT_REBOOT:
- 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.

LWM2M_CARRIER_EVENT_ERROR:

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.

Errors	More information	Recovery
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.

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 nRF9160: LwM2M carrier sample, you can enable the LwM2M carrier shell by building with the overlay file overlay-shell.conf.

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:

> carrier_config print
Automatic startup                No

Custom carrier settings          Yes
  Carriers enabled               All
  Bootstrap from smartcard       Yes
  Session idle timeout           0
  CoAP confirmable interval      0
  APN
  PDN type                       IPv4v6
  Service code
  Device Serial Number type      0

Custom carrier server settings   No
  Is bootstrap server            No  (Not used without server URI)
  Server URI
  PSK security tag               0
  Server lifetime                0
  Server binding                 U

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 __weak implementation of lwm2m_carrier_event_handler() calls lwm2m_carrier_custom_init() on receiving the LWM2M_CARRIER_EVENT_INIT event.

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:

Security
Server
Access Control
Device
Connectivity Monitoring
Firmware Update
Location
Connectivity Statistics
Cellular Connectivity
APN Connection Profile

Resources 

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

Available Power Sources - Defaults to 0 if not set (DC Power).
Power Source Voltage - Defaults to 0 if not set.
Power Source Current - Defaults to 0 if not set.
Battery Level - Defaults to 0 if not set.
Battery Status - Defaults to 5 if not set (Not Installed).
Memory Total - Defaults to 0 if not set.
Error Code - Defaults to 0 if not set (No Error).
Device Type - Defaults to Smart Device if not set.
Software Version - Defaults to LwM2M <libversion>. For example, LwM2M 0.30.2 for release 0.30.2.
Hardware Version - Default value is read from the modem. An example value is nRF9160 SICA B0A.
Location - Defaults to 0 if not set.

The following values are read from the modem by default but can be overwritten:

Manufacturer
Model Number
UTC Offset
Time zone
Current Time

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.