1.. _lwm2m_interface: 2 3Lightweight M2M (LWM2M) 4####################### 5 6.. contents:: 7 :local: 8 :depth: 2 9 10Overview 11******** 12 13Lightweight Machine to Machine (LwM2M) is an application layer protocol 14designed with device management, data reporting and device actuation in mind. 15Based on CoAP/UDP, `LwM2M`_ is a 16`standard <https://openmobilealliance.org/release/LightweightM2M/>`_ defined by 17the Open Mobile Alliance and suitable for constrained devices by its use of 18CoAP packet-size optimization and a simple, stateless flow that supports a 19REST API. 20 21One of the key differences between LwM2M and CoAP is that an LwM2M client 22initiates the connection to an LwM2M server. The server can then use the 23REST API to manage various interfaces with the client. 24 25LwM2M uses a simple resource model with the core set of objects and resources 26defined in the specification. 27 28The LwM2M library can be enabled with :kconfig:option:`CONFIG_LWM2M` Kconfig option. 29 30Example LwM2M object and resources: Device 31****************************************** 32 33*Object definition* 34 35.. list-table:: 36 :header-rows: 1 37 38 * - Object ID 39 - Name 40 - Instance 41 - Mandatory 42 43 * - 3 44 - Device 45 - Single 46 - Mandatory 47 48*Resource definitions* 49 50``* R=Read, W=Write, E=Execute`` 51 52.. list-table:: 53 :header-rows: 1 54 55 * - ID 56 - Name 57 - OP\* 58 - Instance 59 - Mandatory 60 - Type 61 62 * - 0 63 - Manufacturer 64 - R 65 - Single 66 - Optional 67 - String 68 69 * - 1 70 - Model 71 - R 72 - Single 73 - Optional 74 - String 75 76 * - 2 77 - Serial number 78 - R 79 - Single 80 - Optional 81 - String 82 83 * - 3 84 - Firmware version 85 - R 86 - Single 87 - Optional 88 - String 89 90 * - 4 91 - Reboot 92 - E 93 - Single 94 - Mandatory 95 - 96 97 * - 5 98 - Factory Reset 99 - E 100 - Single 101 - Optional 102 - 103 104 * - 6 105 - Available Power Sources 106 - R 107 - Multiple 108 - Optional 109 - Integer 0-7 110 111 * - 7 112 - Power Source Voltage (mV) 113 - R 114 - Multiple 115 - Optional 116 - Integer 117 118 * - 8 119 - Power Source Current (mA) 120 - R 121 - Multiple 122 - Optional 123 - Integer 124 125 * - 9 126 - Battery Level % 127 - R 128 - Single 129 - Optional 130 - Integer 131 132 * - 10 133 - Memory Free (Kb) 134 - R 135 - Single 136 - Optional 137 - Integer 138 139 * - 11 140 - Error Code 141 - R 142 - Multiple 143 - Optional 144 - Integer 0-8 145 146 * - 12 147 - Reset Error 148 - E 149 - Single 150 - Optional 151 - 152 153 * - 13 154 - Current Time 155 - RW 156 - Single 157 - Optional 158 - Time 159 160 * - 14 161 - UTC Offset 162 - RW 163 - Single 164 - Optional 165 - String 166 167 * - 15 168 - Timezone 169 - RW 170 - Single 171 - Optional 172 - String 173 174 * - 16 175 - Supported Binding 176 - R 177 - Single 178 - Mandatory 179 - String 180 181 * - 17 182 - Device Type 183 - R 184 - Single 185 - Optional 186 - String 187 188 * - 18 189 - Hardware Version 190 - R 191 - Single 192 - Optional 193 - String 194 195 * - 19 196 - Software Version 197 - R 198 - Single 199 - Optional 200 - String 201 202 * - 20 203 - Battery Status 204 - R 205 - Single 206 - Optional 207 - Integer 0-6 208 209 * - 21 210 - Memory Total (Kb) 211 - R 212 - Single 213 - Optional 214 - Integer 215 216 * - 22 217 - ExtDevInfo 218 - R 219 - Multiple 220 - Optional 221 - ObjLnk 222 223The server could query the ``Manufacturer`` resource for ``Device`` object 224instance 0 (the default and only instance) by sending a ``READ 3/0/0`` 225operation to the client. 226 227The full list of registered objects and resource IDs can be found in the 228`OMA LwM2M registries`_. 229 230Zephyr's LwM2M library lives in the :zephyr_file:`subsys/net/lib/lwm2m`, with a 231client sample in :zephyr_file:`samples/net/lwm2m_client`. For more information 232about the provided sample see: :zephyr:code-sample:`lwm2m-client`. The sample can be 233configured to use normal unsecure network sockets or sockets secured via DTLS. 234 235The Zephyr LwM2M library implements the following items: 236 237* engine to process networking events and core functions 238* RD client which performs BOOTSTRAP and REGISTRATION functions 239* SenML CBOR, SenML JSON, CBOR, TLV, JSON, and plain text formatting functions 240* LwM2M Technical Specification Enabler objects such as Security, Server, 241 Device, Firmware Update, etc. 242* Extended IPSO objects such as Light Control, Temperature Sensor, and Timer 243 244By default, the library implements `LwM2M specification 1.0.2`_ and can be set to 245`LwM2M specification 1.1.1`_ with a Kconfig option. 246 247For more information about LwM2M specification releases visit the 248`OMA LwM2M releases`_ page. 249 250Sample usage 251************ 252 253To use the LwM2M library, start by creating an LwM2M client context 254:c:struct:`lwm2m_ctx` structure: 255 256.. code-block:: c 257 258 /* LwM2M client context */ 259 static struct lwm2m_ctx client; 260 261Create callback functions for LwM2M resource executions: 262 263.. code-block:: c 264 265 static int device_reboot_cb(uint16_t obj_inst_id, uint8_t *args, 266 uint16_t args_len) 267 { 268 LOG_INF("Device rebooting."); 269 LOG_PANIC(); 270 sys_reboot(0); 271 return 0; /* won't reach this */ 272 } 273 274The LwM2M RD client can send events back to the sample. To receive those 275events, setup a callback function: 276 277.. code-block:: c 278 279 static void rd_client_event(struct lwm2m_ctx *client, 280 enum lwm2m_rd_client_event client_event) 281 { 282 switch (client_event) { 283 284 case LWM2M_RD_CLIENT_EVENT_NONE: 285 /* do nothing */ 286 break; 287 288 case LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_FAILURE: 289 LOG_DBG("Bootstrap registration failure!"); 290 break; 291 292 case LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_COMPLETE: 293 LOG_DBG("Bootstrap registration complete"); 294 break; 295 296 case LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_TRANSFER_COMPLETE: 297 LOG_DBG("Bootstrap transfer complete"); 298 break; 299 300 case LWM2M_RD_CLIENT_EVENT_REGISTRATION_FAILURE: 301 LOG_DBG("Registration failure!"); 302 break; 303 304 case LWM2M_RD_CLIENT_EVENT_REGISTRATION_COMPLETE: 305 LOG_DBG("Registration complete"); 306 break; 307 308 case LWM2M_RD_CLIENT_EVENT_REG_TIMEOUT: 309 LOG_DBG("Registration timeout!"); 310 break; 311 312 case LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE: 313 LOG_DBG("Registration update complete"); 314 break; 315 316 case LWM2M_RD_CLIENT_EVENT_DEREGISTER_FAILURE: 317 LOG_DBG("Deregister failure!"); 318 break; 319 320 case LWM2M_RD_CLIENT_EVENT_DISCONNECT: 321 LOG_DBG("Disconnected"); 322 break; 323 324 case LWM2M_RD_CLIENT_EVENT_REG_UPDATE: 325 LOG_DBG("Registration update"); 326 break; 327 328 case LWM2M_RD_CLIENT_EVENT_DEREGISTER: 329 LOG_DBG("Deregistration client"); 330 break; 331 332 case LWM2M_RD_CLIENT_EVENT_SERVER_DISABLED: 333 LOG_DBG("LwM2M server disabled"); 334 break; 335 } 336 } 337 338Next we assign ``Security`` resource values to let the client know where and how 339to connect as well as set the ``Manufacturer`` and ``Reboot`` resources in the 340``Device`` object with some data and the callback we defined above: 341 342.. code-block:: c 343 344 /* 345 * Server URL of default Security object = 0/0/0 346 * Use leshan.eclipse.org server IP (5.39.83.206) for connection 347 */ 348 lwm2m_set_string(&LWM2M_OBJ(0, 0, 0), "coap://5.39.83.206"); 349 350 /* 351 * Security Mode of default Security object = 0/0/2 352 * 3 = NoSec mode (no security beware!) 353 */ 354 lwm2m_set_u8(&LWM2M_OBJ(0, 0, 2), 3); 355 356 #define CLIENT_MANUFACTURER "Zephyr Manufacturer" 357 358 /* 359 * Manufacturer resource of Device object = 3/0/0 360 * We use lwm2m_set_res_data() function to set a pointer to the 361 * CLIENT_MANUFACTURER string. 362 * Note the LWM2M_RES_DATA_FLAG_RO flag which stops the engine from 363 * trying to assign a new value to the buffer. 364 */ 365 lwm2m_set_res_data(&LWM2M_OBJ(3, 0, 0), CLIENT_MANUFACTURER, 366 sizeof(CLIENT_MANUFACTURER), 367 LWM2M_RES_DATA_FLAG_RO); 368 369 /* Reboot resource of Device object = 3/0/4 */ 370 lwm2m_register_exec_callback(&LWM2M_OBJ(3, 0, 4), device_reboot_cb); 371 372Lastly, we start the LwM2M RD client (which in turn starts the LwM2M engine). 373The second parameter of :c:func:`lwm2m_rd_client_start` is the client 374endpoint name. This is important as it needs to be unique per LwM2M server: 375 376.. code-block:: c 377 378 (void)memset(&client, 0x0, sizeof(client)); 379 lwm2m_rd_client_start(&client, "unique-endpoint-name", 0, rd_client_event); 380 381.. _lwm2m_security: 382 383LwM2M security modes 384******************** 385 386The Zephyr LwM2M library can be used either without security or use DTLS to secure the communication channel. 387When using DTLS with the LwM2M engine, PSK (Pre-Shared Key) and X.509 certificates are the security modes that can be used to secure the communication. 388The engine uses LwM2M Security object (Id 0) to read the stored credentials and feed keys from the security object into 389the TLS credential subsystem, see :ref:`secure sockets documentation <secure_sockets_interface>`. 390Enable the :kconfig:option:`CONFIG_LWM2M_DTLS_SUPPORT` Kconfig option to use the security. 391 392Depending on the selected mode, the security object must contain following data: 393 394PSK 395 Security Mode (Resource ID 2) set to zero (Pre-Shared Key mode). 396 Identity (Resource ID 3) contains PSK ID in binary form. 397 Secret key (Resource ID 5) contains the PSK key in binary form. 398 If the key or identity is provided as a hex string, it must be converted to binary before storing into the security object. 399 400X509 401 When X509 certificates are used, set Security Mode (ID 2) to ``2`` (Certificate mode). 402 Identity (ID 3) is used to store the client certificate and Secret key (ID 5) must have a private key associated with the certificate. 403 Server Public Key resource (ID 4) must contain a server certificate or CA certificate used to sign the certificate chain. 404 If the :kconfig:option:`CONFIG_MBEDTLS_PEM_CERTIFICATE_FORMAT` Kconfig option is enabled, certificates and private key can be entered in PEM format. 405 Otherwise, they must be in binary DER format. 406 407NoSec 408 When no security is used, set Security Mode (Resource ID 2) to ``3`` (NoSec). 409 410In all modes, Server URI resource (ID 0) must contain the full URI for the target server. 411When DNS names are used, the DNS resolver must be enabled. 412 413When DTLS is used, following options are recommended to reduce DTLS handshake traffic when connection is re-established: 414 415* :kconfig:option:`CONFIG_LWM2M_DTLS_CID` enables DTLS Connection Identifier support. When server supports it, this completely removes the handshake when device resumes operation after long idle period. Greatly helps when NAT mappings have timed out. 416* :kconfig:option:`CONFIG_LWM2M_TLS_SESSION_CACHING` uses session cache when before falling back to full DTLS handshake. Reduces few packets from handshake, when session is still cached on server side. Most significant effect is to avoid full registration. 417 418LwM2M stack provides callbacks in the :c:struct:`lwm2m_ctx` structure. 419They are used to feed keys from the LwM2M security object into the TLS credential subsystem. 420By default, these callbacks can be left as NULL pointers, in which case default callbacks are used. 421When an external TLS stack, or non-default socket options are required, you can overwrite the :c:func:`lwm2m_ctx.load_credentials` or :c:func:`lwm2m_ctx.set_socketoptions` callbacks. 422 423An example of setting up the security object for PSK mode: 424 425.. code-block:: c 426 427 /* "000102030405060708090a0b0c0d0e0f" */ 428 static unsigned char client_psk[] = { 429 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 430 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f 431 }; 432 433 static const char client_identity[] = "Client_identity"; 434 435 lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 0), "coaps://lwm2m.example.com"); 436 lwm2m_set_u8(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 2), LWM2M_SECURITY_PSK); 437 /* Set the client identity as a string, but this could be binary as well */ 438 lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 3), client_identity); 439 /* Set the client pre-shared key (PSK) */ 440 lwm2m_set_opaque(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 5), client_psk, sizeof(client_psk)); 441 442An example of setting up the security object for X509 certificate mode: 443 444.. code-block:: c 445 446 static const char certificate[] = "-----BEGIN CERTIFICATE-----\nMIIB6jCCAY+gAw..."; 447 static const char key[] = "-----BEGIN EC PRIVATE KEY-----\nMHcCAQ..."; 448 static const char root_ca[] = "-----BEGIN CERTIFICATE-----\nMIIBaz..."; 449 450 lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 0), "coaps://lwm2m.example.com"); 451 lwm2m_set_u8(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 2), LWM2M_SECURITY_CERT); 452 lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 3), certificate); 453 lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 5), key); 454 lwm2m_set_string(&LWM2M_OBJ(LWM2M_OBJECT_SECURITY_ID, 0, 4), root_ca); 455 456Before calling :c:func:`lwm2m_rd_client_start` assign the tls_tag # where the 457LwM2M library should store the DTLS information prior to connection (normally a 458value of 1 is ok here). 459 460.. code-block:: c 461 462 (void)memset(&client, 0x0, sizeof(client)); 463 client.tls_tag = 1; /* <---- */ 464 lwm2m_rd_client_start(&client, "endpoint-name", 0, rd_client_event); 465 466For a more detailed LwM2M client sample see: :zephyr:code-sample:`lwm2m-client`. 467 468Multi-thread usage 469****************** 470Writing a value to a resource can be done using functions like lwm2m_set_u8. When writing 471to multiple resources, the function lwm2m_registry_lock will ensure that the 472client halts until all writing operations are finished: 473 474.. code-block:: c 475 476 lwm2m_registry_lock(); 477 lwm2m_set_u32(&LWM2M_OBJ(1, 0, 1), 60); 478 lwm2m_set_u8(&LWM2M_OBJ(5, 0, 3), 0); 479 lwm2m_set_f64(&LWM2M_OBJ(3303, 0, 5700), value); 480 lwm2m_registry_unlock(); 481 482This is especially useful if the server is composite-observing the resources being 483written to. Locking will then ensure that the client only updates and sends notifications 484to the server after all operations are done, resulting in fewer messages in general. 485 486Support for time series data 487**************************** 488 489LwM2M version 1.1 adds support for SenML CBOR and SenML JSON data formats. These data formats add 490support for time series data. Time series formats can be used for READ, NOTIFY and SEND operations. 491When data cache is enabled for a resource, each write will create a timestamped entry in a cache, 492and its content is then returned as a content in READ, NOTIFY or SEND operation for a given 493resource. 494 495Data cache is only supported for resources with a fixed data size. 496 497Supported resource types: 498 499* Signed and unsigned 8-64-bit integers 500* Float 501* Boolean 502 503Enabling and configuring 504======================== 505 506Enable data cache by selecting :kconfig:option:`CONFIG_LWM2M_RESOURCE_DATA_CACHE_SUPPORT`. 507Application needs to allocate an array of :c:struct:`lwm2m_time_series_elem` structures and then 508enable the cache by calling :c:func:`lwm2m_enable_cache` for a given resource. Each resource 509must be enabled separately and each resource needs their own storage. 510 511.. code-block:: c 512 513 /* Allocate data cache storage */ 514 static struct lwm2m_time_series_elem temperature_cache[10]; 515 /* Enable data cache */ 516 lwm2m_enable_cache(LWM2M_OBJ(IPSO_OBJECT_TEMP_SENSOR_ID, 0, SENSOR_VALUE_RID), 517 temperature_cache, ARRAY_SIZE(temperature_cache)); 518 519LwM2M engine have room for four resources that have cache enabled. Limit can be increased by 520changing :kconfig:option:`CONFIG_LWM2M_MAX_CACHED_RESOURCES`. This affects a static memory usage of 521engine. 522 523Data caches depends on one of the SenML data formats 524:kconfig:option:`CONFIG_LWM2M_RW_SENML_CBOR_SUPPORT` or 525:kconfig:option:`CONFIG_LWM2M_RW_SENML_JSON_SUPPORT` and needs :kconfig:option:`CONFIG_POSIX_TIMERS` 526so it can request a timestamp from the system and :kconfig:option:`CONFIG_RING_BUFFER` for ring 527buffer. 528 529Read and Write operations 530========================= 531 532Full content of data cache is written into a payload when any READ, SEND or NOTIFY operation 533internally reads the content of a given resource. This has a side effect that any read callbacks 534registered for a that resource are ignored when cache is enabled. 535Data is written into a cache when any of the ``lwm2m_set_*`` functions are called. To filter 536the data entering the cache, application may register a validation callback using 537:c:func:`lwm2m_register_validate_callback`. 538 539Limitations 540=========== 541 542Cache size should be manually set so small that the content can fit normal packets sizes. 543When cache is full, new values are dropped. 544 545LwM2M engine and application events 546*********************************** 547 548The Zephyr LwM2M engine defines events that can be sent back to the application through callback 549functions. 550The engine state machine shows when the events are spawned. 551Events depicted in the diagram are listed in the table. 552The events are prefixed with ``LWM2M_RD_CLIENT_EVENT_``. 553 554.. figure:: images/lwm2m_engine_state_machine.svg 555 :alt: LwM2M engine state machine 556 557 State machine for the LwM2M engine 558 559.. list-table:: LwM2M RD Client events 560 :widths: auto 561 :header-rows: 1 562 563 * - Event ID 564 - Event Name 565 - Description 566 * - 0 567 - NONE 568 - No event 569 * - 1 570 - BOOTSTRAP_REG_FAILURE 571 - Bootstrap registration failed. 572 Occurs if there is a timeout or failure in bootstrap registration. 573 * - 2 574 - BOOTSTRAP_REG_COMPLETE 575 - Bootstrap registration complete. 576 Occurs after successful bootstrap registration. 577 * - 3 578 - BOOTSTRAP_TRANSFER_COMPLETE 579 - Bootstrap finish command received from the server. 580 * - 4 581 - REGISTRATION_FAILURE 582 - Registration to LwM2M server failed. 583 Occurs if server rejects the registration attempt. 584 * - 5 585 - REGISTRATION_COMPLETE 586 - Registration to LwM2M server successful. 587 Occurs after a successful registration reply from the LwM2M server 588 or when session resumption is used. 589 * - 6 590 - REG_TIMEOUT 591 - Registration status lost. 592 Occurs if there is socket errors or message timeouts. Client have lost connection to the server. 593 * - 7 594 - REG_UPDATE_COMPLETE 595 - Registration update completed. 596 Occurs after successful registration update reply from the LwM2M server. 597 * - 8 598 - DEREGISTER_FAILURE 599 - Deregistration to LwM2M server failed. 600 Occurs if there is a timeout or failure in the deregistration. 601 * - 9 602 - DISCONNECT 603 - LwM2M client have de-registered from server and is now stopped. 604 Triggered only if the application have requested the client to stop. 605 * - 10 606 - QUEUE_MODE_RX_OFF 607 - Used only in queue mode, not actively listening for incoming packets. 608 In queue mode the client is not required to actively listen for the incoming packets 609 after a configured time period. 610 * - 11 611 - ENGINE_SUSPENDED 612 - Indicate that client has now paused as a result of calling :c:func:`lwm2m_engine_pause`. 613 State machine is no longer running and the handler thread is suspended. 614 All timers are stopped so notifications are not triggered. 615 * - 12 616 - SERVER_DISABLED 617 - Server have executed the disable command. 618 Client will deregister and stay idle for the disable period. 619 * - 13 620 - NETWORK_ERROR 621 - Sending messages to the network failed too many times. 622 Client cannot reach any servers or fallback to bootstrap. 623 LwM2M engine cannot recover and have stopped. 624 625The LwM2M client engine handles most of the state transitions automatically. The application 626needs to handle only the events that indicate that the client have stopped or is in a state 627where it cannot recover. 628 629.. list-table:: How application should react to events 630 :widths: auto 631 :header-rows: 1 632 633 * - Event Name 634 - How application should react 635 * - NONE 636 - Ignore the event. 637 * - BOOTSTRAP_REG_FAILURE 638 - Try to recover network connection. Then restart the client by calling :c:func:`lwm2m_rd_client_start`. 639 This might also indicate configuration issue. 640 * - BOOTSTRAP_REG_COMPLETE 641 - No actions needed 642 * - BOOTSTRAP_TRANSFER_COMPLETE 643 - No actions needed 644 * - REGISTRATION_FAILURE 645 - No actions needed. 646 Client proceeds re-registration automatically. Might need a bootstrap or configuration fix. Cannot send or receive data. 647 * - REGISTRATION_COMPLETE 648 - No actions needed. 649 Application can send or receive data. 650 * - REG_TIMEOUT 651 - No actions needed. 652 Client proceeds to re-registration automatically. Cannot send or receive data. 653 * - REG_UPDATE_COMPLETE 654 - No actions needed 655 Application can send or receive data. 656 * - DEREGISTER_FAILURE 657 - No actions needed, client proceeds to idle state automatically. Cannot send or receive data. 658 * - DISCONNECT 659 - Engine have stopped as a result of calling :c:func:`lwm2m_rd_client_stop`. 660 If connection is required, the application should restart the client by calling :c:func:`lwm2m_rd_client_start`. 661 * - QUEUE_MODE_RX_OFF 662 - No actions needed. 663 Application can send but cannot receive data. 664 Any data transmission will trigger a registration update. 665 * - ENGINE_SUSPENDED 666 - Engine can be resumed by calling :c:func:`lwm2m_engine_resume`. 667 Cannot send or receive data. 668 * - SERVER_DISABLED 669 - No actions needed, client will re-register once the disable period is over. 670 Cannot send or receive data. 671 * - NETWORK_ERROR 672 - Try to recover network connection. Then restart the client by calling :c:func:`lwm2m_rd_client_start`. 673 This might also indicate configuration issue. 674 675Sending of data in the table above refers to calling :c:func:`lwm2m_send_cb` or by writing into one of the observed resources where observation would trigger a notify message. 676Receiving of data refers to receiving read, write or execute operations from the server. Application can register callbacks for these operations. 677 678Configuring lifetime and activity period 679**************************************** 680 681In LwM2M engine, there are three Kconfig options and one runtime value that configures how often the 682client will send LwM2M Update message. 683 684.. list-table:: Update period variables 685 :widths: auto 686 :header-rows: 1 687 688 * - Variable 689 - Effect 690 * - LwM2M registration lifetime 691 - The lifetime parameter in LwM2M specifies how long a device's registration with an LwM2M server remains valid. 692 Device is expected to send LwM2M Update message before the lifetime exprires. 693 * - :kconfig:option:`CONFIG_LWM2M_ENGINE_DEFAULT_LIFETIME` 694 - Default lifetime value, unless set by the bootstrap server. 695 Also defines lower limit that client accepts as a lifetime. 696 * - :kconfig:option:`CONFIG_LWM2M_UPDATE_PERIOD` 697 - How long the client can stay idle before sending a next update. 698 * - :kconfig:option:`CONFIG_LWM2M_SECONDS_TO_UPDATE_EARLY` 699 - Minimum time margin to send the update message before the registration lifetime expires. 700 701.. figure:: images/lwm2m_lifetime_seconds_early.png 702 :alt: LwM2M seconds to update early 703 704 Default way of calculating when to update registration. 705 706By default, the client uses :kconfig:option:`CONFIG_LWM2M_SECONDS_TO_UPDATE_EARLY` to calculate how 707many seconds before the expiration of lifetime it is going to send the registration update. 708The problem with default mode is when the server changes the lifetime of the registration. 709This is then affecting the period of updates the client is doing. 710If this is used with the QUEUE mode, which is typical in IPv4 networks, it is also affecting the 711period of when the device is reachable from the server. 712 713.. figure:: images/lwm2m_lifetime_both.png 714 :alt: LwM2M update time when both values are set 715 716 Update time is controlled by UPDATE_PERIOD. 717 718When also the :kconfig:option:`CONFIG_LWM2M_UPDATE_PERIOD` is set, time to send the update message 719is the earliest when any of these values expire. This allows setting long lifetime for the 720registration and configure the period accurately, even if server changes the lifetime parameter. 721 722In runtime, the update frequency is limited to once in 15 seconds to avoid flooding. 723 724.. _lwm2m_shell: 725 726LwM2M shell 727*********** 728For testing the client it is possible to enable Zephyr's shell and LwM2M specific commands which 729support changing the state of the client. Operations supported are read, write and execute 730resources. Client start, stop, pause and resume are also available. The feature is enabled by 731selecting :kconfig:option:`CONFIG_LWM2M_SHELL`. The shell is meant for testing so productions 732systems should not enable it. 733 734One imaginable scenario, where to use the shell, would be executing client side actions over UART 735when a server side tests would require those. It is assumed that not all tests are able to trigger 736required actions from the server side. 737 738.. code-block:: console 739 740 uart:~$ lwm2m 741 lwm2m - LwM2M commands 742 Subcommands: 743 send :send PATHS 744 LwM2M SEND operation 745 746 exec :exec PATH [PARAM] 747 Execute a resource 748 749 read :read PATH [OPTIONS] 750 Read value from LwM2M resource 751 -x Read value as hex stream (default) 752 -s Read value as string 753 -b Read value as bool (1/0) 754 -uX Read value as uintX_t 755 -sX Read value as intX_t 756 -f Read value as float 757 -t Read value as time_t 758 759 write :write PATH [OPTIONS] VALUE 760 Write into LwM2M resource 761 -s Write value as string (default) 762 -b Write value as bool 763 -uX Write value as uintX_t 764 -sX Write value as intX_t 765 -f Write value as float 766 -t Write value as time_t 767 768 create :create PATH 769 Create object or resource instance 770 771 delete :delete PATH 772 Delete object or resource instance 773 774 cache :cache PATH NUM 775 Enable data cache for resource 776 PATH is LwM2M path 777 NUM how many elements to cache 778 779 start :start EP_NAME [BOOTSTRAP FLAG] 780 Start the LwM2M RD (Registration / Discovery) Client 781 -b Set the bootstrap flag (default 0) 782 783 stop :stop [OPTIONS] 784 Stop the LwM2M RD (De-register) Client 785 -f Force close the connection 786 787 update :Trigger Registration Update of the LwM2M RD Client 788 789 pause :LwM2M engine thread pause 790 resume :LwM2M engine thread resume 791 lock :Lock the LwM2M registry 792 unlock :Unlock the LwM2M registry 793 obs : List observations 794 ls : ls [PATH] 795 List objects, instances, resources 796 797 798 799 800.. _lwm2m_api_reference: 801 802API Reference 803************* 804 805.. doxygengroup:: lwm2m_api 806 807.. _LwM2M: 808 https://www.openmobilealliance.org/specifications/lwm2m 809 810.. _OMA LwM2M registries: 811 https://www.openmobilealliance.org/specifications/registries 812 813.. _OMA LwM2M releases: 814 https://www.openmobilealliance.org/specifications/lwm2m/releases 815 816.. _LwM2M specification 1.0.2: 817 https://www.openmobilealliance.org/release/LightweightM2M/V1_0_2-20180209-A/OMA-TS-LightweightM2M-V1_0_2-20180209-A.pdf 818 819.. _LwM2M specification 1.1.1: 820 https://www.openmobilealliance.org/release/LightweightM2M/V1_1_1-20190617-A/ 821
