LwM2M carrier¶
You can use the LwM2M carrier library in your nRF91 application in order to connect to the LwM2M operator network. Integrating this library into an application causes the device to connect to the operator’s device management platform autonomously. Two examples of such device management platforms are Verizon’s Thingspace and AT&T’s IoT Platform.
Important
It is mandatory to include the LwM2M carrier library in any Verizon or AT&T certified products.
This library uses LwM2M protocol to communicate with device manager platforms, but it does not expose an LwM2M API to your application. If you want to use LwM2M for other purposes, see Lightweight M2M (LWM2M).
The nRF9160: LwM2M carrier sample demonstrates how to run this library in an application. The LwM2M carrier library is also used in the nRF9160: Asset Tracker application.
API documentation¶
lib/bin/lwm2m_carrier/include
lib/bin/lwm2m_carrier
LWM2M carrier library API¶
-
group
lwm2m_carrier_api
LWM2M carrier library API functions.
Defines
-
LWM2M_CARRIER_POWER_SOURCE_DC
¶ LWM2M device power sources type.
-
LWM2M_CARRIER_POWER_SOURCE_INTERNAL_BATTERY
¶
-
LWM2M_CARRIER_POWER_SOURCE_EXTERNAL_BATTERY
¶
-
LWM2M_CARRIER_POWER_SOURCE_ETHERNET
¶
-
LWM2M_CARRIER_POWER_SOURCE_USB
¶
-
LWM2M_CARRIER_POWER_SOURCE_AC
¶
-
LWM2M_CARRIER_POWER_SOURCE_SOLAR
¶
-
LWM2M_CARRIER_ERROR_CODE_NO_ERROR
¶ LWM2M device error codes.
-
LWM2M_CARRIER_ERROR_CODE_LOW_CHARGE
¶
-
LWM2M_CARRIER_ERROR_CODE_EXTERNAL_SUPPLY_OFF
¶
-
LWM2M_CARRIER_ERROR_CODE_GPS_FAILURE
¶
-
LWM2M_CARRIER_ERROR_CODE_LOW_SIGNAL
¶
-
LWM2M_CARRIER_ERROR_CODE_OUT_OF_MEMORY
¶
-
LWM2M_CARRIER_ERROR_CODE_SMS_FAILURE
¶
-
LWM2M_CARRIER_ERROR_CODE_IP_CONNECTIVITY_FAILURE
¶
-
LWM2M_CARRIER_ERROR_CODE_PERIPHERAL_MALFUNCTION
¶
-
LWM2M_CARRIER_BATTERY_STATUS_NORMAL
¶ LWM2M device battery status.
- Note
These values are only valid for the LWM2M Device INTERNAL_BATTERY if present.
-
LWM2M_CARRIER_BATTERY_STATUS_CHARGING
¶
-
LWM2M_CARRIER_BATTERY_STATUS_CHARGE_COMPLETE
¶
-
LWM2M_CARRIER_BATTERY_STATUS_DAMAGED
¶
-
LWM2M_CARRIER_BATTERY_STATUS_LOW_BATTERY
¶
-
LWM2M_CARRIER_BATTERY_STATUS_NOT_INSTALLED
¶
-
LWM2M_CARRIER_BATTERY_STATUS_UNKNOWN
¶
-
LWM2M_CARRIER_IDENTITY_ID
¶ LWM2M portfolio identity types.
-
LWM2M_CARRIER_IDENTITY_MANUFACTURER
¶
-
LWM2M_CARRIER_IDENTITY_MODEL
¶
-
LWM2M_CARRIER_IDENTITY_SW_VERSION
¶
Functions
-
int
lwm2m_carrier_init
(const lwm2m_carrier_config_t *config)¶ Initialize the LWM2M carrier library.
- Note
The library does not copy the contents of pointers in the config parameters. The application has to make sure that the provided parameters are valid throughout the application lifetime (i. e. placed in static memory or in flash).
- Note
The first time this function is called after a modem firmware update, (FOTA) it may take several seconds to return in order to complete the procedure.
- Return
0 on success, negative error code on error.
- Parameters
[in] config
: Configuration parameters for the library.
-
void
lwm2m_carrier_run
(void)¶ LWM2M carrier library main function.
This is a non-return function, intended to run on a separate thread.
-
void
lwm2m_carrier_time_read
(int32_t *utc_time, int *utc_offset, const char **tz)¶ Function to read all time parameters.
- Parameters
[out] utc_time
: Pointer to time since Epoch in seconds.[out] utc_offset
: Pointer to UTC offset in minutes.[out] tz
: Pointer to null-terminated timezone string pointer.
-
int32_t
lwm2m_carrier_utc_time_read
(void)¶ Function to read current UTC time.
- Note
This function can be implemented by the application, if custom time management is needed.
- Return
Current UTC time since Epoch in seconds.
-
int
lwm2m_carrier_utc_offset_read
(void)¶ Function to read offset to UTC time.
- Note
This function can be implemented by the application, if custom time management is needed.
- Return
UTC offset in minutes.
-
const char *
lwm2m_carrier_timezone_read
(void)¶ Function to read timezone.
- Note
This function can be implemented by the application, if custom time management is needed.
- Return
Null-terminated timezone string pointer, IANA Timezone (TZ) database format.
-
int
lwm2m_carrier_utc_time_write
(int32_t time)¶ Function to write current UTC time (LWM2M server write operation)
- Note
This function can be implemented by the application, if custom time management is needed.
- Return
0 on success, negative error code on error.
- Parameters
[in] time
: Time since Epoch in seconds.
-
int
lwm2m_carrier_utc_offset_write
(int offset)¶ Function to write UTC offset (LWM2M server write operation)
- Note
This function can be implemented by the application, if custom time management is needed.
- Return
0 on success, negative error code on error.
- Parameters
[in] offset
: UTC offset in minutes.
-
int
lwm2m_carrier_timezone_write
(const char *tz)¶ Function to write timezone (LWM2M server write operation).
- Note
This function can be implemented by the application, if custom time management is needed.
- Return
0 on success, negative error code on error.
- Parameters
[in] tz
: Null-terminated timezone string pointer.
-
int
lwm2m_carrier_event_handler
(const lwm2m_carrier_event_t *event)¶ LWM2M carrier library event handler.
This function will be called by the LWM2M carrier library whenever some event significant for the application occurs.
- Note
This function has to be implemented by the application.
- Return
In case of
LWM2M_CARRIER_EVENT_REBOOT
events if non-zero is returned, the LwM2M carrier library will not reboot the device. The application should to reboot at the earliest convenient time.- Parameters
[in] event
: LWM2M carrier event that occurred.
-
struct
lwm2m_carrier_config_t
¶ - #include <lwm2m_carrier.h>
Structure holding LWM2M carrier library initialization parameters.
Public Members
-
const char *
bootstrap_uri
¶ URI of the bootstrap server, null-terminated string.
-
const char *
psk
¶ Pre-Shared Key for the bootstrap server, null-terminated hexadecimal string.
-
const char *
apn
¶ Optional custom APN, null-terminated string.
-
bool
certification_mode
¶ Connect to certification servers if true, connect to production servers otherwise.
-
const char *
-
LWM2M carrier library events¶
-
group
lwm2m_carrier_event
Defines
-
LWM2M_CARRIER_EVENT_BSDLIB_INIT
¶ BSD library initialized.
-
LWM2M_CARRIER_EVENT_CONNECTING
¶ Connecting to the LTE network.
-
LWM2M_CARRIER_EVENT_CONNECTED
¶ Connected to the LTE network.
-
LWM2M_CARRIER_EVENT_DISCONNECTING
¶ Disconnecting from the LTE network.
-
LWM2M_CARRIER_EVENT_DISCONNECTED
¶ Disconnected from the LTE network.
-
LWM2M_CARRIER_EVENT_BOOTSTRAPPED
¶ LWM2M carrier bootstrapped.
-
LWM2M_CARRIER_EVENT_REGISTERED
¶ LWM2M carrier registered.
-
LWM2M_CARRIER_EVENT_DEFERRED
¶ LWM2M carrier operation is deferred.
-
LWM2M_CARRIER_EVENT_FOTA_START
¶ Modem update started.
-
LWM2M_CARRIER_EVENT_REBOOT
¶ Application will reboot. LTE network is ready to be used.
-
LWM2M_CARRIER_EVENT_LTE_READY
¶
-
LWM2M_CARRIER_EVENT_ERROR
¶ An error occurred.
-
LWM2M_CARRIER_DEFERRED_NO_REASON
¶ LWM2M carrier library event deferred reason.
No reason given.
-
LWM2M_CARRIER_DEFERRED_PDN_ACTIVATE
¶ Failed to activate PDN.
-
LWM2M_CARRIER_DEFERRED_BOOTSTRAP_NO_ROUTE
¶ No route to bootstrap server.
-
LWM2M_CARRIER_DEFERRED_BOOTSTRAP_CONNECT
¶ Failed to connect to bootstrap server.
-
LWM2M_CARRIER_DEFERRED_BOOTSTRAP_SEQUENCE
¶ Bootstrap sequence not completed.
-
LWM2M_CARRIER_DEFERRED_SERVER_NO_ROUTE
¶ No route to server.
-
LWM2M_CARRIER_DEFERRED_SERVER_CONNECT
¶ Failed to connect to server.
-
LWM2M_CARRIER_DEFERRED_SERVER_REGISTRATION
¶ Server registration sequence not completed.
-
LWM2M_CARRIER_ERROR_NO_ERROR
¶ LWM2M carrier library event error codes.
No error.
-
LWM2M_CARRIER_ERROR_CONNECT_FAIL
¶ Failed to connect to the LTE network.
-
LWM2M_CARRIER_ERROR_DISCONNECT_FAIL
¶ Failed to disconnect from the LTE network.
-
LWM2M_CARRIER_ERROR_BOOTSTRAP
¶ LWM2M carrier bootstrap failed.
-
LWM2M_CARRIER_ERROR_FOTA_PKG
¶ Update package rejected.
-
LWM2M_CARRIER_ERROR_FOTA_PROTO
¶ Protocol error.
-
LWM2M_CARRIER_ERROR_FOTA_CONN
¶ Connection error.
-
LWM2M_CARRIER_ERROR_FOTA_CONN_LOST
¶ Connection lost.
-
LWM2M_CARRIER_ERROR_FOTA_FAIL
¶ Update failed.
-
struct
lwm2m_carrier_event_t
¶ - #include <lwm2m_carrier.h>
LWM2M carrier library event structure.
-
struct
lwm2m_carrier_event_deferred_t
¶ - #include <lwm2m_carrier.h>
-
struct
lwm2m_carrier_event_error_t
¶ - #include <lwm2m_carrier.h>
LWM2M carrier library error event structure.
-
LWM2M OS layer¶
-
group
lwm2m_carrier_os
Defines
-
LWM2M_OS_MAX_TIMER_COUNT
¶ Maximum number of timers that the system must support.
-
LWM2M_LOG_LEVEL_NONE
¶
-
LWM2M_LOG_LEVEL_ERR
¶
-
LWM2M_LOG_LEVEL_WRN
¶
-
LWM2M_LOG_LEVEL_INF
¶
-
LWM2M_LOG_LEVEL_TRC
¶
-
LWM2M_OS_STORAGE_BASE
¶ Range of the non-volatile storage identifiers used by the library.
- Note
The application MUST NOT use the values within this range for its own non-volatile storage management as it could potentially delete or overwrite entries used by the library.
-
LWM2M_OS_STORAGE_END
¶
Typedefs
-
typedef void (*
lwm2m_os_timer_handler_t
)(void *timer)¶ Timer callback function.
-
typedef void (*
lwm2m_os_at_cmd_handler_t
)(void *ctx, const char *response)¶ AT Command handler.
-
typedef int (*
lwm2m_os_download_callback_t
)(const struct lwm2m_os_download_evt *event)¶ Download client asynchronous event handler.
Functions
-
int
lwm2m_os_init
(void)¶ Initialize the LWM2M OS layer.
-
void *
lwm2m_os_malloc
(size_t size)¶ Allocate memory.
-
void
lwm2m_os_free
(void *ptr)¶ Free memory.
-
int64_t
lwm2m_os_uptime_get
(void)¶ Get uptime, in milliseconds.
-
int64_t
lwm2m_os_uptime_delta
(int64_t *ref)¶ Get uptime delta, in milliseconds.
-
int
lwm2m_os_sleep
(int ms)¶ Put a thread to a sleep.
-
void
lwm2m_os_sys_reset
(void)¶ Reboot system.
-
uint32_t
lwm2m_os_rand_get
(void)¶ Get a random value.
-
int
lwm2m_os_storage_delete
(uint16_t id)¶ Delete a non-volatile storage entry.
-
int
lwm2m_os_storage_read
(uint16_t id, void *data, size_t len)¶ Read an entry from non-volatile storage.
-
int
lwm2m_os_storage_write
(uint16_t id, const void *data, size_t len)¶ Write an entry to non-volatile storage.
-
void *
lwm2m_os_timer_get
(lwm2m_os_timer_handler_t handler)¶ Request a timer from the OS.
-
void
lwm2m_os_timer_release
(void *timer)¶ Release a timer.
-
int
lwm2m_os_timer_start
(void *timer, int32_t timeout)¶ Start a timer.
-
void
lwm2m_os_timer_cancel
(void *timer)¶ Cancel a timer run.
-
int32_t
lwm2m_os_timer_remaining
(void *timer)¶ Obtain the time remaining on a timer.
-
const char *
lwm2m_os_log_strdup
(const char *str)¶ Create a string copy for a logger subsystem.
-
void
lwm2m_os_log
(int level, const char *fmt, ...)¶ Log a message.
-
void
lwm2m_os_logdump
(const char *msg, const void *data, size_t len)¶ Print a data dump via logger.
- Parameters
msg
: Log message.data
: Data to dump.len
: Data length.
-
int
lwm2m_os_bsdlib_init
(void)¶ Initialize BSD library.
- Return
0 on success
- Return
-1 on error
- Return
an error from bsd_modem_dfu in case of modem DFU.
-
int
lwm2m_os_bsdlib_shutdown
(void)¶ Shutdown BSD library.
- Return
0 on success, -1 otherwise.
-
int
lwm2m_os_at_init
(void)¶ Initialize AT command driver.
-
int
lwm2m_os_at_notif_register_handler
(void *context, lwm2m_os_at_cmd_handler_t handler)¶ Set AT command global notification handler.
-
int
lwm2m_os_at_cmd_write
(const char *const cmd, char *buf, size_t buf_len)¶ Send an AT command and receive response immediately.
-
void
lwm2m_os_at_params_list_free
(struct lwm2m_os_at_param_list *list)¶ Free a list of AT parameters.
-
int
lwm2m_os_at_params_list_init
(struct lwm2m_os_at_param_list *list, size_t max_params_count)¶ Create a list of AT parameters.
-
int
lwm2m_os_at_params_int_get
(struct lwm2m_os_at_param_list *list, size_t index, uint32_t *value)¶ Get a parameter value as an integer number.
-
int
lwm2m_os_at_params_short_get
(struct lwm2m_os_at_param_list *list, size_t index, uint16_t *value)¶ Get a parameter value as a short number.
-
int
lwm2m_os_at_params_string_get
(struct lwm2m_os_at_param_list *list, size_t index, char *value, size_t *len)¶ Get a parameter value as a string.
-
int
lwm2m_os_at_params_list_clear
(struct lwm2m_os_at_param_list *list)¶ Clear/reset all parameter types and values.
-
int
lwm2m_os_at_parser_params_from_str
(const char *at_params_str, char **next_param_str, struct lwm2m_os_at_param_list *const list)¶ Parse AT command or response parameters from a string.
-
int
lwm2m_os_at_params_valid_count_get
(struct lwm2m_os_at_param_list *list)¶ Get the number of valid parameters in the list.
-
int
lwm2m_os_download_connect
(const char *host, const struct lwm2m_os_download_cfg *cfg)¶ Establish a connection with the server.
-
int
lwm2m_os_download_disconnect
(void)¶ Disconnect from the server.
-
int
lwm2m_os_download_init
(lwm2m_os_download_callback_t lib_callback)¶ Initialize the download client.
-
int
lwm2m_os_download_start
(const char *file, size_t from)¶ Download a file.
-
int
lwm2m_os_download_file_size_get
(size_t *size)¶ Retrieve size of file being downloaded.
- Parameters
size
: Size of the file being downloaded.
-
int
lwm2m_os_lte_link_up
(void)¶
-
int
lwm2m_os_lte_link_down
(void)¶
-
int
lwm2m_os_lte_power_down
(void)¶
-
int
lwm2m_os_errno
(void)¶ Translate the error number.
-
const char *
lwm2m_os_strerror
(void)¶ Return a textual description for the current error.
-
int
lwm2m_os_sec_ca_chain_exists
(uint32_t sec_tag, bool *exists, uint8_t *perm)¶ Check if a certificate chain credential exists in persistent storage.
- Parameters
[in] sec_tag
: The tag to search for.[out] exists
: Whether the credential exists. Only valid if the operation is successful.[out] perm
: The permission flags of the credential. Not yet implemented.
- Return Value
0
: On success.-ENOBUFS
: Insufficient memory.-EPERM
: Insufficient permissions.
-
int
lwm2m_os_sec_ca_chain_cmp
(uint32_t sec_tag, const void *buf, size_t len)¶ Compare a certificate chain.
- Parameters
[in] sec_tag
: Security tag associated with the certificate chain.[in] buf
: Buffer to compare the certificate chain to.[in] len
: Length of the certificate chain.
- Return Value
0
: If the certificate chain match.1
: If the certificate chain do not match.<
: 0 On error.
-
int
lwm2m_os_sec_ca_chain_write
(uint32_t sec_tag, const void *buf, size_t len)¶ Provision a certificate chain or update an existing one.
- Note
If used when the LTE link is active, the function will return an error and the key will not be written.
- Parameters
[in] sec_tag
: Security tag for this credential.[in] buf
: Buffer containing the credential data.[in] len
: Length of the buffer.
- Return Value
0
: On success.-EINVAL
: Invalid parameters.-ENOBUFS
: Internal buffer is too small.-EACCES
: The operation failed because the LTE link is active.-ENOMEM
: Not enough memory to store the credential.-ENOENT
: The security tag could not be written.-EPERM
: Insufficient permissions.
-
int
lwm2m_os_sec_psk_exists
(uint32_t sec_tag, bool *exists, uint8_t *perm_flags)¶ Check if a pre-shared key exists in persistent storage.
- Parameters
[in] sec_tag
: The tag to search for.[out] exists
: Whether the credential exists. Only valid if the operation is successful.[out] perm_flags
: The permission flags of the credential. Only valid if the operation is successful andexists
istrue
. Not yet implemented.
- Return Value
0
: On success.-ENOBUFS
: Internal buffer is too small.-EPERM
: Insufficient permissions.-EIO
: Internal error.
-
int
lwm2m_os_sec_psk_write
(uint32_t sec_tag, const void *buf, uint16_t len)¶ Provision a new pre-shared key or update an existing one.
- Note
If used when the LTE link is active, the function will return an error and the key will not be written.
- Parameters
[in] sec_tag
: Security tag for this credential.[in] buf
: Buffer containing the credential data.[in] len
: Length of the buffer.
- Return Value
0
: On success.-EINVAL
: Invalid parameters.-ENOBUFS
: Internal buffer is too small.-ENOMEM
: Not enough memory to store the credential.-EACCES
: The operation failed because the LTE link is active.-ENOENT
: The security tag could not be written.-EPERM
: Insufficient permissions.-EIO
: Internal error.
-
int
lwm2m_os_sec_psk_delete
(uint32_t sec_tag)¶ Delete pre-shared key.
- Note
If used when the LTE link is active, the function will return an error and the key will not be deleted.
- Parameters
[in] sec_tag
: Security tag for this credential.
- Return Value
0
: On success.-ENOBUFS
: Internal buffer is too small.-EACCES
: The operation failed because the LTE link is active.-ENOENT
: No credential associated with the givensec_tag
andcred_type
.-EPERM
: Insufficient permissions.
-
int
lwm2m_os_sec_identity_exists
(uint32_t sec_tag, bool *exists, uint8_t *perm_flags)¶ Check if an identity credential exists in persistent storage.
- Parameters
[in] sec_tag
: The tag to search for.[out] exists
: Whether the credential exists. Only valid if the operation is successful.[out] perm_flags
: The permission flags of the credential. Only valid if the operation is successful andexists
istrue
. Not yet implemented.
- Return Value
0
: On success.-ENOBUFS
: Internal buffer is too small.-EPERM
: Insufficient permissions.-EIO
: Internal error.
-
int
lwm2m_os_sec_identity_write
(uint32_t sec_tag, const void *buf, uint16_t len)¶ Provision a new identity credential or update an existing one.
- Note
If used when the LTE link is active, the function will return an error and the key will not be written.
- Parameters
[in] sec_tag
: Security tag for this credential.[in] buf
: Buffer containing the credential data.[in] len
: Length of the buffer.
- Return Value
0
: On success.-EINVAL
: Invalid parameters.-ENOBUFS
: Internal buffer is too small.-ENOMEM
: Not enough memory to store the credential.-EACCES
: The operation failed because the LTE link is active.-ENOENT
: The security tag could not be written.-EPERM
: Insufficient permissions.-EIO
: Internal error.
-
int
lwm2m_os_sec_identity_delete
(uint32_t sec_tag)¶ Delete identity credential.
- Note
If used when the LTE link is active, the function will return an error and the key will not be deleted.
- Parameters
[in] sec_tag
: Security tag for this credential.
- Return Value
0
: On success.-ENOBUFS
: Internal buffer is too small.-EACCES
: The operation failed because the LTE link is active.-ENOENT
: No credential associated with the givensec_tag
andcred_type
.-EPERM
: Insufficient permissions.
-
struct
lwm2m_os_at_param_list
¶ - #include <lwm2m_os.h>
List of AT parameters that compose an AT command or response.
-
struct
lwm2m_os_download_evt
¶ - #include <lwm2m_os.h>
Download client event.
-
struct
lwm2m_os_download_cfg
¶ - #include <lwm2m_os.h>
Download client configuration options.
-