API documentation

Following are the LwM2M carrier and LwM2M OS abstraction layer API elements used by the library:

LwM2M carrier library

Header files: lib/bin/lwm2m_carrier/include/lwm2m_carrier.h
Source files: lib/bin/lwm2m_carrier/os/lwm2m_carrier.c

LwM2M carrier library start up

group lwm2m_carrier_init

You can configure the carrier library startup using the structs and macros defined here.

When calling lwm2m_carrier_main you can either give NULL as a parameter to use default settings, or give a lwm2m_carrier_config_t to use custom settings. For example to connect to a different server than the factory default, carrier defined servers.

LwM2M enabled carriers

To be set in lwm2m_carrier_config_t::carriers_enabled.

LWM2M_CARRIER_GENERIC

If the detected SIM Subscriber ID does not match any of the enabled carriers, the LwM2M carrier library will run in generic mode and connect to a custom server. See lwm2m_carrier_config_t::server_uri.

LWM2M_CARRIER_VERIZON

If the Verizon SIM Subscriber ID is detected (device is in the Verizon network), the LwM2M Carrier library will connect to a LwM2M Device Management server specified by Verizon.

LWM2M_CARRIER_LG_UPLUS

If the LG U+ SIM Subscriber ID is detected (device is in the LG U+ network), the LwM2M Carrier library will connect to a LwM2M Device Management server specified by LG U+.

LWM2M_CARRIER_T_MOBILE

If the T-Mobile SIM Subscriber ID is detected (device is in the T-Mobile network), the LwM2M Carrier library will connect to a LwM2M Device Management server specified by T-Mobile.

LWM2M_CARRIER_SOFTBANK

If the Softbank SIM Subscriber ID is detected (device is in the Softbank network), the LwM2M Carrier library will connect to a LwM2M Device Management server specified by Softbank.

LWM2M_CARRIER_BELL_CA

If the Bell Canada SIM Subscriber ID is detected (device is in the Bell Canada network), the LwM2M Carrier library will connect to a LwM2M Device Management server specified by Bell Canada.

LwM2M Server binding

To be set in lwm2m_carrier_config_t::server_binding.

LWM2M_CARRIER_SERVER_BINDING_UDP

Allow the server to connect using UDP.

LWM2M_CARRIER_SERVER_BINDING_NONIP

Allow the server to connect using Non-IP.

PDN types

To be set in lwm2m_carrier_config_t::pdn_type.

LWM2M_CARRIER_PDN_TYPE_IPV4V6

Both IPv4 and IPv6 are supported on this PDN.

LWM2M_CARRIER_PDN_TYPE_IPV4

Only IPv4 is supported on this PDN.

LWM2M_CARRIER_PDN_TYPE_IPV6

Only IPv6 is supported on this PDN.

LWM2M_CARRIER_PDN_TYPE_NONIP

Only Non-IP (NIDD) is on this PDN.

LG U+ Device Serial Number types

To be set in lwm2m_carrier_lg_uplus_config_t::device_serial_no_type.

LWM2M_CARRIER_LG_UPLUS_DEVICE_SERIAL_NO_IMEI

Use the IMEI as the serial number for identification to the LG U+ network.

LWM2M_CARRIER_LG_UPLUS_DEVICE_SERIAL_NO_2DID

Use the the two-dimensional barcode etched on top of the module as the serial number for identification in the LG U+ network.

Functions

int lwm2m_carrier_main(const lwm2m_carrier_config_t *config)

LwM2M carrier library main function.

Note

This function is intended to run on a separate thread. The function will only exit on configuration errors and non-recoverable errors.

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

Parameters:

  • config – [in] Configuration parameters for the library. Optional.

Return values:

  • 0 – If library main function exited on an unrecoverable error or a deferred reboot.

  • -EINVAL – If configuration parameters are invalid. See lwm2m_carrier_config_t

  • -EFAULT – If library failed due to an internal error.

struct lwm2m_carrier_lg_uplus_config_t
#include <lwm2m_carrier.h>

LG U+ configuration structure. To be set in lwm2m_carrier_config_t::lg_uplus.

Public Members

const char *service_code

LG U+ Service Code registered for this device. Null-terminated string of at most 5 characters.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_LG_UPLUS_SERVICE_CODE.

uint8_t device_serial_no_type

Indicates the type of Device Serial Number to be used in the LG U+ network. See lwm2m_carrier_lg_uplus_device_serial_no_values.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_LG_UPLUS_DEVICE_SERIAL_NUMBER.

struct lwm2m_carrier_config_t
#include <lwm2m_carrier.h>

Structure holding LwM2M carrier library initialization parameters. Used as a parameter when calling lwm2m_carrier_main().

Public Members

uint32_t carriers_enabled

Configure enabled carriers.

This configuration allows you to choose the networks on which the carrier library will apply. It also determines the working of the following server configurations:

These server configurations will:

  • configure a custom server when LWM2M_CARRIER_GENERIC is set,

  • overwrite the factory bootstrap configuration if only one carrier is selected,

  • be ignored if multiple carriers are selected but not LWM2M_CARRIER_GENERIC (default).

See lwm2m_carrier_carriers_values. All carriers are enabled when no bits are set.

Note

using lwm2m_carrier.c these carriers can be set using kconfig

  • CONFIG_LWM2M_CARRIER_GENERIC

  • CONFIG_LWM2M_CARRIER_VERIZON

  • CONFIG_LWM2M_CARRIER_BELL_CA

  • CONFIG_LWM2M_CARRIER_LG_UPLUS

  • CONFIG_LWM2M_CARRIER_T_MOBILE

  • CONFIG_LWM2M_CARRIER_SOFTBANK

bool disable_auto_register

This configuration allows you to disable automatic registration upon LTE Attach.

This option is only used for LWM2M_CARRIER_GENERIC and LWM2M_CARRIER_SOFTBANK. In other carriers you are not allowed to disable automatic registration.

When this option is set you need to manually register using LWM2M_CARRIER_REQUEST_REGISTER.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_AUTO_REGISTER to false.

bool disable_bootstrap_from_smartcard

This configuration allows you to disable bootstrap from smartcard.

This option is only used for LWM2M_CARRIER_GENERIC, LWM2M_CARRIER_T_MOBILE and LWM2M_CARRIER_BELL_CA. In other carriers bootstrap from smartcard is always disabled.

When this option is set, you disable reading bootstrap information from the smartcard (SIM card).

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_BOOTSTRAP_SMARTCARD to false.

bool disable_queue_mode

This configuration allows you to disable queue mode.

By default the library will inform the LwM2M Server that it may be disconnected for an extended period of time. The server will then queue their requests until the library does a registration update.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_QUEUE_MODE to false.

bool is_bootstrap_server

Denotes whether lwm2m_carrier_config_t::server_uri is an LwM2M Bootstrap-Server.

This configuration is ignored if lwm2m_carrier_config_t::server_uri is not set.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_IS_BOOTSTRAP_SERVER.

const char *server_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. Null-terminated string of max 255 characters.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_CUSTOM_URI.

uint32_t server_sec_tag

This configuration provides the library with a security tag. The security tag must contain a PSK, and can additionally contain a PSK identity.

This configuration should normally be left empty (0) unless stated by the operator, or when connecting to a custom URI.

  • If left empty, the library will automatically apply the correct PSK and PSK identity for the carrier device management server, depending on the detected SIM Subscriber ID.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_SERVER_SEC_TAG.

uint8_t server_binding

This configuration can be used to overwrite the server binding. See lwm2m_carrier_server_binding_values.

This configuration is ignored if a bootstrap server is configured (either by the carrier’s factory configuration, or by lwm2m_carrier_config_t::is_bootstrap_server.)

If UDP binding is configured, a URI must also be set lwm2m_carrier_config_t::server_uri.

The APN (either network default, or the one set with lwm2m_carrier_config_t::apn) must be UDP (IP) or non-IP respectively.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_SERVER_BINDING.

int32_t server_lifetime

This configuration specifies the lifetime of the LwM2M Server.

This configuration is ignored if a bootstrap server is configured (either by our factory configuration, or by lwm2m_carrier_config_t::is_bootstrap_server.

  • If this configuration is left empty (0) the factory configuration is used. This can be different for each supported carrier. For generic operation (LWM2M_CARRIER_GENERIC), the default is 1 hour.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_SERVER_LIFETIME.

int32_t session_idle_timeout

This configuration specifies the session idle (inactivity) timeout.

Upon timeout two things can happen:

  1. If a secure session is used, the LwM2M carrier library closes the DTLS session. A new DTLS session will be created on the next activity (for example, lifetime trigger). This does not apply when the DTLS session is using Connection ID.

  2. If a non-default PDP context (CID different than 0) is used, and there is no activity scheduled within 15 minutes, the PDP context is released.

  • Leaving this configuration empty (0) sets it to a default of 60 seconds.

  • Setting this configuration to -1 disables the session idle timeout.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_SESSION_IDLE_TIMEOUT.

int32_t coap_con_interval

This configuration specifies how often to send a Confirmable (CON) message instead of a Non-Confirmable (NON) 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.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_COAP_CON_INTERVAL.

uint16_t firmware_download_timeout

This configuration specifies the time (in minutes) allowed for a single firmware image download.

If the download is not completed by the time the specified number of minutes elapses, the download shall be aborted. This configuration is only supported for Push delivery method of firmware images.

  • Leaving this configuration empty (0) sets the timer to 30 minutes for the SoftBank subscriber ID, and disables it for all other subscriber IDs.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_FIRMWARE_DOWNLOAD_TIMEOUT.

const char *apn

This configuration can provide an APN to use instead of the default APN.

For LWM2M_CARRIER_VERIZON this configuration is ignored.

Null-terminated string of max 63 characters.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_CUSTOM_APN.

uint8_t pdn_type

This configuration selects the PDN type of the custom APN lwm2m_carrier_config_t::apn.

See lwm2m_carrier_pdn_type_values.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_PDN_TYPE.

const char *manufacturer

This configuration allows you to override the Manufacturer resource in the OMA LwM2M Device object (/3/0/0). This is only allowed for LWM2M_CARRIER_LG_UPLUS and LWM2M_CARRIER_GENERIC.

Null-terminated string of max 32 characters.

  • By default the manufacturer is read from the modem: “Nordic Semiconductor ASA”.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_DEVICE_MANUFACTURER.

const char *model_number

This configuration allows you to override the Model Number resource in the OMA LwM2M Device object (/3/0/1). This is only allowed for LWM2M_CARRIER_LG_UPLUS and LWM2M_CARRIER_GENERIC.

Null-terminated string of max 32 characters.

  • By default the model_number is read from the modem, for example: “nRF9160”.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_DEVICE_MODEL_NUMBER.

const char *device_type

This configuration allows you to override the Device Type resource in the OMA LwM2M Device object (/3/0/17).

Null-terminated string of max 32 characters.

  • By default the device_type is set to “Module”.

  • For LWM2M_CARRIER_SOFTBANK the device_type cannot be set and is always the IMEI.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_DEVICE_TYPE.

const char *hardware_version

This configuration allows you to override the Hardware Version resource in the OMA LwM2M Device object (/3/0/18).

Null-terminated string of max 32 characters.

  • By default the hardware_version is read from the modem, for example: “nRF9161 LACA ADA”.

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_HARDWARE_VERSION.

const char *software_version

This configuration allows you to add a string to the Software Version resource in the OMA LwM2M Device object (/3/0/19). The string is added to the LwM2M Carrier library version and separated with a new line ‘\n’. This allows the application to indicate its version to the server independently of the LwM2M carrier library version.

Null-terminated string of max 32 characters.

  • By default the software_version contains only the LwM2M carrier library version, for example: “LwM2M_carrier_1.2.3”.

  • For LWM2M_CARRIER_SOFTBANK, ‘:’ is used to separate the two strings in software_version. and the LwM2M carrier library, for example “LwM2M_carrier_1.2.3:<my_app_version>”

Note

using lwm2m_carrier.c this option can be set in kconfig by setting CONFIG_LWM2M_CARRIER_SOFTWARE_VERSION.

lwm2m_carrier_lg_uplus_config_t lg_uplus

LG U+ configuration, only required for devices certifying with LWM2M_CARRIER_LG_UPLUS.

LwM2M carrier library events

group lwm2m_carrier_events

Events generated by the carrier library

The lwm2m_carrier_event_handler() function may be implemented by your application. A __weak implementation is included in lwm2m_carrier.c.

LwM2M carrier library events

Used in lwm2m_carrier_event_t::type

This event indicates that the device must connect to the LTE network.

This event is triggered:

This event indicates that the device must disconnect from the LTE network. The link must be offline until a subsequent LWM2M_CARRIER_EVENT_LTE_LINK_UP event.

This event is triggered:

LWM2M_CARRIER_EVENT_LTE_POWER_OFF

This event indicates that the device must power off the modem.

This event is triggered:

  • Before a reboot.

  • Before a modem shutdown when applying a new modem firmware.

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 just for your information, nothing needs to be done.

This event is triggered for carriers that use a bootstrap server (all except LWM2M_CARRIER_SOFTBANK):

  • In case of LWM2M_CARRIER_LG_UPLUS at every startup.

  • For all other carriers only at first startup.

  • After doing a full erase of the flash (same as “first startup”).

  • After switching SIM card to a different carrier that uses a bootstrap server.

  • After the server has executed the OMA LwM2M Server object Bootstrap-request trigger resource (/1/x/9).

  • After the server has executed the OMA LwM2M Device object Factory Reset resource (/3/0/5).

LWM2M_CARRIER_EVENT_REGISTERED

This event indicates that the device has registered successfully to the carrier’s device management servers. This means the connection to the server has been set up successfully and the server can now start to read, write and execute LwM2M resources. This event is just for your information, nothing needs to be done.

It can be used as an indication that the LwM2M carrier library is done asking the application to LWM2M_CARRIER_EVENT_LTE_LINK_UP and LWM2M_CARRIER_EVENT_LTE_LINK_DOWN. D(TLS) connection setups will not be needed by the carrier library until the server issues an operation such as a firmware update.

This event is triggered for the first successful registration to the server:

LWM2M_CARRIER_EVENT_DEREGISTERED

This event indicates that the device has successfully deregistered from the carrier’s device management servers. This event is just for your information, nothing needs to be done.

This event is triggered:

LWM2M_CARRIER_EVENT_DEFERRED

This event indicates that the connection to the device management server has failed and will be retried later. This event is just for your information, nothing needs to be done.

The LWM2M_CARRIER_EVENT_DEFERRED event can appear instead of the LWM2M_CARRIER_EVENT_BOOTSTRAPPED or the LWM2M_CARRIER_EVENT_REGISTERED event.

lwm2m_carrier_event_t::data contains lwm2m_carrier_event_deferred_t to indicate what triggered the event.

LWM2M_CARRIER_EVENT_FOTA_START

This event indicates that the firmware update has started.

The application must immediately terminate any open TLS and DTLS sessions. The download might happen on a secure socket, which is a limited modem resource.

lwm2m_carrier_event_t::data contains lwm2m_carrier_event_fota_start_t.

This event is triggered:

  • When the server pushes a firmware package to the OMA LwM2M Firmware object Package resource (/5/0/0). In this case, lwm2m_carrier_event_fota_start_t is empty.

  • When the server writes a URI to the OMA LwM2M Firmware object Package URI resource (/5/0/1). In this case, lwm2m_carrier_event_fota_start_t contains the URI of the package that will be downloaded.

LWM2M_CARRIER_EVENT_FOTA_SUCCESS

This event indicates that the FOTA procedure was successful. This event is just for your information, nothing needs to be done.

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.

This event is triggered:

  • After switching SIM to a different carrier.

  • After the server has executed the OMA LwM2M Firmware object Update resource (/5/0/2) when an application update is performed.

  • After the server has executed the OMA LwM2M Device object Reboot resource (/3/0/4).

LWM2M_CARRIER_EVENT_MODEM_DOMAIN

This event indicates a modem domain event. This event is just for your information, nothing needs to be done.

lwm2m_carrier_event_t::data contains lwm2m_carrier_event_modem_domain_t to indicate what triggered the event.

Note

Deprecated, you can instead get this information from the link controller library.

LWM2M_CARRIER_EVENT_APP_DATA

This event indicates that data was received through the App Data Container object or the Binary App Data Container object.

This event is triggered:

  • After the server has written to the OMA LwM2M BinaryAppDataContainer object Data resource (/19/x/0/y).

  • After the server has written to the Huawei LwM2M App Data Container object Data resource (/10250/0/1).

lwm2m_carrier_event_t::data contains lwm2m_carrier_event_app_data_t.

LWM2M_CARRIER_EVENT_MODEM_INIT

This event indicates that the application must initialize the modem for the LwM2M carrier library to proceed.

This event is triggered:

  • During FOTA procedures to reinitialize the Modem library integration layer.

LWM2M_CARRIER_EVENT_MODEM_SHUTDOWN

This event indicates that the application must shut down the modem for the LwM2M carrier library to proceed.

This event is triggered:

  • During FOTA procedures to reinitialize the Modem library integration layer.

LWM2M_CARRIER_EVENT_ERROR_CODE_RESET

This event indicates that the server has reset the error codes resource in the OMA LwM2M Device object Error Code resource (/3/0/11). The errors should be re-evaluated and set again if they still apply. The relevant APIs for setting the error codes are lwm2m_carrier_error_code_add() and lwm2m_carrier_error_code_remove().

This event is triggered:

  • After the server has executed the OMA LwM2M Device object Reset Error Code resource (/3/0/12).

LWM2M_CARRIER_EVENT_ERROR

This event indicates an error. This event is just for your information, no logic is needed in the application to resolve the error. During development this likely indicates a misconfiguration that needs to be resolved.

lwm2m_carrier_event_t::data contains lwm2m_carrier_event_error_t to indicate what triggered the error using lwm2m_carrier_error_values.

LwM2M carrier library modem domain event types

LWM2M_CARRIER_MODEM_EVENT_ME_OVERHEATED

Mobile Equipment (ME) is overheated and therefore the modem is deactivated.

LWM2M_CARRIER_MODEM_EVENT_ME_BATTERY_LOW

Mobile Equipment (ME) battery voltage is low and therefore the modem is deactivated.

LWM2M_CARRIER_MODEM_EVENT_RESET_LOOP

Modem has detected a reset loop and will restrict Attach attempts for the next 30 minutes.

LwM2M carrier library app data event types

Used in lwm2m_carrier_event_app_data_t::type.

LWM2M_CARRIER_APP_DATA_EVENT_DATA_WRITE

Data was written to a resource in an app data container object.

LWM2M_CARRIER_APP_DATA_EVENT_OBSERVE_START

An observation has started on a resource in an app data container object.

LWM2M_CARRIER_APP_DATA_EVENT_OBSERVE_STOP

An observation has stopped on a resource in an app data container object.

LwM2M carrier library event deferred reasons

Used in lwm2m_carrier_event_deferred_t::reason

LWM2M_CARRIER_DEFERRED_NO_REASON

No reason given.

LWM2M_CARRIER_DEFERRED_PDN_ACTIVATE

Failed to activate PDN. This event indicates a problem with the SIM card, or temporary network problems. If this persists, contact the carrier.

LWM2M_CARRIER_DEFERRED_BOOTSTRAP_NO_ROUTE

No route to bootstrap server. There is a routing problem in the carrier network. If this event persists, contact the carrier.

LWM2M_CARRIER_DEFERRED_BOOTSTRAP_CONNECT

Failed to connect to bootstrap server. 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

Bootstrap sequence not completed. 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

No route to server. There is a routing problem in the carrier network. If this event persists, contact the carrier.

LWM2M_CARRIER_DEFERRED_SERVER_CONNECT

Failed to connect to server. 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

Server registration sequence not completed. 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

Server in maintenance mode. The server is unavailable, for example due to maintenance. In the Verizon network, this event can be triggered by the server to block excessive numbers of bootstrap and connections.

LWM2M_CARRIER_DEFERRED_SIM_MSISDN

Waiting for SIM MSISDN. The device is waiting for the SIM MSISDN to be available to read.

LwM2M carrier library event error types

Used in lwm2m_carrier_event_error_t::type.

LWM2M_CARRIER_ERROR_NO_ERROR

No error.

Failed to connect to the LTE network.

Failed to disconnect from the LTE network.

LWM2M_CARRIER_ERROR_BOOTSTRAP

LwM2M carrier bootstrap failed.

LWM2M_CARRIER_ERROR_FOTA_FAIL

Firmware update failed. value:

  • -ECONNREFUSED Connection refused using available security tags.

  • -ENOTSUP Protocol not supported.

  • -ENOMEM Too many open connections.

  • -EBADF Incorrect firmware update version.

LWM2M_CARRIER_ERROR_CONFIGURATION

Illegal object configuration detected.

LWM2M_CARRIER_ERROR_INIT

LwM2M carrier init failed.

LWM2M_CARRIER_ERROR_RUN

LwM2M carrier run failed.

LWM2M_CARRIER_ERROR_CONNECT

LwM2M carrier connect failed.

Typedefs

typedef uint32_t lwm2m_carrier_event_modem_domain_t

LwM2M carrier library modem domain event type lwm2m_carrier_modem_events_values. Used for LWM2M_CARRIER_EVENT_MODEM_DOMAIN.

Functions

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.

Parameters:

  • event – [in] LwM2M carrier event that occurred.

Returns:

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 reboot at the earliest convenient time.

struct lwm2m_carrier_event_fota_start_t
#include <lwm2m_carrier.h>

LwM2M carrier library firmware update event structure. Used for LWM2M_CARRIER_EVENT_FOTA_START.

Public Members

const char *uri

URI from where the firmware will be downloaded. Set to NULL if no URI will be used.

struct lwm2m_carrier_event_app_data_t
#include <lwm2m_carrier.h>

LwM2M carrier library app data event structure. Used for LWM2M_CARRIER_EVENT_APP_DATA.

Public Members

const uint8_t *buffer

Buffer containing received application data.

size_t buffer_len

Number of bytes received.

uint16_t path[4]

Path to the resource or resource instance that received the data. The first value will be either LWM2M_CARRIER_OBJECT_BINARY_APP_DATA_CONTAINER or LWM2M_CARRIER_OBJECT_APP_DATA_CONTAINER.

uint8_t path_len

Length of the path.

uint8_t type

lwm2m_carrier_app_data_event_values.

struct lwm2m_carrier_event_deferred_t
#include <lwm2m_carrier.h>

LwM2M carrier library deferred event structure. Used for LWM2M_CARRIER_EVENT_DEFERRED.

Public Members

uint32_t reason

lwm2m_carrier_deferred_values.

int32_t timeout

Time before the LwM2M carrier library will retry the connection (seconds).

struct lwm2m_carrier_event_error_t
#include <lwm2m_carrier.h>

LwM2M carrier library error event structure. Used for LWM2M_CARRIER_EVENT_ERROR.

Public Members

uint32_t type

lwm2m_carrier_error_values.

int32_t value

Error event value.

struct lwm2m_carrier_event_t
#include <lwm2m_carrier.h>

LwM2M carrier library event structure. Used to pass on events through lwm2m_carrier_event_handler().

Public Members

uint32_t type

lwm2m_carrier_event_values

lwm2m_carrier_event_fota_start_t *fota_start

LWM2M_CARRIER_EVENT_FOTA_START

lwm2m_carrier_event_modem_domain_t *modem_domain

LWM2M_CARRIER_EVENT_MODEM_DOMAIN

lwm2m_carrier_event_app_data_t *app_data

LWM2M_CARRIER_EVENT_APP_DATA

lwm2m_carrier_event_deferred_t *deferred

LWM2M_CARRIER_EVENT_DEFERRED

lwm2m_carrier_event_error_t *error

LWM2M_CARRIER_EVENT_ERROR

union lwm2m_carrier_event_t.[anonymous] data

Pointer to event data, according to event type.

LwM2M carrier library API

group lwm2m_carrier_api

This section describes the needed interaction between the LwM2M carrier library and the user application.

LwM2M carrier library modem initialization results

Used to pass on the modem update result in lwm2m_carrier_on_modem_init().

LWM2M_CARRIER_MODEM_INIT_SUCCESS

Modem initialization successful.

LWM2M_CARRIER_MODEM_INIT_UPDATED

Modem firmware update successful.

LWM2M_CARRIER_MODEM_INIT_UPDATE_FAILED

Modem firmware update failed.

LwM2M carrier requests

Used in lwm2m_carrier_request().

LWM2M_CARRIER_REQUEST_REBOOT

Request a system reboot.

Indicate to the LwM2M carrier library that the application is about to go online. A LWM2M_CARRIER_EVENT_LTE_LINK_UP will be generated once the library is ready.

indicate to the LwM2M carrier library that the application is about to go offline. A LWM2M_CARRIER_EVENT_LTE_LINK_DOWN will be generated once the library is ready.

LWM2M_CARRIER_REQUEST_REGISTER

Schedule a register operation to all configured LwM2M servers. If the server is already registered, a registration update will be scheduled instead.

Only used for LWM2M_CARRIER_SOFTBANK and LWM2M_CARRIER_GENERIC. This is necessary if lwm2m_carrier_config_t::disable_auto_register is set.

LWM2M_CARRIER_REQUEST_DEREGISTER

Schedule a deregister operation to all connected LwM2M servers.

Only used for LWM2M_CARRIER_SOFTBANK and LWM2M_CARRIER_GENERIC.

Functions

void lwm2m_carrier_on_modem_init(int result)

LwM2M carrier library modem initialization handler.

This function must be called whenever the modem is initialized, as otherwise the device management services will not be enabled.

Note

This is already implemented in lwm2m_carrier.c.

Parameters:
void lwm2m_carrier_on_modem_cfun(int mode)

LwM2M carrier library modem functional mode handler.

This function must be called whenever modem functional mode is changed.

Note

This is already implemented in lwm2m_carrier.c.

Parameters:

  • mode – [in] Modem functional mode.

void lwm2m_carrier_on_modem_shutdown(void)

LwM2M carrier library modem shutdown handler.

This function must be called whenever the modem is shut down, as it will shut down the device management services.

Note

This is already implemented in lwm2m_carrier.c.

int lwm2m_carrier_request(int request)

Request the LwM2M carrier library to perform an action.

This function will behave differently depending on the chosen request.

Parameters:
Return values:

  • 0 – If all requests were scheduled successfully.

  • -EINVAL – If an invalid request was selected.

  • -EPERM – If the selected request is not supported for the carrier.

  • -EBADR – If the selected request was not scheduled.

  • -EALREADY – If a registration was requested when a registration was already scheduled.

int lwm2m_carrier_data_send(const uint16_t *path, uint8_t path_len)

Schedule an OMA LwM2M Send operation for a resource. This will push an update of a value to the server without the server needing to observe or read the resource.

This operation is only supported for resources of the OMA LwM2M Opaque type.

Parameters:

  • path – [in] The path of the resource or resource instance to be sent. The path contains the object id, object instance id, resource id and resource instance id in order.

  • path_len – [in] The length of the path. Must be 3 or 4.

Return values:

  • 0 – If the data has been scheduled to be sent successfully.

  • -EPERM – If the operation was attempted on a resource that is not readable.

  • -ENOENT – If the path points to something that is not yet initialized.

  • -EINVAL – If the operation was attempted on an unsupported resource.

  • -EINPROGRESS – If the operation was attempted while a send request was already in progress.

  • -ECANCELED – If the Mute Send resource is enabled for the LwM2M server.

int lwm2m_carrier_custom_init(lwm2m_carrier_config_t *config)

Initialize the LwM2M carrier library with a custom configuration.

This function supplies the application with the config generated by Kconfig. This allows the application to inject or change configurations. The LwM2M shell and Serial LTE Modem application use this function to make the LwM2M configuration run-time configurable.

Note

A weak version of this function is supplied in lwm2m_carrier.c that does not change any configurations.

Parameters:

  • config – [in] Configuration parameters for the library.

LwM2M carrier library objects

group lwm2m_carrier_objects

This section describes commands to interact with values set in LwM2M objects in the carrier library. This allows you to communicate information to the LwM2M server.

LwM2M carrier library app data container objects

Used in lwm2m_carrier_app_data_set() and lwm2m_carrier_event_app_data_t to identify the application date object.

LWM2M_CARRIER_OBJECT_BINARY_APP_DATA_CONTAINER

Object identifier for OMA LwM2M BinaryAppDataContainer Object (/19).

Available in LWM2M_CARRIER_SOFTBANK and LWM2M_CARRIER_GENERIC.

LWM2M_CARRIER_OBJECT_APP_DATA_CONTAINER

Object identifier for Huawei LwM2M App Data Container Object (/10250).

Available in LWM2M_CARRIER_LG_UPLUS.

LwM2M device available power sources

Values for the OMA LwM2M Device object Available Power Sources resource (/3/0/6). Set using lwm2m_carrier_avail_power_sources_set().

LWM2M_CARRIER_POWER_SOURCE_DC
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 device error codes

Values for the OMA LwM2M Device object Error Code resource (/3/0/11).

Set using lwm2m_carrier_error_code_add() and cleared using lwm2m_carrier_error_code_remove().

LWM2M_CARRIER_ERROR_CODE_NO_ERROR
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 device battery status

Values for the OMA LwM2M Device object Battery Status resource (/3/0/20).

Set using lwm2m_carrier_battery_status_set().

Note

The battery status resource is only relevant if lwm2m_carrier_power_source_values has been set to LWM2M_CARRIER_POWER_SOURCE_INTERNAL_BATTERY.

LWM2M_CARRIER_BATTERY_STATUS_NORMAL
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 portfolio identity types

Resource instance identifiers (y) for the OMA LwM2M Portfolio object Identity resource (/16/x/0/y).

Used in lwm2m_carrier_identity_read() and lwm2m_carrier_identity_write().

LWM2M_CARRIER_IDENTITY_ID
LWM2M_CARRIER_IDENTITY_MANUFACTURER
LWM2M_CARRIER_IDENTITY_MODEL
LWM2M_CARRIER_IDENTITY_SW_VERSION

Functions

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

Read all time parameters.

Input NULL for the parameters to ignore.

Note

This function can be implemented by the application, if custom time management is needed. A __weak implementation is included inside the LwM2M carrier library which will read the time from modem.

Parameters:

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

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

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

int32_t lwm2m_carrier_utc_time_read(void)

Read the OMA LwM2M Device object Current Time resource (/3/0/13).

Note

This function can be implemented by the application, if custom time management is needed. A __weak implementation is included inside the LwM2M carrier library which will read the time from modem.

Returns:

Current UTC time since Epoch in seconds.

int lwm2m_carrier_utc_offset_read(void)

Read the OMA LwM2M Device object UTC Offset resource (/3/0/14).

Note

This function can be implemented by the application, if custom time management is needed. A __weak implementation is included inside the LwM2M carrier library which will read the offset from modem.

Returns:

UTC offset in minutes.

char *lwm2m_carrier_timezone_read(void)

Read of the OMA LwM2M Device object Timezone resource (/3/0/15).

Note

This function can be implemented by the application, if custom time management is needed. A __weak implementation is included inside the LwM2M carrier library which will read the timezone from modem.

Returns:

Null-terminated timezone string pointer, IANA Timezone (TZ) database format.

int lwm2m_carrier_utc_time_write(int32_t time)

Write to the OMA LwM2M Device object Current Time resource (/3/0/13).

Note

This function can be implemented by the application, if custom time management is needed. A __weak implementation is included inside the LwM2M carrier library which will write the time to modem.

Parameters:

  • time – [in] Time since Epoch in seconds.

Return values:

0 – If success.

int lwm2m_carrier_utc_offset_write(int offset)

Write to the OMA LwM2M Device object UTC Offset resource (/3/0/14).

Note

This function can be implemented by the application, if custom time management is needed. A __weak implementation is included inside the LwM2M carrier library which will write the offset to modem.

Parameters:

  • offset – [in] UTC offset in minutes.

Return values:

0 – If success.

int lwm2m_carrier_timezone_write(const char *tz)

Write to the OMA LwM2M Device object Timezone resource (/3/0/15).

Note

This function can be implemented by the application, if custom time management is needed. A __weak implementation is included inside the LwM2M carrier library which will write the timezone to modem.

Parameters:

  • tz – [in] Null-terminated time zone string pointer.

Return values:

0 – If success.

int lwm2m_carrier_avail_power_sources_set(const uint8_t *power_sources, uint8_t power_source_count)

Set the OMA LwM2M Device object Available Power Sources resource (/3/0/6).

It is necessary to call this function before any other device power source related functions listed in this file, as any updates of voltage/current measurements performed on power sources that have not been reported will be discarded. Upon consecutive calls of this function, the corresponding current and voltage measurements will be reset to 0. Similarly, the battery status will be set to UNKNOWN and the battery level to 0%.

Parameters:
Return values:

  • 0 – If the available power sources have been set successfully.

  • -E2BIG – If the reported number of power sources is bigger than the maximum supported.

  • -EINVAL – If one or more of the power sources are not supported.

  • -ENOENT – If LwM2M object is not initialized yet.

int lwm2m_carrier_power_source_voltage_set(uint8_t power_source, int32_t value)

Set the OMA LwM2M Device object Power Source Voltage resource (/3/0/7).

The power source source needs to be enabled first using lwm2m_carrier_avail_power_sources_set().

  • The default value of this resource is 0 (mV).

Parameters:

  • power_source – [in] Power source to which the measurement corresponds.

  • value – [in] Voltage measurement expressed in millivolt (mV).

Return values:

  • 0 – If the voltage measurements have been updated successfully.

  • -EINVAL – If the power source is not supported.

  • -ENODEV – If the power source is not listed as an available power source.

int lwm2m_carrier_power_source_current_set(uint8_t power_source, int32_t value)

Set the OMA LwM2M Device object Power Source Current resource (/3/0/8).

The power source source needs to be enabled first using lwm2m_carrier_avail_power_sources_set().

  • The default value of this resource is 0 (mA).

Parameters:

  • power_source – [in] Power source to which the measurement corresponds.

  • value – [in] Current measurement expressed in milliampere (mA).

Return values:

  • 0 – If the current measurements have been updated successfully.

  • -EINVAL – If the power source is not supported.

  • -ENODEV – If the power source is not listed as an available power source.

int lwm2m_carrier_battery_level_set(uint8_t battery_level)

Set the OMA LwM2M Device object Battery Level resource (/3/0/9).

LWM2M_CARRIER_POWER_SOURCE_INTERNAL_BATTERY needs to be enabled first using lwm2m_carrier_avail_power_sources_set().

  • The default value of this resource is 0 (%).

Parameters:

  • battery_level – [in] Internal battery level percentage (0-100).

Return values:

  • 0 – If the battery level has been updated successfully.

  • -EINVAL – If the specified battery level lies outside the 0-100% range.

  • -ENODEV – If internal battery is not listed as an available power source.

int lwm2m_carrier_battery_status_set(int32_t battery_status)

Set the OMA LwM2M Device object Battery Status resource (/3/0/20).

LWM2M_CARRIER_POWER_SOURCE_INTERNAL_BATTERY needs to be enabled first using lwm2m_carrier_avail_power_sources_set().

Parameters:
Return values:

  • 0 – If the battery status has been updated successfully.

  • -EINVAL – If the battery status is not supported.

  • -ENODEV – If internal battery is not listed as an available power source.

int lwm2m_carrier_error_code_add(int32_t error)

Set an error code in the OMA LwM2M Device object Error Code resource (/3/0/11).

At startup the error code is specified as 0, indicating no error. The error code is to be updated whenever a new error occurs. Or after an LWM2M_CARRIER_EVENT_ERROR_CODE_RESET event if the error code is still valid. Multiple error codes can be set, if the reported error is already present, the error code will remain unchanged.

Parameters:
Return values:

  • 0 – If the error code has been added successfully.

  • -EINVAL – If the error code is not supported.

  • -ENOENT – If LwM2M object is not initialized yet.

int lwm2m_carrier_error_code_remove(int32_t error)

Clear an error code in the OMA LwM2M Device object Error Code resource (/3/0/11).

Parameters:
Return values:

  • 0 – If the error has been removed successfully.

  • -EINVAL – If the error code is not supported.

  • -ENOENT – If the error to be removed is not present on the error code list.

int lwm2m_carrier_memory_total_set(uint32_t memory_total)

Set the OMA LwM2M Device object Memory Total resource (/3/0/21).

  • The default value of this resource is 0 (kB).

Parameters:

  • memory_total – [in] Total amount of storage space in kilobytes (kB).

Return values:

  • 0 – If the total amount of storage space has been set successfully.

  • -EINVAL – If the reported value is bigger than INT32_MAX.

int lwm2m_carrier_memory_free_read(void)

Read the OMA LwM2M Device object Memory Free resource (/3/0/10).

Note

This function must be implemented by the application in order to support the reporting of memory free, otherwise the returned value will be 0.

Returns:

Available amount of storage space expressed in kilobytes (kB).

int lwm2m_carrier_identity_read(uint16_t instance_id, uint16_t identity_type, char *buffer, uint16_t *buffer_len)

Read an identity in the OMA LwM2M Portfolio object Identity resource (/16/instance_id /0/identity_type ).

Note

If the provided buffer is NULL, the function will perform a dry run to determine the required buffer size (including the null terminator).

Parameters:

  • instance_id – [in] Portfolio object instance identifier.

  • identity_type – [in] Type of Identity field to be read (lwm2m_carrier_portfolio_identity_values).

  • buffer – [inout] Buffer where the null-terminated response will be stored.

  • buffer_len – [inout] Length of the provided buffer. Will return the number of bytes of the full response.

Return values:

  • 0 – If the operation was successful.

  • -ENOENT – If the instance does not exist.

  • -EINVAL – If the provided buffer length reference is NULL or the identity type is invalid.

  • -ENOMEM – If the provided buffer is too small.

int lwm2m_carrier_identity_write(uint16_t instance_id, uint16_t identity_type, const char *value)

Set an identity in the OMA LwM2M Portfolio object Identity resource (/16/instance_id /0/identity_type ).

Parameters:

  • instance_id – [in] Portfolio object instance identifier.

  • identity_type – [in] Type of Identity field to be written. (lwm2m_carrier_portfolio_identity_values).

  • value – [in] Null terminated string to be written into the Identity field.

Return values:

  • 0 – If the Identity field has been updated successfully.

  • -EPERM – If the specified object instance ID corresponds to the Primary Host identity.

  • -EINVAL – If the input argument is a NULL pointer or an empty string, or the identity type is invalid.

  • -ENOENT – If the instance does not exist.

  • -E2BIG – If the input string is too long.

  • -ENOMEM – If it was not possible to allocate memory storage to hold the string.

int lwm2m_carrier_portfolio_instance_create(uint16_t instance_id)

Create a new instance in the OMA LwM2M Portfolio object (/16/instance_id ).

Parameters:

  • instance_id – [in] The identifier to be used for the new instance.

Return values:

  • 0 – If the instance has been created successfully.

  • -ENOENT – If the object is not yet initialized.

  • -ENOMEM – If it was not possible to create the instance because the maximum number of supported object instances has already been reached.

  • -EINVAL – If the provided instance identifier is already in use.

int lwm2m_carrier_location_set(double latitude, double longitude, float altitude, uint32_t timestamp, float uncertainty)

Set your location in the OMA LwM2M Location object (/6/0).

  • The default all resource values of this object are set to 0.

Parameters:

  • latitude – [in] Latitude (/6/0/0) in degrees. Must be between -90.0 and 90.0.

  • longitude – [in] Longitude (/6/0/1) in degrees. Must be between -180.0 and 180.0.

  • altitude – [in] Altitude (/6/0/2) is meters over sea level.

  • timestamp – [in] Unix timestamp of the current GPS measurement (/6/0/5). Must not be older than the previous timestamp passed to this function.

  • uncertainty – [in] Positioning uncertainty given as a radius in meters (/6/0/3).

Return values:

  • 0 – If the location data has been updated successfully.

  • -EINVAL – If at least one input argument is incorrect.

  • -ENOENT – If the object is not yet initialized.

int lwm2m_carrier_velocity_set(int heading, float speed_h, float speed_v, float uncertainty_h, float uncertainty_v)

Set the OMA LwM2M Location object Velocity resource (/6/0/4). The Speed resource (/6/0/6) will be calculated from speed_h and * speed_v.

Optional float arguments shall be set to NAN if they are not available to the user.

Parameters:

  • heading – [in] Horizontal direction of movement in degrees clockwise from North. Valid range is 0 to 359.

  • speed_h – [in] Horizontal speed in meters per second. Must be non-negative.

  • speed_v – [in] Optional. Vertical speed in meters per second. Positive value indicates upward motion. Negative value indicates downward motion.

  • uncertainty_h – [in] Optional. Horizontal uncertainty speed, i.e. maximal deviation from the true speed, given in meters per second. Must be non-negative.

  • uncertainty_v – [in] Optional. Vertical uncertainty speed in meters per second. Must be non-negative.

Return values:

  • 0 – If the velocity data has been updated successfully.

  • -EINVAL – If at least one input argument is incorrect.

  • -ENOENT – If the object is not yet initialized.

  • -ENOMEM – If it was not possible to allocate memory storage to hold the velocity data.

int lwm2m_carrier_app_data_set(const uint16_t *path, uint16_t path_len, const uint8_t *buffer, size_t buffer_len)

Set application data in either the OMA LwM2M BinaryAppDataContainer Object (/19/x/1/y), or the Huawei LwM2M App Data Container Object (/10250/0/1).

This function sets the resource given by the path to the desired value. The resource can then be read by, or reported to, the LwM2M Server.

Note

LWM2M_CARRIER_OBJECT_BINARY_APP_DATA_CONTAINER is available in LWM2M_CARRIER_SOFTBANK and LWM2M_CARRIER_GENERIC. LWM2M_CARRIER_OBJECT_APP_DATA_CONTAINER is available in LWM2M_CARRIER_LG_UPLUS.

Parameters:
Return values:

  • 0 – If the resource has been set successfully.

  • -ENOENT – If the object is not initialized.

  • -EINVAL – If at least one input argument is incorrect.

  • -ENOMEM – If there is not enough memory to copy the buffer contents to the resource model.

int lwm2m_carrier_log_data_set(const uint8_t *buffer, size_t buffer_len)

Set the OMA LwM2M Event Log object LogData resource (/20/0/4014).

Note

The Event Log object is only available in LWM2M_CARRIER_SOFTBANK and LWM2M_CARRIER_GENERIC.

Parameters:

  • buffer – [in] Buffer containing the log data to be set.

  • buffer_len – [in] Number of bytes in the buffer.

Return values:

  • 0 – If the resource has been set successfully.

  • -ENOENT – If the object is not yet initialized.

  • -EINVAL – If the buffer is NULL.

  • -ENOMEM – If there is not enough memory to copy the buffer contents to the resource model.

OS abstraction layer

Header file: lib/bin/lwm2m_carrier/include/lwm2m_os.h
Source file: lib/bin/lwm2m_carrier/os/lwm2m_os.c

LwM2M OS layer

group lwm2m_carrier_os

Defines

LWM2M_OS_MAX_WORK_QS

Maximum number of work queues that the system must support.

LWM2M_OS_MAX_TIMER_COUNT

Maximum number of timers that the system must support.

LWM2M_OS_MAX_SEM_COUNT

Maximum number of semaphores that the system must support.

LWM2M_OS_LTE_MODE_NONE
LWM2M_OS_LTE_MODE_CAT_M1
LWM2M_OS_LTE_MODE_CAT_NB1
LWM2M_OS_STORAGE_BASE

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

LWM2M_OS_STORAGE_END
LWM2M_OS_DFU_HEADER_MAGIC
LWM2M_OS_DFU_HEADER_MAGIC_LEN
LWM2M_OS_DFU_HEADER_LEN

Typedefs

typedef int lwm2m_os_work_q_t
typedef int lwm2m_os_timer_t
typedef int lwm2m_os_sem_t
typedef void (*lwm2m_os_at_handler_callback_t)(const char *notif)

AT command error handler callback function.

typedef void (*lwm2m_os_timer_handler_t)(lwm2m_os_timer_t *timer)

Timer callback function.

typedef void (*lwm2m_os_sms_callback_t)(struct lwm2m_os_sms_data *const data, void *context)

SMS subscriber callback function.

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

Download client asynchronous event handler.

typedef void (*lwm2m_os_pdn_event_handler_t)(uint8_t cid, enum lwm2m_os_pdn_event event, int reason)

PDN event handler.

If assigned during PDP context creation, the event handler will receive status information relative to the Packet Data Network connection, as reported by the AT notifications CNEC and GGEV.

This handler is executed by the same context that dispatches AT notifications.

Enums

enum lwm2m_os_pdn_fam

PDN family.

Values:

enumerator LWM2M_OS_PDN_FAM_IPV4
enumerator LWM2M_OS_PDN_FAM_IPV6
enumerator LWM2M_OS_PDN_FAM_IPV4V6
enumerator LWM2M_OS_PDN_FAM_NONIP
enum lwm2m_os_pdn_event

PDN event.

Values:

enumerator LWM2M_OS_PDN_EVENT_CNEC_ESM
enumerator LWM2M_OS_PDN_EVENT_ACTIVATED
enumerator LWM2M_OS_PDN_EVENT_DEACTIVATED
enumerator LWM2M_OS_PDN_EVENT_IPV6_UP
enumerator LWM2M_OS_PDN_EVENT_IPV6_DOWN
enumerator LWM2M_OS_PDN_EVENT_NETWORK_DETACHED

Functions

int lwm2m_os_pdn_ctx_create(uint8_t *cid, lwm2m_os_pdn_event_handler_t cb)

Create a Packet Data Protocol (PDP) context.

If a callback is provided via the cb parameter, generate events from the CNEC and GGEV AT notifications to report state of the Packet Data Network (PDN) connection.

Parameters:

  • cid – [out] The ID of the new PDP context.

  • cb – Optional event handler.

Return values:

0 – If success.

int lwm2m_os_pdn_ctx_configure(uint8_t cid, const char *apn, enum lwm2m_os_pdn_fam family)

Configure a Packet Data Protocol context.

Parameters:

  • cid – The PDP context to configure.

  • apn – The Access Point Name to configure the PDP context with.

  • family – The family to configure the PDN context for.

Return values:

0 – If success.

int lwm2m_os_pdn_ctx_destroy(uint8_t cid)

Destroy a Packet Data Protocol context.

Parameters:

  • cid – The PDP context to destroy.

Return values:

0 – If success.

int lwm2m_os_pdn_activate(uint8_t cid, int *esm, enum lwm2m_os_pdn_fam *family)

Activate a Packet Data Network (PDN) connection.

Parameters:

  • cid – The PDP context ID to activate a connection for.

  • esm – [out] If provided, the function will block to return the ESM error reason.

  • family – [out] If provided, the function will block to return PDN_FAM_IPV4 if only IPv4 is supported, or PDN_FAM_IPV6 if only IPv6 is supported. Otherwise, this value will remain unchanged.

Return values:

0 – If success.

int lwm2m_os_pdn_deactivate(uint8_t cid)

Deactivate a Packet Data Network (PDN) connection.

Parameters:

  • cid – The PDP context ID.

Return values:

0 – If success.

int lwm2m_os_pdn_id_get(uint8_t cid)

Retrieve the PDN ID for a given PDP Context.

The PDN ID can be used to route traffic through a Packet Data Network.

Parameters:

  • cid – The context ID of the PDN connection.

Return values:

0 – If success.

int lwm2m_os_pdn_default_callback_set(lwm2m_os_pdn_event_handler_t cb)

Set a callback for events pertaining to the default PDP context (zero).

Parameters:

  • cb – The PDN event handler.

void *lwm2m_os_malloc(size_t size)

Allocate memory.

void lwm2m_os_free(void *ptr)

Free memory.

int lwm2m_os_sem_init(lwm2m_os_sem_t **sem, unsigned int initial_count, unsigned int limit)

Initialize a semaphore.

Parameters:

  • sem – Address of the pointer to the semaphore.

  • initial_count – Initial semaphore count.

  • limit – Maximum permitted semaphore count.

Return values:

  • 0 – Semaphore created successfully.

  • -EINVAL – Invalid values.

int lwm2m_os_sem_take(lwm2m_os_sem_t *sem, int timeout)

Take a semaphore.

Parameters:

  • sem – Address of the semaphore.

  • timeout – Timeout in ms, or -1 for forever, in which case the semaphore is taken for as long as necessary.

Return values:

  • 0 – Semaphore taken.

  • -EBUSY – Returned without waiting.

  • -EAGAIN – Waiting period timed out.

void lwm2m_os_sem_give(lwm2m_os_sem_t *sem)

Give a semaphore.

Parameters:

  • sem – Address of the semaphore.

void lwm2m_os_sem_reset(lwm2m_os_sem_t *sem)

Reset a semaphore.

Parameters:

  • sem – Address of the semaphore.

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.

Parameters:

  • ms – Desired duration of sleep in milliseconds.

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.

lwm2m_os_work_q_t *lwm2m_os_work_q_start(int index, const char *name)

Start a workqueue.

Parameters:

  • index – Number of the queue.

  • name – Name of the queue.

Returns:

Workqueue.

void lwm2m_os_timer_get(lwm2m_os_timer_handler_t handler, lwm2m_os_timer_t **timer)

Reserve a timer task from the OS.

Parameters:

  • handler – Function to run for this task.

  • timer – Assigned timer task.

void lwm2m_os_timer_release(lwm2m_os_timer_t *timer)

Release a timer task.

int lwm2m_os_timer_start(lwm2m_os_timer_t *timer, int64_t delay)

Start a timer on system work queue.

Parameters:

  • timer – Timer task.

  • delay – Delay before submitting the task in ms.

Return values:

  • 0 – Work placed on queue, already on queue or already running.

  • -EINVAL – Timer not found.

int lwm2m_os_timer_start_on_q(lwm2m_os_work_q_t *work_q, lwm2m_os_timer_t *timer, int64_t delay)

Start a timer on a specific queue.

Parameters:

  • work_q – Workqueue.

  • timer – Timer task.

  • delay – Delay before submitting the task in ms.

Return values:

  • 0 – Work placed on queue, already on queue or already running.

  • -EINVAL – Timer or work_q not found.

void lwm2m_os_timer_cancel(lwm2m_os_timer_t *timer, bool sync)

Cancel a timer run.

Parameters:

  • timer – Timer task.

  • sync – If true, wait for active tasks to finish before canceling.

int64_t lwm2m_os_timer_remaining(lwm2m_os_timer_t *timer)

Obtain the time remaining on a timer.

Parameters:

  • timer – Timer task.

Returns:

Time remaining in ms.

bool lwm2m_os_timer_is_pending(lwm2m_os_timer_t *timer)

Check if a timer task is pending.

Parameters:

  • timer – Timer task.

Return values:

true – If a timer task is pending.

int lwm2m_os_at_init(lwm2m_os_at_handler_callback_t callback)

Initialize AT command driver.

Return values:

  • 0 – If success.

  • -EIO – If AT command driver initialization failed.

int lwm2m_os_sms_client_register(lwm2m_os_sms_callback_t lib_callback, void *context)

Register as an SMS client/listener.

Return values:

  • 0 – If success.

  • -EIO – If unable to register as SMS listener.

void lwm2m_os_sms_client_deregister(int handle)

degister as an SMS client/listener.

int lwm2m_os_download_get(const char *host, const struct lwm2m_os_download_cfg *cfg, size_t from)

Establish a connection with the server and download a file.

Return values:

0 – If success.

int lwm2m_os_download_disconnect(void)

Disconnect from the server.

Return values:

0 – If success.

int lwm2m_os_download_init(lwm2m_os_download_callback_t lib_callback)

Initialize the download client.

Return values:

0 – If success.

int lwm2m_os_download_file_size_get(size_t *size)

Retrieve size of file being downloaded.

Parameters:

  • size – Size of the file being downloaded.

Return values:

0 – If success.

size_t lwm2m_os_lte_modes_get(int32_t *modes)

get enabled system modes from modem.

Parameters:

  • modes – Array to store the enabled modes. LWM2M_OS_LTE_MODE_CAT_M1 Cat-M1 (LTE-FDD) LWM2M_OS_LTE_MODE_CAT_NB1 Cat-NB1 (NB-IoT)

Returns:

Number of enabled modes:

void lwm2m_os_lte_mode_request(int32_t prefer)

set preferred bearer in modem.

Parameters:

  • prefer – LWM2M_OS_LTE_MODE_NONE for no preference LWM2M_OS_LTE_MODE_CAT_M1 for Cat-M1 (LTE-FDD) LWM2M_OS_LTE_MODE_CAT_NB1 for Cat-NB1 (NB-IoT)

Returns:

Number of enabled modes:

int lwm2m_os_nrf_errno(void)

Translate the error number.

int lwm2m_os_dfu_img_type(const void *const buf, size_t len, struct lwm2m_os_dfu_header **header)

Find the image type for the buffer of bytes received.

Parameters:

  • buf – [in] A buffer of bytes which are the start of a binary firmware image.

  • len – [in] The length of the provided buffer.

  • header – [out] DFU image header descriptor. Only applicable to MCUboot-style upgrades over multiple files.

Returns:

Identifier for a supported image type or LWM2M_OS_DFU_IMG_TYPE_NONE if image type is not recognized or not supported.

int lwm2m_os_dfu_start(int img_type, size_t max_file_size, bool crc_validate)

Start a firmware upgrade.

Parameters:

  • img_type – [in] DFU target type to be initialized.

  • max_file_size – [in] Estimate of the new firmware image to be received. May be greater than or equal to the actual image size received by the end.

  • crc_validate – [in] Flag to indicate whether to validate the incoming image fragments by means of IEEE CRC32.

Return values:

  • 0 – Ready to start a new firmware upgrade.

  • -EBUSY – Another firmware upgrade is already ongoing.

  • -EFBIG – File size exceeds the DFU area size.

  • -ENOTSUP – Firmware image not supported or unknown.

  • -EIO – Internal error.

Returns:

A positive number of bytes written so far, if the previous upgrade was not completed. In this case, the upgrade will resume from this offset.

int lwm2m_os_dfu_fragment(const char *buf, size_t len, uint32_t crc32)

Receive a firmware image fragment and validate its CRC if required.

Parameters:

  • buf – [in] Buffer containing the fragment.

  • len – [in] Length of the fragment in bytes.

  • crc32 – [in] Expected IEEE CRC32 value to be checked for the whole fragment. Can be any value if no validation expected.

Return values:

  • 0 – Success.

  • -EACCES – lwm2m_os_dfu_start() was not called beforehand.

  • -ENOMEM – Not enough memory to process the fragment.

  • -EINVAL – CRC error.

  • -EIO – Internal error.

int lwm2m_os_dfu_done(bool successful, uint32_t crc32)

Finalize the current firmware upgrade and CRC-validate the image if required.

Parameters:

  • successful – [in] Indicate if upload was successful.

  • crc32 – [in] Expected IEEE CRC32 value to be checked for the whole file in flash. Can be any value if no validation expected.

Return values:

  • 0 – Success.

  • -EACCES – lwm2m_os_dfu_start() was not called beforehand.

  • -EINVAL – CRC error.

  • -EIO – Internal error.

int lwm2m_os_dfu_pause(void)

Pause the DFU process and release the resources temporarily.

Return values:
Returns:

A positive number of bytes written so far.

int lwm2m_os_dfu_schedule_update(void)

Schedule update for uploaded image.

Return values:

0 – If success.

void lwm2m_os_dfu_reset(void)

Reset the current DFU target.

bool lwm2m_os_dfu_application_update_validate(void)

Validate the application image update.

Return values:

true – If the application image was updated successfully.

struct lwm2m_os_sms_deliver_address
#include <lwm2m_os.h>
struct lwm2m_os_sms_udh_app_port
#include <lwm2m_os.h>
struct lwm2m_os_sms_deliver_header
#include <lwm2m_os.h>
union lwm2m_os_sms_header
#include <lwm2m_os.h>

Public Members

struct lwm2m_os_sms_deliver_header deliver
struct lwm2m_os_sms_data
#include <lwm2m_os.h>

SMS PDU data.

Public Members

union lwm2m_os_sms_header header

SMS header.

int payload_len

Length of the data in data buffer.

char *payload

SMS message data.

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.

Public Members

const int *sec_tag_list

Security tag to be used for TLS. Set to NULL if non-secure.

uint8_t sec_tag_count

Number of security tags in list. Set to 0 if non-secure.

int pdn_id

PDN ID to be used for the download.

enum lwm2m_os_pdn_fam family

Address family to be used for the download.

struct lwm2m_os_dfu_header
#include <lwm2m_os.h>

LwM2M OS DFU image type

group lwm2m_os_dfu_img_type

Defines

LWM2M_OS_DFU_IMG_TYPE_NONE
LWM2M_OS_DFU_IMG_TYPE_APPLICATION

MCUboot-style upgrades

LWM2M_OS_DFU_IMG_TYPE_MODEM_DELTA

Modem delta upgrades

LWM2M_OS_DFU_IMG_TYPE_APPLICATION_FILE

MCUboot-style upgrades over multiple files.