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.
It provides an abstraction of the following modules:
nRF Connect SDK modules:
The OS abstraction layer is fully implemented for the nRF Connect SDK, and it would have 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.
You can enable the module using the
CONFIG_LWM2M_CARRIER Kconfig option.
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 Kconfig options described below:
This configuration specifies if the LwM2M carrier library will connect to the carrier’s certification servers or production servers.
Expected to be set during self-testing part of the certification process.
This configuration is ignored if
This configuration, together with
CONFIG_LWM2M_CARRIER_CUSTOM_BOOTSTRAP_URIlets the LwM2M carrier library connect to a bootstrap server other than the normal carrier server, thereby enabling the generic mode.
Expected to be set during self-testing, or if the end product is not to be certified with the applicable carriers. See Certification and version dependencies.
If this configuration is set,
If connecting to the normal carrier device management servers (normal operation), this configuration must not be set unless your carrier explicitly states to use a custom PSK, for example during self-testing.
CONFIG_LWM2M_CARRIER_CUSTOM_BOOTSTRAP_URIoption is set and the server requires a secure connection, a PSK is required.
This configuration, together with
CONFIG_LWM2M_CARRIER_CUSTOM_APNproduce different results depending on normal or generic mode of operation.
CONFIG_LWM2M_CARRIER_USE_CUSTOM_BOOTSTRAP_URIis not set (normal), this configuration supplies a fallback APN. This might be required in your application, depending on the requirements from the carrier.
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.
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\include\lwm2m_carrier.h for all the events and API.
Following are the various LwM2M carrier library events:
This event indicates that the CA certificates must be provisioned to the modem by the application. The LwM2M carrier library expects the application to assign the event data
lwm2m_carrier_event_t.datato a structure
ca_cert_tags_t. This structure must contain the security tags that indicate where the CA certificates are stored in the modem. See nRF9160: LwM2M carrier sample for an example of how these certificates are written to the modem using Modem key management library. The LwM2M carrier library will apply these certificates during certain out-of-band FOTA operations.
These events indicate that the device is connecting to or disconnecting 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 is registered to the LTE network (home or roaming).
The bootstrap sequence is complete, and the application can use the LTE link.
This event indicates that the device has registered successfully to the carrier’s device management servers.
This event indicates that the connection to the device management server has failed.
timeoutparameter 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
timeoutis 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_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.
This event indicates that the modem update has started.
The application must immediately terminate any open TLS sessions.
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_tcontains the information about the error (
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
valuefield of the event.
LWM2M_CARRIER_ERROR_BOOTSTRAP- This error is generated from the
modem_key_mgmt_write()function, if the
valuefield is negative. If the
valuefield is 0, it indicates that the bootstrap sequence has failed. If this error persists, contact your carrier.
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
valuefield will have an error of type
nrf_dfu_err_tfrom the file
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_CONFIGURATION- This error indicates that an illegal object configuration was detected.
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
Device Type (Defaults to
Smart Deviceif not set)
Software Version (Defaults to
LwM2M <libversion>. For example,
LwM2M 0.8.0for release 0.8.0.)
Hardware Version (Defaults to
1.0if not set)
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.