Lightweight M2M (LWM2M)

Overview

Lightweight Machine to Machine (LwM2M) is an application layer protocol designed with device management, data reporting and device actuation in mind. Based on CoAP/UDP, LwM2M is a standard defined by the Open Mobile Alliance and suitable for constrained devices by its use of CoAP packet-size optimization and a simple, stateless flow that supports a REST API.

One of the key differences between LwM2M and CoAP is that an LwM2M client initiates the connection to an LwM2M server. The server can then use the REST API to manage various interfaces with the client.

LwM2M uses a simple resource model with the core set of objects and resources defined in the specification.

The LwM2M library can be enabled with CONFIG_LWM2M Kconfig option.

Example LwM2M object and resources: Device

Object definition

Object ID	Name	Instance	Mandatory
3	Device	Single	Mandatory

Resource definitions

* R=Read, W=Write, E=Execute

ID	Name	OP*	Instance	Mandatory	Type
0	Manufacturer	R	Single	Optional	String
1	Model	R	Single	Optional	String
2	Serial number	R	Single	Optional	String
3	Firmware version	R	Single	Optional	String
4	Reboot	E	Single	Mandatory
5	Factory Reset	E	Single	Optional
6	Available Power Sources	R	Multiple	Optional	Integer 0-7
7	Power Source Voltage (mV)	R	Multiple	Optional	Integer
8	Power Source Current (mA)	R	Multiple	Optional	Integer
9	Battery Level %	R	Single	Optional	Integer
10	Memory Free (Kb)	R	Single	Optional	Integer
11	Error Code	R	Multiple	Optional	Integer 0-8
12	Reset Error	E	Single	Optional
13	Current Time	RW	Single	Optional	Time
14	UTC Offset	RW	Single	Optional	String
15	Timezone	RW	Single	Optional	String
16	Supported Binding	R	Single	Mandatory	String
17	Device Type	R	Single	Optional	String
18	Hardware Version	R	Single	Optional	String
19	Software Version	R	Single	Optional	String
20	Battery Status	R	Single	Optional	Integer 0-6
21	Memory Total (Kb)	R	Single	Optional	Integer
22	ExtDevInfo	R	Multiple	Optional	ObjLnk

The server could query the Manufacturer resource for Device object instance 0 (the default and only instance) by sending a READ 3/0/0 operation to the client.

The full list of registered objects and resource IDs can be found in the LwM2M registry.

Zephyr’s LwM2M library lives in the subsys/net/lib/lwm2m, with a client sample in samples/net/lwm2m_client. For more information about the provided sample see: LwM2M client. The sample can be configured to use normal unsecure network sockets or sockets secured via DTLS.

The Zephyr LwM2M library implements the following items:

• engine to process networking events and core functions

• RD client which performs BOOTSTRAP and REGISTRATION functions

• SenML CBOR, SenML JSON, CBOR, TLV, JSON, and plain text formatting functions

• LwM2M Technical Specification Enabler objects such as Security, Server, Device, Firmware Update, etc.

• Extended IPSO objects such as Light Control, Temperature Sensor, and Timer

By default, the library implements LwM2M specification 1.0.2 and can be set to LwM2M specification 1.1.1 with a Kconfig option.

For more information about LwM2M visit OMA Specworks LwM2M.

Sample usage

To use the LwM2M library, start by creating an LwM2M client context lwm2m_ctx structure:

/* LwM2M client context */
static struct lwm2m_ctx client;

Create callback functions for LwM2M resource executions:

static int device_reboot_cb(uint16_t obj_inst_id, uint8_t *args,
                            uint16_t args_len)
{
        LOG_INF("Device rebooting.");
        LOG_PANIC();
        sys_reboot(0);
        return 0; /* won't reach this */
}

The LwM2M RD client can send events back to the sample. To receive those events, setup a callback function:

static void rd_client_event(struct lwm2m_ctx *client,
                            enum lwm2m_rd_client_event client_event)
{
        switch (client_event) {

        case LWM2M_RD_CLIENT_EVENT_NONE:
                /* do nothing */
                break;

        case LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_FAILURE:
                LOG_DBG("Bootstrap registration failure!");
                break;

        case LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_COMPLETE:
                LOG_DBG("Bootstrap registration complete");
                break;

        case LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_TRANSFER_COMPLETE:
                LOG_DBG("Bootstrap transfer complete");
                break;

        case LWM2M_RD_CLIENT_EVENT_REGISTRATION_FAILURE:
                LOG_DBG("Registration failure!");
                break;

        case LWM2M_RD_CLIENT_EVENT_REGISTRATION_COMPLETE:
                LOG_DBG("Registration complete");
                break;

        case LWM2M_RD_CLIENT_EVENT_REG_TIMEOUT:
                LOG_DBG("Registration timeout!");
                break;

        case LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE:
                LOG_DBG("Registration update complete");
                break;

        case LWM2M_RD_CLIENT_EVENT_DEREGISTER_FAILURE:
                LOG_DBG("Deregister failure!");
                break;

        case LWM2M_RD_CLIENT_EVENT_DISCONNECT:
                LOG_DBG("Disconnected");
                break;

        case LWM2M_RD_CLIENT_EVENT_REG_UPDATE:
                LOG_DBG("Registration update");
                break;

        case LWM2M_RD_CLIENT_EVENT_DEREGISTER:
                LOG_DBG("Deregistration client");
                break;

        case LWM2M_RD_CLIENT_EVENT_SERVER_DISABLED:
                LOG_DBG("LwM2M server disabled");
          break;
        }
}

Next we assign Security resource values to let the client know where and how to connect as well as set the Manufacturer and Reboot resources in the Device object with some data and the callback we defined above:

/*
 * Server URL of default Security object = 0/0/0
 * Use leshan.eclipse.org server IP (5.39.83.206) for connection
 */
lwm2m_set_string(&LWM2M_OBJ(0, 0, 0), "coap://5.39.83.206");

/*
 * Security Mode of default Security object = 0/0/2
 * 3 = NoSec mode (no security beware!)
 */
lwm2m_set_u8(&LWM2M_OBJ(0, 0, 2), 3);

#define CLIENT_MANUFACTURER "Zephyr Manufacturer"

/*
 * Manufacturer resource of Device object = 3/0/0
 * We use lwm2m_set_res_data() function to set a pointer to the
 * CLIENT_MANUFACTURER string.
 * Note the LWM2M_RES_DATA_FLAG_RO flag which stops the engine from
 * trying to assign a new value to the buffer.
 */
lwm2m_set_res_data(&LWM2M_OBJ(3, 0, 0), CLIENT_MANUFACTURER,
                   sizeof(CLIENT_MANUFACTURER),
                   LWM2M_RES_DATA_FLAG_RO);

/* Reboot resource of Device object = 3/0/4 */
lwm2m_register_exec_callback(&LWM2M_OBJ(3, 0, 4), device_reboot_cb);

Lastly, we start the LwM2M RD client (which in turn starts the LwM2M engine). The second parameter of lwm2m_rd_client_start() is the client endpoint name. This is important as it needs to be unique per LwM2M server:

(void)memset(&client, 0x0, sizeof(client));
lwm2m_rd_client_start(&client, "unique-endpoint-name", 0, rd_client_event);

LwM2M security modes

The Zephyr LwM2M library can be used either without security or use DTLS to secure the communication channel. When using DTLS with the LwM2M engine, PSK (Pre-Shared Key) and X.509 certificates are the security modes that can be used to secure the communication. The engine uses LwM2M Security object (Id 0) to read the stored credentials and feed keys from the security object into the TLS credential subsystem, see secure sockets documentation. Enable the CONFIG_LWM2M_DTLS_SUPPORT Kconfig option to use the security.

Depending on the selected mode, the security object must contain following data:

PSK

Security Mode (Resource ID 2) set to zero (Pre-Shared Key mode). Identity (Resource ID 3) contains PSK ID in binary form. Secret key (Resource ID 5) contains the PSK key in binary form. If the key or identity is provided as a hex string, it must be converted to binary before storing into the security object.

X509

When X509 certificates are used, set Security Mode (ID 2) to 2 (Certificate mode). Identity (ID 3) is used to store the client certificate and Secret key (ID 5) must have a private key associated with the certificate. Server Public Key resource (ID 4) must contain a server certificate or CA certificate used to sign the certificate chain. If the CONFIG_MBEDTLS_PEM_CERTIFICATE_FORMAT Kconfig option is enabled, certificates and private key can be entered in PEM format. Otherwise, they must be in binary DER format.

NoSec

When no security is used, set Security Mode (Resource ID 2) to 3 (NoSec).

In all modes, Server URI resource (ID 0) must contain the full URI for the target server. When DNS names are used, the DNS resolver must be enabled.

When DTLS is used, following options are recommended to reduce DTLS handshake traffic when connection is re-established:

• CONFIG_LWM2M_DTLS_CID enables DTLS Connection Identifier support. When server supports it, this completely removes the handshake when device resumes operation after long idle period. Greatly helps when NAT mappings have timed out.

• CONFIG_LWM2M_TLS_SESSION_CACHING uses session cache when before falling back to full DTLS handshake. Reduces few packets from handshake, when session is still cached on server side. Most significant effect is to avoid full registration.

LwM2M stack provides callbacks in the lwm2m_ctx structure. They are used to feed keys from the LwM2M security object into the TLS credential subsystem. By default, these callbacks can be left as NULL pointers, in which case default callbacks are used. When an external TLS stack, or non-default socket options are required, you can overwrite the lwm2m_ctx.load_credentials() or lwm2m_ctx.set_socketoptions() callbacks.

An example of setting up the security object for PSK mode:

/* "000102030405060708090a0b0c0d0e0f" */
static unsigned char client_psk[] = {
        0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
        0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f
};

static const char client_identity[] = "Client_identity";

lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 0), "coaps://lwm2m.example.com");
lwm2m_set_u8(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 2), LWM2M_SECURITY_PSK);
/* Set the client identity as a string, but this could be binary as well */
lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 3), client_identity);
/* Set the client pre-shared key (PSK) */
lwm2m_set_opaque(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 5), client_psk, sizeof(client_psk));

An example of setting up the security object for X509 certificate mode:

static const char certificate[] = "-----BEGIN CERTIFICATE-----\nMIIB6jCCAY+gAw...";
static const char key[] = "-----BEGIN EC PRIVATE KEY-----\nMHcCAQ...";
static const char root_ca[] = "-----BEGIN CERTIFICATE-----\nMIIBaz...";

lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 0), "coaps://lwm2m.example.com");
lwm2m_set_u8(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 2), LWM2M_SECURITY_CERT);
lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 3), certificate);
lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 5), key);
lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 4), root_ca);

Before calling lwm2m_rd_client_start() assign the tls_tag # where the LwM2M library should store the DTLS information prior to connection (normally a value of 1 is ok here).

(void)memset(&client, 0x0, sizeof(client));
client.tls_tag = 1; /* <---- */
lwm2m_rd_client_start(&client, "endpoint-name", 0, rd_client_event);

For a more detailed LwM2M client sample see: LwM2M client.

Multi-thread usage

Writing a value to a resource can be done using functions like lwm2m_set_u8. When writing to multiple resources, the function lwm2m_registry_lock will ensure that the client halts until all writing operations are finished:

lwm2m_registry_lock();
lwm2m_set_u32(&LWM2M_OBJ(1, 0, 1), 60);
lwm2m_set_u8(&LWM2M_OBJ(5, 0, 3), 0);
lwm2m_set_f64(&LWM2M_OBJ(3303, 0, 5700), value);
lwm2m_registry_unlock();

This is especially useful if the server is composite-observing the resources being written to. Locking will then ensure that the client only updates and sends notifications to the server after all operations are done, resulting in fewer messages in general.

Support for time series data

LwM2M version 1.1 adds support for SenML CBOR and SenML JSON data formats. These data formats add support for time series data. Time series formats can be used for READ, NOTIFY and SEND operations. When data cache is enabled for a resource, each write will create a timestamped entry in a cache, and its content is then returned as a content in READ, NOTIFY or SEND operation for a given resource.

Data cache is only supported for resources with a fixed data size.

Supported resource types:

• Signed and unsigned 8-64-bit integers

• Float

• Boolean

Enabling and configuring

Enable data cache by selecting CONFIG_LWM2M_RESOURCE_DATA_CACHE_SUPPORT. Application needs to allocate an array of lwm2m_time_series_elem structures and then enable the cache by calling lwm2m_engine_enable_cache() for a given resource. Each resource must be enabled separately and each resource needs their own storage.

/* Allocate data cache storage */
static struct lwm2m_time_series_elem temperature_cache[10];
/* Enable data cache */
lwm2m_engine_enable_cache(LWM2M_PATH(IPSO_OBJECT_TEMP_SENSOR_ID, 0, SENSOR_VALUE_RID),
        temperature_cache, ARRAY_SIZE(temperature_cache));

LwM2M engine have room for four resources that have cache enabled. Limit can be increased by changing CONFIG_LWM2M_MAX_CACHED_RESOURCES. This affects a static memory usage of engine.

Data caches depends on one of the SenML data formats CONFIG_LWM2M_RW_SENML_CBOR_SUPPORT or CONFIG_LWM2M_RW_SENML_JSON_SUPPORT and needs CONFIG_POSIX_TIMERS so it can request a timestamp from the system and CONFIG_RING_BUFFER for ring buffer.

Read and Write operations

Full content of data cache is written into a payload when any READ, SEND or NOTIFY operation internally reads the content of a given resource. This has a side effect that any read callbacks registered for a that resource are ignored when cache is enabled. Data is written into a cache when any of the lwm2m_set_* functions are called. To filter the data entering the cache, application may register a validation callback using lwm2m_register_validate_callback().

Limitations

Cache size should be manually set so small that the content can fit normal packets sizes. When cache is full, new values are dropped.

LwM2M engine and application events

The Zephyr LwM2M engine defines events that can be sent back to the application through callback functions. The engine state machine shows when the events are spawned. Events depicted in the diagram are listed in the table. The events are prefixed with LWM2M_RD_CLIENT_EVENT_.

State machine for the LwM2M engine

LwM2M RD Client events

Event ID	Event Name	Description
0	NONE	No event
1	BOOTSTRAP_REG_FAILURE	Bootstrap registration failed. Occurs if there is a timeout or failure in bootstrap registration.
2	BOOTSTRAP_REG_COMPLETE	Bootstrap registration complete. Occurs after successful bootstrap registration.
3	BOOTSTRAP_TRANSFER_COMPLETE	Bootstrap finish command received from the server.
4	REGISTRATION_FAILURE	Registration to LwM2M server failed. Occurs if there is a failure in the registration.
5	REGISTRATION_COMPLETE	Registration to LwM2M server successful. Occurs after a successful registration reply from the LwM2M server or when session resumption is used.
6	REG_TIMEOUT	Registration or registration update timeout. Occurs if there is a timeout during registration. Client have lost connection to the server.
7	REG_UPDATE_COMPLETE	Registration update completed. Occurs after successful registration update reply from the LwM2M server.
8	DEREGISTER_FAILURE	Deregistration to LwM2M server failed. Occurs if there is a timeout or failure in the deregistration.
9	DISCONNECT	LwM2M client have de-registered from server and is now stopped. Triggered only if the application have requested the client to stop.
10	QUEUE_MODE_RX_OFF	Used only in queue mode, not actively listening for incoming packets. In queue mode the client is not required to actively listen for the incoming packets after a configured time period.
11	ENGINE_SUSPENDED	Indicate that client has now paused as a result of calling lwm2m_engine_pause(). State machine is no longer running and the handler thread is suspended. All timers are stopped so notifications are not triggered.
12	SERVER_DISABLED	Server have executed the disable command. Client will deregister and stay idle for the disable period.
13	NETWORK_ERROR	Sending messages to the network failed too many times. Client cannot reach any servers or fallback to bootstrap. LwM2M engine cannot recover and have stopped.

The LwM2M client engine handles most of the state transitions automatically. The application needs to handle only the events that indicate that the client have stopped or is in a state where it cannot recover.

How application should react to events

Event Name	How application should react
NONE	Ignore the event.
BOOTSTRAP_REG_FAILURE	Try to recover network connection. Then restart the client by calling lwm2m_rd_client_start(). This might also indicate configuration issue.
BOOTSTRAP_REG_COMPLETE	No actions needed
BOOTSTRAP_TRANSFER_COMPLETE	No actions needed
REGISTRATION_FAILURE	No actions needed
REGISTRATION_COMPLETE	No actions needed. Application can send or receive data.
REG_TIMEOUT	No actions needed. Client proceeds to re-registration automatically. Cannot send or receive data.
REG_UPDATE_COMPLETE	No actions needed Application can send or receive data.
DEREGISTER_FAILURE	No actions needed, client proceeds to idle state automatically. Cannot send or receive data.
DISCONNECT	Engine have stopped as a result of calling lwm2m_rd_client_stop(). If connection is required, the application should restart the client by calling lwm2m_rd_client_start().
QUEUE_MODE_RX_OFF	No actions needed. Application can send but cannot receive data. Any data transmission will trigger a registration update.
ENGINE_SUSPENDED	Engine can be resumed by calling lwm2m_engine_resume(). Cannot send or receive data.
SERVER_DISABLED	No actions needed, client will re-register once the disable period is over. Cannot send or receive data.
NETWORK_ERROR	Try to recover network connection. Then restart the client by calling lwm2m_rd_client_start(). This might also indicate configuration issue.

Sending of data in the table above refers to calling lwm2m_send_cb() or by writing into one of the observed resources where observation would trigger a notify message. Receiving of data refers to receiving read, write or execute operations from the server. Application can register callbacks for these operations.

Configuring lifetime and activity period

In LwM2M engine, there are three Kconfig options and one runtime value that configures how often the client will send LwM2M Update message.

Update period variables

Variable	Effect
LwM2M registration lifetime	The lifetime parameter in LwM2M specifies how long a device’s registration with an LwM2M server remains valid. Device is expected to send LwM2M Update message before the lifetime exprires.
CONFIG_LWM2M_ENGINE_DEFAULT_LIFETIME	Default lifetime value, unless set by the bootstrap server. Also defines lower limit that client accepts as a lifetime.
CONFIG_LWM2M_UPDATE_PERIOD	How long the client can stay idle before sending a next update.
CONFIG_LWM2M_SECONDS_TO_UPDATE_EARLY	Minimum time margin to send the update message before the registration lifetime expires.

Default way of calculating when to update registration.

By default, the client uses CONFIG_LWM2M_SECONDS_TO_UPDATE_EARLY to calculate how many seconds before the expiration of lifetime it is going to send the registration update. The problem with default mode is when the server changes the lifetime of the registration. This is then affecting the period of updates the client is doing. If this is used with the QUEUE mode, which is typical in IPv4 networks, it is also affecting the period of when the device is reachable from the server.

Update time is controlled by UPDATE_PERIOD.

When also the CONFIG_LWM2M_UPDATE_PERIOD is set, time to send the update message is the earliest when any of these values expire. This allows setting long lifetime for the registration and configure the period accurately, even if server changes the lifetime parameter.

In runtime, the update frequency is limited to once in 15 seconds to avoid flooding.

LwM2M shell

For testing the client it is possible to enable Zephyr’s shell and LwM2M specific commands which support changing the state of the client. Operations supported are read, write and execute resources. Client start, stop, pause and resume are also available. The feature is enabled by selecting CONFIG_LWM2M_SHELL. The shell is meant for testing so productions systems should not enable it.

One imaginable scenario, where to use the shell, would be executing client side actions over UART when a server side tests would require those. It is assumed that not all tests are able to trigger required actions from the server side.

uart:~$ lwm2m
lwm2m - LwM2M commands
Subcommands:
  send    :send PATHS
          LwM2M SEND operation

  exec    :exec PATH [PARAM]
          Execute a resource

  read    :read PATH [OPTIONS]
          Read value from LwM2M resource
          -x   Read value as hex stream (default)
          -s   Read value as string
          -b   Read value as bool (1/0)
          -uX  Read value as uintX_t
          -sX  Read value as intX_t
          -f   Read value as float
          -t   Read value as time_t

  write   :write PATH [OPTIONS] VALUE
          Write into LwM2M resource
          -s   Write value as string (default)
          -b   Write value as bool
          -uX  Write value as uintX_t
          -sX  Write value as intX_t
          -f   Write value as float
          -t   Write value as time_t

  create  :create PATH
          Create object or resource instance

  delete  :delete PATH
          Delete object or resource instance

  cache   :cache PATH NUM
          Enable data cache for resource
          PATH is LwM2M path
          NUM how many elements to cache

  start   :start EP_NAME [BOOTSTRAP FLAG]
          Start the LwM2M RD (Registration / Discovery) Client
          -b   Set the bootstrap flag (default 0)

  stop    :stop [OPTIONS]
          Stop the LwM2M RD (De-register) Client
          -f   Force close the connection

  update  :Trigger Registration Update of the LwM2M RD Client

  pause   :LwM2M engine thread pause
  resume  :LwM2M engine thread resume
  lock    :Lock the LwM2M registry
  unlock  :Unlock the LwM2M registry

API Reference

Related code samples

LwM2M client

Implement a LwM2M client that connects to a LwM2M server.

group lwm2m_api

Since

1.9

Version

0.8.0

LwM2M Objects managed by OMA for LwM2M tech specification.

Objects in this range have IDs from 0 to 1023.

LWM2M_OBJECT_SECURITY_ID

Security object.

LWM2M_OBJECT_SERVER_ID

Server object.

LWM2M_OBJECT_ACCESS_CONTROL_ID

Access Control object.

LWM2M_OBJECT_DEVICE_ID

Device object.

LWM2M_OBJECT_CONNECTIVITY_MONITORING_ID

Connectivity Monitoring object.

LWM2M_OBJECT_FIRMWARE_ID

Firmware object.

LWM2M_OBJECT_LOCATION_ID

Location object.

LWM2M_OBJECT_CONNECTIVITY_STATISTICS_ID

Connectivity Statistics object.

LWM2M_OBJECT_SOFTWARE_MANAGEMENT_ID

Software Management object.

LWM2M_OBJECT_PORTFOLIO_ID

Portfolio object.

LWM2M_OBJECT_BINARYAPPDATACONTAINER_ID

Binary App Data Container object.

LWM2M_OBJECT_EVENT_LOG_ID

Event Log object.

LWM2M_OBJECT_OSCORE_ID

OSCORE object.

LWM2M_OBJECT_GATEWAY_ID

Gateway object.

LwM2M Objects produced by 3rd party Standards Development

Organizations.

Refer to the OMA LightweightM2M (LwM2M) Object and Resource Registry: http://www.openmobilealliance.org/wp/OMNA/LwM2M/LwM2MRegistry.html

IPSO_OBJECT_GENERIC_SENSOR_ID

IPSO Generic Sensor object.

IPSO_OBJECT_TEMP_SENSOR_ID

IPSO Temperature Sensor object.

IPSO_OBJECT_HUMIDITY_SENSOR_ID

IPSO Humidity Sensor object.

IPSO_OBJECT_LIGHT_CONTROL_ID

IPSO Light Control object.

IPSO_OBJECT_ACCELEROMETER_ID

IPSO Accelerometer object.

IPSO_OBJECT_VOLTAGE_SENSOR_ID

IPSO Voltage Sensor object.

IPSO_OBJECT_CURRENT_SENSOR_ID

IPSO Current Sensor object.

IPSO_OBJECT_PRESSURE_ID

IPSO Pressure Sensor object.

IPSO_OBJECT_BUZZER_ID

IPSO Buzzer object.

IPSO_OBJECT_TIMER_ID

IPSO Timer object.

IPSO_OBJECT_ONOFF_SWITCH_ID

IPSO On/Off Switch object.

IPSO_OBJECT_PUSH_BUTTON_ID

IPSO Push Button object.

UCIFI_OBJECT_BATTERY_ID

uCIFI Battery object

IPSO_OBJECT_FILLING_LEVEL_SENSOR_ID

IPSO Filling Level Sensor object.

Power source types used for the “Available Power Sources” resource of

the LwM2M Device object (3/0/6).

LWM2M_DEVICE_PWR_SRC_TYPE_DC_POWER

DC power.

LWM2M_DEVICE_PWR_SRC_TYPE_BAT_INT

Internal battery.

LWM2M_DEVICE_PWR_SRC_TYPE_BAT_EXT

External battery.

LWM2M_DEVICE_PWR_SRC_TYPE_FUEL_CELL

Fuel cell.

LWM2M_DEVICE_PWR_SRC_TYPE_PWR_OVER_ETH

Power over Ethernet.

LWM2M_DEVICE_PWR_SRC_TYPE_USB

USB.

LWM2M_DEVICE_PWR_SRC_TYPE_AC_POWER

AC (mains) power.

LWM2M_DEVICE_PWR_SRC_TYPE_SOLAR

Solar.

LWM2M_DEVICE_PWR_SRC_TYPE_MAX

Max value for Available Power Source type.

Error codes used for the “Error Code” resource of the LwM2M Device

object.

An LwM2M client can register one of the following error codes via the lwm2m_device_add_err() function.

LWM2M_DEVICE_ERROR_NONE

No error.

LWM2M_DEVICE_ERROR_LOW_POWER

Low battery power.

LWM2M_DEVICE_ERROR_EXT_POWER_SUPPLY_OFF

External power supply off.

LWM2M_DEVICE_ERROR_GPS_FAILURE

GPS module failure.

LWM2M_DEVICE_ERROR_LOW_SIGNAL_STRENGTH

Low received signal strength.

LWM2M_DEVICE_ERROR_OUT_OF_MEMORY

Out of memory.

LWM2M_DEVICE_ERROR_SMS_FAILURE

SMS failure.

LWM2M_DEVICE_ERROR_NETWORK_FAILURE

IP Connectivity failure.

LWM2M_DEVICE_ERROR_PERIPHERAL_FAILURE

Peripheral malfunction.

Battery status codes used for the “Battery Status” resource (3/0/20)

of the LwM2M Device object.

As the battery status changes, an LwM2M client can set one of the following codes via: lwm2m_set_u8(“3/0/20”, [battery status])

LWM2M_DEVICE_BATTERY_STATUS_NORMAL

The battery is operating normally and not on power.

LWM2M_DEVICE_BATTERY_STATUS_CHARGING

The battery is currently charging.

LWM2M_DEVICE_BATTERY_STATUS_CHARGE_COMP

The battery is fully charged and the charger is still connected.

LWM2M_DEVICE_BATTERY_STATUS_DAMAGED

The battery has some problem.

LWM2M_DEVICE_BATTERY_STATUS_LOW

The battery is low on charge.

LWM2M_DEVICE_BATTERY_STATUS_NOT_INST

The battery is not installed.

LWM2M_DEVICE_BATTERY_STATUS_UNKNOWN

The battery information is not available.

LWM2M Firmware Update object states

An LwM2M client or the LwM2M Firmware Update object use the following codes to represent the LwM2M Firmware Update state (5/0/3).

STATE_IDLE

Idle.

Before downloading or after successful updating.

STATE_DOWNLOADING

Downloading.

The data sequence is being downloaded.

STATE_DOWNLOADED

Downloaded.

The whole data sequence has been downloaded.

STATE_UPDATING

Updating.

The device is being updated.

LWM2M Firmware Update object result codes

After processing a firmware update, the client sets the result via one of the following codes via lwm2m_set_u8(“5/0/5”, [result code])

RESULT_DEFAULT

Initial value.

RESULT_SUCCESS

Firmware updated successfully.

RESULT_NO_STORAGE

Not enough flash memory for the new firmware package.

RESULT_OUT_OF_MEM

Out of RAM during downloading process.

RESULT_CONNECTION_LOST

Connection lost during downloading process.

RESULT_INTEGRITY_FAILED

Integrity check failure for new downloaded package.

RESULT_UNSUP_FW

Unsupported package type.

RESULT_INVALID_URI

Invalid URI.

RESULT_UPDATE_FAILED

Firmware update failed.

RESULT_UNSUP_PROTO

Unsupported protocol.

Defines

LWM2M_OBJLNK_MAX_ID

Maximum value for Objlnk resource fields.

LWM2M_RES_DATA_READ_ONLY

Resource read-only value bit.

LWM2M_RES_DATA_FLAG_RO

Resource read-only flag.

LWM2M_HAS_RES_FLAG(res, f)

Read resource flags helper macro.

LWM2M_RD_CLIENT_FLAG_BOOTSTRAP

Run bootstrap procedure in current session.

LWM2M_MAX_PATH_STR_SIZE

LwM2M path maximum length.

Typedefs

typedef void (*lwm2m_socket_fault_cb_t)(int error)

Callback function called when a socket error is encountered.

Param error:

Error code

typedef void (*lwm2m_observe_cb_t)(enum lwm2m_observe_event event, struct lwm2m_obj_path *path, void *user_data)

Observe callback indicating observer adds and deletes, and notification ACKs and timeouts.

Param event:

[in] Observer add/delete or notification ack/timeout

Param path:

[in] LwM2M path

Param user_data:

[in] Pointer to user_data buffer, as provided in send_traceable_notification(). Used to determine for which data the ACKed/timed out notification was.

typedef void (*lwm2m_ctx_event_cb_t)(struct lwm2m_ctx *ctx, enum lwm2m_rd_client_event event)

Asynchronous RD client event callback.

Param ctx:

[in] LwM2M context generating the event

Param event:

[in] LwM2M RD client event code

typedef void *(*lwm2m_engine_get_data_cb_t)(uint16_t obj_inst_id, uint16_t res_id, uint16_t res_inst_id, size_t *data_len)

Asynchronous callback to get a resource buffer and length.

Prior to accessing the data buffer of a resource, the engine can use this callback to get the buffer pointer and length instead of using the resource’s data buffer.

The client or LwM2M objects can register a function of this type via: lwm2m_register_read_callback() lwm2m_register_pre_write_callback()

Param obj_inst_id:

[in] Object instance ID generating the callback.

Param res_id:

[in] Resource ID generating the callback.

Param res_inst_id:

[in] Resource instance ID generating the callback (typically 0 for non-multi instance resources).

Param data_len:

[out] Length of the data buffer.

Return:

Callback returns a pointer to the data buffer or NULL for failure.

typedef int (*lwm2m_engine_set_data_cb_t)(uint16_t obj_inst_id, uint16_t res_id, uint16_t res_inst_id, uint8_t *data, uint16_t data_len, bool last_block, size_t total_size, size_t offset)

Asynchronous callback when data has been set to a resource buffer.

After changing the data of a resource buffer, the LwM2M engine can make use of this callback to pass the data back to the client or LwM2M objects.

On a block-wise transfers the handler is called multiple times with the data blocks and increasing offset. The last block has the last_block flag set to true. Beginning of the block transfer has the offset set to 0.

A function of this type can be registered via: lwm2m_register_validate_callback() lwm2m_register_post_write_callback()

Param obj_inst_id:

[in] Object instance ID generating the callback.

Param res_id:

[in] Resource ID generating the callback.

Param res_inst_id:

[in] Resource instance ID generating the callback (typically 0 for non-multi instance resources).

Param data:

[in] Pointer to data.

Param data_len:

[in] Length of the data.

Param last_block:

[in] Flag used during block transfer to indicate the last block of data. For non-block transfers this is always false.

Param total_size:

[in] Expected total size of data for a block transfer. For non-block transfers this is 0.

Param offset:

[in] Offset of the data block. For non-block transfers this is always 0.

Return:

Callback returns a negative error code (errno.h) indicating reason of failure or 0 for success.

typedef int (*lwm2m_engine_user_cb_t)(uint16_t obj_inst_id)

Asynchronous event notification callback.

Various object instance and resource-based events in the LwM2M engine can trigger a callback of this function type: object instance create, and object instance delete.

Register a function of this type via: lwm2m_register_create_callback() lwm2m_register_delete_callback()

Param obj_inst_id:

[in] Object instance ID generating the callback.

Return:

Callback returns a negative error code (errno.h) indicating reason of failure or 0 for success.

typedef int (*lwm2m_engine_execute_cb_t)(uint16_t obj_inst_id, uint8_t *args, uint16_t args_len)

Asynchronous execute notification callback.

Resource executes trigger a callback of this type.

Register a function of this type via: lwm2m_register_exec_callback()

Param obj_inst_id:

[in] Object instance ID generating the callback.

Param args:

[in] Pointer to execute arguments payload. (This can be NULL if no arguments are provided)

Param args_len:

[in] Length of argument payload in bytes.

Return:

Callback returns a negative error code (errno.h) indicating reason of failure or 0 for success.

typedef void (*lwm2m_send_cb_t)(enum lwm2m_send_status status)

Callback returning send status.

Enums

enum lwm2m_observe_event

Observe callback events.

Values:

enumerator LWM2M_OBSERVE_EVENT_OBSERVER_ADDED

Observer added.

enumerator LWM2M_OBSERVE_EVENT_OBSERVER_REMOVED

Observer removed.

enumerator LWM2M_OBSERVE_EVENT_NOTIFY_ACK

Notification ACKed.

enumerator LWM2M_OBSERVE_EVENT_NOTIFY_TIMEOUT

Notification timed out.

enum lwm2m_socket_states

Different traffic states of the LwM2M socket.

This information can be used to give hints for the network interface that can decide what kind of power management should be used.

These hints are given from CoAP layer messages, so usage of DTLS might affect the actual number of expected datagrams.

Values:

enumerator LWM2M_SOCKET_STATE_ONGOING

Ongoing traffic is expected.

enumerator LWM2M_SOCKET_STATE_ONE_RESPONSE

One response is expected for the next message.

enumerator LWM2M_SOCKET_STATE_LAST

Next message is the last one.

enumerator LWM2M_SOCKET_STATE_NO_DATA

No more data is expected.

enum lwm2m_rd_client_event

LwM2M RD client events.

LwM2M client events are passed back to the event_cb function in lwm2m_rd_client_start()

Values:

enumerator LWM2M_RD_CLIENT_EVENT_NONE

Invalid event.

enumerator LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_FAILURE

Bootstrap registration failure.

enumerator LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_COMPLETE

Bootstrap registration complete.

enumerator LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_TRANSFER_COMPLETE

Bootstrap transfer complete.

enumerator LWM2M_RD_CLIENT_EVENT_REGISTRATION_FAILURE

Registration failure.

enumerator LWM2M_RD_CLIENT_EVENT_REGISTRATION_COMPLETE

Registration complete.

enumerator LWM2M_RD_CLIENT_EVENT_REG_TIMEOUT

Registration timeout.

enumerator LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE

Registration update complete.

enumerator LWM2M_RD_CLIENT_EVENT_DEREGISTER_FAILURE

De-registration failure.

enumerator LWM2M_RD_CLIENT_EVENT_DISCONNECT

Disconnected.

enumerator LWM2M_RD_CLIENT_EVENT_QUEUE_MODE_RX_OFF

Queue mode RX off.

enumerator LWM2M_RD_CLIENT_EVENT_ENGINE_SUSPENDED

Engine suspended.

enumerator LWM2M_RD_CLIENT_EVENT_NETWORK_ERROR

Network error.

enumerator LWM2M_RD_CLIENT_EVENT_REG_UPDATE

Registration update.

enumerator LWM2M_RD_CLIENT_EVENT_DEREGISTER

De-register.

enumerator LWM2M_RD_CLIENT_EVENT_SERVER_DISABLED

Server disabled.

enum lwm2m_send_status

LwM2M send status.

LwM2M send status are generated back to the lwm2m_send_cb_t function in lwm2m_send_cb()

Values:

enumerator LWM2M_SEND_STATUS_SUCCESS

Succeed.

enumerator LWM2M_SEND_STATUS_FAILURE

Failure.

enumerator LWM2M_SEND_STATUS_TIMEOUT

Timeout.

enum lwm2m_security_mode_e

Security modes as defined in LwM2M Security object.

Values:

enumerator LWM2M_SECURITY_PSK = 0

Pre-Shared Key mode.

enumerator LWM2M_SECURITY_RAW_PK = 1

Raw Public Key mode.

enumerator LWM2M_SECURITY_CERT = 2

Certificate mode.

enumerator LWM2M_SECURITY_NOSEC = 3

NoSec mode.

enumerator LWM2M_SECURITY_CERT_EST = 4

Certificate mode with EST.

Functions

int lwm2m_device_add_err(uint8_t error_code)

Register a new error code with LwM2M Device object.

Parameters:

• error_code – [in] New error code.

Returns:

0 for success or negative in case of error.

void lwm2m_firmware_set_write_cb(lwm2m_engine_set_data_cb_t cb)

Set data callback for firmware block transfer.

LwM2M clients use this function to register a callback for receiving the block transfer data when performing a firmware update.

Parameters:

• cb – [in] A callback function to receive the block transfer data

lwm2m_engine_set_data_cb_t lwm2m_firmware_get_write_cb(void)

Get the data callback for firmware block transfer writes.

Returns:

A registered callback function to receive the block transfer data

void lwm2m_firmware_set_write_cb_inst(uint16_t obj_inst_id, lwm2m_engine_set_data_cb_t cb)

Set data callback for firmware block transfer.

LwM2M clients use this function to register a callback for receiving the block transfer data when performing a firmware update.

Parameters:

• obj_inst_id – [in] Object instance ID

• cb – [in] A callback function to receive the block transfer data

lwm2m_engine_set_data_cb_t lwm2m_firmware_get_write_cb_inst(uint16_t obj_inst_id)

Get the data callback for firmware block transfer writes.

Parameters:

• obj_inst_id – [in] Object instance ID

Returns:

A registered callback function to receive the block transfer data

void lwm2m_firmware_set_cancel_cb(lwm2m_engine_user_cb_t cb)

Set callback for firmware update cancel.

LwM2M clients use this function to register a callback to perform actions on firmware update cancel.

Parameters:

• cb – [in] A callback function perform actions on firmware update cancel.

lwm2m_engine_user_cb_t lwm2m_firmware_get_cancel_cb(void)

Get a callback for firmware update cancel.

Returns:

A registered callback function perform actions on firmware update cancel.

void lwm2m_firmware_set_cancel_cb_inst(uint16_t obj_inst_id, lwm2m_engine_user_cb_t cb)

Set data callback for firmware update cancel.

LwM2M clients use this function to register a callback to perform actions on firmware update cancel.

Parameters:

• obj_inst_id – [in] Object instance ID

• cb – [in] A callback function perform actions on firmware update cancel.

lwm2m_engine_user_cb_t lwm2m_firmware_get_cancel_cb_inst(uint16_t obj_inst_id)

Get the callback for firmware update cancel.

Parameters:

• obj_inst_id – [in] Object instance ID

Returns:

A registered callback function perform actions on firmware update cancel.

void lwm2m_firmware_set_update_cb(lwm2m_engine_execute_cb_t cb)

Set data callback to handle firmware update execute events.

LwM2M clients use this function to register a callback for receiving the update resource “execute” operation on the LwM2M Firmware Update object.

Parameters:

• cb – [in] A callback function to receive the execute event.

lwm2m_engine_execute_cb_t lwm2m_firmware_get_update_cb(void)

Get the event callback for firmware update execute events.

Returns:

A registered callback function to receive the execute event.

void lwm2m_firmware_set_update_cb_inst(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb)

Set data callback to handle firmware update execute events.

LwM2M clients use this function to register a callback for receiving the update resource “execute” operation on the LwM2M Firmware Update object.

Parameters:

• obj_inst_id – [in] Object instance ID

• cb – [in] A callback function to receive the execute event.

lwm2m_engine_execute_cb_t lwm2m_firmware_get_update_cb_inst(uint16_t obj_inst_id)

Get the event callback for firmware update execute events.

Parameters:

• obj_inst_id – [in] Object instance ID

Returns:

A registered callback function to receive the execute event.

int lwm2m_swmgmt_set_activate_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb)

Set callback to handle software activation requests.

The callback will be executed when the LWM2M execute operation gets called on the corresponding object’s Activate resource instance.

Parameters:

• obj_inst_id – [in] The instance number to set the callback for.

• cb – [in] A callback function to receive the execute event.

Returns:

0 on success, otherwise a negative integer.

int lwm2m_swmgmt_set_deactivate_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb)

Set callback to handle software deactivation requests.

The callback will be executed when the LWM2M execute operation gets called on the corresponding object’s Deactivate resource instance.

Parameters:

• obj_inst_id – [in] The instance number to set the callback for.

• cb – [in] A callback function to receive the execute event.

Returns:

0 on success, otherwise a negative integer.

int lwm2m_swmgmt_set_install_package_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb)

Set callback to handle software install requests.

The callback will be executed when the LWM2M execute operation gets called on the corresponding object’s Install resource instance.

Parameters:

• obj_inst_id – [in] The instance number to set the callback for.

• cb – [in] A callback function to receive the execute event.

Returns:

0 on success, otherwise a negative integer.

int lwm2m_swmgmt_set_delete_package_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb)

Set callback to handle software uninstall requests.

The callback will be executed when the LWM2M execute operation gets called on the corresponding object’s Uninstall resource instance.

Parameters:

• obj_inst_id – [in] The instance number to set the callback for.

• cb – [in] A callback function for handling the execute event.

Returns:

0 on success, otherwise a negative integer.

int lwm2m_swmgmt_set_read_package_version_cb(uint16_t obj_inst_id, lwm2m_engine_get_data_cb_t cb)

Set callback to read software package.

The callback will be executed when the LWM2M read operation gets called on the corresponding object.

Parameters:

• obj_inst_id – [in] The instance number to set the callback for.

• cb – [in] A callback function for handling the read event.

Returns:

0 on success, otherwise a negative integer.

int lwm2m_swmgmt_set_write_package_cb(uint16_t obj_inst_id, lwm2m_engine_set_data_cb_t cb)

Set data callback for software management block transfer.

The callback will be executed when the LWM2M block write operation gets called on the corresponding object’s resource instance.

Parameters:

• obj_inst_id – [in] The instance number to set the callback for.

• cb – [in] A callback function for handling the block write event.

Returns:

0 on success, otherwise a negative integer.

int lwm2m_swmgmt_install_completed(uint16_t obj_inst_id, int error_code)

Function to be called when a Software Management object instance completed the Install operation.

return 0 on success, otherwise a negative integer.

Parameters:

• obj_inst_id – [in] The Software Management object instance

• error_code – [in] The result code of the operation. Zero on success otherwise it should be a negative integer.

void lwm2m_event_log_set_read_log_data_cb(lwm2m_engine_get_data_cb_t cb)

Set callback to read log data.

The callback will be executed when the LWM2M read operation gets called on the corresponding object.

Parameters:

• cb – [in] A callback function for handling the read event.

int lwm2m_update_observer_min_period(struct lwm2m_ctx *client_ctx, const struct lwm2m_obj_path *path, uint32_t period_s)

Change an observer’s pmin value.

LwM2M clients use this function to modify the pmin attribute for an observation being made. Example to update the pmin of a temperature sensor value being observed: lwm2m_update_observer_min_period(client_ctx, &LWM2M_OBJ(3303, 0, 5700), 5);

Parameters:

• client_ctx – [in] LwM2M context

• path – [in] LwM2M path as a struct

• period_s – [in] Value of pmin to be given (in seconds).

Returns:

0 for success or negative in case of error.

int lwm2m_update_observer_max_period(struct lwm2m_ctx *client_ctx, const struct lwm2m_obj_path *path, uint32_t period_s)

Change an observer’s pmax value.

LwM2M clients use this function to modify the pmax attribute for an observation being made. Example to update the pmax of a temperature sensor value being observed: lwm2m__update_observer_max_period(client_ctx, &LWM2M_OBJ(3303, 0, 5700), 5);

Parameters:

• client_ctx – [in] LwM2M context

• path – [in] LwM2M path as a struct

• period_s – [in] Value of pmax to be given (in seconds).

Returns:

0 for success or negative in case of error.

int lwm2m_create_object_inst(const struct lwm2m_obj_path *path)

Create an LwM2M object instance.

LwM2M clients use this function to create non-default LwM2M objects: Example to create first temperature sensor object: lwm2m_create_obj_inst(&LWM2M_OBJ(3303, 0));

Parameters:

• path – [in] LwM2M path as a struct

Returns:

0 for success or negative in case of error.

int lwm2m_delete_object_inst(const struct lwm2m_obj_path *path)

Delete an LwM2M object instance.

LwM2M clients use this function to delete LwM2M objects.

Parameters:

• path – [in] LwM2M path as a struct

Returns:

0 for success or negative in case of error.

void lwm2m_registry_lock(void)

Locks the registry for this thread.

Use this function before writing to multiple resources. This halts the lwm2m main thread until all the write-operations are finished.

void lwm2m_registry_unlock(void)

Unlocks the registry previously locked by lwm2m_registry_lock().

int lwm2m_set_opaque(const struct lwm2m_obj_path *path, const char *data_ptr, uint16_t data_len)

Set resource (instance) value (opaque buffer)

Parameters:

• path – [in] LwM2M path as a struct

• data_ptr – [in] Data buffer

• data_len – [in] Length of buffer

Returns:

0 for success or negative in case of error.

int lwm2m_set_string(const struct lwm2m_obj_path *path, const char *data_ptr)

Set resource (instance) value (string)

Parameters:

• path – [in] LwM2M path as a struct

• data_ptr – [in] NULL terminated char buffer

Returns:

0 for success or negative in case of error.

int lwm2m_set_u8(const struct lwm2m_obj_path *path, uint8_t value)

Set resource (instance) value (u8)

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] u8 value

Returns:

0 for success or negative in case of error.

int lwm2m_set_u16(const struct lwm2m_obj_path *path, uint16_t value)

Set resource (instance) value (u16)

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] u16 value

Returns:

0 for success or negative in case of error.

int lwm2m_set_u32(const struct lwm2m_obj_path *path, uint32_t value)

Set resource (instance) value (u32)

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] u32 value

Returns:

0 for success or negative in case of error.

int lwm2m_set_u64(const struct lwm2m_obj_path *path, uint64_t value)

Set resource (instance) value (u64)

Deprecated:

Unsigned 64bit value type does not exits. This is internally handled as a int64_t. Use lwm2m_set_s64() instead.

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] u64 value

Returns:

0 for success or negative in case of error.

int lwm2m_set_s8(const struct lwm2m_obj_path *path, int8_t value)

Set resource (instance) value (s8)

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] s8 value

Returns:

0 for success or negative in case of error.

int lwm2m_set_s16(const struct lwm2m_obj_path *path, int16_t value)

Set resource (instance) value (s16)

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] s16 value

Returns:

0 for success or negative in case of error.

int lwm2m_set_s32(const struct lwm2m_obj_path *path, int32_t value)

Set resource (instance) value (s32)

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] s32 value

Returns:

0 for success or negative in case of error.

int lwm2m_set_s64(const struct lwm2m_obj_path *path, int64_t value)

Set resource (instance) value (s64)

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] s64 value

Returns:

0 for success or negative in case of error.

int lwm2m_set_bool(const struct lwm2m_obj_path *path, bool value)

Set resource (instance) value (bool)

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] bool value

Returns:

0 for success or negative in case of error.

int lwm2m_set_f64(const struct lwm2m_obj_path *path, const double value)

Set resource (instance) value (double)

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] double value

Returns:

0 for success or negative in case of error.

int lwm2m_set_objlnk(const struct lwm2m_obj_path *path, const struct lwm2m_objlnk *value)

Set resource (instance) value (Objlnk)

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] pointer to the lwm2m_objlnk structure

Returns:

0 for success or negative in case of error.

int lwm2m_set_time(const struct lwm2m_obj_path *path, time_t value)

Set resource (instance) value (Time)

Parameters:

• path – [in] LwM2M path as a struct

• value – [in] Epoch timestamp

Returns:

0 for success or negative in case of error.

int lwm2m_set_bulk(const struct lwm2m_res_item res_list[], size_t res_list_size)

Set multiple resource (instance) values.

NOTE: Value type must match the target resource as this function does not do any type conversion. See struct lwm2m_res_item for list of resource types.

Parameters:

• res_list – [in] LwM2M resource item list

• res_list_size – [in] Length of resource list

Returns:

0 for success or negative in case of error.

int lwm2m_get_opaque(const struct lwm2m_obj_path *path, void *buf, uint16_t buflen)

Get resource (instance) value (opaque buffer)

Parameters:

• path – [in] LwM2M path as a struct

• buf – [out] Data buffer to copy data into

• buflen – [in] Length of buffer

Returns:

0 for success or negative in case of error.

int lwm2m_get_string(const struct lwm2m_obj_path *path, void *str, uint16_t buflen)

Get resource (instance) value (string)

Parameters:

• path – [in] LwM2M path as a struct

• str – [out] String buffer to copy data into

• buflen – [in] Length of buffer

Returns:

0 for success or negative in case of error.

int lwm2m_get_u8(const struct lwm2m_obj_path *path, uint8_t *value)

Get resource (instance) value (u8)

Parameters:

• path – [in] LwM2M path as a struct

• value – [out] u8 buffer to copy data into

Returns:

0 for success or negative in case of error.

int lwm2m_get_u16(const struct lwm2m_obj_path *path, uint16_t *value)

Get resource (instance) value (u16)

Parameters:

• path – [in] LwM2M path as a struct

• value – [out] u16 buffer to copy data into

Returns:

0 for success or negative in case of error.

int lwm2m_get_u32(const struct lwm2m_obj_path *path, uint32_t *value)

Get resource (instance) value (u32)

Parameters:

• path – [in] LwM2M path as a struct

• value – [out] u32 buffer to copy data into

Returns:

0 for success or negative in case of error.

int lwm2m_get_u64(const struct lwm2m_obj_path *path, uint64_t *value)

Get resource (instance) value (u64)

Deprecated:

Unsigned 64bit value type does not exits. This is internally handled as a int64_t. Use lwm2m_get_s64() instead.

Parameters:

• path – [in] LwM2M path as a struct

• value – [out] u64 buffer to copy data into

Returns:

0 for success or negative in case of error.

int lwm2m_get_s8(const struct lwm2m_obj_path *path, int8_t *value)

Get resource (instance) value (s8)

Parameters:

• path – [in] LwM2M path as a struct

• value – [out] s8 buffer to copy data into

Returns:

0 for success or negative in case of error.

int lwm2m_get_s16(const struct lwm2m_obj_path *path, int16_t *value)

Get resource (instance) value (s16)

Parameters:

• path – [in] LwM2M path as a struct

• value – [out] s16 buffer to copy data into

Returns:

0 for success or negative in case of error.

int lwm2m_get_s32(const struct lwm2m_obj_path *path, int32_t *value)

Get resource (instance) value (s32)

Parameters:

• path – [in] LwM2M path as a struct

• value – [out] s32 buffer to copy data into

Returns:

0 for success or negative in case of error.

int lwm2m_get_s64(const struct lwm2m_obj_path *path, int64_t *value)

Get resource (instance) value (s64)

Parameters:

• path – [in] LwM2M path as a struct

• value – [out] s64 buffer to copy data into

Returns:

0 for success or negative in case of error.

int lwm2m_get_bool(const struct lwm2m_obj_path *path, bool *value)

Get resource (instance) value (bool)

Parameters:

• path – [in] LwM2M path as a struct

• value – [out] bool buffer to copy data into

Returns:

0 for success or negative in case of error.

int lwm2m_get_f64(const struct lwm2m_obj_path *path, double *value)

Get resource (instance) value (double)

Parameters:

• path – [in] LwM2M path as a struct

• value – [out] double buffer to copy data into

Returns:

0 for success or negative in case of error.

int lwm2m_get_objlnk(const struct lwm2m_obj_path *path, struct lwm2m_objlnk *buf)

Get resource (instance) value (Objlnk)

Parameters:

• path – [in] LwM2M path as a struct

• buf – [out] lwm2m_objlnk buffer to copy data into

Returns:

0 for success or negative in case of error.

int lwm2m_get_time(const struct lwm2m_obj_path *path, time_t *buf)

Get resource (instance) value (Time)

Parameters:

• path – [in] LwM2M path as a struct

• buf – [out] time_t pointer to copy data

Returns:

0 for success or negative in case of error.

int lwm2m_register_read_callback(const struct lwm2m_obj_path *path, lwm2m_engine_get_data_cb_t cb)

Set resource (instance) read callback.

LwM2M clients can use this to set the callback function for resource reads when data handling in the LwM2M engine needs to be bypassed. For example reading back opaque binary data from external storage.

This callback should not generally be used for any data that might be observed as engine does not have any knowledge of data changes.

When separate buffer for data should be used, use lwm2m_set_res_buf() instead to set the storage.

Parameters:

• path – [in] LwM2M path as a struct

• cb – [in] Read resource callback

Returns:

0 for success or negative in case of error.

int lwm2m_register_pre_write_callback(const struct lwm2m_obj_path *path, lwm2m_engine_get_data_cb_t cb)

Set resource (instance) pre-write callback.

This callback is triggered before setting the value of a resource. It can pass a special data buffer to the engine so that the actual resource value can be calculated later, etc.

Parameters:

• path – [in] LwM2M path as a struct

• cb – [in] Pre-write resource callback

Returns:

0 for success or negative in case of error.

int lwm2m_register_validate_callback(const struct lwm2m_obj_path *path, lwm2m_engine_set_data_cb_t cb)

Set resource (instance) validation callback.

This callback is triggered before setting the value of a resource to the resource data buffer.

The callback allows an LwM2M client or object to validate the data before writing and notify an error if the data should be discarded for any reason (by returning a negative error code).

Note

All resources that have a validation callback registered are initially decoded into a temporary validation buffer. Make sure that CONFIG_LWM2M_ENGINE_VALIDATION_BUFFER_SIZE is large enough to store each of the validated resources (individually).

Parameters:

• path – [in] LwM2M path as a struct

• cb – [in] Validate resource data callback

Returns:

0 for success or negative in case of error.

int lwm2m_register_post_write_callback(const struct lwm2m_obj_path *path, lwm2m_engine_set_data_cb_t cb)

Set resource (instance) post-write callback.

This callback is triggered after setting the value of a resource to the resource data buffer.

It allows an LwM2M client or object to post-process the value of a resource or trigger other related resource calculations.

Parameters:

• path – [in] LwM2M path as a struct

• cb – [in] Post-write resource callback

Returns:

0 for success or negative in case of error.

int lwm2m_register_exec_callback(const struct lwm2m_obj_path *path, lwm2m_engine_execute_cb_t cb)

Set resource execute event callback.

This event is triggered when the execute method of a resource is enabled.

Parameters:

• path – [in] LwM2M path as a struct

• cb – [in] Execute resource callback

Returns:

0 for success or negative in case of error.

int lwm2m_register_create_callback(uint16_t obj_id, lwm2m_engine_user_cb_t cb)

Set object instance create event callback.

This event is triggered when an object instance is created.

Parameters:

• obj_id – [in] LwM2M object id

• cb – [in] Create object instance callback

Returns:

0 for success or negative in case of error.

int lwm2m_register_delete_callback(uint16_t obj_id, lwm2m_engine_user_cb_t cb)

Set object instance delete event callback.

This event is triggered when an object instance is deleted.

Parameters:

• obj_id – [in] LwM2M object id

• cb – [in] Delete object instance callback

Returns:

0 for success or negative in case of error.

int lwm2m_set_res_buf(const struct lwm2m_obj_path *path, void *buffer_ptr, uint16_t buffer_len, uint16_t data_len, uint8_t data_flags)

Set data buffer for a resource.

Use this function to set the data buffer and flags for the specified LwM2M resource.

Parameters:

• path – [in] LwM2M path as a struct

• buffer_ptr – [in] Data buffer pointer

• buffer_len – [in] Length of buffer

• data_len – [in] Length of existing data in the buffer

• data_flags – [in] Data buffer flags (such as read-only, etc)

Returns:

0 for success or negative in case of error.

int lwm2m_set_res_data_len(const struct lwm2m_obj_path *path, uint16_t data_len)

Update data size for a resource.

Use this function to set the new size of data in the buffer if you write to a buffer received by lwm2m_get_res_buf().

Parameters:

• path – [in] LwM2M path as a struct

• data_len – [in] Length of data

Returns:

0 for success or negative in case of error.

int lwm2m_get_res_buf(const struct lwm2m_obj_path *path, void **buffer_ptr, uint16_t *buffer_len, uint16_t *data_len, uint8_t *data_flags)

Get data buffer for a resource.

Use this function to get the data buffer information for the specified LwM2M resource.

If you directly write into the buffer, you must use lwm2m_set_res_data_len() function to update the new size of the written data.

All parameters, except for the pathstr, can be NULL if you don’t want to read those values.

Parameters:

• path – [in] LwM2M path as a struct

• buffer_ptr – [out] Data buffer pointer

• buffer_len – [out] Length of buffer

• data_len – [out] Length of existing data in the buffer

• data_flags – [out] Data buffer flags (such as read-only, etc)

Returns:

0 for success or negative in case of error.

int lwm2m_create_res_inst(const struct lwm2m_obj_path *path)

Create a resource instance.

LwM2M clients use this function to create multi-resource instances: Example to create 0 instance of device available power sources: lwm2m_create_res_inst(&LWM2M_OBJ(3, 0, 6, 0));

Parameters:

• path – [in] LwM2M path as a struct

Returns:

0 for success or negative in case of error.

int lwm2m_delete_res_inst(const struct lwm2m_obj_path *path)

Delete a resource instance.

Use this function to remove an existing resource instance

Parameters:

• path – [in] LwM2M path as a struct

Returns:

0 for success or negative in case of error.

int lwm2m_update_device_service_period(uint32_t period_ms)

Update the period of the device service.

Change the duration of the periodic device service that notifies the current time.

Parameters:

• period_ms – [in] New period for the device service (in milliseconds)

Returns:

0 for success or negative in case of error.

bool lwm2m_path_is_observed(const struct lwm2m_obj_path *path)

Check whether a path is observed.

Parameters:

• path – [in] LwM2M path as a struct to check

Returns:

true when there exists an observation of the same level or lower as the given path, false if it doesn’t or path is not a valid LwM2M-path. E.g. true if path refers to a resource and the parent object has an observation, false for the inverse.

int lwm2m_engine_stop(struct lwm2m_ctx *client_ctx)

Stop the LwM2M engine.

LwM2M clients normally do not need to call this function as it is called within lwm2m_rd_client. However, if the client does not use the RD client implementation, it will need to be called manually.

Parameters:

• client_ctx – [in] LwM2M context

Returns:

0 for success or negative in case of error.

int lwm2m_engine_start(struct lwm2m_ctx *client_ctx)

Start the LwM2M engine.

LwM2M clients normally do not need to call this function as it is called by lwm2m_rd_client_start(). However, if the client does not use the RD client implementation, it will need to be called manually.

Parameters:

• client_ctx – [in] LwM2M context

Returns:

0 for success or negative in case of error.

void lwm2m_acknowledge(struct lwm2m_ctx *client_ctx)

Acknowledge the currently processed request with an empty ACK.

LwM2M engine by default sends piggybacked responses for requests. This function allows to send an empty ACK for a request earlier (from the application callback). The LwM2M engine will then send the actual response as a separate CON message after all callbacks are executed.

Parameters:

• client_ctx – [in] LwM2M context

int lwm2m_rd_client_start(struct lwm2m_ctx *client_ctx, const char *ep_name, uint32_t flags, lwm2m_ctx_event_cb_t event_cb, lwm2m_observe_cb_t observe_cb)

Start the LwM2M RD (Registration / Discovery) Client.

The RD client sits just above the LwM2M engine and performs the necessary actions to implement the “Registration interface”. For more information see Section “Client Registration Interface” of LwM2M Technical Specification.

NOTE: lwm2m_engine_start() is called automatically by this function.

Parameters:

• client_ctx – [in] LwM2M context

• ep_name – [in] Registered endpoint name

• flags – [in] Flags used to configure current LwM2M session.

• event_cb – [in] Client event callback function

• observe_cb – [in] Observe callback function called when an observer was added or deleted, and when a notification was acked or has timed out

Returns:

0 for success, -EINPROGRESS when client is already running or negative error codes in case of failure.

int lwm2m_rd_client_stop(struct lwm2m_ctx *client_ctx, lwm2m_ctx_event_cb_t event_cb, bool deregister)

Stop the LwM2M RD (De-register) Client.

The RD client sits just above the LwM2M engine and performs the necessary actions to implement the “Registration interface”. For more information see Section “Client Registration Interface” of the LwM2M Technical Specification.

Parameters:

• client_ctx – [in] LwM2M context

• event_cb – [in] Client event callback function

• deregister – [in] True to deregister the client if registered. False to force close the connection.

Returns:

0 for success or negative in case of error.

int lwm2m_engine_pause(void)

Suspend the LwM2M engine Thread.

Suspend LwM2M engine. Use case could be when network connection is down. LwM2M Engine indicate before it suspend by LWM2M_RD_CLIENT_EVENT_ENGINE_SUSPENDED event.

Returns:

0 for success or negative in case of error.

int lwm2m_engine_resume(void)

Resume the LwM2M engine thread.

Resume suspended LwM2M engine. After successful resume call engine will do full registration or registration update based on suspended time. Event’s LWM2M_RD_CLIENT_EVENT_REGISTRATION_COMPLETE or LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE indicate that client is connected to server.

Returns:

0 for success or negative in case of error.

void lwm2m_rd_client_update(void)

Trigger a Registration Update of the LwM2M RD Client.

char *lwm2m_path_log_buf(char *buf, struct lwm2m_obj_path *path)

Helper function to print path objects’ contents to log.

Parameters:

• buf – [in] The buffer to use for formatting the string

• path – [in] The path to stringify

Returns:

Resulting formatted path string

int lwm2m_send_cb(struct lwm2m_ctx *ctx, const struct lwm2m_obj_path path_list[], uint8_t path_list_size, lwm2m_send_cb_t reply_cb)

 LwM2M SEND operation to given path list asynchronously with confirmation callback

Parameters:

• ctx – LwM2M context

• path_list – LwM2M path struct list

• path_list_size – Length of path list. Max size is CONFIG_LWM2M_COMPOSITE_PATH_LIST_SIZE

• reply_cb – Callback triggered with confirmation state or NULL if not used

Returns:

0 for success or negative in case of error.

struct lwm2m_ctx *lwm2m_rd_client_ctx(void)

Returns LwM2Mclient context

Returns:

ctx LwM2M context

int lwm2m_enable_cache(const struct lwm2m_obj_path *path, struct lwm2m_time_series_elem *data_cache, size_t cache_len)

 Enable data cache for a resource.

Application may enable caching of resource data by allocating buffer for LwM2M engine to use. Buffer must be size of struct lwm2m_time_series_elem times cache_len

Parameters:

• path – LwM2M path to resource as a struct

• data_cache – Pointer to Data cache array

• cache_len – number of cached entries

Returns:

0 for success or negative in case of error.

int lwm2m_security_mode(struct lwm2m_ctx *ctx)

Read security mode from selected security object instance.

This data is valid only if RD client is running.

Parameters:

• ctx – Pointer to client context.

Returns:

int Positive values are lwm2m_security_mode_e, negative error codes otherwise.

int lwm2m_set_default_sockopt(struct lwm2m_ctx *ctx)

Set default socket options for DTLS connections.

The engine calls this when lwm2m_ctx::set_socketoptions is not overwritten. You can call this from the overwritten callback to set extra options after or before defaults.

Parameters:

• ctx – Client context

Returns:

0 for success or negative in case of error.

struct lwm2m_obj_path

#include <lwm2m.h>

LwM2M object path structure.

Public Members

uint16_t obj_id

Object ID.

uint16_t obj_inst_id

Object instance ID.

uint16_t res_id

Resource ID.

uint16_t res_inst_id

Resource instance ID.

uint8_t level

Path level (0-4).

Ex. 4 = resource instance.

struct lwm2m_ctx

#include <lwm2m.h>

LwM2M context structure to maintain information for a single LwM2M connection.

DTLS related information

Available only when CONFIG_LWM2M_DTLS_SUPPORT is enabled and lwm2m_ctx::use_dtls is set to true.

int tls_tag

TLS tag is set by client as a reference used when the LwM2M engine calls tls_credential_(add|delete)

char *desthostname

Destination hostname.

When MBEDTLS SNI is enabled socket must be set with destination server hostname.

uint16_t desthostnamelen

Destination hostname length.

bool hostname_verify

Flag to indicate if hostname verification is enabled.

int (*load_credentials)(struct lwm2m_ctx *client_ctx)

Custom load_credentials function.

Client can set load_credentials function as a way of overriding the default behavior of load_tls_credential() in lwm2m_engine.c

Public Members

struct sockaddr remote_addr

Destination address storage.

void *processed_req

A pointer to currently processed request, for internal LwM2M engine use.

The underlying type is struct lwm2m_message, but since it’s declared in a private header and not exposed to the application, it’s stored as a void pointer.

int (*set_socketoptions)(struct lwm2m_ctx *client_ctx)

Custom socket options.

Client can override default socket options by providing a callback that is called after a socket is created and before connect.

bool use_dtls

Flag to indicate if context should use DTLS.

Enabled via the use of coaps:// protocol prefix in connection information. NOTE: requires CONFIG_LWM2M_DTLS_SUPPORT

bool connection_suspended

Flag to indicate that the socket connection is suspended.

With queue mode, this will tell if there is a need to reconnect.

bool buffer_client_messages

Flag to indicate that the client is buffering Notifications and Send messages.

True value buffer Notifications and Send messages.

int sec_obj_inst

Current index of Security Object used for server credentials.

int srv_obj_inst

Current index of Server Object used in this context.

bool bootstrap_mode

Flag to enable BOOTSTRAP interface.

See Section “Bootstrap Interface” of LwM2M Technical Specification for more information.

int sock_fd

Socket File Descriptor.

lwm2m_socket_fault_cb_t fault_cb

Socket fault callback.

LwM2M processing thread will call this callback in case of socket errors on receive.

lwm2m_observe_cb_t observe_cb

Callback for new or cancelled observations, and acknowledged or timed out notifications.

lwm2m_ctx_event_cb_t event_cb

Callback for client events.

uint8_t validate_buf[CONFIG_LWM2M_ENGINE_VALIDATION_BUFFER_SIZE]

Validation buffer.

Used as a temporary buffer to decode the resource value before validation. On successful validation, its content is copied into the actual resource buffer.

void (*set_socket_state)(int fd, enum lwm2m_socket_states state)

Callback to indicate transmission states.

Client application may request LwM2M engine to indicate hints about transmission states and use that information to control various power saving modes.

struct lwm2m_time_series_elem

#include <lwm2m.h>

LwM2M Time series data structure.

Public Members

time_t t

Cached data Unix timestamp.

union lwm2m_time_series_elem

Element value.

struct lwm2m_objlnk

#include <lwm2m.h>

LWM2M Objlnk resource type structure.

Public Members

uint16_t obj_id

Object ID.

uint16_t obj_inst

Object instance ID.

struct lwm2m_res_item

#include <lwm2m.h>

LwM2M resource item structure.

Value type must match the target resource as no type conversion are done and the value is just memcopied.

Following C types are used for resource types:

• BOOL is uint8_t

• U8 is uint8_t

• S8 is int8_t

• U16 is uint16_t

• S16 is int16_t

• U32 is uint32_t

• S32 is int32_t

• S64 is int64_t

• TIME is time_t

• FLOAT is double

• OBJLNK is struct lwm2m_objlnk

• STRING is char * and the null-terminator should be included in the size.

• OPAQUE is any binary data. When null-terminated string is written in OPAQUE resource, the terminator should not be included in size.

Public Members

struct lwm2m_obj_path *path

Pointer to LwM2M path as a struct.

void *value

Pointer to resource value.

uint16_t size

Size of the value.

For string resources, it should contain the null-terminator.