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

LWM2M_CARRIER_EVENT_INIT

Carrier library initialized.

Request connect to the LTE network.

Request disconnect from the LTE network. The link must be offline until a subsequent LWM2M_CARRIER_EVENT_LTE_LINK_UP event.

LWM2M_CARRIER_EVENT_LTE_POWER_OFF

Request power off LTE network.

LWM2M_CARRIER_EVENT_BOOTSTRAPPED

LwM2M carrier bootstrapped.

LWM2M_CARRIER_EVENT_REGISTERED

LwM2M carrier registered.

LWM2M_CARRIER_EVENT_DEFERRED

LwM2M carrier operation is deferred.

LWM2M_CARRIER_EVENT_FOTA_START

Firmware update started.

LWM2M_CARRIER_EVENT_REBOOT

Application will reboot.

LWM2M_CARRIER_EVENT_MODEM_DOMAIN

Modem domain event received.

LWM2M_CARRIER_EVENT_APP_DATA

Data received through the App Data Container object

LWM2M_CARRIER_EVENT_ERROR

An error occurred.

LwM2M carrier library firmware update types.

LWM2M_CARRIER_FOTA_START_MODEM_DELTA

Receiving a modem firmware delta patch.

LWM2M_CARRIER_FOTA_START_APPLICATION

Receiving application firmware.

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 event deferred reasons.

LWM2M_CARRIER_DEFERRED_NO_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_DEFERRED_SERVICE_UNAVAILABLE

Server in maintenance mode.

LWM2M_CARRIER_DEFERRED_SIM_MSISDN

Waiting for SIM MSISDN.

LwM2M carrier library event error types.

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

LWM2M_CARRIER_ERROR_CONFIGURATION

Illegal object configuration detected.

LWM2M_CARRIER_ERROR_INIT

LwM2M carrier init failed.

LWM2M_CARRIER_ERROR_INTERNAL

Internal error detected.

LWM2M_CARRIER_ERROR_RUN

LwM2M carrier run failed.

LwM2M device power sources types.

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.

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.

Note

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

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.

LWM2M_CARRIER_IDENTITY_ID
LWM2M_CARRIER_IDENTITY_MANUFACTURER
LWM2M_CARRIER_IDENTITY_MODEL
LWM2M_CARRIER_IDENTITY_SW_VERSION

PDN types.

LWM2M_CARRIER_PDN_TYPE_IPV4V6
LWM2M_CARRIER_PDN_TYPE_IPV4
LWM2M_CARRIER_PDN_TYPE_IPV6
LWM2M_CARRIER_PDN_TYPE_NONIP

LG U+ Device Serial Number types.

LWM2M_CARRIER_LG_UPLUS_DEVICE_SERIAL_NO_IMEI
LWM2M_CARRIER_LG_UPLUS_DEVICE_SERIAL_NO_2DID

LwM2M carrier requests.

LWM2M_CARRIER_REQUEST_REBOOT

Unnamed Group

LWM2M_CARRIER_GENERIC

LwM2M enabled carriers.

LWM2M_CARRIER_VERIZON
LWM2M_CARRIER_ATT
LWM2M_CARRIER_LG_UPLUS
LWM2M_CARRIER_T_MOBILE

Typedefs

typedef uint32_t lwm2m_carrier_event_modem_domain_t

LwM2M carrier library modem domain event type value.

Functions

int lwm2m_carrier_init(void)

Initialize the LwM2M carrier library.

Note

This function will block until a SIM card is initialized by the modem. The library cannot proceed if, for example, no SIM is inserted, or a PIN code must be entered.

Note

The first time this function is called after a modem firmware update (FOTA), it may block for several seconds in order to complete the procedure.

Return values

  • 0 – If initialization was successful.

  • -EACCES – If initialization failed due to an error in the OS integration layer.

  • -ENOMEM – If initialization failed due to insufficient OS resources.

  • -EIO – If initialization failed due to a modem or AT command error.

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

int lwm2m_carrier_run(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 at modem shutdown.

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

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

int lwm2m_carrier_request(int request)

Request the LwM2M carrier library to perform an action.

Note

This function will behave differently depending on the chosen request. LWM2M_CARRIER_REQUEST_REBOOT shall request a system reboot. LWM2M_CARRIER_REQUEST_LINK_UP shall indicate to the LwM2M carrier library that the application is about to go online, so that a LWM2M_CARRIER_EVENT_LTE_LINK_UP shall be generated once the library is ready. LWM2M_CARRIER_REQUEST_LINK_DOWN shall indicate to the LwM2M carrier library that the application is about to go offline, so that a LWM2M_CARRIER_EVENT_LTE_LINK_DOWN shall be generated once the library is ready.

Parameters

  • request – [in] Request to be sent to the LwM2M carrier library.

Return values

  • 0 – If success.

  • -EINVAL – If an invalid request was selected.

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

Function to read all time parameters.

Input NULL for the parameters to ignore.

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)

Function to read current UTC time.

Note

This function can be implemented by the application, if custom time management is needed.

Returns

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.

Returns

UTC offset in minutes.

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.

Returns

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.

Parameters

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

Return values

0 – If success.

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.

Parameters

  • offset – [in] UTC offset in minutes.

Return values

0 – If success.

int lwm2m_carrier_timezone_write(const char *tz)

Function to write time zone (LwM2M server write operation).

Note

This function can be implemented by the application, if custom time management is needed.

Parameters

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

Return values

0 – If success.

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.

int lwm2m_carrier_avail_power_sources_set(const uint8_t *power_sources, uint8_t power_source_count)

Set the available power sources supported and used by the LwM2M device.

Note

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.

Note

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

  • power_sources – [in] Array of available device power sources.

  • power_source_count – [in] Number of power sources currently used by the device.

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 or update the latest voltage measurements made on one of the available device power sources.

Note

The voltage measurement needs to be specified in millivolts (mV) and is to be assigned to one of the available power sources.

Parameters

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

  • value – [in] Voltage measurement expressed in 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 or update the latest current measurements made on one of the available device power sources.

Note

The current measurement needs to be specified in milliamperes (mA) and is to be assigned to one of the available power sources.

Parameters

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

  • value – [in] Current measurement expressed in 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 or update the latest battery level (internal battery).

Note

The battery level is to be specified as a percentage, hence values outside the range 0-100 will be ignored.

Note

The value is only valid for the Device internal battery if present.

Parameters

  • battery_level – [in] Internal battery level percentage.

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 or update the latest battery status (internal battery).

Note

The value is only valid for the Device internal battery.

Parameters

  • battery_status – [in] Internal battery status to be reported.

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)

Update the device object instance error code by adding an individual error.

Note

Upon initialization of the device object instance, the error code is specified as 0, indicating no error. The error code is to be updated whenever a new error occurs.

Note

If the reported error is NO_ERROR, all existing error codes will be reset.

Note

If the reported error is already present, the error code will remain unchanged.

Parameters

  • error – [in] Individual error to be added.

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)

Update the device object instance error code by removing an individual error.

Note

Upon initialization of the device object instance, the error code is specified as 0, indicating no error. The error code is to be updated whenever an error is no longer present. When all the errors are removed, the error code is specified as 0, hence indicating no error again.

Parameters

  • error – [in] Individual error code to be removed.

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 total amount of storage space to store data and software in the LwM2M Device.

Note

The value is expressed in kilobytes (kB).

Parameters

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

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 estimated current available amount of storage space to store data and software in the LwM2M Device.

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

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

Read the Identity field of a given Portfolio object instance.

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.

  • 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 the corresponding Identity field of a Portfolio object instance to a given value.

Parameters

  • instance_id – [in] Portfolio object instance identifier.

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

  • 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 of the Portfolio object.

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 or update the latest location information provided by GPS.

Parameters

  • latitude – [in] Latitude in degrees. Must be between -90.0 and 90.0.

  • longitude – [in] Longitude in degrees. Must be between -180.0 and 180.0.

  • altitude – [in] Altitude is meters over sea level.

  • timestamp – [in] Unix timestamp of the current GPS measurement. Must not be older than the previous timestamp passed to this function.

  • uncertainty – [in] Positioning uncertainty given as a radius in meters.

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 or update the latest velocity information provided by GPS.

Note

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_send(const uint8_t *buffer, size_t buffer_len)

Schedule application data to be sent using the App Data Container object.

This function sets the “UL data” (uplink) resource of this object to the desired value, which can then be read by, or reported to, the LwM2M server.

Note

The App Data Container object will not be initialized for every carrier.

Parameters

  • buffer – [in] Buffer containing the application data to be sent.

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

int lwm2m_carrier_custom_init(lwm2m_carrier_config_t *config)

Initialize the LwM2M carrier library with custom configuration.

Note

This function may be implemented by the application if custom settings are needed.

Parameters

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

struct lwm2m_carrier_event_fota_start_t
#include <lwm2m_carrier.h>

LwM2M carrier library firmware update event structure.

Public Members

uint32_t type

Firmware type to be received.

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.

Public Members

const uint8_t *buffer

Buffer containing received application data.

size_t buffer_len

Number of bytes received.

struct lwm2m_carrier_event_deferred_t
#include <lwm2m_carrier.h>

LwM2M carrier library deferred event structure.

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 type

Error event type.

int32_t value

Error event value.

struct lwm2m_carrier_event_t
#include <lwm2m_carrier.h>

LwM2M carrier library event structure.

Public Members

uint32_t type

Event type.

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.

struct lwm2m_carrier_lg_uplus_config_t
#include <lwm2m_carrier.h>

LG U+ configuration structure.

Public Members

const char *service_code

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

uint8_t device_serial_no_type

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

struct lwm2m_carrier_config_t
#include <lwm2m_carrier.h>

Structure holding LwM2M carrier library initialization parameters.

Public Members

uint32_t carriers_enabled

Configure enabled carriers. All carriers are enabled when no bits are set.

bool disable_bootstrap_from_smartcard

Disable bootstrap from Smartcard mode when this is enabled by the carrier.

bool is_bootstrap_server

Denotes whether server_uri is an LwM2M Bootstrap-Server or an LwM2M Server.

const char *server_uri

Optional URI of the custom server. Null-terminated string of max 255 characters.

uint32_t server_sec_tag

Optional security tag when using a custom PSK.

uint8_t server_binding

Optional server binding. Valid values: ‘U’ or ‘N’.

int32_t server_lifetime

Default server lifetime (in seconds). Used only for an LwM2M Server.

int32_t session_idle_timeout

Default DTLS session idle timeout (in seconds).

int32_t coap_con_interval

How often to send CON instead of NON in CoAP observables (in seconds).

const char *apn

Optional custom APN. Null-terminated string of max 63 characters.

uint8_t pdn_type

Optional PDN type for custom APN.

const char *manufacturer

Optional LwM2M device manufacturer name. Null-terminated string of max 32 characters.

const char *model_number

Optional LwM2M device model number. Null-terminated string of max 32 characters.

const char *device_type

Optional LwM2M device type. Null-terminated string of max 32 characters.

const char *hardware_version

Optional LwM2M device hardware version. Null-terminated string of max 32 characters.

const char *software_version

Optional LwM2M device software version. Null-terminated string of max 32 characters.

lwm2m_carrier_lg_uplus_config_t lg_uplus

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

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_THREAD_COUNT

Maximum number of threads 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_DOWNLOAD_SEC_TAG_NONE

Download client configuration values.

Typedefs

typedef int lwm2m_os_work_q_t
typedef int lwm2m_os_timer_t
typedef void (*lwm2m_os_thread_entry_t)(void *p1, void *p2, void *p3)
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

Functions

int lwm2m_os_pdn_init(void)

Initialize the PDN functionality.

Return values

0 – If success.

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_apn_get(char *buf, size_t len)

Retrieve the default Access Point Name (APN).

The default APN is the APN of the default PDP context (zero).

Parameters

  • buf – The buffer to copy the APN into.

  • len – The size of the output buffer.

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.

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.

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.

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.

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.

lwm2m_os_timer_t *lwm2m_os_timer_get(lwm2m_os_timer_handler_t handler)

Reserve a timer task from the OS.

Parameters

  • handler – Function to run for this task.

Returns

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)

Cancel a timer run.

Parameters

  • timer – Timer task.

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_thread_start(int index, lwm2m_os_thread_entry_t entry, const char *name)

Create and start a new thread.

Parameters

  • index – Number of the thread.

  • entry – Thread entry function.

  • name – Name of the thread.

Return values

  • 0 – Thread created and started.

  • -EINVAL – Thread index not valid.

int lwm2m_os_nrf_modem_init(void)

Initialize modem library.

Return values

  • 0 – If success.

  • -EIO – If modem initialization failed.

Returns

A positive number nrf_modem_dfu in case of modem firmware update.

int lwm2m_os_nrf_modem_shutdown(void)

Shutdown the Modem library.

Return values

  • 0 – If success.

  • -EIO – If modem shutdown failed.

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_init(void)

Initialize SMS subscriber library.

void lwm2m_os_sms_uninit(void)

Uninitialize SMS subscriber library.

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_connect(const char *host, const struct lwm2m_os_download_cfg *cfg)

Establish a connection with the server.

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_start(const char *file, size_t from)

Download a file.

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_app_fota_start(size_t max_file_size)

Start an application firmware upgrade.

Parameters

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

Return values

  • 0 – Ready to start a new firmware upgrade.

  • -EBUSY – Another application firmware upgrade is already ongoing.

  • -ENOMEM – Not enough memory to store the file of the given size.

  • -EIO – Internal error.

  • -ENOTSUP – This function is not implemented.

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_app_fota_fragment(const char *buf, uint16_t len, uint16_t offset, uint32_t crc32)

Receive an application firmware image fragment and validate its CRC.

Parameters

  • buf – [in] Buffer containing the fragment.

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

  • offset – [in] Offset into the buffer, from which to start copying the fragment to flash.

  • crc32 – [in] Expected IEEE CRC32 value. Must be checked for the whole fragment.

Return values

  • 0 – Success.

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

  • -ENOMEM – Not enough memory to store the file.

  • -EINVAL – CRC error.

  • -EIO – Internal error.

  • -ENOTSUP – Firmware image not recognized, or this function is not implemented.

int lwm2m_os_app_fota_finish(uint32_t crc32)

Finalize the current application firmware upgrade and CRC-validate the image.

Parameters

  • crc32 – [in] Expected IEEE CRC32 value. Should be checked for the whole file in flash.

Return values

  • 0 – Success.

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

  • -EINVAL – CRC error.

  • -EIO – Internal error.

  • -ENOTSUP – This function is not implemented.

void lwm2m_os_app_fota_abort(void)

Abort the current application firmware upgrade.

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

int sec_tag

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

int pdn_id

PDN ID to be used for the download.