LwM2M carrier

You can use the LwM2M carrier library in your nRF91 application in order to connect to the operator LwM2M network. Integrating this library into an application causes the device to connect to the device management platform autonomously.

Every released version is considered for certification with carriers. Refer to the Changelog to check the certification status of a particular release. Your final device must go through certification by the carrier.

The nRF9160: LwM2M carrier sample demonstrates how to run this library in an application.

Prerequisites

The LwM2M carrier library has dependencies on Zephyr and the nRF Connect SDK. See the Changelog of the library to check which version of nRF Connect SDK it is built for. To integrate the library into an application, the application must be based on a supported nRF Connect SDK version.

Application integration

To run the library in an application, you must implement the application with the API of the library.

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

The library automatically reports the updated values to the relevant server.

The application must also implement an event handler and error handlers, as shown in the nRF9160: LwM2M carrier sample. The bsdlib_init function is called by the library because of the need to track modem update state.

Application limitations

While running this module, the application has some limitations.

Several system resources are used to maintain the device management platform connection.

While running the module, the application cannot use DTLS through the modem.

Additionally, you must apply workarounds for the following limitations:

  • TLS through the modem is available, but requires that the application respects the LWM2M_CARRIER_EVENT_FOTA_START event.
  • TLS handshakes through the modem might fail if the module is performing one at the same time. Implement a retry mechanism so that the application can perform its handshake later.

Certification

The changelog contains information about the certification status of each version of the library. Your final product will typically need certification from the carrier as well. Contact the carrier for information about their device certification program.

Library changelog

See the changelog for the latest updates in the library, and for a list of known issues and limitations.

API documentation

Header files: lib/bin/lwm2m_carrier/include
Source files: lib/bin/lwm2m_carrier

LWM2M carrier library API

group lwm2m_carrier_api

LWM2M carrier library API functions.

Defines

LWM2M_CARRIER_POWER_SOURCE_DC

LWM2M device power sources type.

LWM2M_CARRIER_POWER_SOURCE_INTERNAL_BATTERY
LWM2M_CARRIER_POWER_SOURCE_EXTERNAL_BATTERY
LWM2M_CARRIER_POWER_SOURCE_ETHERNET
LWM2M_CARRIER_POWER_SOURCE_USB
LWM2M_CARRIER_POWER_SOURCE_AC
LWM2M_CARRIER_POWER_SOURCE_SOLAR
LWM2M_CARRIER_ERROR_CODE_NO_ERROR

LWM2M device error codes.

LWM2M_CARRIER_ERROR_CODE_LOW_CHARGE
LWM2M_CARRIER_ERROR_CODE_EXTERNAL_SUPPLY_OFF
LWM2M_CARRIER_ERROR_CODE_GPS_FAILURE
LWM2M_CARRIER_ERROR_CODE_LOW_SIGNAL
LWM2M_CARRIER_ERROR_CODE_OUT_OF_MEMORY
LWM2M_CARRIER_ERROR_CODE_SMS_FAILURE
LWM2M_CARRIER_ERROR_CODE_IP_CONNECTIVITY_FAILURE
LWM2M_CARRIER_ERROR_CODE_PERIPHERAL_MALFUNCTION
LWM2M_CARRIER_BATTERY_STATUS_NORMAL

LWM2M device battery status.

Note
These values are only valid for the LWM2M Device INTERNAL_BATTERY if present.

LWM2M_CARRIER_BATTERY_STATUS_CHARGING
LWM2M_CARRIER_BATTERY_STATUS_CHARGE_COMPLETE
LWM2M_CARRIER_BATTERY_STATUS_DAMAGED
LWM2M_CARRIER_BATTERY_STATUS_LOW_BATTERY
LWM2M_CARRIER_BATTERY_STATUS_NOT_INSTALLED
LWM2M_CARRIER_BATTERY_STATUS_UNKNOWN

Functions

int lwm2m_carrier_init(const lwm2m_carrier_config_t *config)

Initialize the LWM2M carrier library.

Note
The library does not create a copy of the config parameters, hence the application has to make sure that the parameters provided are valid throughout the application lifetime (i. e. placed in static memory or in flash).
Return
0 on success, negative error code on error.
Parameters
  • config: Configuration parameters for the library.

void lwm2m_carrier_run(void)

LWM2M carrier library main function.

This is a non-return function, intended to run on a separate thread.

int32_t lwm2m_carrier_utc_time_read(void)

Function to read current UTC time.

Note
This function can be implemented by the application, if custom time management is needed.
Return
Current UTC time since Epoch in seconds

int lwm2m_carrier_utc_offset_read(void)

Function to read offset to UTC time.

Note
This function can be implemented by the application, if custom time management is needed.
Return
UTC offset in minutes

const char *lwm2m_carrier_timezone_read(void)

Function to read timezone.

Note
This function can be implemented by the application, if custom time management is needed.
Return
Null-terminated timezone string pointer, IANA Timezone (TZ) database format

int lwm2m_carrier_utc_time_write(int32_t time)

Function to write current UTC time (LWM2M server write operation)

Note
This function can be implemented by the application, if custom time management is needed.
Return
0 on success, negative error code on error.
Parameters
  • time: Time since Epoch in seconds

int lwm2m_carrier_utc_offset_write(int offset)

Function to write UTC offset (LWM2M server write operation)

Note
This function can be implemented by the application, if custom time management is needed.
Return
0 on success, negative error code on error.
Parameters
  • offset: UTC offset in minutes

int lwm2m_carrier_timezone_write(const char *p_tz)

Function to write timezone (LWM2M server write operation)

Note
This function can be implemented by the application, if custom time management is needed.
Return
0 on success, negative error code on error.
Parameters
  • p_tz: Null-terminated timezone string pointer

int lwm2m_carrier_event_handler(const lwm2m_carrier_event_t *event)

LWM2M carrier library event handler.

This function will be called by the LWM2M carrier library whenever some event significant for the application occurs.

Note
This function has to be implemented by the application.
Return
In case of LWM2M_CARRIER_EVENT_REBOOT events if non-zero is returned, the LwM2M carrier library will not reboot the device. The application should to reboot at the earliest convenient time.
Parameters
  • event: LWM2M carrier event that occurred.

struct lwm2m_carrier_event_t
#include <lwm2m_carrier.h>

LWM2M carrier library event structure.

Public Members

uint32_t type

Event type.

void *data

Event data. Can be NULL, depending on event type.

struct lwm2m_carrier_config_t
#include <lwm2m_carrier.h>

Structure holding LWM2M carrier library initialization parameters.

Public Members

char *bootstrap_uri

URI of the bootstrap server, null-terminated.

char *psk

Pre-shared key that the device will use.

size_t psk_length

Length of the pre-shared key.

LWM2M carrier library events

group lwm2m_carrier_event

Defines

LWM2M_CARRIER_EVENT_BSDLIB_INIT

BSD library initialized.

LWM2M_CARRIER_EVENT_CONNECT

LTE link connected.

LWM2M_CARRIER_EVENT_DISCONNECT

LTE link will disconnect.

LWM2M_CARRIER_EVENT_BOOTSTRAPPED

LWM2M carrier bootstrapped.

LWM2M_CARRIER_EVENT_READY

LWM2M carrier registered.

LWM2M_CARRIER_EVENT_FOTA_START

Modem update started.

LWM2M_CARRIER_EVENT_REBOOT

Application will reboot.

LWM2M OS layer

group lwm2m_carrier_os

Defines

LWM2M_OS_MAX_TIMER_COUNT

Maximum number of timers that the system must support.

LWM2M_LOG_LEVEL_NONE
LWM2M_LOG_LEVEL_ERR
LWM2M_LOG_LEVEL_WRN
LWM2M_LOG_LEVEL_INF
LWM2M_LOG_LEVEL_TRC
LWM2M_OS_STORAGE_BASE

Range of the non-volatile storage identifiers used by the library.

Note
The application MUST NOT use the values within this range for its own non-volatile storage management as it could potentially delete or overwrite entries used by the library.

LWM2M_OS_STORAGE_END

Typedefs

typedef void (*lwm2m_os_timer_handler_t)(void *timer)

Timer callback function.

typedef void (*lwm2m_os_at_cmd_handler_t)(void *ctx, char *response)

AT Command handler.

typedef int (*lwm2m_os_download_callback_t)(const struct lwm2m_os_download_evt *event)

Download client asynchronous event handler.

Functions

int lwm2m_os_init(void)

Initialize the LWM2M OS layer.

void *lwm2m_os_malloc(size_t size)

Allocate memory.

void lwm2m_os_free(void *ptr)

Free memory.

int64_t lwm2m_os_uptime_get(void)

Get uptime, in milliseconds.

int64_t lwm2m_os_uptime_delta(int64_t *ref)

Get uptime delta, in milliseconds.

int lwm2m_os_sleep(int ms)

Put a thread to a sleep.

void lwm2m_os_sys_reset(void)

Reboot system.

uint32_t lwm2m_os_rand_get(void)

Get a random value.

int lwm2m_os_storage_delete(uint16_t id)

Delete a non-volatile storage entry.

int lwm2m_os_storage_read(uint16_t id, void *data, size_t len)

Read an entry from non-volatile storage.

int lwm2m_os_storage_write(uint16_t id, const void *data, size_t len)

Write an entry to non-volatile storage.

void *lwm2m_os_timer_get(lwm2m_os_timer_handler_t handler)

Request a timer from the OS.

void lwm2m_os_timer_release(void *timer)

Release a timer.

int lwm2m_os_timer_start(void *timer, int32_t timeout)

Start a timer.

void lwm2m_os_timer_cancel(void *timer)

Cancel a timer run.

int32_t lwm2m_os_timer_remaining(void *timer)

Obtain the time remaining on a timer.

const char *lwm2m_os_log_strdup(const char *str)

Create a string copy for a logger subsystem.

void lwm2m_os_log(int level, const char *fmt, ...)

Log a message.

int lwm2m_os_bsdlib_init(void)

Initialize BSD library.

Return
0 on success
Return
-1 on error
Return
an error from bsd_modem_dfu in case of modem DFU

int lwm2m_os_bsdlib_shutdown(void)

Shutdown BSD library.

Return
0 on success, -1 otherwise.

int lwm2m_os_at_init(void)

Initialize AT command driver.

int lwm2m_os_at_notif_register_handler(void *context, lwm2m_os_at_cmd_handler_t handler)

Set AT command global notification handler.

int lwm2m_os_at_cmd_write(const char *const cmd, char *buf, size_t buf_len)

Send an AT command and receive response immediately.

void lwm2m_os_at_params_list_free(struct lwm2m_os_at_param_list *list)

Free a list of AT parameters.

int lwm2m_os_at_params_list_init(struct lwm2m_os_at_param_list *list, size_t max_params_count)

Create a list of AT parameters.

int lwm2m_os_at_params_int_get(struct lwm2m_os_at_param_list *list, size_t index, uint32_t *value)

Get a parameter value as an integer number.

int lwm2m_os_at_params_short_get(struct lwm2m_os_at_param_list *list, size_t index, uint16_t *value)

Get a parameter value as a short number.

int lwm2m_os_at_params_string_get(struct lwm2m_os_at_param_list *list, size_t index, char *value, size_t *len)

Get a parameter value as a string.

int lwm2m_os_at_params_list_clear(struct lwm2m_os_at_param_list *list)

Clear/reset all parameter types and values.

int lwm2m_os_at_parser_params_from_str(const char *at_params_str, char **next_param_str, struct lwm2m_os_at_param_list *const list)

Parse AT command or response parameters from a string.

int lwm2m_os_at_params_valid_count_get(struct lwm2m_os_at_param_list *list)

Get the number of valid parameters in the list.

int lwm2m_os_download_connect(const char *host, const struct lwm2m_os_download_cfg *cfg)

Establish a connection with the server.

int lwm2m_os_download_disconnect(void)

Disconnect from the server.

int lwm2m_os_download_init(lwm2m_os_download_callback_t lib_callback)

Initialize the download client.

int lwm2m_os_download_start(const char *file, size_t from)

Download a file.

int lwm2m_os_lte_power_down(void)
void lwm2m_os_pdn_disconnect(int pdn_fd)
int lwm2m_os_pdn_init_and_connect(const char *apn_name)
int lwm2m_os_errno(void)

Translate the error number.

struct lwm2m_os_at_param_list
#include <lwm2m_os.h>

List of AT parameters that compose an AT command or response.

struct lwm2m_os_download_evt
#include <lwm2m_os.h>

Download client event.

Public Members

int id

Event ID.

int error

Error cause.

struct lwm2m_os_download_cfg
#include <lwm2m_os.h>

Download client configuration options.