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 : * @brief Asynchronous callback to get a resource buffer and length.
353 : *
354 : * Prior to accessing the data buffer of a resource, the engine can
355 : * use this callback to get the buffer pointer and length instead
356 : * of using the resource's data buffer.
357 : *
358 : * The client or LwM2M objects can register a function of this type via:
359 : * lwm2m_register_read_callback()
360 : * lwm2m_register_pre_write_callback()
361 : *
362 : * @param[in] obj_inst_id Object instance ID generating the callback.
363 : * @param[in] res_id Resource ID generating the callback.
364 : * @param[in] res_inst_id Resource instance ID generating the callback
365 : * (typically 0 for non-multi instance resources).
366 : * @param[out] data_len Length of the data buffer.
367 : *
368 : * @return Callback returns a pointer to the data buffer or NULL for failure.
369 : */
370 1 : typedef void *(*lwm2m_engine_get_data_cb_t)(uint16_t obj_inst_id,
371 : uint16_t res_id,
372 : uint16_t res_inst_id,
373 : size_t *data_len);
374 :
375 : /**
376 : * @brief Asynchronous callback when data has been set to a resource buffer.
377 : *
378 : * After changing the data of a resource buffer, the LwM2M engine can
379 : * make use of this callback to pass the data back to the client or LwM2M
380 : * objects.
381 : *
382 : * On a block-wise transfers the handler is called multiple times with the data blocks
383 : * and increasing offset. The last block has the last_block flag set to true.
384 : * Beginning of the block transfer has the offset set to 0.
385 : *
386 : * A function of this type can be registered via:
387 : * lwm2m_register_validate_callback()
388 : * lwm2m_register_post_write_callback()
389 : *
390 : * @param[in] obj_inst_id Object instance ID generating the callback.
391 : * @param[in] res_id Resource ID generating the callback.
392 : * @param[in] res_inst_id Resource instance ID generating the callback
393 : * (typically 0 for non-multi instance resources).
394 : * @param[in] data Pointer to data.
395 : * @param[in] data_len Length of the data.
396 : * @param[in] last_block Flag used during block transfer to indicate the last
397 : * block of data. For non-block transfers this is always
398 : * false.
399 : * @param[in] total_size Expected total size of data for a block transfer.
400 : * For non-block transfers this is 0.
401 : * @param[in] offset Offset of the data block. For non-block transfers this is always 0.
402 : *
403 : * @return Callback returns a negative error code (errno.h) indicating
404 : * reason of failure or 0 for success.
405 : */
406 1 : typedef int (*lwm2m_engine_set_data_cb_t)(uint16_t obj_inst_id,
407 : uint16_t res_id, uint16_t res_inst_id,
408 : uint8_t *data, uint16_t data_len,
409 : bool last_block, size_t total_size, size_t offset);
410 :
411 : /**
412 : * @brief Asynchronous event notification callback.
413 : *
414 : * Various object instance and resource-based events in the LwM2M engine
415 : * can trigger a callback of this function type: object instance create,
416 : * and object instance delete.
417 : *
418 : * Register a function of this type via:
419 : * lwm2m_register_create_callback()
420 : * lwm2m_register_delete_callback()
421 : *
422 : * @param[in] obj_inst_id Object instance ID generating the callback.
423 : *
424 : * @return Callback returns a negative error code (errno.h) indicating
425 : * reason of failure or 0 for success.
426 : */
427 1 : typedef int (*lwm2m_engine_user_cb_t)(uint16_t obj_inst_id);
428 :
429 : /**
430 : * @brief Asynchronous execute notification callback.
431 : *
432 : * Resource executes trigger a callback of this type.
433 : *
434 : * Register a function of this type via:
435 : * lwm2m_register_exec_callback()
436 : *
437 : * @param[in] obj_inst_id Object instance ID generating the callback.
438 : * @param[in] args Pointer to execute arguments payload. (This can be
439 : * NULL if no arguments are provided)
440 : * @param[in] args_len Length of argument payload in bytes.
441 : *
442 : * @return Callback returns a negative error code (errno.h) indicating
443 : * reason of failure or 0 for success.
444 : */
445 1 : typedef int (*lwm2m_engine_execute_cb_t)(uint16_t obj_inst_id,
446 : uint8_t *args, uint16_t args_len);
447 :
448 : /**
449 : * @name Power source types used for the "Available Power Sources" resource of
450 : * the LwM2M Device object (3/0/6).
451 : * @{
452 : */
453 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_DC_POWER 0 /**< DC power */
454 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_BAT_INT 1 /**< Internal battery */
455 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_BAT_EXT 2 /**< External battery */
456 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_FUEL_CELL 3 /**< Fuel cell */
457 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_PWR_OVER_ETH 4 /**< Power over Ethernet */
458 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_USB 5 /**< USB */
459 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_AC_POWER 6 /**< AC (mains) power */
460 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_SOLAR 7 /**< Solar */
461 1 : #define LWM2M_DEVICE_PWR_SRC_TYPE_MAX 8 /**< Max value for Available Power Source type */
462 : /** @} */
463 :
464 : /**
465 : * @name Error codes used for the "Error Code" resource of the LwM2M Device
466 : * object.
467 : * An LwM2M client can register one of the following error codes via
468 : * the lwm2m_device_add_err() function.
469 : * @{
470 : */
471 1 : #define LWM2M_DEVICE_ERROR_NONE 0 /**< No error */
472 1 : #define LWM2M_DEVICE_ERROR_LOW_POWER 1 /**< Low battery power */
473 1 : #define LWM2M_DEVICE_ERROR_EXT_POWER_SUPPLY_OFF 2 /**< External power supply off */
474 1 : #define LWM2M_DEVICE_ERROR_GPS_FAILURE 3 /**< GPS module failure */
475 1 : #define LWM2M_DEVICE_ERROR_LOW_SIGNAL_STRENGTH 4 /**< Low received signal strength */
476 1 : #define LWM2M_DEVICE_ERROR_OUT_OF_MEMORY 5 /**< Out of memory */
477 1 : #define LWM2M_DEVICE_ERROR_SMS_FAILURE 6 /**< SMS failure */
478 1 : #define LWM2M_DEVICE_ERROR_NETWORK_FAILURE 7 /**< IP Connectivity failure */
479 1 : #define LWM2M_DEVICE_ERROR_PERIPHERAL_FAILURE 8 /**< Peripheral malfunction */
480 :
481 : /** @} */
482 :
483 : /**
484 : * @name Battery status codes used for the "Battery Status" resource (3/0/20)
485 : * of the LwM2M Device object. As the battery status changes, an LwM2M
486 : * client can set one of the following codes via:
487 : * lwm2m_set_u8("3/0/20", [battery status])
488 : * @{
489 : */
490 : #define LWM2M_DEVICE_BATTERY_STATUS_NORMAL 0 /**< The battery is operating normally and not on
491 : * power
492 1 : */
493 1 : #define LWM2M_DEVICE_BATTERY_STATUS_CHARGING 1 /**< The battery is currently charging */
494 : #define LWM2M_DEVICE_BATTERY_STATUS_CHARGE_COMP 2 /**< The battery is fully charged and the charger
495 : * is still connected
496 1 : */
497 1 : #define LWM2M_DEVICE_BATTERY_STATUS_DAMAGED 3 /**< The battery has some problem */
498 1 : #define LWM2M_DEVICE_BATTERY_STATUS_LOW 4 /**< The battery is low on charge */
499 1 : #define LWM2M_DEVICE_BATTERY_STATUS_NOT_INST 5 /**< The battery is not installed */
500 1 : #define LWM2M_DEVICE_BATTERY_STATUS_UNKNOWN 6 /**< The battery information is not available */
501 :
502 : /** @} */
503 :
504 : /**
505 : * @brief Register a new error code with LwM2M Device object.
506 : *
507 : * @param[in] error_code New error code.
508 : *
509 : * @return 0 for success or negative in case of error.
510 : */
511 1 : int lwm2m_device_add_err(uint8_t error_code);
512 :
513 :
514 : /**
515 : * @name LWM2M Firmware Update object states
516 : *
517 : * An LwM2M client or the LwM2M Firmware Update object use the following codes
518 : * to represent the LwM2M Firmware Update state (5/0/3).
519 : * @{
520 : */
521 :
522 : /**
523 : * Idle. Before downloading or after successful updating.
524 : */
525 1 : #define STATE_IDLE 0
526 : /**
527 : * Downloading. The data sequence is being downloaded.
528 : */
529 1 : #define STATE_DOWNLOADING 1
530 : /**
531 : * Downloaded. The whole data sequence has been downloaded.
532 : */
533 1 : #define STATE_DOWNLOADED 2
534 : /**
535 : * Updating. The device is being updated.
536 : */
537 1 : #define STATE_UPDATING 3
538 :
539 : /** @} */
540 :
541 : /**
542 : * @name LWM2M Firmware Update object result codes
543 : *
544 : * After processing a firmware update, the client sets the result via one of
545 : * the following codes via lwm2m_set_u8("5/0/5", [result code])
546 : * @{
547 : */
548 :
549 1 : #define RESULT_DEFAULT 0 /**< Initial value */
550 1 : #define RESULT_SUCCESS 1 /**< Firmware updated successfully */
551 1 : #define RESULT_NO_STORAGE 2 /**< Not enough flash memory for the new firmware package */
552 1 : #define RESULT_OUT_OF_MEM 3 /**< Out of RAM during downloading process */
553 1 : #define RESULT_CONNECTION_LOST 4 /**< Connection lost during downloading process */
554 1 : #define RESULT_INTEGRITY_FAILED 5 /**< Integrity check failure for new downloaded package */
555 1 : #define RESULT_UNSUP_FW 6 /**< Unsupported package type */
556 1 : #define RESULT_INVALID_URI 7 /**< Invalid URI */
557 1 : #define RESULT_UPDATE_FAILED 8 /**< Firmware update failed */
558 1 : #define RESULT_UNSUP_PROTO 9 /**< Unsupported protocol */
559 :
560 : /** @} */
561 :
562 : #if defined(CONFIG_LWM2M_FIRMWARE_UPDATE_OBJ_SUPPORT) || defined(__DOXYGEN__)
563 : /**
564 : * @brief Set data callback for firmware block transfer.
565 : *
566 : * LwM2M clients use this function to register a callback for receiving the
567 : * block transfer data when performing a firmware update.
568 : *
569 : * @param[in] cb A callback function to receive the block transfer data
570 : */
571 1 : void lwm2m_firmware_set_write_cb(lwm2m_engine_set_data_cb_t cb);
572 :
573 : /**
574 : * @brief Get the data callback for firmware block transfer writes.
575 : *
576 : * @return A registered callback function to receive the block transfer data
577 : */
578 1 : lwm2m_engine_set_data_cb_t lwm2m_firmware_get_write_cb(void);
579 :
580 : /**
581 : * @brief Set data callback for firmware block transfer.
582 : *
583 : * LwM2M clients use this function to register a callback for receiving the
584 : * block transfer data when performing a firmware update.
585 : *
586 : * @param[in] obj_inst_id Object instance ID
587 : * @param[in] cb A callback function to receive the block transfer data
588 : */
589 1 : void lwm2m_firmware_set_write_cb_inst(uint16_t obj_inst_id, lwm2m_engine_set_data_cb_t cb);
590 :
591 : /**
592 : * @brief Get the data callback for firmware block transfer writes.
593 : *
594 : * @param[in] obj_inst_id Object instance ID
595 : * @return A registered callback function to receive the block transfer data
596 : */
597 1 : lwm2m_engine_set_data_cb_t lwm2m_firmware_get_write_cb_inst(uint16_t obj_inst_id);
598 :
599 : /**
600 : * @brief Set callback for firmware update cancel.
601 : *
602 : * LwM2M clients use this function to register a callback to perform actions
603 : * on firmware update cancel.
604 : *
605 : * @param[in] cb A callback function perform actions on firmware update cancel.
606 : */
607 1 : void lwm2m_firmware_set_cancel_cb(lwm2m_engine_user_cb_t cb);
608 :
609 : /**
610 : * @brief Get a callback for firmware update cancel.
611 : *
612 : * @return A registered callback function perform actions on firmware update cancel.
613 : */
614 1 : lwm2m_engine_user_cb_t lwm2m_firmware_get_cancel_cb(void);
615 :
616 : /**
617 : * @brief Set data callback for firmware update cancel.
618 : *
619 : * LwM2M clients use this function to register a callback to perform actions
620 : * on firmware update cancel.
621 : *
622 : * @param[in] obj_inst_id Object instance ID
623 : * @param[in] cb A callback function perform actions on firmware update cancel.
624 : */
625 1 : void lwm2m_firmware_set_cancel_cb_inst(uint16_t obj_inst_id, lwm2m_engine_user_cb_t cb);
626 :
627 : /**
628 : * @brief Get the callback for firmware update cancel.
629 : *
630 : * @param[in] obj_inst_id Object instance ID
631 : * @return A registered callback function perform actions on firmware update cancel.
632 : */
633 1 : lwm2m_engine_user_cb_t lwm2m_firmware_get_cancel_cb_inst(uint16_t obj_inst_id);
634 :
635 : /**
636 : * @brief Set data callback to handle firmware update execute events.
637 : *
638 : * LwM2M clients use this function to register a callback for receiving the
639 : * update resource "execute" operation on the LwM2M Firmware Update object.
640 : *
641 : * @param[in] cb A callback function to receive the execute event.
642 : */
643 1 : void lwm2m_firmware_set_update_cb(lwm2m_engine_execute_cb_t cb);
644 :
645 : /**
646 : * @brief Get the event callback for firmware update execute events.
647 : *
648 : * @return A registered callback function to receive the execute event.
649 : */
650 1 : lwm2m_engine_execute_cb_t lwm2m_firmware_get_update_cb(void);
651 :
652 : /**
653 : * @brief Set data callback to handle firmware update execute events.
654 : *
655 : * LwM2M clients use this function to register a callback for receiving the
656 : * update resource "execute" operation on the LwM2M Firmware Update object.
657 : *
658 : * @param[in] obj_inst_id Object instance ID
659 : * @param[in] cb A callback function to receive the execute event.
660 : */
661 1 : void lwm2m_firmware_set_update_cb_inst(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb);
662 :
663 : /**
664 : * @brief Get the event callback for firmware update execute events.
665 : *
666 : * @param[in] obj_inst_id Object instance ID
667 : * @return A registered callback function to receive the execute event.
668 : */
669 1 : lwm2m_engine_execute_cb_t lwm2m_firmware_get_update_cb_inst(uint16_t obj_inst_id);
670 : #endif
671 :
672 : #if defined(CONFIG_LWM2M_SWMGMT_OBJ_SUPPORT) || defined(__DOXYGEN__)
673 :
674 : /**
675 : * @brief Set callback to handle software activation requests
676 : *
677 : * The callback will be executed when the LWM2M execute operation gets called
678 : * on the corresponding object's Activate resource instance.
679 : *
680 : * @param[in] obj_inst_id The instance number to set the callback for.
681 : * @param[in] cb A callback function to receive the execute event.
682 : *
683 : * @return 0 on success, otherwise a negative integer.
684 : */
685 1 : int lwm2m_swmgmt_set_activate_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb);
686 :
687 : /**
688 : * @brief Set callback to handle software deactivation requests
689 : *
690 : * The callback will be executed when the LWM2M execute operation gets called
691 : * on the corresponding object's Deactivate resource instance.
692 : *
693 : * @param[in] obj_inst_id The instance number to set the callback for.
694 : * @param[in] cb A callback function to receive the execute event.
695 : *
696 : * @return 0 on success, otherwise a negative integer.
697 : */
698 1 : int lwm2m_swmgmt_set_deactivate_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb);
699 :
700 : /**
701 : * @brief Set callback to handle software install requests
702 : *
703 : * The callback will be executed when the LWM2M execute operation gets called
704 : * on the corresponding object's Install resource instance.
705 : *
706 : * @param[in] obj_inst_id The instance number to set the callback for.
707 : * @param[in] cb A callback function to receive the execute event.
708 : *
709 : * @return 0 on success, otherwise a negative integer.
710 : */
711 1 : int lwm2m_swmgmt_set_install_package_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb);
712 :
713 : /**
714 : * @brief Set callback to handle software uninstall requests
715 : *
716 : * The callback will be executed when the LWM2M execute operation gets called
717 : * on the corresponding object's Uninstall resource instance.
718 : *
719 : * @param[in] obj_inst_id The instance number to set the callback for.
720 : * @param[in] cb A callback function for handling the execute event.
721 : *
722 : * @return 0 on success, otherwise a negative integer.
723 : */
724 1 : int lwm2m_swmgmt_set_delete_package_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb);
725 :
726 : /**
727 : * @brief Set callback to read software package
728 : *
729 : * The callback will be executed when the LWM2M read operation gets called
730 : * on the corresponding object.
731 : *
732 : * @param[in] obj_inst_id The instance number to set the callback for.
733 : * @param[in] cb A callback function for handling the read event.
734 : *
735 : * @return 0 on success, otherwise a negative integer.
736 : */
737 1 : int lwm2m_swmgmt_set_read_package_version_cb(uint16_t obj_inst_id, lwm2m_engine_get_data_cb_t cb);
738 :
739 : /**
740 : * @brief Set data callback for software management block transfer.
741 : *
742 : * The callback will be executed when the LWM2M block write operation gets called
743 : * on the corresponding object's resource instance.
744 : *
745 : * @param[in] obj_inst_id The instance number to set the callback for.
746 : * @param[in] cb A callback function for handling the block write event.
747 : *
748 : * @return 0 on success, otherwise a negative integer.
749 : */
750 1 : int lwm2m_swmgmt_set_write_package_cb(uint16_t obj_inst_id, lwm2m_engine_set_data_cb_t cb);
751 :
752 : /**
753 : * Function to be called when a Software Management object instance
754 : * completed the Install operation.
755 : *
756 : * @param[in] obj_inst_id The Software Management object instance
757 : * @param[in] error_code The result code of the operation. Zero on success
758 : * otherwise it should be a negative integer.
759 : *
760 : * return 0 on success, otherwise a negative integer.
761 : */
762 1 : int lwm2m_swmgmt_install_completed(uint16_t obj_inst_id, int error_code);
763 :
764 : #endif
765 :
766 : #if defined(CONFIG_LWM2M_EVENT_LOG_OBJ_SUPPORT) || defined(__DOXYGEN__)
767 :
768 : /**
769 : * @brief Set callback to read log data
770 : *
771 : * The callback will be executed when the LWM2M read operation gets called
772 : * on the corresponding object.
773 : *
774 : * @param[in] cb A callback function for handling the read event.
775 : */
776 1 : void lwm2m_event_log_set_read_log_data_cb(lwm2m_engine_get_data_cb_t cb);
777 :
778 : #endif
779 :
780 : /**
781 : * @brief Maximum value for Objlnk resource fields
782 : */
783 1 : #define LWM2M_OBJLNK_MAX_ID USHRT_MAX
784 :
785 : /**
786 : * @brief LWM2M Objlnk resource type structure
787 : */
788 1 : struct lwm2m_objlnk {
789 1 : uint16_t obj_id; /**< Object ID */
790 1 : uint16_t obj_inst; /**< Object instance ID */
791 : };
792 :
793 : /**
794 : * @brief Change an observer's pmin value.
795 : *
796 : * LwM2M clients use this function to modify the pmin attribute
797 : * for an observation being made.
798 : * Example to update the pmin of a temperature sensor value being observed:
799 : * lwm2m_update_observer_min_period(client_ctx, &LWM2M_OBJ(3303, 0, 5700), 5);
800 : *
801 : * @param[in] client_ctx LwM2M context
802 : * @param[in] path LwM2M path as a struct
803 : * @param[in] period_s Value of pmin to be given (in seconds).
804 : *
805 : * @return 0 for success or negative in case of error.
806 : */
807 1 : int lwm2m_update_observer_min_period(struct lwm2m_ctx *client_ctx,
808 : const struct lwm2m_obj_path *path, uint32_t period_s);
809 :
810 : /**
811 : * @brief Change an observer's pmax value.
812 : *
813 : * LwM2M clients use this function to modify the pmax attribute
814 : * for an observation being made.
815 : * Example to update the pmax of a temperature sensor value being observed:
816 : * lwm2m__update_observer_max_period(client_ctx, &LWM2M_OBJ(3303, 0, 5700), 5);
817 : *
818 : * @param[in] client_ctx LwM2M context
819 : * @param[in] path LwM2M path as a struct
820 : * @param[in] period_s Value of pmax to be given (in seconds).
821 : *
822 : * @return 0 for success or negative in case of error.
823 : */
824 1 : int lwm2m_update_observer_max_period(struct lwm2m_ctx *client_ctx,
825 : const struct lwm2m_obj_path *path, uint32_t period_s);
826 :
827 : /**
828 : * @brief Create an LwM2M object instance.
829 : *
830 : * LwM2M clients use this function to create non-default LwM2M objects:
831 : * Example to create first temperature sensor object:
832 : * lwm2m_create_obj_inst(&LWM2M_OBJ(3303, 0));
833 : *
834 : * @param[in] path LwM2M path as a struct
835 : *
836 : * @return 0 for success or negative in case of error.
837 : */
838 1 : int lwm2m_create_object_inst(const struct lwm2m_obj_path *path);
839 :
840 : /**
841 : * @brief Delete an LwM2M object instance.
842 : *
843 : * LwM2M clients use this function to delete LwM2M objects.
844 : *
845 : * @param[in] path LwM2M path as a struct
846 : *
847 : * @return 0 for success or negative in case of error.
848 : */
849 1 : int lwm2m_delete_object_inst(const struct lwm2m_obj_path *path);
850 :
851 : /**
852 : * @brief Locks the registry for this thread.
853 : *
854 : * Use this function before writing to multiple resources. This halts the
855 : * lwm2m main thread until all the write-operations are finished.
856 : *
857 : */
858 1 : void lwm2m_registry_lock(void);
859 :
860 : /**
861 : * @brief Unlocks the registry previously locked by lwm2m_registry_lock().
862 : *
863 : */
864 1 : void lwm2m_registry_unlock(void);
865 :
866 : /**
867 : * @brief Set resource (instance) value (opaque buffer)
868 : *
869 : * @param[in] path LwM2M path as a struct
870 : * @param[in] data_ptr Data buffer
871 : * @param[in] data_len Length of buffer
872 : *
873 : * @return 0 for success or negative in case of error.
874 : */
875 1 : int lwm2m_set_opaque(const struct lwm2m_obj_path *path, const char *data_ptr, uint16_t data_len);
876 :
877 : /**
878 : * @brief Set resource (instance) value (string)
879 : *
880 : * @param[in] path LwM2M path as a struct
881 : * @param[in] data_ptr NULL terminated char buffer
882 : *
883 : * @return 0 for success or negative in case of error.
884 : */
885 1 : int lwm2m_set_string(const struct lwm2m_obj_path *path, const char *data_ptr);
886 :
887 : /**
888 : * @brief Set resource (instance) value (u8)
889 : *
890 : * @param[in] path LwM2M path as a struct
891 : * @param[in] value u8 value
892 : *
893 : * @return 0 for success or negative in case of error.
894 : */
895 1 : int lwm2m_set_u8(const struct lwm2m_obj_path *path, uint8_t value);
896 :
897 : /**
898 : * @brief Set resource (instance) value (u16)
899 : *
900 : * @param[in] path LwM2M path as a struct
901 : * @param[in] value u16 value
902 : *
903 : * @return 0 for success or negative in case of error.
904 : */
905 1 : int lwm2m_set_u16(const struct lwm2m_obj_path *path, uint16_t value);
906 :
907 : /**
908 : * @brief Set resource (instance) value (u32)
909 : *
910 : * @param[in] path LwM2M path as a struct
911 : * @param[in] value u32 value
912 : *
913 : * @return 0 for success or negative in case of error.
914 : */
915 1 : int lwm2m_set_u32(const struct lwm2m_obj_path *path, uint32_t value);
916 :
917 : /**
918 : * @brief Set resource (instance) value (s8)
919 : *
920 : * @param[in] path LwM2M path as a struct
921 : * @param[in] value s8 value
922 : *
923 : * @return 0 for success or negative in case of error.
924 : */
925 1 : int lwm2m_set_s8(const struct lwm2m_obj_path *path, int8_t value);
926 :
927 : /**
928 : * @brief Set resource (instance) value (s16)
929 : *
930 : * @param[in] path LwM2M path as a struct
931 : * @param[in] value s16 value
932 : *
933 : * @return 0 for success or negative in case of error.
934 : */
935 1 : int lwm2m_set_s16(const struct lwm2m_obj_path *path, int16_t value);
936 :
937 : /**
938 : * @brief Set resource (instance) value (s32)
939 : *
940 : * @param[in] path LwM2M path as a struct
941 : * @param[in] value s32 value
942 : *
943 : * @return 0 for success or negative in case of error.
944 : */
945 1 : int lwm2m_set_s32(const struct lwm2m_obj_path *path, int32_t value);
946 :
947 : /**
948 : * @brief Set resource (instance) value (s64)
949 : *
950 : * @param[in] path LwM2M path as a struct
951 : * @param[in] value s64 value
952 : *
953 : * @return 0 for success or negative in case of error.
954 : */
955 1 : int lwm2m_set_s64(const struct lwm2m_obj_path *path, int64_t value);
956 :
957 : /**
958 : * @brief Set resource (instance) value (bool)
959 : *
960 : * @param[in] path LwM2M path as a struct
961 : * @param[in] value bool value
962 : *
963 : * @return 0 for success or negative in case of error.
964 : */
965 1 : int lwm2m_set_bool(const struct lwm2m_obj_path *path, bool value);
966 :
967 : /**
968 : * @brief Set resource (instance) value (double)
969 : *
970 : * @param[in] path LwM2M path as a struct
971 : * @param[in] value double value
972 : *
973 : * @return 0 for success or negative in case of error.
974 : */
975 1 : int lwm2m_set_f64(const struct lwm2m_obj_path *path, const double value);
976 :
977 : /**
978 : * @brief Set resource (instance) value (Objlnk)
979 : *
980 : * @param[in] path LwM2M path as a struct
981 : * @param[in] value pointer to the lwm2m_objlnk structure
982 : *
983 : * @return 0 for success or negative in case of error.
984 : */
985 1 : int lwm2m_set_objlnk(const struct lwm2m_obj_path *path, const struct lwm2m_objlnk *value);
986 :
987 : /**
988 : * @brief Set resource (instance) value (Time)
989 : *
990 : * @param[in] path LwM2M path as a struct
991 : * @param[in] value Epoch timestamp
992 : *
993 : * @return 0 for success or negative in case of error.
994 : */
995 1 : int lwm2m_set_time(const struct lwm2m_obj_path *path, time_t value);
996 :
997 : /**
998 : * @brief LwM2M resource item structure
999 : *
1000 : * Value type must match the target resource as no type conversion are
1001 : * done and the value is just memcopied.
1002 : *
1003 : * Following C types are used for resource types:
1004 : * * BOOL is uint8_t
1005 : * * U8 is uint8_t
1006 : * * S8 is int8_t
1007 : * * U16 is uint16_t
1008 : * * S16 is int16_t
1009 : * * U32 is uint32_t
1010 : * * S32 is int32_t
1011 : * * S64 is int64_t
1012 : * * TIME is time_t
1013 : * * FLOAT is double
1014 : * * OBJLNK is struct lwm2m_objlnk
1015 : * * STRING is char * and the null-terminator should be included in the size.
1016 : * * OPAQUE is any binary data. When null-terminated string is written in OPAQUE
1017 : * resource, the terminator should not be included in size.
1018 : *
1019 : */
1020 1 : struct lwm2m_res_item {
1021 : /** Pointer to LwM2M path as a struct */
1022 1 : struct lwm2m_obj_path *path;
1023 : /** Pointer to resource value */
1024 1 : void *value;
1025 : /** Size of the value. For string resources, it should contain the null-terminator. */
1026 1 : uint16_t size;
1027 : };
1028 :
1029 : /**
1030 : * @brief Set multiple resource (instance) values
1031 : *
1032 : * NOTE: Value type must match the target resource as this function
1033 : * does not do any type conversion.
1034 : * See struct @ref lwm2m_res_item for list of resource types.
1035 : *
1036 : * @param[in] res_list LwM2M resource item list
1037 : * @param[in] res_list_size Length of resource list
1038 : *
1039 : * @return 0 for success or negative in case of error.
1040 : */
1041 1 : int lwm2m_set_bulk(const struct lwm2m_res_item res_list[], size_t res_list_size);
1042 :
1043 : /**
1044 : * @brief Get resource (instance) value (opaque buffer)
1045 : *
1046 : * @param[in] path LwM2M path as a struct
1047 : * @param[out] buf Data buffer to copy data into
1048 : * @param[in] buflen Length of buffer
1049 : *
1050 : * @return 0 for success or negative in case of error.
1051 : */
1052 1 : int lwm2m_get_opaque(const struct lwm2m_obj_path *path, void *buf, uint16_t buflen);
1053 :
1054 : /**
1055 : * @brief Get resource (instance) value (string)
1056 : *
1057 : * @param[in] path LwM2M path as a struct
1058 : * @param[out] str String buffer to copy data into
1059 : * @param[in] buflen Length of buffer
1060 : *
1061 : * @return 0 for success or negative in case of error.
1062 : */
1063 1 : int lwm2m_get_string(const struct lwm2m_obj_path *path, void *str, uint16_t buflen);
1064 :
1065 : /**
1066 : * @brief Get resource (instance) value (u8)
1067 : *
1068 : * @param[in] path LwM2M path as a struct
1069 : * @param[out] value u8 buffer to copy data into
1070 : *
1071 : * @return 0 for success or negative in case of error.
1072 : */
1073 1 : int lwm2m_get_u8(const struct lwm2m_obj_path *path, uint8_t *value);
1074 :
1075 : /**
1076 : * @brief Get resource (instance) value (u16)
1077 : *
1078 : * @param[in] path LwM2M path as a struct
1079 : * @param[out] value u16 buffer to copy data into
1080 : *
1081 : * @return 0 for success or negative in case of error.
1082 : */
1083 1 : int lwm2m_get_u16(const struct lwm2m_obj_path *path, uint16_t *value);
1084 :
1085 : /**
1086 : * @brief Get resource (instance) value (u32)
1087 : *
1088 : * @param[in] path LwM2M path as a struct
1089 : * @param[out] value u32 buffer to copy data into
1090 : *
1091 : * @return 0 for success or negative in case of error.
1092 : */
1093 1 : int lwm2m_get_u32(const struct lwm2m_obj_path *path, uint32_t *value);
1094 :
1095 : /**
1096 : * @brief Get resource (instance) value (s8)
1097 : *
1098 : * @param[in] path LwM2M path as a struct
1099 : * @param[out] value s8 buffer to copy data into
1100 : *
1101 : * @return 0 for success or negative in case of error.
1102 : */
1103 1 : int lwm2m_get_s8(const struct lwm2m_obj_path *path, int8_t *value);
1104 :
1105 : /**
1106 : * @brief Get resource (instance) value (s16)
1107 : *
1108 : * @param[in] path LwM2M path as a struct
1109 : * @param[out] value s16 buffer to copy data into
1110 : *
1111 : * @return 0 for success or negative in case of error.
1112 : */
1113 1 : int lwm2m_get_s16(const struct lwm2m_obj_path *path, int16_t *value);
1114 :
1115 : /**
1116 : * @brief Get resource (instance) value (s32)
1117 : *
1118 : * @param[in] path LwM2M path as a struct
1119 : * @param[out] value s32 buffer to copy data into
1120 : *
1121 : * @return 0 for success or negative in case of error.
1122 : */
1123 1 : int lwm2m_get_s32(const struct lwm2m_obj_path *path, int32_t *value);
1124 :
1125 : /**
1126 : * @brief Get resource (instance) value (s64)
1127 : *
1128 : * @param[in] path LwM2M path as a struct
1129 : * @param[out] value s64 buffer to copy data into
1130 : *
1131 : * @return 0 for success or negative in case of error.
1132 : */
1133 1 : int lwm2m_get_s64(const struct lwm2m_obj_path *path, int64_t *value);
1134 :
1135 : /**
1136 : * @brief Get resource (instance) value (bool)
1137 : *
1138 : * @param[in] path LwM2M path as a struct
1139 : * @param[out] value bool buffer to copy data into
1140 : *
1141 : * @return 0 for success or negative in case of error.
1142 : */
1143 1 : int lwm2m_get_bool(const struct lwm2m_obj_path *path, bool *value);
1144 :
1145 : /**
1146 : * @brief Get resource (instance) value (double)
1147 : *
1148 : * @param[in] path LwM2M path as a struct
1149 : * @param[out] value double buffer to copy data into
1150 : *
1151 : * @return 0 for success or negative in case of error.
1152 : */
1153 1 : int lwm2m_get_f64(const struct lwm2m_obj_path *path, double *value);
1154 :
1155 : /**
1156 : * @brief Get resource (instance) value (Objlnk)
1157 : *
1158 : * @param[in] path LwM2M path as a struct
1159 : * @param[out] buf lwm2m_objlnk buffer to copy data into
1160 : *
1161 : * @return 0 for success or negative in case of error.
1162 : */
1163 1 : int lwm2m_get_objlnk(const struct lwm2m_obj_path *path, struct lwm2m_objlnk *buf);
1164 :
1165 : /**
1166 : * @brief Get resource (instance) value (Time)
1167 : *
1168 : * @param[in] path LwM2M path as a struct
1169 : * @param[out] buf time_t pointer to copy data
1170 : *
1171 : * @return 0 for success or negative in case of error.
1172 : */
1173 1 : int lwm2m_get_time(const struct lwm2m_obj_path *path, time_t *buf);
1174 :
1175 : /**
1176 : * @brief Set resource (instance) read callback
1177 : *
1178 : * LwM2M clients can use this to set the callback function for resource reads when data
1179 : * handling in the LwM2M engine needs to be bypassed.
1180 : * For example reading back opaque binary data from external storage.
1181 : *
1182 : * This callback should not generally be used for any data that might be observed as
1183 : * engine does not have any knowledge of data changes.
1184 : *
1185 : * When separate buffer for data should be used, use lwm2m_set_res_buf() instead
1186 : * to set the storage.
1187 : *
1188 : * @param[in] path LwM2M path as a struct
1189 : * @param[in] cb Read resource callback
1190 : *
1191 : * @return 0 for success or negative in case of error.
1192 : */
1193 1 : int lwm2m_register_read_callback(const struct lwm2m_obj_path *path, lwm2m_engine_get_data_cb_t cb);
1194 :
1195 : /**
1196 : * @brief Set resource (instance) pre-write callback
1197 : *
1198 : * This callback is triggered before setting the value of a resource. It
1199 : * can pass a special data buffer to the engine so that the actual resource
1200 : * value can be calculated later, etc.
1201 : *
1202 : * @param[in] path LwM2M path as a struct
1203 : * @param[in] cb Pre-write resource callback
1204 : *
1205 : * @return 0 for success or negative in case of error.
1206 : */
1207 1 : int lwm2m_register_pre_write_callback(const struct lwm2m_obj_path *path,
1208 : lwm2m_engine_get_data_cb_t cb);
1209 :
1210 : /**
1211 : * @brief Set resource (instance) validation callback
1212 : *
1213 : * This callback is triggered before setting the value of a resource to the
1214 : * resource data buffer.
1215 : *
1216 : * The callback allows an LwM2M client or object to validate the data before
1217 : * writing and notify an error if the data should be discarded for any reason
1218 : * (by returning a negative error code).
1219 : *
1220 : * @note All resources that have a validation callback registered are initially
1221 : * decoded into a temporary validation buffer. Make sure that
1222 : * ``CONFIG_LWM2M_ENGINE_VALIDATION_BUFFER_SIZE`` is large enough to
1223 : * store each of the validated resources (individually).
1224 : *
1225 : * @param[in] path LwM2M path as a struct
1226 : * @param[in] cb Validate resource data callback
1227 : *
1228 : * @return 0 for success or negative in case of error.
1229 : */
1230 1 : int lwm2m_register_validate_callback(const struct lwm2m_obj_path *path,
1231 : lwm2m_engine_set_data_cb_t cb);
1232 :
1233 : /**
1234 : * @brief Set resource (instance) post-write callback
1235 : *
1236 : * This callback is triggered after setting the value of a resource to the
1237 : * resource data buffer.
1238 : *
1239 : * It allows an LwM2M client or object to post-process the value of a resource
1240 : * or trigger other related resource calculations.
1241 : *
1242 : * @param[in] path LwM2M path as a struct
1243 : * @param[in] cb Post-write resource callback
1244 : *
1245 : * @return 0 for success or negative in case of error.
1246 : */
1247 1 : int lwm2m_register_post_write_callback(const struct lwm2m_obj_path *path,
1248 : lwm2m_engine_set_data_cb_t cb);
1249 :
1250 : /**
1251 : * @brief Set resource execute event callback
1252 : *
1253 : * This event is triggered when the execute method of a resource is enabled.
1254 : *
1255 : * @param[in] path LwM2M path as a struct
1256 : * @param[in] cb Execute resource callback
1257 : *
1258 : * @return 0 for success or negative in case of error.
1259 : */
1260 1 : int lwm2m_register_exec_callback(const struct lwm2m_obj_path *path, lwm2m_engine_execute_cb_t cb);
1261 :
1262 : /**
1263 : * @brief Set object instance create event callback
1264 : *
1265 : * This event is triggered when an object instance is created.
1266 : *
1267 : * @param[in] obj_id LwM2M object id
1268 : * @param[in] cb Create object instance callback
1269 : *
1270 : * @return 0 for success or negative in case of error.
1271 : */
1272 1 : int lwm2m_register_create_callback(uint16_t obj_id,
1273 : lwm2m_engine_user_cb_t cb);
1274 :
1275 : /**
1276 : * @brief Set object instance delete event callback
1277 : *
1278 : * This event is triggered when an object instance is deleted.
1279 : *
1280 : * @param[in] obj_id LwM2M object id
1281 : * @param[in] cb Delete object instance callback
1282 : *
1283 : * @return 0 for success or negative in case of error.
1284 : */
1285 1 : int lwm2m_register_delete_callback(uint16_t obj_id,
1286 : lwm2m_engine_user_cb_t cb);
1287 :
1288 : /**
1289 : * @brief Resource read-only value bit
1290 : */
1291 1 : #define LWM2M_RES_DATA_READ_ONLY 0
1292 :
1293 : /**
1294 : * @brief Resource read-only flag
1295 : */
1296 1 : #define LWM2M_RES_DATA_FLAG_RO BIT(LWM2M_RES_DATA_READ_ONLY)
1297 :
1298 : /**
1299 : * @brief Read resource flags helper macro
1300 : */
1301 1 : #define LWM2M_HAS_RES_FLAG(res, f) ((res->data_flags & f) == f)
1302 :
1303 : /**
1304 : * @brief Set data buffer for a resource
1305 : *
1306 : * Use this function to set the data buffer and flags for the specified LwM2M
1307 : * resource.
1308 : *
1309 : * @param[in] path LwM2M path as a struct
1310 : * @param[in] buffer_ptr Data buffer pointer
1311 : * @param[in] buffer_len Length of buffer
1312 : * @param[in] data_len Length of existing data in the buffer
1313 : * @param[in] data_flags Data buffer flags (such as read-only, etc)
1314 : *
1315 : * @return 0 for success or negative in case of error.
1316 : */
1317 1 : int lwm2m_set_res_buf(const struct lwm2m_obj_path *path, void *buffer_ptr, uint16_t buffer_len,
1318 : uint16_t data_len, uint8_t data_flags);
1319 :
1320 : /**
1321 : * @brief Update data size for a resource
1322 : *
1323 : * Use this function to set the new size of data in the buffer if you write
1324 : * to a buffer received by lwm2m_get_res_buf().
1325 : *
1326 : * @param[in] path LwM2M path as a struct
1327 : * @param[in] data_len Length of data
1328 : * @return 0 for success or negative in case of error.
1329 : */
1330 1 : int lwm2m_set_res_data_len(const struct lwm2m_obj_path *path, uint16_t data_len);
1331 :
1332 : /**
1333 : * @brief Get data buffer for a resource
1334 : *
1335 : * Use this function to get the data buffer information for the specified LwM2M
1336 : * resource.
1337 : *
1338 : * If you directly write into the buffer, you must use lwm2m_set_res_data_len()
1339 : * function to update the new size of the written data.
1340 : *
1341 : * All parameters, except for the pathstr, can be NULL if you don't want to read those values.
1342 : *
1343 : * @param[in] path LwM2M path as a struct
1344 : * @param[out] buffer_ptr Data buffer pointer
1345 : * @param[out] buffer_len Length of buffer
1346 : * @param[out] data_len Length of existing data in the buffer
1347 : * @param[out] data_flags Data buffer flags (such as read-only, etc)
1348 : *
1349 : * @return 0 for success or negative in case of error.
1350 : */
1351 1 : int lwm2m_get_res_buf(const struct lwm2m_obj_path *path, void **buffer_ptr, uint16_t *buffer_len,
1352 : uint16_t *data_len, uint8_t *data_flags);
1353 :
1354 : /**
1355 : * @brief Create a resource instance
1356 : *
1357 : * LwM2M clients use this function to create multi-resource instances:
1358 : * Example to create 0 instance of device available power sources:
1359 : * lwm2m_create_res_inst(&LWM2M_OBJ(3, 0, 6, 0));
1360 : *
1361 : * @param[in] path LwM2M path as a struct
1362 : *
1363 : * @return 0 for success or negative in case of error.
1364 : */
1365 1 : int lwm2m_create_res_inst(const struct lwm2m_obj_path *path);
1366 :
1367 : /**
1368 : * @brief Delete a resource instance
1369 : *
1370 : * Use this function to remove an existing resource instance
1371 : *
1372 : * @param[in] path LwM2M path as a struct
1373 : *
1374 : * @return 0 for success or negative in case of error.
1375 : */
1376 1 : int lwm2m_delete_res_inst(const struct lwm2m_obj_path *path);
1377 :
1378 : /**
1379 : * @brief Update the period of the device service.
1380 : *
1381 : * Change the duration of the periodic device service that notifies the
1382 : * current time.
1383 : *
1384 : * @param[in] period_ms New period for the device service (in milliseconds)
1385 : *
1386 : * @return 0 for success or negative in case of error.
1387 : */
1388 1 : int lwm2m_update_device_service_period(uint32_t period_ms);
1389 :
1390 : /**
1391 : * @brief Check whether a path is observed
1392 : *
1393 : * @param[in] path LwM2M path as a struct to check
1394 : *
1395 : * @return true when there exists an observation of the same level
1396 : * or lower as the given path, false if it doesn't or path is not a
1397 : * valid LwM2M-path.
1398 : * E.g. true if path refers to a resource and the parent object has an
1399 : * observation, false for the inverse.
1400 : */
1401 1 : bool lwm2m_path_is_observed(const struct lwm2m_obj_path *path);
1402 :
1403 : /**
1404 : * @brief Stop the LwM2M engine
1405 : *
1406 : * LwM2M clients normally do not need to call this function as it is called
1407 : * within lwm2m_rd_client. However, if the client does not use the RD
1408 : * client implementation, it will need to be called manually.
1409 : *
1410 : * @param[in] client_ctx LwM2M context
1411 : *
1412 : * @return 0 for success or negative in case of error.
1413 : */
1414 1 : int lwm2m_engine_stop(struct lwm2m_ctx *client_ctx);
1415 :
1416 : /**
1417 : * @brief Start the LwM2M engine
1418 : *
1419 : * LwM2M clients normally do not need to call this function as it is called
1420 : * by lwm2m_rd_client_start(). However, if the client does not use the RD
1421 : * client implementation, it will need to be called manually.
1422 : *
1423 : * @param[in] client_ctx LwM2M context
1424 : *
1425 : * @return 0 for success or negative in case of error.
1426 : */
1427 1 : int lwm2m_engine_start(struct lwm2m_ctx *client_ctx);
1428 :
1429 : /**
1430 : * @brief Acknowledge the currently processed request with an empty ACK.
1431 : *
1432 : * LwM2M engine by default sends piggybacked responses for requests.
1433 : * This function allows to send an empty ACK for a request earlier (from the
1434 : * application callback). The LwM2M engine will then send the actual response
1435 : * as a separate CON message after all callbacks are executed.
1436 : *
1437 : * @param[in] client_ctx LwM2M context
1438 : *
1439 : */
1440 1 : void lwm2m_acknowledge(struct lwm2m_ctx *client_ctx);
1441 :
1442 : /*
1443 : * LwM2M RD client flags, used to configure LwM2M session.
1444 : */
1445 :
1446 : /**
1447 : * @brief Run bootstrap procedure in current session.
1448 : */
1449 1 : #define LWM2M_RD_CLIENT_FLAG_BOOTSTRAP BIT(0)
1450 :
1451 : /**
1452 : * @brief Start the LwM2M RD (Registration / Discovery) Client
1453 : *
1454 : * The RD client sits just above the LwM2M engine and performs the necessary
1455 : * actions to implement the "Registration interface".
1456 : * For more information see Section "Client Registration Interface" of
1457 : * LwM2M Technical Specification.
1458 : *
1459 : * NOTE: lwm2m_engine_start() is called automatically by this function.
1460 : *
1461 : * @param[in] client_ctx LwM2M context
1462 : * @param[in] ep_name Registered endpoint name
1463 : * @param[in] flags Flags used to configure current LwM2M session.
1464 : * @param[in] event_cb Client event callback function
1465 : * @param[in] observe_cb Observe callback function called when an observer was
1466 : * added or deleted, and when a notification was acked or
1467 : * has timed out
1468 : *
1469 : * @return 0 for success, -EINPROGRESS when client is already running
1470 : * or negative error codes in case of failure.
1471 : */
1472 1 : int lwm2m_rd_client_start(struct lwm2m_ctx *client_ctx, const char *ep_name,
1473 : uint32_t flags, lwm2m_ctx_event_cb_t event_cb,
1474 : lwm2m_observe_cb_t observe_cb);
1475 :
1476 : /**
1477 : * @brief Stop the LwM2M RD (De-register) Client
1478 : *
1479 : * The RD client sits just above the LwM2M engine and performs the necessary
1480 : * actions to implement the "Registration interface".
1481 : * For more information see Section "Client Registration Interface" of the
1482 : * LwM2M Technical Specification.
1483 : *
1484 : * @param[in] client_ctx LwM2M context
1485 : * @param[in] event_cb Client event callback function
1486 : * @param[in] deregister True to deregister the client if registered.
1487 : * False to force close the connection.
1488 : *
1489 : * @return 0 for success or negative in case of error.
1490 : */
1491 1 : int lwm2m_rd_client_stop(struct lwm2m_ctx *client_ctx,
1492 : lwm2m_ctx_event_cb_t event_cb, bool deregister);
1493 :
1494 : /**
1495 : * @brief Suspend the LwM2M engine Thread
1496 : *
1497 : * Suspend LwM2M engine. Use case could be when network connection is down.
1498 : * LwM2M Engine indicate before it suspend by
1499 : * LWM2M_RD_CLIENT_EVENT_ENGINE_SUSPENDED event.
1500 : *
1501 : * @return 0 for success or negative in case of error.
1502 : */
1503 1 : int lwm2m_engine_pause(void);
1504 :
1505 : /**
1506 : * @brief Resume the LwM2M engine thread
1507 : *
1508 : * Resume suspended LwM2M engine. After successful resume call engine will do
1509 : * full registration or registration update based on suspended time.
1510 : * Event's LWM2M_RD_CLIENT_EVENT_REGISTRATION_COMPLETE or LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE
1511 : * indicate that client is connected to server.
1512 : *
1513 : * @return 0 for success or negative in case of error.
1514 : */
1515 1 : int lwm2m_engine_resume(void);
1516 :
1517 : /**
1518 : * @brief Trigger a Registration Update of the LwM2M RD Client
1519 : */
1520 1 : void lwm2m_rd_client_update(void);
1521 :
1522 : /**
1523 : * @brief LwM2M path maximum length
1524 : */
1525 1 : #define LWM2M_MAX_PATH_STR_SIZE sizeof("/65535/65535/65535/65535")
1526 :
1527 : /**
1528 : * @brief Helper function to print path objects' contents to log
1529 : *
1530 : * @param[in] buf The buffer to use for formatting the string
1531 : * @param[in] path The path to stringify
1532 : *
1533 : * @return Resulting formatted path string
1534 : */
1535 1 : char *lwm2m_path_log_buf(char *buf, struct lwm2m_obj_path *path);
1536 :
1537 : /**
1538 : * @brief LwM2M send status
1539 : *
1540 : * LwM2M send status are generated back to the lwm2m_send_cb_t function in
1541 : * lwm2m_send_cb()
1542 : */
1543 1 : enum lwm2m_send_status {
1544 : LWM2M_SEND_STATUS_SUCCESS, /**< Succeed */
1545 : LWM2M_SEND_STATUS_FAILURE, /**< Failure */
1546 : LWM2M_SEND_STATUS_TIMEOUT, /**< Timeout */
1547 : };
1548 :
1549 : /**
1550 : * @typedef lwm2m_send_cb_t
1551 : * @brief Callback returning send status
1552 : */
1553 1 : typedef void (*lwm2m_send_cb_t)(enum lwm2m_send_status status);
1554 :
1555 : /**
1556 : * @brief LwM2M SEND operation to given path list asynchronously with confirmation callback
1557 : *
1558 : * @param ctx LwM2M context
1559 : * @param path_list LwM2M path struct list
1560 : * @param path_list_size Length of path list. Max size is CONFIG_LWM2M_COMPOSITE_PATH_LIST_SIZE
1561 : * @param reply_cb Callback triggered with confirmation state or NULL if not used
1562 : *
1563 : * @return 0 for success or negative in case of error.
1564 : *
1565 : */
1566 1 : int lwm2m_send_cb(struct lwm2m_ctx *ctx, const struct lwm2m_obj_path path_list[],
1567 : uint8_t path_list_size, lwm2m_send_cb_t reply_cb);
1568 :
1569 : /**
1570 : * @brief Returns LwM2M client context
1571 : *
1572 : * @return ctx LwM2M context
1573 : *
1574 : */
1575 1 : struct lwm2m_ctx *lwm2m_rd_client_ctx(void);
1576 :
1577 : /**
1578 : * @brief Enable data cache for a resource.
1579 : *
1580 : * Application may enable caching of resource data by allocating buffer for LwM2M engine to use.
1581 : * Buffer must be size of struct @ref lwm2m_time_series_elem times cache_len
1582 : *
1583 : * @param path LwM2M path to resource as a struct
1584 : * @param data_cache Pointer to Data cache array
1585 : * @param cache_len number of cached entries
1586 : *
1587 : * @return 0 for success or negative in case of error.
1588 : *
1589 : */
1590 1 : int lwm2m_enable_cache(const struct lwm2m_obj_path *path, struct lwm2m_time_series_elem *data_cache,
1591 : size_t cache_len);
1592 :
1593 : /**
1594 : * @brief Security modes as defined in LwM2M Security object.
1595 : */
1596 1 : enum lwm2m_security_mode_e {
1597 : LWM2M_SECURITY_PSK = 0, /**< Pre-Shared Key mode */
1598 : LWM2M_SECURITY_RAW_PK = 1, /**< Raw Public Key mode */
1599 : LWM2M_SECURITY_CERT = 2, /**< Certificate mode */
1600 : LWM2M_SECURITY_NOSEC = 3, /**< NoSec mode */
1601 : LWM2M_SECURITY_CERT_EST = 4, /**< Certificate mode with EST */
1602 : };
1603 :
1604 : /**
1605 : * @brief Read security mode from selected security object instance.
1606 : *
1607 : * This data is valid only if RD client is running.
1608 : *
1609 : * @param ctx Pointer to client context.
1610 : * @return int Positive values are @ref lwm2m_security_mode_e, negative error codes otherwise.
1611 : */
1612 1 : int lwm2m_security_mode(struct lwm2m_ctx *ctx);
1613 :
1614 : /**
1615 : * @brief Set default socket options for DTLS connections.
1616 : *
1617 : * The engine calls this when @ref lwm2m_ctx::set_socketoptions is not overwritten.
1618 : * You can call this from the overwritten callback to set extra options after or
1619 : * before defaults.
1620 : *
1621 : * @param ctx Client context
1622 : * @return 0 for success or negative in case of error.
1623 : */
1624 1 : int lwm2m_set_default_sockopt(struct lwm2m_ctx *ctx);
1625 :
1626 : /**
1627 : * @brief Set the @ref lwm2m_ctx::set_socketoptions callback for the pull context's client.
1628 : *
1629 : * This allows setting specific socket options on the socket that is used to pull
1630 : * firmware updates. The callback will be called after the pull context socket has been
1631 : * created and before it will connect.
1632 : *
1633 : * @param[in] set_sockopt_cb A callback function to set sockopts for the pull context client.
1634 : */
1635 1 : void lwm2m_pull_context_set_sockopt_callback(lwm2m_set_sockopt_cb_t set_sockopt_cb);
1636 :
1637 : #ifdef __cplusplus
1638 : }
1639 : #endif
1640 :
1641 : #endif /* ZEPHYR_INCLUDE_NET_LWM2M_H_ */
1642 : /**@} */
|
