LwM2M carrier

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

Some examples of carrier device management platforms are listed below:

This library uses LwM2M protocol to communicate with device manager platforms, but it does not expose an LwM2M API to your application. If you want to use LwM2M for other purposes, see Lightweight M2M (LWM2M).

The nRF9160: LwM2M carrier sample demonstrates how to run this library in an application. The LwM2M carrier library is also used in the nRF9160: Asset Tracker application.

Application integration

The LwM2M carrier library has an OS abstraction layer. See lwm2m_os.h. 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:

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.

A bootstrap server provides the application with the configuration needed to connect to the device management servers. During self-testing of the certification process, you can provide the initialization parameter lwm2m_carrier_config_t to overwrite the carrier default settings as described below:

A PSK Identity is automatically generated and handled by the LwM2M carrier library. It is used for the bootstrap server transactions. A PSK Key should be provided through the CONFIG_LWM2M_CARRIER_USE_CUSTOM_BOOTSTRAP_PSK option only if the carrier explicitly states to not use the carrier default.

Note

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.

For a production build, the lwm2m_carrier_init() function should always be initialized without parameters. 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

LWM2M_CARRIER_EVENT_BSDLIB_INIT

This event indicates that the BSD library is initialized and can be used. (See Requirements and Application limitations).

LWM2M_CARRIER_EVENT_CONNECTING, LWM2M_CARRIER_EVENT_CONNECTED, LWM2M_CARRIER_EVENT_DISCONNECTING, LWM2M_CARRIER_EVENT_DISCONNECTED

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.

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_READY

This event indicates that the device has connected successfully to the carrier’s device management server.

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_READY event. The timeout parameter supplied with this event determines when the LwM2M carrier library will retry the connection.

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_EVENT_FOTA_START

This event indicates that the modem update has started. The application should immediately terminate any open TLS sessions. See Requirements and Application limitations.

LWM2M_CARRIER_EVENT_REBOOT

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

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 from the modem_key_mgmt_write() function, if the value field is negative. If the value field 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 value field will have an error of type nrf_dfu_err_t from the file nrfxlib\bsdlib\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.

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.8.0 for release 0.8.0.)

  • Hardware Version (Defaults to 1.0 if 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.

Requirements and Application limitations

Below are some of the requirements and limitations of the application while running this module.

  • The application should not call the bsdlib_init() function.

    • The LwM2M carrier library initializes and uses the BSD library. This library is needed to track the modem FOTA states.

  • The application should not use the NB-IoT LTE mode.

    • The LwM2M carrier library is currently only certified for the LTE-M LTE mode.

    • The CONFIG_LTE_NETWORK_USE_FALLBACK should be disabled in your application, as seen in the nRF9160: LwM2M carrier sample project configuration (nrf/samples/nrf9160/lwm2m_carrier/prj.conf).

  • The LwM2M carrier library registers to receive several AT event reports using the AT command interface and AT command notifications libraries. The following notifications should not be deregistered by the application:

    • SMS events (AT+CNMI).

    • Packet Domain events (AT+CGEREP).

    • Report Network Error Codes events (AT+CNEC): EPS Session Management events are used by the LwM2M carrier library. The application may enable or disable EPS Mobility Management events.

    • Network Registration Status events (AT+CEREG): Notification Level 2 is used by the LwM2M carrier library. The application may increase this level, but should not decrease it.

  • The LwM2M carrier library controls the LTE link.

  • The LwM2M carrier library uses a TLS session for FOTA. TLS handshakes performed by the application might fail if the LwM2M carrier library is performing one at the same time.

    • If the application is in a TLS session and a LWM2M_CARRIER_EVENT_FOTA_START event is sent to the application, the application must immediately end the TLS session.

    • TLS becomes available again upon the next LWM2M_CARRIER_EVENT_READY or LWM2M_CARRIER_EVENT_DEFERRED event.

    • The application should implement a retry mechanism so that the application can perform the TLS handshake later.

    • Another alternative is to supply TLS from a source other than the modem, for example Mbed TLS.

  • The LwM2M carrier library uses both the DTLS sessions made available through the modem. Therefore, the application can not run any DTLS sessions.

  • The LwM2M carrier library provisions the necessary security credentials to the security tags 11, 25, 26, 27, 28. These tags should not be used by the application.

  • The LwM2M carrier library uses the following NVS record key range: 0xCA00 - 0xCAFF. This range should not be used by the application.

Certification and Version Dependencies

Every released version of the LwM2M carrier library is considered for certification with the carriers. The library is certified together with specific versions of the modem firmware and the nRF Connect SDK. Refer to the Changelog to check the certification status of a particular version of the library, and to see the version of the nRF Connect SDK it was released with.

Note

Your final product will need certification from the carrier. You can contact the carrier for more information on the respective device certification program.

Version Dependency table

See the following table for the certification status of the library and the related version dependencies:

LwM2M carrier library version

Modem version

nRF Connect SDK release

Certification

0.9.0

1.2.1

1.3.0

0.8.1+build1

1.1.0

1.2.0

Verizon

0.8.0

1.1.0

1.1.0

0.6.0

1.0.1

1.0.0

LwM2M carrier library changelog

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

Message Sequence Charts

The below message sequence chart shows the initialization of the LwM2M carrier library:

msc {
hscale = "1.1";
Application,"LwM2M carrier Library";
Application=>"LwM2M carrier Library"       [label="lwm2m_carrier_init()"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_BSDLIB_INIT"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_CONNECTING"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_CONNECTED"];
Application<<"LwM2M carrier Library"       [label="Success"];
Application=>"LwM2M carrier Library"       [label="lwm2m_carrier_run()"];
|||;
"LwM2M carrier Library" :> "LwM2M carrier Library" [label="(no return)"];
...;
}

The following message sequence chart shows the bootstrap process:

msc {
hscale = "1.1";
Application,"LwM2M carrier Library";
|||;
---                                       [label="Device is not bootstrapped yet"];
|||;
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_DISCONNECTING"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_DISCONNECTED"];
"LwM2M carrier Library" rbox "LwM2M carrier Library" [label="Write keys to modem"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_CONNECTING"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_CONNECTED"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_BOOTSTRAPPED"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_READY"];
}

The following message sequence chart shows FOTA updates:

msc {
hscale = "1.1";
Application,"LwM2M carrier Library";
|||;
---                                       [label="Carrier initiates modem update"];
|||;
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_FOTA_START"];
...;
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_DISCONNECTING"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_DISCONNECTED"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_CONNECTING"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_CONNECTED"];
Application<<="LwM2M carrier Library"      [label="LWM2M_CARRIER_EVENT_READY"];
...;
}

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
LWM2M_CARRIER_IDENTITY_ID

LWM2M portfolio identity types.

LWM2M_CARRIER_IDENTITY_MANUFACTURER
LWM2M_CARRIER_IDENTITY_MODEL
LWM2M_CARRIER_IDENTITY_SW_VERSION

Functions

int lwm2m_carrier_init(const lwm2m_carrier_config_t *config)

Initialize the LWM2M carrier library.

Note

The library does not copy the contents of pointers in the config parameters. The application has to make sure that the provided parameters 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
  • [in] 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.

void lwm2m_carrier_time_read(int32_t *utc_time, int *utc_offset, const char **tz)

Function to read all time parameters.

Parameters
  • [out] utc_time: Pointer to time since Epoch in seconds.

  • [out] utc_offset: Pointer to UTC offset in minutes.

  • [out] tz: Pointer to null-terminated timezone string pointer.

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
  • [in] 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
  • [in] offset: UTC offset in minutes.

int lwm2m_carrier_timezone_write(const char *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
  • [in] 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
  • [in] event: LWM2M carrier event that occurred.

struct lwm2m_carrier_config_t
#include <lwm2m_carrier.h>

Structure holding LWM2M carrier library initialization parameters.

Public Members

const char *bootstrap_uri

URI of the bootstrap server, null-terminated string.

const char *psk

Pre-Shared Key for the bootstrap server, null-terminated hexadecimal string.

const char *apn

Optional custom APN, null-terminated string.

bool certification_mode

Connect to certification servers if true, connect to production servers otherwise

LWM2M carrier library events

group lwm2m_carrier_event

Defines

LWM2M_CARRIER_EVENT_BSDLIB_INIT

BSD library initialized.

LWM2M_CARRIER_EVENT_CONNECTING

Connecting to the LTE network.

LWM2M_CARRIER_EVENT_CONNECTED

Connected to the LTE network.

LWM2M_CARRIER_EVENT_DISCONNECTING

Disconnecting from the LTE network.

LWM2M_CARRIER_EVENT_DISCONNECTED

Disconnected from the LTE network.

LWM2M_CARRIER_EVENT_BOOTSTRAPPED

LWM2M carrier bootstrapped.

LWM2M_CARRIER_EVENT_READY

LWM2M carrier registered.

LWM2M_CARRIER_EVENT_DEFERRED

LWM2M carrier operation is deferred.

LWM2M_CARRIER_EVENT_FOTA_START

Modem update started.

LWM2M_CARRIER_EVENT_REBOOT

Application will reboot.

LWM2M_CARRIER_EVENT_ERROR

An error occurred.

LWM2M_CARRIER_DEFERRED_NO_REASON

LWM2M carrier library event deferred reason.

No reason given.

LWM2M_CARRIER_DEFERRED_PDN_ACTIVATE

Failed to activate PDN.

LWM2M_CARRIER_DEFERRED_BOOTSTRAP_NO_ROUTE

No route to bootstrap server.

LWM2M_CARRIER_DEFERRED_BOOTSTRAP_CONNECT

Failed to connect to bootstrap server.

LWM2M_CARRIER_DEFERRED_BOOTSTRAP_SEQUENCE

Bootstrap sequence not completed.

LWM2M_CARRIER_DEFERRED_SERVER_NO_ROUTE

No route to server.

LWM2M_CARRIER_DEFERRED_SERVER_CONNECT

Failed to connect to server.

LWM2M_CARRIER_DEFERRED_SERVER_REGISTRATION

Server registration sequence not completed.

LWM2M_CARRIER_ERROR_NO_ERROR

LWM2M carrier library event error codes.

No error.

LWM2M_CARRIER_ERROR_CONNECT_FAIL

Failed to connect to the LTE network.

LWM2M_CARRIER_ERROR_DISCONNECT_FAIL

Failed to disconnect from the LTE network.

LWM2M_CARRIER_ERROR_BOOTSTRAP

LWM2M carrier bootstrap failed.

LWM2M_CARRIER_ERROR_FOTA_PKG

Update package rejected.

LWM2M_CARRIER_ERROR_FOTA_PROTO

Protocol error.

LWM2M_CARRIER_ERROR_FOTA_CONN

Connection error.

LWM2M_CARRIER_ERROR_FOTA_CONN_LOST

Connection lost.

LWM2M_CARRIER_ERROR_FOTA_FAIL

Update failed.

struct lwm2m_carrier_event_t
#include <lwm2m_carrier.h>

LWM2M carrier library event structure.

Public Members

uint32_t type

Event type.

const void *data

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

struct lwm2m_carrier_event_deferred_t
#include <lwm2m_carrier.h>

Public Members

uint32_t reason

Deferred event reason.

int32_t timeout

Time before operation is resumed (seconds).

struct lwm2m_carrier_event_error_t
#include <lwm2m_carrier.h>

LWM2M carrier library error event structure.

Public Members

uint32_t code

Error event code.

int32_t value

Error event value.

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, const 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_download_file_size_get(size_t *size)

Retrieve size of file being downloaded.

Parameters
  • size: Size of the file being downloaded.

int lwm2m_os_lte_power_down(void)
int lwm2m_os_errno(void)

Translate the error number.

const char *lwm2m_os_strerror(void)

Return a textual description for the current error.

int lwm2m_os_sec_ca_chain_exists(uint32_t sec_tag, bool *exists, uint8_t *perm)

Check if a certificate chain credential exists in persistent storage.

Parameters
  • [in] sec_tag: The tag to search for.

  • [out] exists: Whether the credential exists. Only valid if the operation is successful.

  • [out] perm: The permission flags of the credential. Not yet implemented.

Return Value
  • 0: On success.

  • -ENOBUFS: Insufficient memory.

  • -EPERM: Insufficient permissions.

int lwm2m_os_sec_ca_chain_cmp(uint32_t sec_tag, const void *buf, size_t len)

Compare a certificate chain.

Parameters
  • [in] sec_tag: Security tag associated with the certificate chain.

  • [in] buf: Buffer to compare the certificate chain to.

  • [in] len: Length of the certificate chain.

Return Value
  • 0: If the certificate chain match.

  • 1: If the certificate chain do not match.

  • <: 0 On error.

int lwm2m_os_sec_ca_chain_write(uint32_t sec_tag, const void *buf, size_t len)

Provision a certificate chain or update an existing one.

Note

If used when the LTE link is active, the function will return an error and the key will not be written.

Parameters
  • [in] sec_tag: Security tag for this credential.

  • [in] buf: Buffer containing the credential data.

  • [in] len: Length of the buffer.

Return Value
  • 0: On success.

  • -EINVAL: Invalid parameters.

  • -ENOBUFS: Internal buffer is too small.

  • -EACCES: The operation failed because the LTE link is active.

  • -ENOMEM: Not enough memory to store the credential.

  • -ENOENT: The security tag could not be written.

  • -EPERM: Insufficient permissions.

int lwm2m_os_sec_psk_exists(uint32_t sec_tag, bool *exists, uint8_t *perm_flags)

Check if a pre-shared key exists in persistent storage.

Parameters
  • [in] sec_tag: The tag to search for.

  • [out] exists: Whether the credential exists. Only valid if the operation is successful.

  • [out] perm_flags: The permission flags of the credential. Only valid if the operation is successful and exists is true. Not yet implemented.

Return Value
  • 0: On success.

  • -ENOBUFS: Internal buffer is too small.

  • -EPERM: Insufficient permissions.

  • -EIO: Internal error.

int lwm2m_os_sec_psk_write(uint32_t sec_tag, const void *buf, uint16_t len)

Provision a new pre-shared key or update an existing one.

Note

If used when the LTE link is active, the function will return an error and the key will not be written.

Parameters
  • [in] sec_tag: Security tag for this credential.

  • [in] buf: Buffer containing the credential data.

  • [in] len: Length of the buffer.

Return Value
  • 0: On success.

  • -EINVAL: Invalid parameters.

  • -ENOBUFS: Internal buffer is too small.

  • -ENOMEM: Not enough memory to store the credential.

  • -EACCES: The operation failed because the LTE link is active.

  • -ENOENT: The security tag could not be written.

  • -EPERM: Insufficient permissions.

  • -EIO: Internal error.

int lwm2m_os_sec_psk_delete(uint32_t sec_tag)

Delete pre-shared key.

Note

If used when the LTE link is active, the function will return an error and the key will not be deleted.

Parameters
  • [in] sec_tag: Security tag for this credential.

Return Value
  • 0: On success.

  • -ENOBUFS: Internal buffer is too small.

  • -EACCES: The operation failed because the LTE link is active.

  • -ENOENT: No credential associated with the given sec_tag and cred_type.

  • -EPERM: Insufficient permissions.

int lwm2m_os_sec_identity_exists(uint32_t sec_tag, bool *exists, uint8_t *perm_flags)

Check if an identity credential exists in persistent storage.

Parameters
  • [in] sec_tag: The tag to search for.

  • [out] exists: Whether the credential exists. Only valid if the operation is successful.

  • [out] perm_flags: The permission flags of the credential. Only valid if the operation is successful and exists is true. Not yet implemented.

Return Value
  • 0: On success.

  • -ENOBUFS: Internal buffer is too small.

  • -EPERM: Insufficient permissions.

  • -EIO: Internal error.

int lwm2m_os_sec_identity_write(uint32_t sec_tag, const void *buf, uint16_t len)

Provision a new identity credential or update an existing one.

Note

If used when the LTE link is active, the function will return an error and the key will not be written.

Parameters
  • [in] sec_tag: Security tag for this credential.

  • [in] buf: Buffer containing the credential data.

  • [in] len: Length of the buffer.

Return Value
  • 0: On success.

  • -EINVAL: Invalid parameters.

  • -ENOBUFS: Internal buffer is too small.

  • -ENOMEM: Not enough memory to store the credential.

  • -EACCES: The operation failed because the LTE link is active.

  • -ENOENT: The security tag could not be written.

  • -EPERM: Insufficient permissions.

  • -EIO: Internal error.

int lwm2m_os_sec_identity_delete(uint32_t sec_tag)

Delete identity credential.

Note

If used when the LTE link is active, the function will return an error and the key will not be deleted.

Parameters
  • [in] sec_tag: Security tag for this credential.

Return Value
  • 0: On success.

  • -ENOBUFS: Internal buffer is too small.

  • -EACCES: The operation failed because the LTE link is active.

  • -ENOENT: No credential associated with the given sec_tag and cred_type.

  • -EPERM: Insufficient permissions.

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.