Line data Source code
1 1 : /*
2 : * Copyright (c) 2017 Linaro Limited
3 : * Copyright (c) 2017-2019 Foundries.io
4 : *
5 : * SPDX-License-Identifier: Apache-2.0
6 : */
7 :
8 : /** @file lwm2m.h
9 : *
10 : * @brief LwM2M high-level API
11 : *
12 : * @details
13 : * LwM2M high-level interface is defined in this header.
14 : *
15 : * @note The implementation assumes UDP module is enabled.
16 : *
17 : * @note For more information refer to Technical Specification
18 : * OMA-TS-LightweightM2M_Core-V1_1_1-20190617-A
19 : *
20 : * @defgroup lwm2m_api LwM2M high-level API
21 : * @since 1.9
22 : * @version 0.8.0
23 : * @ingroup networking
24 : * @{
25 : */
26 :
27 : #ifndef ZEPHYR_INCLUDE_NET_LWM2M_H_
28 : #define ZEPHYR_INCLUDE_NET_LWM2M_H_
29 :
30 : #include <time.h>
31 : #include <zephyr/kernel.h>
32 : #include <zephyr/sys/mutex.h>
33 : #include <zephyr/net/coap.h>
34 : #include <zephyr/net/lwm2m_path.h>
35 :
36 : #ifdef __cplusplus
37 : extern "C" {
38 : #endif
39 :
40 : /**
41 : * @name LwM2M Objects managed by OMA for LwM2M tech specification.
42 : * Objects in this range have IDs from 0 to 1023.
43 : * @{
44 : */
45 :
46 : /* clang-format off */
47 1 : #define LWM2M_OBJECT_SECURITY_ID 0 /**< Security object */
48 1 : #define LWM2M_OBJECT_SERVER_ID 1 /**< Server object */
49 1 : #define LWM2M_OBJECT_ACCESS_CONTROL_ID 2 /**< Access Control object */
50 1 : #define LWM2M_OBJECT_DEVICE_ID 3 /**< Device object */
51 1 : #define LWM2M_OBJECT_CONNECTIVITY_MONITORING_ID 4 /**< Connectivity Monitoring object */
52 1 : #define LWM2M_OBJECT_FIRMWARE_ID 5 /**< Firmware object */
53 1 : #define LWM2M_OBJECT_LOCATION_ID 6 /**< Location object */
54 1 : #define LWM2M_OBJECT_CONNECTIVITY_STATISTICS_ID 7 /**< Connectivity Statistics object */
55 1 : #define LWM2M_OBJECT_SOFTWARE_MANAGEMENT_ID 9 /**< Software Management object */
56 1 : #define LWM2M_OBJECT_PORTFOLIO_ID 16 /**< Portfolio object */
57 1 : #define LWM2M_OBJECT_BINARYAPPDATACONTAINER_ID 19 /**< Binary App Data Container object */
58 1 : #define LWM2M_OBJECT_EVENT_LOG_ID 20 /**< Event Log object */
59 1 : #define LWM2M_OBJECT_OSCORE_ID 21 /**< OSCORE object */
60 1 : #define LWM2M_OBJECT_GATEWAY_ID 25 /**< Gateway object */
61 : /* clang-format on */
62 :
63 : /** @} */
64 :
65 : /**
66 : * @name LwM2M Objects produced by 3rd party Standards Development
67 : * Organizations.
68 : * Refer to the OMA LightweightM2M (LwM2M) Object and Resource Registry:
69 : * http://www.openmobilealliance.org/wp/OMNA/LwM2M/LwM2MRegistry.html
70 : * @{
71 : */
72 :
73 : /* clang-format off */
74 1 : #define IPSO_OBJECT_GENERIC_SENSOR_ID 3300 /**< IPSO Generic Sensor object */
75 1 : #define IPSO_OBJECT_TEMP_SENSOR_ID 3303 /**< IPSO Temperature Sensor object */
76 1 : #define IPSO_OBJECT_HUMIDITY_SENSOR_ID 3304 /**< IPSO Humidity Sensor object */
77 1 : #define IPSO_OBJECT_LIGHT_CONTROL_ID 3311 /**< IPSO Light Control object */
78 1 : #define IPSO_OBJECT_ACCELEROMETER_ID 3313 /**< IPSO Accelerometer object */
79 1 : #define IPSO_OBJECT_VOLTAGE_SENSOR_ID 3316 /**< IPSO Voltage Sensor object */
80 1 : #define IPSO_OBJECT_CURRENT_SENSOR_ID 3317 /**< IPSO Current Sensor object */
81 1 : #define IPSO_OBJECT_PRESSURE_ID 3323 /**< IPSO Pressure Sensor object */
82 1 : #define IPSO_OBJECT_BUZZER_ID 3338 /**< IPSO Buzzer object */
83 1 : #define IPSO_OBJECT_TIMER_ID 3340 /**< IPSO Timer object */
84 1 : #define IPSO_OBJECT_ONOFF_SWITCH_ID 3342 /**< IPSO On/Off Switch object */
85 1 : #define IPSO_OBJECT_PUSH_BUTTON_ID 3347 /**< IPSO Push Button object */
86 1 : #define UCIFI_OBJECT_BATTERY_ID 3411 /**< uCIFI Battery object */
87 1 : #define IPSO_OBJECT_FILLING_LEVEL_SENSOR_ID 3435 /**< IPSO Filling Level Sensor object */
88 : /* clang-format on */
89 :
90 : /** @} */
91 :
92 : /**
93 : * @brief Callback function called when a socket error is encountered
94 : *
95 : * @param error Error code
96 : */
97 1 : typedef void (*lwm2m_socket_fault_cb_t)(int error);
98 :
99 : /** @brief LwM2M object path structure */
100 1 : struct lwm2m_obj_path {
101 1 : uint16_t obj_id; /**< Object ID */
102 1 : uint16_t obj_inst_id; /**< Object instance ID */
103 1 : uint16_t res_id; /**< Resource ID */
104 1 : uint16_t res_inst_id; /**< Resource instance ID */
105 1 : uint8_t level; /**< Path level (0-4). Ex. 4 = resource instance. */
106 : };
107 :
108 : /**
109 : * @brief Observe callback events
110 : */
111 1 : enum lwm2m_observe_event {
112 : LWM2M_OBSERVE_EVENT_OBSERVER_ADDED, /**< Observer added */
113 : LWM2M_OBSERVE_EVENT_OBSERVER_REMOVED, /**< Observer removed */
114 : LWM2M_OBSERVE_EVENT_NOTIFY_ACK, /**< Notification ACKed */
115 : LWM2M_OBSERVE_EVENT_NOTIFY_TIMEOUT, /**< Notification timed out */
116 : };
117 :
118 : /**
119 : * @brief Observe callback indicating observer adds and deletes, and
120 : * notification ACKs and timeouts
121 : *
122 : * @param[in] event Observer add/delete or notification ack/timeout
123 : * @param[in] path LwM2M path
124 : * @param[in] user_data Pointer to user_data buffer, as provided in
125 : * send_traceable_notification(). Used to determine for which
126 : * data the ACKed/timed out notification was.
127 : */
128 1 : typedef void (*lwm2m_observe_cb_t)(enum lwm2m_observe_event event, struct lwm2m_obj_path *path,
129 : void *user_data);
130 :
131 :
132 : struct lwm2m_ctx;
133 :
134 : /**
135 : * @brief LwM2M RD client events
136 : *
137 : * LwM2M client events are passed back to the event_cb function in
138 : * lwm2m_rd_client_start()
139 : */
140 1 : enum lwm2m_rd_client_event {
141 : /** Invalid event */
142 : LWM2M_RD_CLIENT_EVENT_NONE,
143 : /** Bootstrap registration failure */
144 : LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_FAILURE,
145 : /** Bootstrap registration complete */
146 : LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_COMPLETE,
147 : /** Bootstrap transfer complete */
148 : LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_TRANSFER_COMPLETE,
149 : /** Registration failure */
150 : LWM2M_RD_CLIENT_EVENT_REGISTRATION_FAILURE,
151 : /** Registration complete */
152 : LWM2M_RD_CLIENT_EVENT_REGISTRATION_COMPLETE,
153 : /** Registration timeout */
154 : LWM2M_RD_CLIENT_EVENT_REG_TIMEOUT,
155 : /** Registration update complete */
156 : LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE,
157 : /** De-registration failure */
158 : LWM2M_RD_CLIENT_EVENT_DEREGISTER_FAILURE,
159 : /** Disconnected */
160 : LWM2M_RD_CLIENT_EVENT_DISCONNECT,
161 : /** Queue mode RX off */
162 : LWM2M_RD_CLIENT_EVENT_QUEUE_MODE_RX_OFF,
163 : /** Engine suspended */
164 : LWM2M_RD_CLIENT_EVENT_ENGINE_SUSPENDED,
165 : /** Network error */
166 : LWM2M_RD_CLIENT_EVENT_NETWORK_ERROR,
167 : /** Registration update */
168 : LWM2M_RD_CLIENT_EVENT_REG_UPDATE,
169 : /** De-register */
170 : LWM2M_RD_CLIENT_EVENT_DEREGISTER,
171 : /** Server disabled */
172 : LWM2M_RD_CLIENT_EVENT_SERVER_DISABLED,
173 : };
174 :
175 :
176 : /**
177 : * @brief Asynchronous RD client event callback
178 : *
179 : * @param[in] ctx LwM2M context generating the event
180 : * @param[in] event LwM2M RD client event code
181 : */
182 1 : typedef void (*lwm2m_ctx_event_cb_t)(struct lwm2m_ctx *ctx,
183 : enum lwm2m_rd_client_event event);
184 :
185 0 : typedef int (*lwm2m_set_sockopt_cb_t)(struct lwm2m_ctx *client_ctx);
186 :
187 : /**
188 : * @brief Different traffic states of the LwM2M socket.
189 : *
190 : * This information can be used to give hints for the network interface
191 : * that can decide what kind of power management should be used.
192 : *
193 : * These hints are given from CoAP layer messages, so usage of DTLS might affect the
194 : * actual number of expected datagrams.
195 : */
196 1 : enum lwm2m_socket_states {
197 : LWM2M_SOCKET_STATE_ONGOING, /**< Ongoing traffic is expected. */
198 : LWM2M_SOCKET_STATE_ONE_RESPONSE, /**< One response is expected for the next message. */
199 : LWM2M_SOCKET_STATE_LAST, /**< Next message is the last one. */
200 : LWM2M_SOCKET_STATE_NO_DATA, /**< No more data is expected. */
201 : };
202 :
203 : /**
204 : * @brief LwM2M context structure to maintain information for a single
205 : * LwM2M connection.
206 : */
207 1 : struct lwm2m_ctx {
208 : /** Destination address storage */
209 1 : struct sockaddr remote_addr;
210 :
211 : /** @cond INTERNAL_HIDDEN
212 : * Private CoAP and networking structures + 1 is for RD Client own message
213 : */
214 : struct coap_pending pendings[CONFIG_LWM2M_ENGINE_MAX_PENDING + 1];
215 : struct coap_reply replies[CONFIG_LWM2M_ENGINE_MAX_REPLIES + 1];
216 : sys_slist_t pending_sends;
217 : #if defined(CONFIG_LWM2M_QUEUE_MODE_ENABLED)
218 : sys_slist_t queued_messages;
219 : #endif
220 : sys_slist_t observer;
221 : struct k_mutex lock;
222 : /** @endcond */
223 :
224 : /** A pointer to currently processed request, for internal LwM2M engine
225 : * use. The underlying type is ``struct lwm2m_message``, but since it's
226 : * declared in a private header and not exposed to the application,
227 : * it's stored as a void pointer.
228 : */
229 1 : void *processed_req;
230 :
231 : #if defined(CONFIG_LWM2M_DTLS_SUPPORT) || defined(__DOXYGEN__)
232 : /**
233 : * @name DTLS related information
234 : * Available only when @kconfig{CONFIG_LWM2M_DTLS_SUPPORT} is enabled and
235 : * @ref lwm2m_ctx.use_dtls is set to true.
236 : * @{
237 : */
238 : /** TLS tag is set by client as a reference used when the
239 : * LwM2M engine calls tls_credential_(add|delete)
240 : */
241 1 : int tls_tag;
242 :
243 : /** Destination hostname.
244 : * When MBEDTLS SNI is enabled socket must be set with destination
245 : * server hostname.
246 : */
247 1 : char *desthostname;
248 : /** Destination hostname length */
249 1 : uint16_t desthostnamelen;
250 :
251 : /** Custom load_credentials function.
252 : * Client can set load_credentials function as a way of overriding
253 : * the default behavior of load_tls_credential() in lwm2m_engine.c
254 : */
255 1 : int (*load_credentials)(struct lwm2m_ctx *client_ctx);
256 : /** @} */
257 : #endif
258 : /** Custom socket options.
259 : * Client can override default socket options by providing
260 : * a callback that is called after a socket is created and before
261 : * connect.
262 : */
263 1 : lwm2m_set_sockopt_cb_t set_socketoptions;
264 :
265 : /** Flag to indicate if context should use DTLS.
266 : * Enabled via the use of coaps:// protocol prefix in connection
267 : * information.
268 : * NOTE: requires @kconfig{CONFIG_LWM2M_DTLS_SUPPORT}
269 : */
270 1 : bool use_dtls;
271 :
272 : /**
273 : * Flag to indicate that the socket connection is suspended.
274 : * With queue mode, this will tell if there is a need to reconnect.
275 : */
276 1 : bool connection_suspended;
277 :
278 : #if defined(CONFIG_LWM2M_QUEUE_MODE_ENABLED) || defined(__DOXYGEN__)
279 : /**
280 : * Flag to indicate that the client is buffering Notifications and Send messages.
281 : * True value buffer Notifications and Send messages.
282 : */
283 1 : bool buffer_client_messages;
284 : #endif
285 : /** Current index of Security Object used for server credentials */
286 1 : int sec_obj_inst;
287 :
288 : /** Current index of Server Object used in this context. */
289 1 : int srv_obj_inst;
290 :
291 : /** Flag to enable BOOTSTRAP interface. See Section "Bootstrap Interface"
292 : * of LwM2M Technical Specification for more information.
293 : */
294 1 : bool bootstrap_mode;
295 :
296 : /** Socket File Descriptor */
297 1 : int sock_fd;
298 :
299 : /** Socket fault callback. LwM2M processing thread will call this
300 : * callback in case of socket errors on receive.
301 : */
302 1 : lwm2m_socket_fault_cb_t fault_cb;
303 :
304 : /** Callback for new or cancelled observations, and acknowledged or timed
305 : * out notifications.
306 : */
307 1 : lwm2m_observe_cb_t observe_cb;
308 :
309 : /** Callback for client events */
310 1 : lwm2m_ctx_event_cb_t event_cb;
311 :
312 : /** Validation buffer. Used as a temporary buffer to decode the resource
313 : * value before validation. On successful validation, its content is
314 : * copied into the actual resource buffer.
315 : */
316 1 : uint8_t validate_buf[CONFIG_LWM2M_ENGINE_VALIDATION_BUFFER_SIZE];
317 :
318 : /**
319 : * Callback to indicate transmission states.
320 : * Client application may request LwM2M engine to indicate hints about
321 : * transmission states and use that information to control various power
322 : * saving modes.
323 : */
324 1 : void (*set_socket_state)(int fd, enum lwm2m_socket_states state);
325 : };
326 :
327 : /**
328 : * LwM2M Time series data structure
329 : */
330 1 : struct lwm2m_time_series_elem {
331 : /** Cached data Unix timestamp */
332 1 : time_t t;
333 : /** Element value */
334 : union {
335 : /** @cond INTERNAL_HIDDEN */
336 : uint8_t u8;
337 : uint16_t u16;
338 : uint32_t u32;
339 : uint64_t u64;
340 : int8_t i8;
341 : int16_t i16;
342 : int32_t i32;
343 : int64_t i64;
344 : time_t time;
345 : double f;
346 : bool b;
347 : /** @endcond */
348 1 : };
349 : };
350 :
351 : /**
352 : * @typedef lwm2m_cache_filter_cb_t
353 : * @brief Callback type for filtering cached time series samples.
354 : *
355 : * Returning false skips storing the provided sample in the LwM2M cache.
356 : *
357 : * @param path Object path of the cached resource.
358 : * @param element Sample produced by the engine for the cache.
359 : *
360 : * @return true to keep the sample, false to discard it.
361 : */
362 1 : typedef bool (*lwm2m_cache_filter_cb_t)(const struct lwm2m_obj_path *path,
363 : const struct lwm2m_time_series_elem *element);
364 :
365 : /**
366 : * @brief Asynchronous callback to get a resource buffer and length.
367 : *
368 : * Prior to accessing the data buffer of a resource, the engine can
369 : * use this callback to get the buffer pointer and length instead
370 : * of using the resource's data buffer.
371 : *
372 : * The client or LwM2M objects can register a function of this type via:
373 : * lwm2m_register_read_callback()
374 : * lwm2m_register_pre_write_callback()
375 : *
376 : * @param[in] obj_inst_id Object instance ID generating the callback.
377 : * @param[in] res_id Resource ID generating the callback.
378 : * @param[in] res_inst_id Resource instance ID generating the callback
379 : * (typically 0 for non-multi instance resources).
380 : * @param[out] data_len Length of the data buffer.
381 : *
382 : * @return Callback returns a pointer to the data buffer or NULL for failure.
383 : */
384 1 : typedef void *(*lwm2m_engine_get_data_cb_t)(uint16_t obj_inst_id,
385 : uint16_t res_id,
386 : uint16_t res_inst_id,
387 : size_t *data_len);
388 :
389 : /**
390 : * @brief Asynchronous callback when data has been set to a resource buffer.
391 : *
392 : * After changing the data of a resource buffer, the LwM2M engine can
393 : * make use of this callback to pass the data back to the client or LwM2M
394 : * objects.
395 : *
396 : * On a block-wise transfers the handler is called multiple times with the data blocks
397 : * and increasing offset. The last block has the last_block flag set to true.
398 : * Beginning of the block transfer has the offset set to 0.
399 : *
400 : * A function of this type can be registered via:
401 : * lwm2m_register_validate_callback()
402 : * lwm2m_register_post_write_callback()
403 : *
404 : * @param[in] obj_inst_id Object instance ID generating the callback.
405 : * @param[in] res_id Resource ID generating the callback.
406 : * @param[in] res_inst_id Resource instance ID generating the callback
407 : * (typically 0 for non-multi instance resources).
408 : * @param[in] data Pointer to data.
409 : * @param[in] data_len Length of the data.
410 : * @param[in] last_block Flag used during block transfer to indicate the last
411 : * block of data. For non-block transfers this is always
412 : * false.
413 : * @param[in] total_size Expected total size of data for a block transfer.
414 : * For non-block transfers this is 0.
415 : * @param[in] offset Offset of the data block. For non-block transfers this is always 0.
416 : *
417 : * @return Callback returns a negative error code (errno.h) indicating
418 : * reason of failure or 0 for success.
419 : */
420 1 : typedef int (*lwm2m_engine_set_data_cb_t)(uint16_t obj_inst_id,
421 : uint16_t res_id, uint16_t res_inst_id,
422 : uint8_t *data, uint16_t data_len,
423 : bool last_block, size_t total_size, size_t offset);
424 :
425 : /**
426 : * @brief Asynchronous event notification callback.
427 : *
428 : * Various object instance and resource-based events in the LwM2M engine
429 : * can trigger a callback of this function type: object instance create,
430 : * and object instance delete.
431 : *
432 : * Register a function of this type via:
433 : * lwm2m_register_create_callback()
434 : * lwm2m_register_delete_callback()
435 : *
436 : * @param[in] obj_inst_id Object instance ID generating the callback.
437 : *
438 : * @return Callback returns a negative error code (errno.h) indicating
439 : * reason of failure or 0 for success.
440 : */
441 1 : typedef int (*lwm2m_engine_user_cb_t)(uint16_t obj_inst_id);
442 :
443 : /**
444 : * @brief Asynchronous execute notification callback.
445 : *
446 : * Resource executes trigger a callback of this type.
447 : *
448 : * Register a function of this type via:
449 : * lwm2m_register_exec_callback()
450 : *
451 : * @param[in] obj_inst_id Object instance ID generating the callback.
452 : * @param[in] args Pointer to execute arguments payload. (This can be
453 : * NULL if no arguments are provided)
454 : * @param[in] args_len Length of argument payload in bytes.
455 : *
456 : * @return Callback returns a negative error code (errno.h) indicating
457 : * reason of failure or 0 for success.
458 : */
459 1 : typedef int (*lwm2m_engine_execute_cb_t)(uint16_t obj_inst_id,
460 : uint8_t *args, uint16_t args_len);
461 :
462 : /**
463 : * @name Power source types used for the "Available Power Sources" resource of
464 : * the LwM2M Device object (3/0/6).
465 : * @{
466 : */
467 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_DC_POWER 0 /**< DC power */
468 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_BAT_INT 1 /**< Internal battery */
469 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_BAT_EXT 2 /**< External battery */
470 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_FUEL_CELL 3 /**< Fuel cell */
471 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_PWR_OVER_ETH 4 /**< Power over Ethernet */
472 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_USB 5 /**< USB */
473 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_AC_POWER 6 /**< AC (mains) power */
474 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_SOLAR 7 /**< Solar */
475 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_MAX 8 /**< Max value for Available Power Source type */
476 : /** @} */
477 :
478 : /**
479 : * @name Error codes used for the "Error Code" resource of the LwM2M Device
480 : * object.
481 : * An LwM2M client can register one of the following error codes via
482 : * the lwm2m_device_add_err() function.
483 : * @{
484 : */
485 1 : #define LWM2M_DEVICE_ERROR_NONE 0 /**< No error */
486 1 : #define LWM2M_DEVICE_ERROR_LOW_POWER 1 /**< Low battery power */
487 1 : #define LWM2M_DEVICE_ERROR_EXT_POWER_SUPPLY_OFF 2 /**< External power supply off */
488 1 : #define LWM2M_DEVICE_ERROR_GPS_FAILURE 3 /**< GPS module failure */
489 1 : #define LWM2M_DEVICE_ERROR_LOW_SIGNAL_STRENGTH 4 /**< Low received signal strength */
490 1 : #define LWM2M_DEVICE_ERROR_OUT_OF_MEMORY 5 /**< Out of memory */
491 1 : #define LWM2M_DEVICE_ERROR_SMS_FAILURE 6 /**< SMS failure */
492 1 : #define LWM2M_DEVICE_ERROR_NETWORK_FAILURE 7 /**< IP Connectivity failure */
493 1 : #define LWM2M_DEVICE_ERROR_PERIPHERAL_FAILURE 8 /**< Peripheral malfunction */
494 :
495 : /** @} */
496 :
497 : /**
498 : * @name Battery status codes used for the "Battery Status" resource (3/0/20)
499 : * of the LwM2M Device object. As the battery status changes, an LwM2M
500 : * client can set one of the following codes via:
501 : * lwm2m_set_u8("3/0/20", [battery status])
502 : * @{
503 : */
504 : #define LWM2M_DEVICE_BATTERY_STATUS_NORMAL 0 /**< The battery is operating normally and not on
505 : * power
506 1 : */
507 1 : #define LWM2M_DEVICE_BATTERY_STATUS_CHARGING 1 /**< The battery is currently charging */
508 : #define LWM2M_DEVICE_BATTERY_STATUS_CHARGE_COMP 2 /**< The battery is fully charged and the charger
509 : * is still connected
510 1 : */
511 1 : #define LWM2M_DEVICE_BATTERY_STATUS_DAMAGED 3 /**< The battery has some problem */
512 1 : #define LWM2M_DEVICE_BATTERY_STATUS_LOW 4 /**< The battery is low on charge */
513 1 : #define LWM2M_DEVICE_BATTERY_STATUS_NOT_INST 5 /**< The battery is not installed */
514 1 : #define LWM2M_DEVICE_BATTERY_STATUS_UNKNOWN 6 /**< The battery information is not available */
515 :
516 : /** @} */
517 :
518 : /**
519 : * @brief Register a new error code with LwM2M Device object.
520 : *
521 : * @param[in] error_code New error code.
522 : *
523 : * @return 0 for success or negative in case of error.
524 : */
525 1 : int lwm2m_device_add_err(uint8_t error_code);
526 :
527 :
528 : /**
529 : * @name LWM2M Firmware Update object states
530 : *
531 : * An LwM2M client or the LwM2M Firmware Update object use the following codes
532 : * to represent the LwM2M Firmware Update state (5/0/3).
533 : * @{
534 : */
535 :
536 : /**
537 : * Idle. Before downloading or after successful updating.
538 : */
539 1 : #define STATE_IDLE 0
540 : /**
541 : * Downloading. The data sequence is being downloaded.
542 : */
543 1 : #define STATE_DOWNLOADING 1
544 : /**
545 : * Downloaded. The whole data sequence has been downloaded.
546 : */
547 1 : #define STATE_DOWNLOADED 2
548 : /**
549 : * Updating. The device is being updated.
550 : */
551 1 : #define STATE_UPDATING 3
552 :
553 : /** @} */
554 :
555 : /**
556 : * @name LWM2M Firmware Update object result codes
557 : *
558 : * After processing a firmware update, the client sets the result via one of
559 : * the following codes via lwm2m_set_u8("5/0/5", [result code])
560 : * @{
561 : */
562 :
563 1 : #define RESULT_DEFAULT 0 /**< Initial value */
564 1 : #define RESULT_SUCCESS 1 /**< Firmware updated successfully */
565 1 : #define RESULT_NO_STORAGE 2 /**< Not enough flash memory for the new firmware package */
566 1 : #define RESULT_OUT_OF_MEM 3 /**< Out of RAM during downloading process */
567 1 : #define RESULT_CONNECTION_LOST 4 /**< Connection lost during downloading process */
568 1 : #define RESULT_INTEGRITY_FAILED 5 /**< Integrity check failure for new downloaded package */
569 1 : #define RESULT_UNSUP_FW 6 /**< Unsupported package type */
570 1 : #define RESULT_INVALID_URI 7 /**< Invalid URI */
571 1 : #define RESULT_UPDATE_FAILED 8 /**< Firmware update failed */
572 1 : #define RESULT_UNSUP_PROTO 9 /**< Unsupported protocol */
573 :
574 : /** @} */
575 :
576 : #if defined(CONFIG_LWM2M_FIRMWARE_UPDATE_OBJ_SUPPORT) || defined(__DOXYGEN__)
577 : /**
578 : * @brief Set data callback for firmware block transfer.
579 : *
580 : * LwM2M clients use this function to register a callback for receiving the
581 : * block transfer data when performing a firmware update.
582 : *
583 : * @param[in] cb A callback function to receive the block transfer data
584 : */
585 1 : void lwm2m_firmware_set_write_cb(lwm2m_engine_set_data_cb_t cb);
586 :
587 : /**
588 : * @brief Get the data callback for firmware block transfer writes.
589 : *
590 : * @return A registered callback function to receive the block transfer data
591 : */
592 1 : lwm2m_engine_set_data_cb_t lwm2m_firmware_get_write_cb(void);
593 :
594 : /**
595 : * @brief Set data callback for firmware block transfer.
596 : *
597 : * LwM2M clients use this function to register a callback for receiving the
598 : * block transfer data when performing a firmware update.
599 : *
600 : * @param[in] obj_inst_id Object instance ID
601 : * @param[in] cb A callback function to receive the block transfer data
602 : */
603 1 : void lwm2m_firmware_set_write_cb_inst(uint16_t obj_inst_id, lwm2m_engine_set_data_cb_t cb);
604 :
605 : /**
606 : * @brief Get the data callback for firmware block transfer writes.
607 : *
608 : * @param[in] obj_inst_id Object instance ID
609 : * @return A registered callback function to receive the block transfer data
610 : */
611 1 : lwm2m_engine_set_data_cb_t lwm2m_firmware_get_write_cb_inst(uint16_t obj_inst_id);
612 :
613 : /**
614 : * @brief Set callback for firmware update cancel.
615 : *
616 : * LwM2M clients use this function to register a callback to perform actions
617 : * on firmware update cancel.
618 : *
619 : * @param[in] cb A callback function perform actions on firmware update cancel.
620 : */
621 1 : void lwm2m_firmware_set_cancel_cb(lwm2m_engine_user_cb_t cb);
622 :
623 : /**
624 : * @brief Get a callback for firmware update cancel.
625 : *
626 : * @return A registered callback function perform actions on firmware update cancel.
627 : */
628 1 : lwm2m_engine_user_cb_t lwm2m_firmware_get_cancel_cb(void);
629 :
630 : /**
631 : * @brief Set data callback for firmware update cancel.
632 : *
633 : * LwM2M clients use this function to register a callback to perform actions
634 : * on firmware update cancel.
635 : *
636 : * @param[in] obj_inst_id Object instance ID
637 : * @param[in] cb A callback function perform actions on firmware update cancel.
638 : */
639 1 : void lwm2m_firmware_set_cancel_cb_inst(uint16_t obj_inst_id, lwm2m_engine_user_cb_t cb);
640 :
641 : /**
642 : * @brief Get the callback for firmware update cancel.
643 : *
644 : * @param[in] obj_inst_id Object instance ID
645 : * @return A registered callback function perform actions on firmware update cancel.
646 : */
647 1 : lwm2m_engine_user_cb_t lwm2m_firmware_get_cancel_cb_inst(uint16_t obj_inst_id);
648 :
649 : /**
650 : * @brief Set data callback to handle firmware update execute events.
651 : *
652 : * LwM2M clients use this function to register a callback for receiving the
653 : * update resource "execute" operation on the LwM2M Firmware Update object.
654 : *
655 : * @param[in] cb A callback function to receive the execute event.
656 : */
657 1 : void lwm2m_firmware_set_update_cb(lwm2m_engine_execute_cb_t cb);
658 :
659 : /**
660 : * @brief Get the event callback for firmware update execute events.
661 : *
662 : * @return A registered callback function to receive the execute event.
663 : */
664 1 : lwm2m_engine_execute_cb_t lwm2m_firmware_get_update_cb(void);
665 :
666 : /**
667 : * @brief Set data callback to handle firmware update execute events.
668 : *
669 : * LwM2M clients use this function to register a callback for receiving the
670 : * update resource "execute" operation on the LwM2M Firmware Update object.
671 : *
672 : * @param[in] obj_inst_id Object instance ID
673 : * @param[in] cb A callback function to receive the execute event.
674 : */
675 1 : void lwm2m_firmware_set_update_cb_inst(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb);
676 :
677 : /**
678 : * @brief Get the event callback for firmware update execute events.
679 : *
680 : * @param[in] obj_inst_id Object instance ID
681 : * @return A registered callback function to receive the execute event.
682 : */
683 1 : lwm2m_engine_execute_cb_t lwm2m_firmware_get_update_cb_inst(uint16_t obj_inst_id);
684 : #endif
685 :
686 : #if defined(CONFIG_LWM2M_SWMGMT_OBJ_SUPPORT) || defined(__DOXYGEN__)
687 :
688 : /**
689 : * @brief Set callback to handle software activation requests
690 : *
691 : * The callback will be executed when the LWM2M execute operation gets called
692 : * on the corresponding object's Activate resource instance.
693 : *
694 : * @param[in] obj_inst_id The instance number to set the callback for.
695 : * @param[in] cb A callback function to receive the execute event.
696 : *
697 : * @return 0 on success, otherwise a negative integer.
698 : */
699 1 : int lwm2m_swmgmt_set_activate_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb);
700 :
701 : /**
702 : * @brief Set callback to handle software deactivation requests
703 : *
704 : * The callback will be executed when the LWM2M execute operation gets called
705 : * on the corresponding object's Deactivate resource instance.
706 : *
707 : * @param[in] obj_inst_id The instance number to set the callback for.
708 : * @param[in] cb A callback function to receive the execute event.
709 : *
710 : * @return 0 on success, otherwise a negative integer.
711 : */
712 1 : int lwm2m_swmgmt_set_deactivate_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb);
713 :
714 : /**
715 : * @brief Set callback to handle software install requests
716 : *
717 : * The callback will be executed when the LWM2M execute operation gets called
718 : * on the corresponding object's Install resource instance.
719 : *
720 : * @param[in] obj_inst_id The instance number to set the callback for.
721 : * @param[in] cb A callback function to receive the execute event.
722 : *
723 : * @return 0 on success, otherwise a negative integer.
724 : */
725 1 : int lwm2m_swmgmt_set_install_package_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb);
726 :
727 : /**
728 : * @brief Set callback to handle software uninstall requests
729 : *
730 : * The callback will be executed when the LWM2M execute operation gets called
731 : * on the corresponding object's Uninstall resource instance.
732 : *
733 : * @param[in] obj_inst_id The instance number to set the callback for.
734 : * @param[in] cb A callback function for handling the execute event.
735 : *
736 : * @return 0 on success, otherwise a negative integer.
737 : */
738 1 : int lwm2m_swmgmt_set_delete_package_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb);
739 :
740 : /**
741 : * @brief Set callback to read software package
742 : *
743 : * The callback will be executed when the LWM2M read operation gets called
744 : * on the corresponding object.
745 : *
746 : * @param[in] obj_inst_id The instance number to set the callback for.
747 : * @param[in] cb A callback function for handling the read event.
748 : *
749 : * @return 0 on success, otherwise a negative integer.
750 : */
751 1 : int lwm2m_swmgmt_set_read_package_version_cb(uint16_t obj_inst_id, lwm2m_engine_get_data_cb_t cb);
752 :
753 : /**
754 : * @brief Set data callback for software management block transfer.
755 : *
756 : * The callback will be executed when the LWM2M block write operation gets called
757 : * on the corresponding object's resource instance.
758 : *
759 : * @param[in] obj_inst_id The instance number to set the callback for.
760 : * @param[in] cb A callback function for handling the block write event.
761 : *
762 : * @return 0 on success, otherwise a negative integer.
763 : */
764 1 : int lwm2m_swmgmt_set_write_package_cb(uint16_t obj_inst_id, lwm2m_engine_set_data_cb_t cb);
765 :
766 : /**
767 : * Function to be called when a Software Management object instance
768 : * completed the Install operation.
769 : *
770 : * @param[in] obj_inst_id The Software Management object instance
771 : * @param[in] error_code The result code of the operation. Zero on success
772 : * otherwise it should be a negative integer.
773 : *
774 : * return 0 on success, otherwise a negative integer.
775 : */
776 1 : int lwm2m_swmgmt_install_completed(uint16_t obj_inst_id, int error_code);
777 :
778 : #endif
779 :
780 : #if defined(CONFIG_LWM2M_EVENT_LOG_OBJ_SUPPORT) || defined(__DOXYGEN__)
781 :
782 : /**
783 : * @brief Set callback to read log data
784 : *
785 : * The callback will be executed when the LWM2M read operation gets called
786 : * on the corresponding object.
787 : *
788 : * @param[in] cb A callback function for handling the read event.
789 : */
790 1 : void lwm2m_event_log_set_read_log_data_cb(lwm2m_engine_get_data_cb_t cb);
791 :
792 : #endif
793 :
794 : /**
795 : * @brief Maximum value for Objlnk resource fields
796 : */
797 1 : #define LWM2M_OBJLNK_MAX_ID USHRT_MAX
798 :
799 : /**
800 : * @brief LWM2M Objlnk resource type structure
801 : */
802 1 : struct lwm2m_objlnk {
803 1 : uint16_t obj_id; /**< Object ID */
804 1 : uint16_t obj_inst; /**< Object instance ID */
805 : };
806 :
807 : /**
808 : * @brief Change an observer's pmin value.
809 : *
810 : * LwM2M clients use this function to modify the pmin attribute
811 : * for an observation being made.
812 : * Example to update the pmin of a temperature sensor value being observed:
813 : * lwm2m_update_observer_min_period(client_ctx, &LWM2M_OBJ(3303, 0, 5700), 5);
814 : *
815 : * @param[in] client_ctx LwM2M context
816 : * @param[in] path LwM2M path as a struct
817 : * @param[in] period_s Value of pmin to be given (in seconds).
818 : *
819 : * @return 0 for success or negative in case of error.
820 : */
821 1 : int lwm2m_update_observer_min_period(struct lwm2m_ctx *client_ctx,
822 : const struct lwm2m_obj_path *path, uint32_t period_s);
823 :
824 : /**
825 : * @brief Change an observer's pmax value.
826 : *
827 : * LwM2M clients use this function to modify the pmax attribute
828 : * for an observation being made.
829 : * Example to update the pmax of a temperature sensor value being observed:
830 : * lwm2m__update_observer_max_period(client_ctx, &LWM2M_OBJ(3303, 0, 5700), 5);
831 : *
832 : * @param[in] client_ctx LwM2M context
833 : * @param[in] path LwM2M path as a struct
834 : * @param[in] period_s Value of pmax to be given (in seconds).
835 : *
836 : * @return 0 for success or negative in case of error.
837 : */
838 1 : int lwm2m_update_observer_max_period(struct lwm2m_ctx *client_ctx,
839 : const struct lwm2m_obj_path *path, uint32_t period_s);
840 :
841 : /**
842 : * @brief Create an LwM2M object instance.
843 : *
844 : * LwM2M clients use this function to create non-default LwM2M objects:
845 : * Example to create first temperature sensor object:
846 : * lwm2m_create_obj_inst(&LWM2M_OBJ(3303, 0));
847 : *
848 : * @param[in] path LwM2M path as a struct
849 : *
850 : * @return 0 for success or negative in case of error.
851 : */
852 1 : int lwm2m_create_object_inst(const struct lwm2m_obj_path *path);
853 :
854 : /**
855 : * @brief Delete an LwM2M object instance.
856 : *
857 : * LwM2M clients use this function to delete LwM2M objects.
858 : *
859 : * @param[in] path LwM2M path as a struct
860 : *
861 : * @return 0 for success or negative in case of error.
862 : */
863 1 : int lwm2m_delete_object_inst(const struct lwm2m_obj_path *path);
864 :
865 : /**
866 : * @brief Locks the registry for this thread.
867 : *
868 : * Use this function before writing to multiple resources. This halts the
869 : * lwm2m main thread until all the write-operations are finished.
870 : *
871 : */
872 1 : void lwm2m_registry_lock(void);
873 :
874 : /**
875 : * @brief Unlocks the registry previously locked by lwm2m_registry_lock().
876 : *
877 : */
878 1 : void lwm2m_registry_unlock(void);
879 :
880 : /**
881 : * @brief Set resource (instance) value (opaque buffer)
882 : *
883 : * @param[in] path LwM2M path as a struct
884 : * @param[in] data_ptr Data buffer
885 : * @param[in] data_len Length of buffer
886 : *
887 : * @return 0 for success or negative in case of error.
888 : */
889 1 : int lwm2m_set_opaque(const struct lwm2m_obj_path *path, const char *data_ptr, uint16_t data_len);
890 :
891 : /**
892 : * @brief Set resource (instance) value (string)
893 : *
894 : * @param[in] path LwM2M path as a struct
895 : * @param[in] data_ptr NULL terminated char buffer
896 : *
897 : * @return 0 for success or negative in case of error.
898 : */
899 1 : int lwm2m_set_string(const struct lwm2m_obj_path *path, const char *data_ptr);
900 :
901 : /**
902 : * @brief Set resource (instance) value (u8)
903 : *
904 : * @param[in] path LwM2M path as a struct
905 : * @param[in] value u8 value
906 : *
907 : * @return 0 for success or negative in case of error.
908 : */
909 1 : int lwm2m_set_u8(const struct lwm2m_obj_path *path, uint8_t value);
910 :
911 : /**
912 : * @brief Set resource (instance) value (u16)
913 : *
914 : * @param[in] path LwM2M path as a struct
915 : * @param[in] value u16 value
916 : *
917 : * @return 0 for success or negative in case of error.
918 : */
919 1 : int lwm2m_set_u16(const struct lwm2m_obj_path *path, uint16_t value);
920 :
921 : /**
922 : * @brief Set resource (instance) value (u32)
923 : *
924 : * @param[in] path LwM2M path as a struct
925 : * @param[in] value u32 value
926 : *
927 : * @return 0 for success or negative in case of error.
928 : */
929 1 : int lwm2m_set_u32(const struct lwm2m_obj_path *path, uint32_t value);
930 :
931 : /**
932 : * @brief Set resource (instance) value (s8)
933 : *
934 : * @param[in] path LwM2M path as a struct
935 : * @param[in] value s8 value
936 : *
937 : * @return 0 for success or negative in case of error.
938 : */
939 1 : int lwm2m_set_s8(const struct lwm2m_obj_path *path, int8_t value);
940 :
941 : /**
942 : * @brief Set resource (instance) value (s16)
943 : *
944 : * @param[in] path LwM2M path as a struct
945 : * @param[in] value s16 value
946 : *
947 : * @return 0 for success or negative in case of error.
948 : */
949 1 : int lwm2m_set_s16(const struct lwm2m_obj_path *path, int16_t value);
950 :
951 : /**
952 : * @brief Set resource (instance) value (s32)
953 : *
954 : * @param[in] path LwM2M path as a struct
955 : * @param[in] value s32 value
956 : *
957 : * @return 0 for success or negative in case of error.
958 : */
959 1 : int lwm2m_set_s32(const struct lwm2m_obj_path *path, int32_t value);
960 :
961 : /**
962 : * @brief Set resource (instance) value (s64)
963 : *
964 : * @param[in] path LwM2M path as a struct
965 : * @param[in] value s64 value
966 : *
967 : * @return 0 for success or negative in case of error.
968 : */
969 1 : int lwm2m_set_s64(const struct lwm2m_obj_path *path, int64_t value);
970 :
971 : /**
972 : * @brief Set resource (instance) value (bool)
973 : *
974 : * @param[in] path LwM2M path as a struct
975 : * @param[in] value bool value
976 : *
977 : * @return 0 for success or negative in case of error.
978 : */
979 1 : int lwm2m_set_bool(const struct lwm2m_obj_path *path, bool value);
980 :
981 : /**
982 : * @brief Set resource (instance) value (double)
983 : *
984 : * @param[in] path LwM2M path as a struct
985 : * @param[in] value double value
986 : *
987 : * @return 0 for success or negative in case of error.
988 : */
989 1 : int lwm2m_set_f64(const struct lwm2m_obj_path *path, const double value);
990 :
991 : /**
992 : * @brief Set resource (instance) value (Objlnk)
993 : *
994 : * @param[in] path LwM2M path as a struct
995 : * @param[in] value pointer to the lwm2m_objlnk structure
996 : *
997 : * @return 0 for success or negative in case of error.
998 : */
999 1 : int lwm2m_set_objlnk(const struct lwm2m_obj_path *path, const struct lwm2m_objlnk *value);
1000 :
1001 : /**
1002 : * @brief Set resource (instance) value (Time)
1003 : *
1004 : * @param[in] path LwM2M path as a struct
1005 : * @param[in] value Epoch timestamp
1006 : *
1007 : * @return 0 for success or negative in case of error.
1008 : */
1009 1 : int lwm2m_set_time(const struct lwm2m_obj_path *path, time_t value);
1010 :
1011 : /**
1012 : * @brief LwM2M resource item structure
1013 : *
1014 : * Value type must match the target resource as no type conversion are
1015 : * done and the value is just memcopied.
1016 : *
1017 : * Following C types are used for resource types:
1018 : * * BOOL is uint8_t
1019 : * * U8 is uint8_t
1020 : * * S8 is int8_t
1021 : * * U16 is uint16_t
1022 : * * S16 is int16_t
1023 : * * U32 is uint32_t
1024 : * * S32 is int32_t
1025 : * * S64 is int64_t
1026 : * * TIME is time_t
1027 : * * FLOAT is double
1028 : * * OBJLNK is struct lwm2m_objlnk
1029 : * * STRING is char * and the null-terminator should be included in the size.
1030 : * * OPAQUE is any binary data. When null-terminated string is written in OPAQUE
1031 : * resource, the terminator should not be included in size.
1032 : *
1033 : */
1034 1 : struct lwm2m_res_item {
1035 : /** Pointer to LwM2M path as a struct */
1036 1 : struct lwm2m_obj_path *path;
1037 : /** Pointer to resource value */
1038 1 : void *value;
1039 : /** Size of the value. For string resources, it should contain the null-terminator. */
1040 1 : uint16_t size;
1041 : };
1042 :
1043 : /**
1044 : * @brief Set multiple resource (instance) values
1045 : *
1046 : * NOTE: Value type must match the target resource as this function
1047 : * does not do any type conversion.
1048 : * See struct @ref lwm2m_res_item for list of resource types.
1049 : *
1050 : * @param[in] res_list LwM2M resource item list
1051 : * @param[in] res_list_size Length of resource list
1052 : *
1053 : * @return 0 for success or negative in case of error.
1054 : */
1055 1 : int lwm2m_set_bulk(const struct lwm2m_res_item res_list[], size_t res_list_size);
1056 :
1057 : /**
1058 : * @brief Get resource (instance) value (opaque buffer)
1059 : *
1060 : * @param[in] path LwM2M path as a struct
1061 : * @param[out] buf Data buffer to copy data into
1062 : * @param[in] buflen Length of buffer
1063 : *
1064 : * @return 0 for success or negative in case of error.
1065 : */
1066 1 : int lwm2m_get_opaque(const struct lwm2m_obj_path *path, void *buf, uint16_t buflen);
1067 :
1068 : /**
1069 : * @brief Get resource (instance) value (string)
1070 : *
1071 : * @param[in] path LwM2M path as a struct
1072 : * @param[out] str String buffer to copy data into
1073 : * @param[in] buflen Length of buffer
1074 : *
1075 : * @return 0 for success or negative in case of error.
1076 : */
1077 1 : int lwm2m_get_string(const struct lwm2m_obj_path *path, void *str, uint16_t buflen);
1078 :
1079 : /**
1080 : * @brief Get resource (instance) value (u8)
1081 : *
1082 : * @param[in] path LwM2M path as a struct
1083 : * @param[out] value u8 buffer to copy data into
1084 : *
1085 : * @return 0 for success or negative in case of error.
1086 : */
1087 1 : int lwm2m_get_u8(const struct lwm2m_obj_path *path, uint8_t *value);
1088 :
1089 : /**
1090 : * @brief Get resource (instance) value (u16)
1091 : *
1092 : * @param[in] path LwM2M path as a struct
1093 : * @param[out] value u16 buffer to copy data into
1094 : *
1095 : * @return 0 for success or negative in case of error.
1096 : */
1097 1 : int lwm2m_get_u16(const struct lwm2m_obj_path *path, uint16_t *value);
1098 :
1099 : /**
1100 : * @brief Get resource (instance) value (u32)
1101 : *
1102 : * @param[in] path LwM2M path as a struct
1103 : * @param[out] value u32 buffer to copy data into
1104 : *
1105 : * @return 0 for success or negative in case of error.
1106 : */
1107 1 : int lwm2m_get_u32(const struct lwm2m_obj_path *path, uint32_t *value);
1108 :
1109 : /**
1110 : * @brief Get resource (instance) value (s8)
1111 : *
1112 : * @param[in] path LwM2M path as a struct
1113 : * @param[out] value s8 buffer to copy data into
1114 : *
1115 : * @return 0 for success or negative in case of error.
1116 : */
1117 1 : int lwm2m_get_s8(const struct lwm2m_obj_path *path, int8_t *value);
1118 :
1119 : /**
1120 : * @brief Get resource (instance) value (s16)
1121 : *
1122 : * @param[in] path LwM2M path as a struct
1123 : * @param[out] value s16 buffer to copy data into
1124 : *
1125 : * @return 0 for success or negative in case of error.
1126 : */
1127 1 : int lwm2m_get_s16(const struct lwm2m_obj_path *path, int16_t *value);
1128 :
1129 : /**
1130 : * @brief Get resource (instance) value (s32)
1131 : *
1132 : * @param[in] path LwM2M path as a struct
1133 : * @param[out] value s32 buffer to copy data into
1134 : *
1135 : * @return 0 for success or negative in case of error.
1136 : */
1137 1 : int lwm2m_get_s32(const struct lwm2m_obj_path *path, int32_t *value);
1138 :
1139 : /**
1140 : * @brief Get resource (instance) value (s64)
1141 : *
1142 : * @param[in] path LwM2M path as a struct
1143 : * @param[out] value s64 buffer to copy data into
1144 : *
1145 : * @return 0 for success or negative in case of error.
1146 : */
1147 1 : int lwm2m_get_s64(const struct lwm2m_obj_path *path, int64_t *value);
1148 :
1149 : /**
1150 : * @brief Get resource (instance) value (bool)
1151 : *
1152 : * @param[in] path LwM2M path as a struct
1153 : * @param[out] value bool buffer to copy data into
1154 : *
1155 : * @return 0 for success or negative in case of error.
1156 : */
1157 1 : int lwm2m_get_bool(const struct lwm2m_obj_path *path, bool *value);
1158 :
1159 : /**
1160 : * @brief Get resource (instance) value (double)
1161 : *
1162 : * @param[in] path LwM2M path as a struct
1163 : * @param[out] value double buffer to copy data into
1164 : *
1165 : * @return 0 for success or negative in case of error.
1166 : */
1167 1 : int lwm2m_get_f64(const struct lwm2m_obj_path *path, double *value);
1168 :
1169 : /**
1170 : * @brief Get resource (instance) value (Objlnk)
1171 : *
1172 : * @param[in] path LwM2M path as a struct
1173 : * @param[out] buf lwm2m_objlnk buffer to copy data into
1174 : *
1175 : * @return 0 for success or negative in case of error.
1176 : */
1177 1 : int lwm2m_get_objlnk(const struct lwm2m_obj_path *path, struct lwm2m_objlnk *buf);
1178 :
1179 : /**
1180 : * @brief Get resource (instance) value (Time)
1181 : *
1182 : * @param[in] path LwM2M path as a struct
1183 : * @param[out] buf time_t pointer to copy data
1184 : *
1185 : * @return 0 for success or negative in case of error.
1186 : */
1187 1 : int lwm2m_get_time(const struct lwm2m_obj_path *path, time_t *buf);
1188 :
1189 : /**
1190 : * @brief Set resource (instance) read callback
1191 : *
1192 : * LwM2M clients can use this to set the callback function for resource reads when data
1193 : * handling in the LwM2M engine needs to be bypassed.
1194 : * For example reading back opaque binary data from external storage.
1195 : *
1196 : * This callback should not generally be used for any data that might be observed as
1197 : * engine does not have any knowledge of data changes.
1198 : *
1199 : * When separate buffer for data should be used, use lwm2m_set_res_buf() instead
1200 : * to set the storage.
1201 : *
1202 : * @param[in] path LwM2M path as a struct
1203 : * @param[in] cb Read resource callback
1204 : *
1205 : * @return 0 for success or negative in case of error.
1206 : */
1207 1 : int lwm2m_register_read_callback(const struct lwm2m_obj_path *path, lwm2m_engine_get_data_cb_t cb);
1208 :
1209 : /**
1210 : * @brief Set resource (instance) pre-write callback
1211 : *
1212 : * This callback is triggered before setting the value of a resource. It
1213 : * can pass a special data buffer to the engine so that the actual resource
1214 : * value can be calculated later, etc.
1215 : *
1216 : * @param[in] path LwM2M path as a struct
1217 : * @param[in] cb Pre-write resource callback
1218 : *
1219 : * @return 0 for success or negative in case of error.
1220 : */
1221 1 : int lwm2m_register_pre_write_callback(const struct lwm2m_obj_path *path,
1222 : lwm2m_engine_get_data_cb_t cb);
1223 :
1224 : /**
1225 : * @brief Set resource (instance) validation callback
1226 : *
1227 : * This callback is triggered before setting the value of a resource to the
1228 : * resource data buffer.
1229 : *
1230 : * The callback allows an LwM2M client or object to validate the data before
1231 : * writing and notify an error if the data should be discarded for any reason
1232 : * (by returning a negative error code).
1233 : *
1234 : * @note All resources that have a validation callback registered are initially
1235 : * decoded into a temporary validation buffer. Make sure that
1236 : * ``CONFIG_LWM2M_ENGINE_VALIDATION_BUFFER_SIZE`` is large enough to
1237 : * store each of the validated resources (individually).
1238 : *
1239 : * @param[in] path LwM2M path as a struct
1240 : * @param[in] cb Validate resource data callback
1241 : *
1242 : * @return 0 for success or negative in case of error.
1243 : */
1244 1 : int lwm2m_register_validate_callback(const struct lwm2m_obj_path *path,
1245 : lwm2m_engine_set_data_cb_t cb);
1246 :
1247 : /**
1248 : * @brief Set resource (instance) post-write callback
1249 : *
1250 : * This callback is triggered after setting the value of a resource to the
1251 : * resource data buffer.
1252 : *
1253 : * It allows an LwM2M client or object to post-process the value of a resource
1254 : * or trigger other related resource calculations.
1255 : *
1256 : * @param[in] path LwM2M path as a struct
1257 : * @param[in] cb Post-write resource callback
1258 : *
1259 : * @return 0 for success or negative in case of error.
1260 : */
1261 1 : int lwm2m_register_post_write_callback(const struct lwm2m_obj_path *path,
1262 : lwm2m_engine_set_data_cb_t cb);
1263 :
1264 : /**
1265 : * @brief Set resource execute event callback
1266 : *
1267 : * This event is triggered when the execute method of a resource is enabled.
1268 : *
1269 : * @param[in] path LwM2M path as a struct
1270 : * @param[in] cb Execute resource callback
1271 : *
1272 : * @return 0 for success or negative in case of error.
1273 : */
1274 1 : int lwm2m_register_exec_callback(const struct lwm2m_obj_path *path, lwm2m_engine_execute_cb_t cb);
1275 :
1276 : /**
1277 : * @brief Set object instance create event callback
1278 : *
1279 : * This event is triggered when an object instance is created.
1280 : *
1281 : * @param[in] obj_id LwM2M object id
1282 : * @param[in] cb Create object instance callback
1283 : *
1284 : * @return 0 for success or negative in case of error.
1285 : */
1286 1 : int lwm2m_register_create_callback(uint16_t obj_id,
1287 : lwm2m_engine_user_cb_t cb);
1288 :
1289 : /**
1290 : * @brief Set object instance delete event callback
1291 : *
1292 : * This event is triggered when an object instance is deleted.
1293 : *
1294 : * @param[in] obj_id LwM2M object id
1295 : * @param[in] cb Delete object instance callback
1296 : *
1297 : * @return 0 for success or negative in case of error.
1298 : */
1299 1 : int lwm2m_register_delete_callback(uint16_t obj_id,
1300 : lwm2m_engine_user_cb_t cb);
1301 :
1302 : /**
1303 : * @brief Resource read-only value bit
1304 : */
1305 1 : #define LWM2M_RES_DATA_READ_ONLY 0
1306 :
1307 : /**
1308 : * @brief Resource read-only flag
1309 : */
1310 1 : #define LWM2M_RES_DATA_FLAG_RO BIT(LWM2M_RES_DATA_READ_ONLY)
1311 :
1312 : /**
1313 : * @brief Read resource flags helper macro
1314 : */
1315 1 : #define LWM2M_HAS_RES_FLAG(res, f) ((res->data_flags & f) == f)
1316 :
1317 : /**
1318 : * @brief Set data buffer for a resource
1319 : *
1320 : * Use this function to set the data buffer and flags for the specified LwM2M
1321 : * resource.
1322 : *
1323 : * @param[in] path LwM2M path as a struct
1324 : * @param[in] buffer_ptr Data buffer pointer
1325 : * @param[in] buffer_len Length of buffer
1326 : * @param[in] data_len Length of existing data in the buffer
1327 : * @param[in] data_flags Data buffer flags (such as read-only, etc)
1328 : *
1329 : * @return 0 for success or negative in case of error.
1330 : */
1331 1 : int lwm2m_set_res_buf(const struct lwm2m_obj_path *path, void *buffer_ptr, uint16_t buffer_len,
1332 : uint16_t data_len, uint8_t data_flags);
1333 :
1334 : /**
1335 : * @brief Update data size for a resource
1336 : *
1337 : * Use this function to set the new size of data in the buffer if you write
1338 : * to a buffer received by lwm2m_get_res_buf().
1339 : *
1340 : * @param[in] path LwM2M path as a struct
1341 : * @param[in] data_len Length of data
1342 : * @return 0 for success or negative in case of error.
1343 : */
1344 1 : int lwm2m_set_res_data_len(const struct lwm2m_obj_path *path, uint16_t data_len);
1345 :
1346 : /**
1347 : * @brief Get data buffer for a resource
1348 : *
1349 : * Use this function to get the data buffer information for the specified LwM2M
1350 : * resource.
1351 : *
1352 : * If you directly write into the buffer, you must use lwm2m_set_res_data_len()
1353 : * function to update the new size of the written data.
1354 : *
1355 : * All parameters, except for the pathstr, can be NULL if you don't want to read those values.
1356 : *
1357 : * @param[in] path LwM2M path as a struct
1358 : * @param[out] buffer_ptr Data buffer pointer
1359 : * @param[out] buffer_len Length of buffer
1360 : * @param[out] data_len Length of existing data in the buffer
1361 : * @param[out] data_flags Data buffer flags (such as read-only, etc)
1362 : *
1363 : * @return 0 for success or negative in case of error.
1364 : */
1365 1 : int lwm2m_get_res_buf(const struct lwm2m_obj_path *path, void **buffer_ptr, uint16_t *buffer_len,
1366 : uint16_t *data_len, uint8_t *data_flags);
1367 :
1368 : /**
1369 : * @brief Create a resource instance
1370 : *
1371 : * LwM2M clients use this function to create multi-resource instances:
1372 : * Example to create 0 instance of device available power sources:
1373 : * lwm2m_create_res_inst(&LWM2M_OBJ(3, 0, 6, 0));
1374 : *
1375 : * @param[in] path LwM2M path as a struct
1376 : *
1377 : * @return 0 for success or negative in case of error.
1378 : */
1379 1 : int lwm2m_create_res_inst(const struct lwm2m_obj_path *path);
1380 :
1381 : /**
1382 : * @brief Delete a resource instance
1383 : *
1384 : * Use this function to remove an existing resource instance
1385 : *
1386 : * @param[in] path LwM2M path as a struct
1387 : *
1388 : * @return 0 for success or negative in case of error.
1389 : */
1390 1 : int lwm2m_delete_res_inst(const struct lwm2m_obj_path *path);
1391 :
1392 : /**
1393 : * @brief Update the period of the device service.
1394 : *
1395 : * Change the duration of the periodic device service that notifies the
1396 : * current time.
1397 : *
1398 : * @param[in] period_ms New period for the device service (in milliseconds)
1399 : *
1400 : * @return 0 for success or negative in case of error.
1401 : */
1402 1 : int lwm2m_update_device_service_period(uint32_t period_ms);
1403 :
1404 : /**
1405 : * @brief Check whether a path is observed
1406 : *
1407 : * @param[in] path LwM2M path as a struct to check
1408 : *
1409 : * @return true when there exists an observation of the same level
1410 : * or lower as the given path, false if it doesn't or path is not a
1411 : * valid LwM2M-path.
1412 : * E.g. true if path refers to a resource and the parent object has an
1413 : * observation, false for the inverse.
1414 : */
1415 1 : bool lwm2m_path_is_observed(const struct lwm2m_obj_path *path);
1416 :
1417 : /**
1418 : * @brief Stop the LwM2M engine
1419 : *
1420 : * LwM2M clients normally do not need to call this function as it is called
1421 : * within lwm2m_rd_client. However, if the client does not use the RD
1422 : * client implementation, it will need to be called manually.
1423 : *
1424 : * @param[in] client_ctx LwM2M context
1425 : *
1426 : * @return 0 for success or negative in case of error.
1427 : */
1428 1 : int lwm2m_engine_stop(struct lwm2m_ctx *client_ctx);
1429 :
1430 : /**
1431 : * @brief Start the LwM2M engine
1432 : *
1433 : * LwM2M clients normally do not need to call this function as it is called
1434 : * by lwm2m_rd_client_start(). However, if the client does not use the RD
1435 : * client implementation, it will need to be called manually.
1436 : *
1437 : * @param[in] client_ctx LwM2M context
1438 : *
1439 : * @return 0 for success or negative in case of error.
1440 : */
1441 1 : int lwm2m_engine_start(struct lwm2m_ctx *client_ctx);
1442 :
1443 : /**
1444 : * @brief Acknowledge the currently processed request with an empty ACK.
1445 : *
1446 : * LwM2M engine by default sends piggybacked responses for requests.
1447 : * This function allows to send an empty ACK for a request earlier (from the
1448 : * application callback). The LwM2M engine will then send the actual response
1449 : * as a separate CON message after all callbacks are executed.
1450 : *
1451 : * @param[in] client_ctx LwM2M context
1452 : *
1453 : */
1454 1 : void lwm2m_acknowledge(struct lwm2m_ctx *client_ctx);
1455 :
1456 : /*
1457 : * LwM2M RD client flags, used to configure LwM2M session.
1458 : */
1459 :
1460 : /**
1461 : * @brief Run bootstrap procedure in current session.
1462 : */
1463 1 : #define LWM2M_RD_CLIENT_FLAG_BOOTSTRAP BIT(0)
1464 :
1465 : /**
1466 : * @brief Start the LwM2M RD (Registration / Discovery) Client
1467 : *
1468 : * The RD client sits just above the LwM2M engine and performs the necessary
1469 : * actions to implement the "Registration interface".
1470 : * For more information see Section "Client Registration Interface" of
1471 : * LwM2M Technical Specification.
1472 : *
1473 : * NOTE: lwm2m_engine_start() is called automatically by this function.
1474 : *
1475 : * @param[in] client_ctx LwM2M context
1476 : * @param[in] ep_name Registered endpoint name
1477 : * @param[in] flags Flags used to configure current LwM2M session.
1478 : * @param[in] event_cb Client event callback function
1479 : * @param[in] observe_cb Observe callback function called when an observer was
1480 : * added or deleted, and when a notification was acked or
1481 : * has timed out
1482 : *
1483 : * @return 0 for success, -EINPROGRESS when client is already running
1484 : * or negative error codes in case of failure.
1485 : */
1486 1 : int lwm2m_rd_client_start(struct lwm2m_ctx *client_ctx, const char *ep_name,
1487 : uint32_t flags, lwm2m_ctx_event_cb_t event_cb,
1488 : lwm2m_observe_cb_t observe_cb);
1489 :
1490 : /**
1491 : * @brief Stop the LwM2M RD (De-register) Client
1492 : *
1493 : * The RD client sits just above the LwM2M engine and performs the necessary
1494 : * actions to implement the "Registration interface".
1495 : * For more information see Section "Client Registration Interface" of the
1496 : * LwM2M Technical Specification.
1497 : *
1498 : * @param[in] client_ctx LwM2M context
1499 : * @param[in] event_cb Client event callback function
1500 : * @param[in] deregister True to deregister the client if registered.
1501 : * False to force close the connection.
1502 : *
1503 : * @return 0 for success or negative in case of error.
1504 : */
1505 1 : int lwm2m_rd_client_stop(struct lwm2m_ctx *client_ctx,
1506 : lwm2m_ctx_event_cb_t event_cb, bool deregister);
1507 :
1508 : /**
1509 : * @brief Suspend the LwM2M engine Thread
1510 : *
1511 : * Suspend LwM2M engine. Use case could be when network connection is down.
1512 : * LwM2M Engine indicate before it suspend by
1513 : * LWM2M_RD_CLIENT_EVENT_ENGINE_SUSPENDED event.
1514 : *
1515 : * @return 0 for success or negative in case of error.
1516 : */
1517 1 : int lwm2m_engine_pause(void);
1518 :
1519 : /**
1520 : * @brief Resume the LwM2M engine thread
1521 : *
1522 : * Resume suspended LwM2M engine. After successful resume call engine will do
1523 : * full registration or registration update based on suspended time.
1524 : * Event's LWM2M_RD_CLIENT_EVENT_REGISTRATION_COMPLETE or LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE
1525 : * indicate that client is connected to server.
1526 : *
1527 : * @return 0 for success or negative in case of error.
1528 : */
1529 1 : int lwm2m_engine_resume(void);
1530 :
1531 : /**
1532 : * @brief Trigger a Registration Update of the LwM2M RD Client
1533 : */
1534 1 : void lwm2m_rd_client_update(void);
1535 :
1536 : /**
1537 : * @brief LwM2M path maximum length
1538 : */
1539 1 : #define LWM2M_MAX_PATH_STR_SIZE sizeof("/65535/65535/65535/65535")
1540 :
1541 : /**
1542 : * @brief Helper function to print path objects' contents to log
1543 : *
1544 : * @param[in] buf The buffer to use for formatting the string
1545 : * @param[in] path The path to stringify
1546 : *
1547 : * @return Resulting formatted path string
1548 : */
1549 1 : char *lwm2m_path_log_buf(char *buf, struct lwm2m_obj_path *path);
1550 :
1551 : /**
1552 : * @brief LwM2M send status
1553 : *
1554 : * LwM2M send status are generated back to the lwm2m_send_cb_t function in
1555 : * lwm2m_send_cb()
1556 : */
1557 1 : enum lwm2m_send_status {
1558 : LWM2M_SEND_STATUS_SUCCESS, /**< Succeed */
1559 : LWM2M_SEND_STATUS_FAILURE, /**< Failure */
1560 : LWM2M_SEND_STATUS_TIMEOUT, /**< Timeout */
1561 : };
1562 :
1563 : /**
1564 : * @typedef lwm2m_send_cb_t
1565 : * @brief Callback returning send status
1566 : */
1567 1 : typedef void (*lwm2m_send_cb_t)(enum lwm2m_send_status status);
1568 :
1569 : /**
1570 : * @brief LwM2M SEND operation to given path list asynchronously with confirmation callback
1571 : *
1572 : * @param ctx LwM2M context
1573 : * @param path_list LwM2M path struct list
1574 : * @param path_list_size Length of path list. Max size is CONFIG_LWM2M_COMPOSITE_PATH_LIST_SIZE
1575 : * @param reply_cb Callback triggered with confirmation state or NULL if not used
1576 : *
1577 : * @return 0 for success or negative in case of error.
1578 : *
1579 : */
1580 1 : int lwm2m_send_cb(struct lwm2m_ctx *ctx, const struct lwm2m_obj_path path_list[],
1581 : uint8_t path_list_size, lwm2m_send_cb_t reply_cb);
1582 :
1583 : /**
1584 : * @brief Returns LwM2M client context
1585 : *
1586 : * @return ctx LwM2M context
1587 : *
1588 : */
1589 1 : struct lwm2m_ctx *lwm2m_rd_client_ctx(void);
1590 :
1591 : /**
1592 : * @brief Enable data cache for a resource.
1593 : *
1594 : * Application may enable caching of resource data by allocating buffer for LwM2M engine to use.
1595 : * Buffer must be size of struct @ref lwm2m_time_series_elem times cache_len
1596 : *
1597 : * @param path LwM2M path to resource as a struct
1598 : * @param data_cache Pointer to Data cache array
1599 : * @param cache_len number of cached entries
1600 : *
1601 : * @return 0 for success or negative in case of error.
1602 : *
1603 : */
1604 1 : int lwm2m_enable_cache(const struct lwm2m_obj_path *path, struct lwm2m_time_series_elem *data_cache,
1605 : size_t cache_len);
1606 :
1607 : /**
1608 : * @brief Register a filtering callback for cached resource samples.
1609 : *
1610 : * The callback is invoked whenever the LwM2M engine attempts to append a new
1611 : * sample to the resource cache. Returning false prevents the sample from being
1612 : * stored. Passing a NULL callback removes any previously registered filter.
1613 : *
1614 : * @param path LwM2M path to the cached resource.
1615 : * @param filter_cb Callback used to decide whether samples should be cached.
1616 : *
1617 : * @return 0 for success or a negative errno code in case of error.
1618 : */
1619 1 : int lwm2m_set_cache_filter(const struct lwm2m_obj_path *path,
1620 : lwm2m_cache_filter_cb_t filter_cb);
1621 :
1622 : /**
1623 : * @brief Security modes as defined in LwM2M Security object.
1624 : */
1625 1 : enum lwm2m_security_mode_e {
1626 : LWM2M_SECURITY_PSK = 0, /**< Pre-Shared Key mode */
1627 : LWM2M_SECURITY_RAW_PK = 1, /**< Raw Public Key mode */
1628 : LWM2M_SECURITY_CERT = 2, /**< Certificate mode */
1629 : LWM2M_SECURITY_NOSEC = 3, /**< NoSec mode */
1630 : LWM2M_SECURITY_CERT_EST = 4, /**< Certificate mode with EST */
1631 : };
1632 :
1633 : /**
1634 : * @brief Read security mode from selected security object instance.
1635 : *
1636 : * This data is valid only if RD client is running.
1637 : *
1638 : * @param ctx Pointer to client context.
1639 : * @return int Positive values are @ref lwm2m_security_mode_e, negative error codes otherwise.
1640 : */
1641 1 : int lwm2m_security_mode(struct lwm2m_ctx *ctx);
1642 :
1643 : /**
1644 : * @brief Set default socket options for DTLS connections.
1645 : *
1646 : * The engine calls this when @ref lwm2m_ctx::set_socketoptions is not overwritten.
1647 : * You can call this from the overwritten callback to set extra options after or
1648 : * before defaults.
1649 : *
1650 : * @param ctx Client context
1651 : * @return 0 for success or negative in case of error.
1652 : */
1653 1 : int lwm2m_set_default_sockopt(struct lwm2m_ctx *ctx);
1654 :
1655 : /**
1656 : * @brief Set the @ref lwm2m_ctx::set_socketoptions callback for the pull context's client.
1657 : *
1658 : * This allows setting specific socket options on the socket that is used to pull
1659 : * firmware updates. The callback will be called after the pull context socket has been
1660 : * created and before it will connect.
1661 : *
1662 : * @param[in] set_sockopt_cb A callback function to set sockopts for the pull context client.
1663 : */
1664 1 : void lwm2m_pull_context_set_sockopt_callback(lwm2m_set_sockopt_cb_t set_sockopt_cb);
1665 :
1666 : #ifdef __cplusplus
1667 : }
1668 : #endif
1669 :
1670 : #endif /* ZEPHYR_INCLUDE_NET_LWM2M_H_ */
1671 : /**@} */
|
