1.. _mcumgr_smp_group_1: 2 3Application/software image management group 4########################################### 5 6Application/software image management group defines following commands: 7 8.. table:: 9 :align: center 10 11 +-------------------+-----------------------------------------------+ 12 | ``Command ID`` | Command description | 13 +===================+===============================================+ 14 | ``0`` | State of images | 15 +-------------------+-----------------------------------------------+ 16 | ``1`` | Image upload | 17 +-------------------+-----------------------------------------------+ 18 | ``2`` | File | 19 | | (reserved but not supported by Zephyr) | 20 +-------------------+-----------------------------------------------+ 21 | ``3`` | Corelist | 22 | | (reserved but not supported by Zephyr) | 23 +-------------------+-----------------------------------------------+ 24 | ``4`` | Coreload | 25 | | (reserved but not supported by Zephyr) | 26 +-------------------+-----------------------------------------------+ 27 | ``5`` | Image erase | 28 +-------------------+-----------------------------------------------+ 29 | ``6`` | Slot info | 30 +-------------------+-----------------------------------------------+ 31 32Notion of "slots" and "images" in Zephyr 33**************************************** 34 35The "slot" and "image" definition comes from mcuboot where "image" would 36consist of two "slots", further named "primary" and "secondary"; the application 37is supposed to run from the "primary slot" and update is supposed to be 38uploaded to the "secondary slot"; the mcuboot is responsible in swapping 39slots on boot. 40This means that pair of slots is dedicated to single upgradable application. 41In case of Zephyr this gets a little bit confusing because DTS will use 42"slot0_partition" and "slot1_partition", as label of ``fixed-partition`` dedicated 43to single application, but will name them as "image-0" and "image-1" respectively. 44 45Currently Zephyr supports at most two images, in which case mapping is as follows: 46 47.. table:: 48 :align: center 49 50 +-------------+-------------------+---------------+ 51 | Image | Slot labels | Slot Names | 52 +=============+===================+===============+ 53 | 1 | "slot0_partition" | "image-0" | 54 | | "slot1_partition" | "image-1" | 55 +-------------+-------------------+---------------+ 56 | 2 | "slot2_partition" | "image-2" | 57 | | "slot3_partition" | "image-3" | 58 +-------------+-------------------+---------------+ 59 60State of images 61*************** 62 63The command is used to set state of images and obtain list of images 64with their current state. 65 66Get state of images request 67=========================== 68 69Get state of images request header fields: 70 71.. table:: 72 :align: center 73 74 +--------+--------------+----------------+ 75 | ``OP`` | ``Group ID`` | ``Command ID`` | 76 +========+==============+================+ 77 | ``0`` | ``1`` | ``0`` | 78 +--------+--------------+----------------+ 79 80The command sends an empty CBOR map as data. 81 82.. _mcumgr_smp_protocol_op_1_grp_1_cmd_0: 83 84Get state of images response 85============================ 86 87Get state of images response header fields: 88 89.. table:: 90 :align: center 91 92 +--------+--------------+----------------+ 93 | ``OP`` | ``Group ID`` | ``Command ID`` | 94 +========+==============+================+ 95 | ``1`` | ``1`` | ``0`` | 96 +--------+--------------+----------------+ 97 98.. note:: 99 Below definition of the response contains "image" field that has been marked 100 as optional(opt): the field may not appear in response when target application 101 does not support more than one image. The field is mandatory when application 102 supports more than one application image to allow identifying which image 103 information is listed. 104 105A response will only contain information for valid images, if an image can not 106be identified as valid it is simply skipped. 107 108CBOR data of successful response: 109 110.. code-block:: none 111 112 { 113 (str)"images" : [ 114 { 115 (str,opt)"image" : (uint) 116 (str)"slot" : (uint) 117 (str)"version" : (str) 118 (str,opt*)"hash" : (byte str) 119 (str,opt)"bootable" : (bool) 120 (str,opt)"pending" : (bool) 121 (str,opt)"confirmed" : (bool) 122 (str,opt)"active" : (bool) 123 (str,opt)"permanent" : (bool) 124 } 125 ... 126 ] 127 (str,opt)"splitStatus" : (int) 128 } 129 130In case of error the CBOR data takes the form: 131 132.. tabs:: 133 134 .. group-tab:: SMP version 2 135 136 .. code-block:: none 137 138 { 139 (str)"err" : { 140 (str)"group" : (uint) 141 (str)"rc" : (uint) 142 } 143 } 144 145 .. group-tab:: SMP version 1 (and non-group SMP version 2) 146 147 .. code-block:: none 148 149 { 150 (str)"rc" : (int) 151 (str,opt)"rsn" : (str) 152 } 153 154where: 155 156.. table:: 157 :align: center 158 159 +------------------+-------------------------------------------------------------------------+ 160 | "image" | semi-optional image number; the field is not required when only one | 161 | | image is supported by the running application. | 162 +------------------+-------------------------------------------------------------------------+ 163 | "slot" | slot number within "image"; each image has two slots : primary (running | 164 | | one) = 0 and secondary (for DFU dual-bank purposes) = 1. | 165 +------------------+-------------------------------------------------------------------------+ 166 | "version" | string representing image version, as set with ``imgtool``. | 167 +------------------+-------------------------------------------------------------------------+ 168 | "hash" | SHA256 hash of the image header and body. Note that this will not be | 169 | | the same as the SHA256 of the whole file, it is the field in the | 170 | | MCUboot TLV section that contains a hash of the data which is used for | 171 | | signature verification purposes. This field is optional but only | 172 | | optional when using MCUboot's serial recovery feature with one pair of | 173 | | image slots, Kconfig :kconfig:option:`CONFIG_BOOT_SERIAL_IMG_GRP_HASH` | 174 | | can be disabled to remove support for hashes in this configuration. | 175 | | MCUmgr in applications must support sending hashes. | 176 | | | 177 | | .. note:: | 178 | | See ``IMAGE_TLV_SHA256`` in the MCUboot image format documentation | 179 | | link below. | 180 +------------------+-------------------------------------------------------------------------+ 181 | "bootable" | true if image has bootable flag set; this field does not have to be | 182 | | present if false. | 183 +------------------+-------------------------------------------------------------------------+ 184 | "pending" | true if image is set for next swap; this field does not have to be | 185 | | present if false. | 186 +------------------+-------------------------------------------------------------------------+ 187 | "confirmed" | true if image has been confirmed; this field does not have to be | 188 | | present if false. | 189 +------------------+-------------------------------------------------------------------------+ 190 | "active" | true if image is currently active application; this field does not have | 191 | | to be present if false. | 192 +------------------+-------------------------------------------------------------------------+ 193 | "permanent" | true if image is to stay in primary slot after the next boot; this | 194 | | does not have to be present if false. | 195 +------------------+-------------------------------------------------------------------------+ 196 | "splitStatus" | states whether loader of split image is compatible with application | 197 | | part; this is unused by Zephyr. | 198 +------------------+-------------------------------------------------------------------------+ 199 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 200 | | appears if an error is returned when using SMP version 2. | 201 +------------------+-------------------------------------------------------------------------+ 202 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 203 | | non-zero (error condition) when using SMP version 2. | 204 +------------------+-------------------------------------------------------------------------+ 205 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 206 | | using SMP version 1 or for SMP errors when using SMP version 2. | 207 +------------------+-------------------------------------------------------------------------+ 208 | "rsn" | optional string that clarifies reason for an error; specifically useful | 209 | | when ``rc`` is :c:enumerator:`MGMT_ERR_EUNKNOWN`. | 210 +------------------+-------------------------------------------------------------------------+ 211 212.. note:: 213 For more information on how does image/slots function, please refer to 214 the MCUBoot documentation 215 https://docs.mcuboot.com/design.html#image-slots 216 For information on MCUboot image format, please reset to the MCUboot 217 documentation https://docs.mcuboot.com/design.html#image-format 218 219 220Set state of image request 221========================== 222 223Set state of image request header fields: 224 225.. table:: 226 :align: center 227 228 +--------+--------------+----------------+ 229 | ``OP`` | ``Group ID`` | ``Command ID`` | 230 +========+==============+================+ 231 | ``2`` | ``1`` | ``0`` | 232 +--------+--------------+----------------+ 233 234CBOR data of request: 235 236.. code-block:: none 237 238 { 239 (str,opt)"hash" : (str) 240 (str)"confirm" : (bool) 241 } 242 243If "confirm" is false or not provided, an image with the "hash" will be set for 244test, which means that it will not be marked as permanent and upon hard reset 245the previous application will be restored to the primary slot. 246In case when "confirm" is true, the "hash" is optional as the currently running 247application will be assumed as target for confirmation. 248 249Set state of image response 250============================ 251 252The response takes the same format as :ref:`mcumgr_smp_protocol_op_1_grp_1_cmd_0` 253 254Image upload 255************ 256 257The image upload command allows to update application image. 258 259Image upload request 260==================== 261 262The image upload request is sent for each chunk of image that is uploaded, until 263complete image gets uploaded to a device. 264 265Image upload request header fields: 266 267.. table:: 268 :align: center 269 270 +--------+--------------+----------------+ 271 | ``OP`` | ``Group ID`` | ``Command ID`` | 272 +========+==============+================+ 273 | ``2`` | ``1`` | ``1`` | 274 +--------+--------------+----------------+ 275 276CBOR data of request: 277 278.. code-block:: none 279 280 { 281 (str,opt)"image" : (uint) 282 (str,opt)"len" : (uint) 283 (str)"off" : (uint) 284 (str,opt)"sha" : (byte str) 285 (str)"data" : (byte str) 286 (str,opt)"upgrade" : (bool) 287 } 288 289where: 290 291.. table:: 292 :align: center 293 294 +-----------+--------------------------------------------------------------------------------+ 295 | "image" | optional image number, it does not have to appear in request at all, in which | 296 | | case it is assumed to be 0. Should only be present when "off" is 0. | 297 +-----------+--------------------------------------------------------------------------------+ 298 | "len" | optional length of an image. Must appear when "off" is 0. | 299 +-----------+--------------------------------------------------------------------------------+ 300 | "off" | offset of image chunk the request carries. | 301 +-----------+--------------------------------------------------------------------------------+ 302 | "sha" | SHA256 hash of an upload; this is used to identify an upload session (e.g. to | 303 | | allow MCUmgr to continue a broken session), and for image verification | 304 | | purposes. This must be a full SHA256 hash of the whole image being uploaded, | 305 | | or not included if the hash is not available (in which case, upload session | 306 | | continuation and image verification functionality will be unavailable). Should | 307 | | only be present when "off" is 0. | 308 +-----------+--------------------------------------------------------------------------------+ 309 | "data" | image data to write at provided offset. | 310 +-----------+--------------------------------------------------------------------------------+ 311 | "upgrade" | optional flag that states that only upgrade should be allowed, so if the | 312 | | version of uploaded software is not higher then already on a device, the image | 313 | | upload will be rejected. Zephyr compares major, minor and revision (x.y.z) by | 314 | | default unless | 315 | | :kconfig:option:`CONFIG_MCUMGR_GRP_IMG_VERSION_CMP_USE_BUILD_NUMBER` is set, | 316 | | whereby it will compare build numbers too. Should only be present when "off" | 317 | | is 0. | 318 +-----------+--------------------------------------------------------------------------------+ 319 320.. note:: 321 There is no field representing size of chunk that is carried as "data" because 322 that information is embedded within "data" field itself. 323 324.. note:: 325 It is possible that a server will respond to an upload with "off" of 0, this 326 may happen if an upload on another transport (or outside of MCUmgr entirely) 327 is started, if the device has rebooted or if a packet has been lost. If this 328 happens, a client must re-send all the required and optional fields that it 329 sent in the original first packet so that the upload state can be re-created 330 by the server. If the original fields are not included, the upload will be 331 unable to continue. 332 333The MCUmgr library uses "sha" field to tag ongoing update session, to be able 334to continue it in case when it gets broken, and for upload verification 335purposes. 336If library gets request with "off" equal zero it checks stored "sha" within its 337state and if it matches it will respond to update client application with 338offset that it should continue with. 339If this hash is not available (e.g. because a file is being streamed) then it 340must not be provided, image verification and upload session continuation 341features will be unavailable in this case. 342 343Image upload response 344===================== 345 346Image upload response header fields: 347 348.. table:: 349 :align: center 350 351 +--------+--------------+----------------+ 352 | ``OP`` | ``Group ID`` | ``Command ID`` | 353 +========+==============+================+ 354 | ``3`` | ``1`` | ``1`` | 355 +--------+--------------+----------------+ 356 357CBOR data of successful response: 358 359.. code-block:: none 360 361 { 362 (str,opt)"off" : (uint) 363 (str,opt)"match" : (bool) 364 } 365 366In case of error the CBOR data takes the form: 367 368.. tabs:: 369 370 .. group-tab:: SMP version 2 371 372 .. code-block:: none 373 374 { 375 (str)"err" : { 376 (str)"group" : (uint) 377 (str)"rc" : (uint) 378 } 379 } 380 381 .. group-tab:: SMP version 1 (and non-group SMP version 2) 382 383 .. code-block:: none 384 385 { 386 (str)"rc" : (int) 387 (str,opt)"rsn" : (str) 388 } 389 390where: 391 392.. table:: 393 :align: center 394 395 +------------------+-------------------------------------------------------------------------+ 396 | "off" | offset of last successfully written byte of update. | 397 +------------------+-------------------------------------------------------------------------+ 398 | "match" | indicates if the uploaded data successfully matches the provided SHA256 | 399 | | hash or not, only sent in the final packet if | 400 | | :kconfig:option:`CONFIG_IMG_ENABLE_IMAGE_CHECK` is enabled. | 401 +------------------+-------------------------------------------------------------------------+ 402 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 403 | | appears if an error is returned when using SMP version 2. | 404 +------------------+-------------------------------------------------------------------------+ 405 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 406 | | non-zero (error condition) when using SMP version 2. | 407 +------------------+-------------------------------------------------------------------------+ 408 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 409 | | using SMP version 1 or for SMP errors when using SMP version 2. | 410 +------------------+-------------------------------------------------------------------------+ 411 | "rsn" | optional string that clarifies reason for an error; specifically useful | 412 | | when ``rc`` is :c:enumerator:`MGMT_ERR_EUNKNOWN`. | 413 +------------------+-------------------------------------------------------------------------+ 414 415The "off" field is only included in responses to successfully processed requests; 416if "rc" is negative then "off" may not appear. 417 418Image erase 419*********** 420 421The command is used for erasing image slot on a target device. 422 423.. note:: 424 This is synchronous command which means that a sender of request will not 425 receive response until the command completes, which can take a long time. 426 427Image erase request 428=================== 429 430Image erase request header fields: 431 432.. table:: 433 :align: center 434 435 +--------+--------------+----------------+ 436 | ``OP`` | ``Group ID`` | ``Command ID`` | 437 +========+==============+================+ 438 | ``2`` | ``1`` | ``5`` | 439 +--------+--------------+----------------+ 440 441CBOR data of request: 442 443.. code-block:: none 444 445 { 446 (str,opt)"slot" : (uint) 447 } 448 449where: 450 451.. table:: 452 :align: center 453 454 +---------+-----------------------------------------------------------------+ 455 | "slot" | optional slot number, it does not have to appear in the request | 456 | | at all, in which case it is assumed to be 1. | 457 +---------+-----------------------------------------------------------------+ 458 459Image erase response 460==================== 461 462Image erase response header fields: 463 464.. table:: 465 :align: center 466 467 +--------+--------------+----------------+ 468 | ``OP`` | ``Group ID`` | ``Command ID`` | 469 +========+==============+================+ 470 | ``3`` | ``1`` | ``5`` | 471 +--------+--------------+----------------+ 472 473The command sends an empty CBOR map as data if successful. In case of error the 474CBOR data takes the form: 475 476.. tabs:: 477 478 .. group-tab:: SMP version 2 479 480 .. code-block:: none 481 482 { 483 (str)"err" : { 484 (str)"group" : (uint) 485 (str)"rc" : (uint) 486 } 487 } 488 489 .. group-tab:: SMP version 1 (and non-group SMP version 2) 490 491 .. code-block:: none 492 493 { 494 (str)"rc" : (int) 495 (str,opt)"rsn" : (str) 496 } 497 498where: 499 500.. table:: 501 :align: center 502 503 +------------------+-------------------------------------------------------------------------+ 504 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 505 | | appears if an error is returned when using SMP version 2. | 506 +------------------+-------------------------------------------------------------------------+ 507 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 508 | | non-zero (error condition) when using SMP version 2. | 509 +------------------+-------------------------------------------------------------------------+ 510 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 511 | | using SMP version 1 or for SMP errors when using SMP version 2. | 512 +------------------+-------------------------------------------------------------------------+ 513 | "rsn" | optional string that clarifies reason for an error; specifically useful | 514 | | when ``rc`` is :c:enumerator:`MGMT_ERR_EUNKNOWN`. | 515 +------------------+-------------------------------------------------------------------------+ 516 517.. note:: 518 Response from Zephyr running device may have "rc" value of 519 :c:enumerator:`MGMT_ERR_EBADSTATE`, which means that the secondary 520 image has been marked for next boot already and may not be erased. 521 522Slot info 523********* 524 525The command is used for fetching information on slots that are available. This command can be 526enabled with :kconfig:option:`CONFIG_MCUMGR_GRP_IMG_SLOT_INFO`. 527 528Slot info request 529================= 530 531Slot info request header fields: 532 533.. table:: 534 :align: center 535 536 +--------+--------------+----------------+ 537 | ``OP`` | ``Group ID`` | ``Command ID`` | 538 +========+==============+================+ 539 | ``0`` | ``1`` | ``6`` | 540 +--------+--------------+----------------+ 541 542The command sends an empty CBOR map as data. 543 544Slot info response 545================== 546 547Slot info response header fields: 548 549.. table:: 550 :align: center 551 552 +--------+--------------+----------------+ 553 | ``OP`` | ``Group ID`` | ``Command ID`` | 554 +========+==============+================+ 555 | ``1`` | ``1`` | ``6`` | 556 +--------+--------------+----------------+ 557 558CBOR data of successful response: 559 560.. code-block:: none 561 562 { 563 (str)"images" : [ 564 { 565 (str)"image" : (uint) 566 (str)"slots" : [ 567 { 568 (str)"slot" : (uint) 569 (str)"size" : (uint) 570 (str,opt)"upload_image_id" : (uint) 571 } 572 ... 573 ] 574 (str,opt)"max_image_size" : (uint) 575 } 576 ... 577 ] 578 } 579 580In case of error the CBOR data takes the form: 581 582.. tabs:: 583 584 .. group-tab:: SMP version 2 585 586 .. code-block:: none 587 588 { 589 (str)"err" : { 590 (str)"group" : (uint) 591 (str)"rc" : (uint) 592 } 593 } 594 595 .. group-tab:: SMP version 1 (and non-group SMP version 2) 596 597 .. code-block:: none 598 599 { 600 (str)"rc" : (int) 601 } 602 603where: 604 605.. table:: 606 :align: center 607 608 +-------------------+--------------------------------------------------------------------------------------------+ 609 | "image" | the image number being enumerated. | 610 +-------------------+--------------------------------------------------------------------------------------------+ 611 | "slot" | the slot inside the image being enumerated (note: this will be 0 or 1, it is the slot of | 612 | | the image not the physical slot number). | 613 +-------------------+--------------------------------------------------------------------------------------------+ 614 | "size" | the size of the slot. | 615 +-------------------+--------------------------------------------------------------------------------------------+ 616 | "upload_image_id" | optional field (only present if :kconfig:option:`CONFIG_MCUMGR_GRP_IMG_DIRECT_UPLOAD` is | 617 | | enabled to allow direct image uploads) which specifies the image ID that can be used by | 618 | | external tools to upload an image to that slot. | 619 +-------------------+--------------------------------------------------------------------------------------------+ 620 | "max_image_size" | optional field (only present if :kconfig:option:`CONFIG_MCUMGR_GRP_IMG_TOO_LARGE_SYSBUILD` | 621 | | or :kconfig:option:`CONFIG_MCUMGR_GRP_IMG_TOO_LARGE_BOOTLOADER_INFO` are enabled) which | 622 | | specifies the maximum size of an application that can be uploaded to that image number. | 623 +-------------------+--------------------------------------------------------------------------------------------+ 624 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only appears if an error is | 625 | | returned when using SMP version 2. | 626 +-------------------+--------------------------------------------------------------------------------------------+ 627 | "err" -> "rc" | contains the index of the group-based error code. Only appears ifnon-zero (error | 628 | | condition) when using SMP version 2. | 629 +-------------------+--------------------------------------------------------------------------------------------+ 630 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when using SMP version 1 | 631 | | or for SMP errors when using SMP version 2. | 632 +-------------------+--------------------------------------------------------------------------------------------+ 633
