This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

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.

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

  • 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 exuctions:

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_UPDATE_FAILURE:
                LOG_DBG("Registration update failure!");
                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;

        }
}

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_engine_set_string("0/0/0", "coap://5.39.83.206");

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

#define CLIENT_MANUFACTURER "Zephyr Manufacturer"

/*
 * Manufacturer resource of Device object = 3/0/0
 * We use lwm2m_engine_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_engine_set_res_data("3/0/0", CLIENT_MANUFACTURER,
                          sizeof(CLIENT_MANUFACTURER),
                          LWM2M_RES_DATA_FLAG_RO);

/* Reboot resource of Device object = 3/0/4 */
lwm2m_engine_register_exec_callback("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);

Using LwM2M library with DTLS

The Zephyr LwM2M library can be used with DTLS transport for secure communication by selecting CONFIG_LWM2M_DTLS_SUPPORT. In the client initialization we need to create a PSK and identity. These need to match the security information loaded onto the LwM2M server. Normally, the endpoint name is used to lookup the related security information:

/* "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";

Next we alter the Security object resources to include DTLS security information. The server URL should begin with coaps:// to indicate security is required. Assign a 0 value (Pre-shared Key mode) to the Security Mode resource. Lastly, set the client identity and PSK resources.

/* Use coaps:// for server URL protocol */
lwm2m_engine_set_string("0/0/0", "coaps://5.39.83.206");
/* 0 = Pre-Shared Key mode */
lwm2m_engine_set_u8("0/0/2", 0);
/* Set the client identity */
lwm2m_engine_set_string("0/0/3", (char *)client_identity);
/* Set the client pre-shared key (PSK) */
lwm2m_engine_set_opaque("0/0/5", (void *)client_psk, sizeof(client_psk));

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.

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

LwM2M engine state machine

Fig. 33 State machine for the LwM2M engine

Table 35 LwM2M RD Client events

Event ID

Event Name

Description

Actions

0

NONE

No event

Do nothing

1

BOOTSTRAP_REG_FAILURE

Bootstrap registration failed. Occurs if there is a timeout or failure in bootstrap registration.

Retry bootstrap

2

BOOTSTRAP_REG_COMPLETE

Bootstrap registration complete. Occurs after successful bootstrap registration.

No actions needed

3

BOOTSTRAP_TRANSFER_COMPLETE

Bootstrap finish command received from the server.

No actions needed, client proceeds to registration.

4

REGISTRATION_FAILURE

Registration to LwM2M server failed. Occurs if there is a timeout or failure in the registration.

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

No actions needed

6

REG_UPDATE_FAILURE

Registration update failed. Occurs if there is a timeout during registration update. NOTE: If registration update fails without a timeout, a full registration is triggered automatically and no registration update failure event is generated.

No actions needed, client proceeds to re-registration automatically.

7

REG_UPDATE_COMPLETE

Registration update completed. Occurs after successful registration update reply from the LwM2M server.

No actions needed

8

DEREGISTER_FAILURE

Deregistration to LwM2M server failed. Occurs if there is a timeout or failure in the deregistration.

No actions needed, client proceeds to idle state automatically.

9

DISCONNECT

Disconnected from LwM2M server. Occurs if there is a timeout during communication with server. Also triggered after deregistration has been done.

If connection is required, the application should restart the client.

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.

No actions needed

11

NETWORK_ERROR

Sending messages to the network failed too many times. If sending a message fails, it will be retried. If the retry counter reaches its limits, this event will be triggered.

No actions needed, client will do a re-registrate automatically.

API Reference

group lwm2m_api

LwM2M high-level API.

LwM2M high-level interface is defined in this header.

Note

The implementation assumes UDP module is enabled.

Note

LwM2M 1.0.x is currently the only supported version.

Defines

LWM2M_OBJECT_SECURITY_ID

LwM2M Objects managed by OMA for LwM2M tech specification. Objects in this range have IDs from 0 to 1023. For more information refer to Technical Specification OMA-TS-LightweightM2M-V1_0_2-20180209-A.

LWM2M_OBJECT_SERVER_ID
LWM2M_OBJECT_ACCESS_CONTROL_ID
LWM2M_OBJECT_DEVICE_ID
LWM2M_OBJECT_CONNECTIVITY_MONITORING_ID
LWM2M_OBJECT_FIRMWARE_ID
LWM2M_OBJECT_LOCATION_ID
LWM2M_OBJECT_CONNECTIVITY_STATISTICS_ID
LWM2M_OBJECT_SOFTWARE_MANAGEMENT_ID
LWM2M_OBJECT_PORTFOLIO_ID
LWM2M_OBJECT_EVENT_LOG_ID
LWM2M_OBJECT_GATEWAY_ID
IPSO_OBJECT_GENERIC_SENSOR_ID

LwM2M Objects produced by 3rd party Standards Development Organizations. Objects in this range have IDs from 2048 to 10240 Refer to the OMA LightweightM2M (LwM2M) Object and Resource Registry: http://www.openmobilealliance.org/wp/OMNA/LwM2M/LwM2MRegistry.html.

IPSO_OBJECT_TEMP_SENSOR_ID
IPSO_OBJECT_HUMIDITY_SENSOR_ID
IPSO_OBJECT_LIGHT_CONTROL_ID
IPSO_OBJECT_ACCELEROMETER_ID
IPSO_OBJECT_CURRENT_SENSOR_ID
IPSO_OBJECT_PRESSURE_ID
IPSO_OBJECT_BUZZER_ID
IPSO_OBJECT_TIMER_ID
IPSO_OBJECT_ONOFF_SWITCH_ID
IPSO_OBJECT_PUSH_BUTTON_ID
UCIFI_OBJECT_BATTERY_ID
IPSO_OBJECT_FILLING_LEVEL_SENSOR_ID
LWM2M_DEVICE_PWR_SRC_TYPE_DC_POWER

Power source types used for the “Available Power Sources” resource of the LwM2M Device object.

LWM2M_DEVICE_PWR_SRC_TYPE_BAT_INT
LWM2M_DEVICE_PWR_SRC_TYPE_BAT_EXT
LWM2M_DEVICE_PWR_SRC_TYPE_UNUSED
LWM2M_DEVICE_PWR_SRC_TYPE_PWR_OVER_ETH
LWM2M_DEVICE_PWR_SRC_TYPE_USB
LWM2M_DEVICE_PWR_SRC_TYPE_AC_POWER
LWM2M_DEVICE_PWR_SRC_TYPE_SOLAR
LWM2M_DEVICE_PWR_SRC_TYPE_MAX
LWM2M_DEVICE_ERROR_NONE

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_LOW_POWER
LWM2M_DEVICE_ERROR_EXT_POWER_SUPPLY_OFF
LWM2M_DEVICE_ERROR_GPS_FAILURE
LWM2M_DEVICE_ERROR_LOW_SIGNAL_STRENGTH
LWM2M_DEVICE_ERROR_OUT_OF_MEMORY
LWM2M_DEVICE_ERROR_SMS_FAILURE
LWM2M_DEVICE_ERROR_NETWORK_FAILURE
LWM2M_DEVICE_ERROR_PERIPHERAL_FAILURE
LWM2M_DEVICE_BATTERY_STATUS_NORMAL

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_engine_set_u8(“3/0/20”, [battery status])

LWM2M_DEVICE_BATTERY_STATUS_CHARGING
LWM2M_DEVICE_BATTERY_STATUS_CHARGE_COMP
LWM2M_DEVICE_BATTERY_STATUS_DAMAGED
LWM2M_DEVICE_BATTERY_STATUS_LOW
LWM2M_DEVICE_BATTERY_STATUS_NOT_INST
LWM2M_DEVICE_BATTERY_STATUS_UNKNOWN
STATE_IDLE

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_DOWNLOADING
STATE_DOWNLOADED
STATE_UPDATING
RESULT_DEFAULT

LWM2M Firmware Update object result codes.

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

RESULT_SUCCESS
RESULT_NO_STORAGE
RESULT_OUT_OF_MEM
RESULT_CONNECTION_LOST
RESULT_INTEGRITY_FAILED
RESULT_UNSUP_FW
RESULT_INVALID_URI
RESULT_UPDATE_FAILED
RESULT_UNSUP_PROTO
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_LEN

LwM2M path maximum length.

Typedefs

typedef void (*lwm2m_socket_fault_cb_t)(int error)
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_engine_register_read_callback() lwm2m_engine_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)

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.

A function of this type can be registered via: lwm2m_engine_register_validate_callback() lwm2m_engine_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.

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_engine_register_create_callback() lwm2m_engine_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_engine_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.

Enums

enum lwm2m_observe_event

Observe callback events.

Values:

enumerator LWM2M_OBSERVE_EVENT_OBSERVER_ADDED
enumerator LWM2M_OBSERVE_EVENT_OBSERVER_REMOVED
enumerator LWM2M_OBSERVE_EVENT_NOTIFY_ACK
enumerator LWM2M_OBSERVE_EVENT_NOTIFY_TIMEOUT
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
enumerator LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_FAILURE
enumerator LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_COMPLETE
enumerator LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_TRANSFER_COMPLETE
enumerator LWM2M_RD_CLIENT_EVENT_REGISTRATION_FAILURE
enumerator LWM2M_RD_CLIENT_EVENT_REGISTRATION_COMPLETE
enumerator LWM2M_RD_CLIENT_EVENT_REG_UPDATE_FAILURE
enumerator LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE
enumerator LWM2M_RD_CLIENT_EVENT_DEREGISTER_FAILURE
enumerator LWM2M_RD_CLIENT_EVENT_DISCONNECT
enumerator LWM2M_RD_CLIENT_EVENT_QUEUE_MODE_RX_OFF
enumerator LWM2M_RD_CLIENT_EVENT_ENGINE_SUSPENDED
enumerator LWM2M_RD_CLIENT_EVENT_NETWORK_ERROR

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.

int lwm2m_engine_update_observer_min_period(struct lwm2m_ctx *client_ctx, const char *pathstr, 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_engine_update_observer_min_period(“client_ctx, 3303/0/5700”, 5);

Parameters
  • client_ctx[in] LwM2M context

  • pathstr[in] LwM2M path string “obj/obj-inst/res”

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

Returns

0 for success or negative in case of error.

int lwm2m_engine_update_observer_max_period(struct lwm2m_ctx *client_ctx, const char *pathstr, 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_engine_update_observer_max_period(“client_ctx, 3303/0/5700”, 5);

Parameters
  • client_ctx[in] LwM2M context

  • pathstr[in] LwM2M path string “obj/obj-inst/res”

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

Returns

0 for success or negative in case of error.

int lwm2m_engine_create_obj_inst(const char *pathstr)

Create an LwM2M object instance.

LwM2M clients use this function to create non-default LwM2M objects: Example to create first temperature sensor object: lwm2m_engine_create_obj_inst(“3303/0”);

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst”

Returns

0 for success or negative in case of error.

int lwm2m_engine_delete_obj_inst(const char *pathstr)

Delete an LwM2M object instance.

LwM2M clients use this function to delete LwM2M objects.

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst”

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_opaque(const char *pathstr, char *data_ptr, uint16_t data_len)

Set resource (instance) value (opaque buffer)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • data_ptr[in] Data buffer

  • data_len[in] Length of buffer

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_string(const char *pathstr, char *data_ptr)

Set resource (instance) value (string)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • data_ptr[in] NULL terminated char buffer

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_u8(const char *pathstr, uint8_t value)

Set resource (instance) value (u8)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[in] u8 value

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_u16(const char *pathstr, uint16_t value)

Set resource (instance) value (u16)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[in] u16 value

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_u32(const char *pathstr, uint32_t value)

Set resource (instance) value (u32)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[in] u32 value

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_u64(const char *pathstr, uint64_t value)

Set resource (instance) value (u64)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[in] u64 value

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_s8(const char *pathstr, int8_t value)

Set resource (instance) value (s8)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[in] s8 value

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_s16(const char *pathstr, int16_t value)

Set resource (instance) value (s16)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[in] s16 value

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_s32(const char *pathstr, int32_t value)

Set resource (instance) value (s32)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[in] s32 value

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_s64(const char *pathstr, int64_t value)

Set resource (instance) value (s64)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[in] s64 value

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_bool(const char *pathstr, bool value)

Set resource (instance) value (bool)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[in] bool value

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_float(const char *pathstr, double *value)

Set resource (instance) value (double)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[in] double value

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_objlnk(const char *pathstr, struct lwm2m_objlnk *value)

Set resource (instance) value (ObjLnk)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[in] pointer to the lwm2m_objlnk structure

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_opaque(const char *pathstr, void *buf, uint16_t buflen)

Get resource (instance) value (opaque buffer)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • 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_engine_get_string(const char *pathstr, void *str, uint16_t strlen)

Get resource (instance) value (string)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • str[out] String buffer to copy data into

  • strlen[in] Length of buffer

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_u8(const char *pathstr, uint8_t *value)

Get resource (instance) value (u8)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[out] u8 buffer to copy data into

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_u16(const char *pathstr, uint16_t *value)

Get resource (instance) value (u16)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[out] u16 buffer to copy data into

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_u32(const char *pathstr, uint32_t *value)

Get resource (instance) value (u32)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[out] u32 buffer to copy data into

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_u64(const char *pathstr, uint64_t *value)

Get resource (instance) value (u64)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[out] u64 buffer to copy data into

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_s8(const char *pathstr, int8_t *value)

Get resource (instance) value (s8)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[out] s8 buffer to copy data into

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_s16(const char *pathstr, int16_t *value)

Get resource (instance) value (s16)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[out] s16 buffer to copy data into

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_s32(const char *pathstr, int32_t *value)

Get resource (instance) value (s32)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[out] s32 buffer to copy data into

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_s64(const char *pathstr, int64_t *value)

Get resource (instance) value (s64)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[out] s64 buffer to copy data into

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_bool(const char *pathstr, bool *value)

Get resource (instance) value (bool)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • value[out] bool buffer to copy data into

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_float(const char *pathstr, double *buf)

Get resource (instance) value (double)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • buf[out] double buffer to copy data into

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_objlnk(const char *pathstr, struct lwm2m_objlnk *buf)

Get resource (instance) value (ObjLnk)

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • buf[out] lwm2m_objlnk buffer to copy data into

Returns

0 for success or negative in case of error.

int lwm2m_engine_register_read_callback(const char *pathstr, 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.

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • cb[in] Read resource callback

Returns

0 for success or negative in case of error.

int lwm2m_engine_register_pre_write_callback(const char *pathstr, 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
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • cb[in] Pre-write resource callback

Returns

0 for success or negative in case of error.

int lwm2m_engine_register_validate_callback(const char *pathstr, 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
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • cb[in] Validate resource data callback

Returns

0 for success or negative in case of error.

int lwm2m_engine_register_post_write_callback(const char *pathstr, 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
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • cb[in] Post-write resource callback

Returns

0 for success or negative in case of error.

int lwm2m_engine_register_exec_callback(const char *pathstr, 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
  • pathstr[in] LwM2M path string “obj/obj-inst/res”

  • cb[in] Execute resource callback

Returns

0 for success or negative in case of error.

int lwm2m_engine_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_engine_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_engine_set_res_buf(const char *pathstr, 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
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • 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_engine_set_res_data(const char *pathstr, void *data_ptr, 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.

Deprecated:

Use lwm2m_engine_set_res_buf() instead, so you can define buffer size and data size separately.

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • data_ptr[in] Data buffer pointer

  • data_len[in] Length of buffer

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

Returns

0 for success or negative in case of error.

int lwm2m_engine_set_res_data_len(const char *pathstr, 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_engine_get_res_buf().

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • data_len[in] Length of data

Returns

0 for success or negative in case of error.

int lwm2m_engine_get_res_buf(const char *pathstr, 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_engine_set_res_data_len() function to update the new size of the written data.

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

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • 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_engine_get_res_data(const char *pathstr, void **data_ptr, 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.

Deprecated:

Use lwm2m_engine_get_res_buf() as it can tell you the size of the buffer as well.

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res(/res-inst)”

  • data_ptr[out] Data buffer pointer

  • 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_engine_create_res_inst(const char *pathstr)

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_engine_create_res_inst(“3/0/6/0”);

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res/res-inst”

Returns

0 for success or negative in case of error.

int lwm2m_engine_delete_res_inst(const char *pathstr)

Delete a resource instance.

Use this function to remove an existing resource instance

Parameters
  • pathstr[in] LwM2M path string “obj/obj-inst/res/res-inst”

Returns

0 for success or negative in case of error.

int lwm2m_engine_update_service_period(k_work_handler_t service, uint32_t period_ms)

Update the period of a given service.

Allow the period modification on an existing service created with lwm2m_engine_add_service(). Example to frequency at which a periodic_service changes it’s values : lwm2m_engine_update_service(device_periodic_service,5*MSEC_PER_SEC);

Parameters
  • service[in] Handler of the periodic_service

  • period_ms[in] New period for the periodic_service (in milliseconds)

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_engine_path_is_observed(const char *pathstr)

Check whether a path is observed.

Parameters
  • pathstr[in] LwM2M path string to check, e.g. “3/0/1”

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 5.3 “Client Registration Interface” of the 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 5.3 “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 WM2M_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_engine_send(struct lwm2m_ctx *ctx, char const *path_list[], uint8_t path_list_size, bool confirmation_request)

 LwM2M SEND operation to given path list

Parameters
  • ctx – LwM2M context

  • path_list – LwM2M Path string list

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

  • confirmation_request – True request confirmation for operation.    

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

struct lwm2m_obj_path
#include <lwm2m.h>
struct lwm2m_ctx
#include <lwm2m.h>

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

Public Members

struct sockaddr remote_addr

Destination address storage

struct coap_pending pendings[CONFIG_LWM2M_ENGINE_MAX_PENDING + 1]

Private CoAP and networking structures + 1 is for RD Client own message

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.

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=y

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.

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 5.2 “Bootstrap Interface” of LwM2M Technical Specification 1.0.2 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.

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.

struct lwm2m_objlnk
#include <lwm2m.h>

LWM2M ObjLnk resource type structure.