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