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
The library currently implements up to LwM2M specification 1.0.2.
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; /* wont 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.
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
¶
-
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_PRESSURE_ID
¶
-
IPSO_OBJECT_BUZZER_ID
¶
-
IPSO_OBJECT_TIMER_ID
¶
-
IPSO_OBJECT_ONOFF_SWITCH_ID
¶
-
IPSO_OBJECT_PUSH_BUTTON_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_FLOAT32_DEC_MAX
¶ Data structure used to represent the LwM2M float type: val1 is the whole number portion of the decimal val2 is the decimal portion *1000000 for 32bit, *1000000000 for 64bit Example: 123.456 == val1: 123, val2:456000 Example: 123.000456 = val1: 123, val2:456.
Maximum precision value for 32-bit LwM2M float val2
-
LWM2M_FLOAT64_DEC_MAX
¶ Maximum precision value for 64-bit LwM2M float val2.
-
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.
Typedefs
-
typedef void (*
lwm2m_socket_fault_cb_t
)(int error)¶
-
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()
- Parameters
obj_inst_id – [in] Object instance ID generating the callback.
res_id – [in] Resource ID generating the callback.
res_inst_id – [in] Resource instance ID generating the callback (typically 0 for non-multi instance resources).
data_len – [out] Length of the data buffer.
- Returns
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()
- Parameters
obj_inst_id – [in] Object instance ID generating the callback.
res_id – [in] Resource ID generating the callback.
res_inst_id – [in] Resource instance ID generating the callback (typically 0 for non-multi instance resources).
data – [in] Pointer to data.
data_len – [in] Length of the data.
last_block – [in] Flag used during block transfer to indicate the last block of data. For non-block transfers this is always false.
total_size – [in] Expected total size of data for a block transfer. For non-block transfers this is 0.
- Returns
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()
- Parameters
obj_inst_id – [in] Object instance ID generating the callback.
- Returns
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()
- Parameters
obj_inst_id – [in] Object instance ID generating the callback.
args – [in] Pointer to execute arguments payload. (This can be NULL if no arguments are provided)
args_len – [in] Length of argument payload in bytes.
- Returns
Callback returns a negative error code (errno.h) indicating reason of failure or 0 for success.
-
typedef struct float32_value
float32_value_t
¶ 32-bit variant of the LwM2M float structure
-
typedef struct float64_value
float64_value_t
¶ 32-bit variant of the LwM2M float structure
-
typedef void (*
lwm2m_ctx_event_cb_t
)(struct lwm2m_ctx *ctx, enum lwm2m_rd_client_event event)¶ Asynchronous RD client event callback.
- Parameters
ctx – [in] LwM2M context generating the event
event – [in] LwM2M RD client event code
Enums
-
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_NETWORK_ERROR
¶
-
enumerator
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
(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(“3303/0/5700”,5);
- Parameters
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
(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(“3303/0/5700”,5);
- Parameters
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
(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
(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
(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
(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
(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
(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
(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
(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
(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
(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
(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
(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
(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_float32
(char *pathstr, float32_value_t *value)¶ Set resource (instance) value (32-bit float structure)
- Parameters
pathstr – [in] LwM2M path string “obj/obj-inst/res(/res-inst)”
value – [in] 32-bit float value
- Returns
0 for success or negative in case of error.
-
int
lwm2m_engine_set_float64
(char *pathstr, float64_value_t *value)¶ Set resource (instance) value (64-bit float structure)
- Parameters
pathstr – [in] LwM2M path string “obj/obj-inst/res(/res-inst)”
value – [in] 64-bit float value
- Returns
0 for success or negative in case of error.
-
int
lwm2m_engine_set_objlnk
(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
(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
(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
(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
(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
(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
(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
(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
(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
(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
(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
(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_float32
(char *pathstr, float32_value_t *buf)¶ Get resource (instance) value (32-bit float structure)
- Parameters
pathstr – [in] LwM2M path string “obj/obj-inst/res(/res-inst)”
buf – [out] 32-bit float buffer to copy data into
- Returns
0 for success or negative in case of error.
-
int
lwm2m_engine_get_float64
(char *pathstr, float64_value_t *buf)¶ Get resource (instance) value (64-bit float structure)
- Parameters
pathstr – [in] LwM2M path string “obj/obj-inst/res(/res-inst)”
buf – [out] 64-bit float buffer to copy data into
- Returns
0 for success or negative in case of error.
-
int
lwm2m_engine_get_objlnk
(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
(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
(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
(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
(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
(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_data
(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.
- 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_get_res_data
(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.
- Parameters
pathstr – [in] LwM2M path string “obj/obj-inst/res(/res-inst)”
data_ptr – [out] Data buffer pointer
data_len – [out] Length of 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
(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
(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_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
-
void
lwm2m_rd_client_start
(struct lwm2m_ctx *client_ctx, const char *ep_name, uint32_t flags, lwm2m_ctx_event_cb_t event_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
-
void
lwm2m_rd_client_stop
(struct lwm2m_ctx *client_ctx, lwm2m_ctx_event_cb_t event_cb)¶ 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
-
struct
lwm2m_ctx
¶ - #include <lwm2m.h>
LwM2M context structure to maintain information for a single LwM2M connection.
Public Members
-
struct coap_pending
pendings
[CONFIG_LWM2M_ENGINE_MAX_PENDING
]¶ Private CoAP and networking structures
-
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
-
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.
-
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 coap_pending
-
struct
float32_value
¶ - #include <lwm2m.h>
32-bit variant of the LwM2M float structure
-
struct
float64_value
¶ - #include <lwm2m.h>
32-bit variant of the LwM2M float structure
-
struct
lwm2m_objlnk
¶ - #include <lwm2m.h>
LWM2M ObjLnk resource type structure.
-