1.. _mcumgr_smp_group_8: 2 3File management 4############### 5 6The file management group provides commands that allow to upload and download files 7to/from a device. 8 9File management group defines following commands: 10 11.. table:: 12 :align: center 13 14 +-------------------+-----------------------------------------------+ 15 | ``Command ID`` | Command description | 16 +===================+===============================================+ 17 | ``0`` | File download/upload | 18 +-------------------+-----------------------------------------------+ 19 | ``1`` | File status | 20 +-------------------+-----------------------------------------------+ 21 | ``2`` | File hash/checksum | 22 +-------------------+-----------------------------------------------+ 23 | ``3`` | Supported file hash/checksum types | 24 +-------------------+-----------------------------------------------+ 25 | ``4`` | File close | 26 +-------------------+-----------------------------------------------+ 27 28File download 29************* 30 31Command allows to download contents of an existing file from specified path 32of a target device. Client applications must keep track of data they have 33already downloaded and where their position in the file is (MCUmgr will cache 34these also), and issue subsequent requests, with modified offset, to gather 35the entire file. 36Request does not carry size of requested chunk, the size is specified 37by application itself. 38Note that file handles will remain open for consecutive requests (as long as 39an idle timeout has not been reached and another transport does not make use 40of uploading/downloading files using fs_mgmt), but files are not exclusively 41owned by MCUmgr, for the time of download session, and may change between 42requests or even be removed. 43 44.. note:: 45 46 By default, all file upload/download requests are unconditionally allowed. 47 However, if the Kconfig option 48 :kconfig:option:`CONFIG_MCUMGR_GRP_FS_FILE_ACCESS_HOOK` is enabled, then an 49 application can register a callback handler for 50 :c:enum:`MGMT_EVT_OP_FS_MGMT_FILE_ACCESS` (see 51 :ref:`MCUmgr callbacks <mcumgr_callbacks>`), which allows for allowing or 52 declining access to reading/writing a particular file, or for rewriting the 53 path supplied by the client. 54 55File download request 56===================== 57 58File download request header: 59 60.. table:: 61 :align: center 62 63 +--------+--------------+----------------+ 64 | ``OP`` | ``Group ID`` | ``Command ID`` | 65 +========+==============+================+ 66 | ``0`` | ``8`` | ``0`` | 67 +--------+--------------+----------------+ 68 69CBOR data of request: 70 71.. code-block:: none 72 73 { 74 (str)"off" : (uint) 75 (str)"name" : (str) 76 } 77 78where: 79 80.. table:: 81 :align: center 82 83 +-----------------------+---------------------------------------------------+ 84 | "off" | offset to start download at | 85 +-----------------------+---------------------------------------------------+ 86 | "name" | absolute path to a file | 87 +-----------------------+---------------------------------------------------+ 88 89File download response 90====================== 91 92File download response header: 93 94.. table:: 95 :align: center 96 97 +--------+--------------+----------------+ 98 | ``OP`` | ``Group ID`` | ``Command ID`` | 99 +========+==============+================+ 100 | ``1`` | ``8`` | ``0`` | 101 +--------+--------------+----------------+ 102 103CBOR data of successful response: 104 105.. code-block:: none 106 107 { 108 (str)"off" : (uint) 109 (str)"data" : (byte str) 110 (str,opt)"len" : (uint) 111 } 112 113In case of error the CBOR data takes the form: 114 115.. tabs:: 116 117 .. group-tab:: SMP version 2 118 119 .. code-block:: none 120 121 { 122 (str)"err" : { 123 (str)"group" : (uint) 124 (str)"rc" : (uint) 125 } 126 } 127 128 .. group-tab:: SMP version 1 (and non-group SMP version 2) 129 130 .. code-block:: none 131 132 { 133 (str)"rc" : (int) 134 } 135 136where: 137 138.. table:: 139 :align: center 140 141 +------------------+-------------------------------------------------------------------------+ 142 | "off" | offset the response is for. | 143 +------------------+-------------------------------------------------------------------------+ 144 | "data" | chunk of data read from file; it is CBOR encoded stream of bytes with | 145 | | embedded size; "data" appears only in responses where "rc" is 0. | 146 +------------------+-------------------------------------------------------------------------+ 147 | "len" | length of file, this field is only mandatory when "off" is 0. | 148 +------------------+-------------------------------------------------------------------------+ 149 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 150 | | appears if an error is returned when using SMP version 2. | 151 +------------------+-------------------------------------------------------------------------+ 152 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 153 | | non-zero (error condition) when using SMP version 2. | 154 +------------------+-------------------------------------------------------------------------+ 155 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 156 | | using SMP version 1 or for SMP errors when using SMP version 2. | 157 +------------------+-------------------------------------------------------------------------+ 158 159File upload 160*********** 161 162Allows to upload a file to a specified location. Command will automatically overwrite 163existing file or create a new one if it does not exist at specified path. 164The protocol supports stateless upload where each requests carries different chunk 165of a file and it is client side responsibility to track progress of upload. 166 167Note that file handles will remain open for consecutive requests (as long as 168an idle timeout has not been reached, but files are not exclusively owned by 169MCUmgr, for the time of download session, and may change between requests or 170even be removed. Note that file handles will remain open for consecutive 171requests (as long as an idle timeout has not been reached and another transport 172does not make use of uploading/downloading files using fs_mgmt), but files are 173not exclusively owned by MCUmgr, for the time of download session, and may 174change between requests or even be removed. 175 176.. note:: 177 Weirdly, the current Zephyr implementation is half-stateless as is able to hold 178 single upload context, holding information on ongoing upload, that consists 179 of bool flag indicating in-progress upload, last successfully uploaded offset 180 and total length only. 181 182.. note:: 183 184 By default, all file upload/download requests are unconditionally allowed. 185 However, if the Kconfig option 186 :kconfig:option:`CONFIG_MCUMGR_GRP_FS_FILE_ACCESS_HOOK` is enabled, then an 187 application can register a callback handler for 188 :c:enum:`MGMT_EVT_OP_FS_MGMT_FILE_ACCESS` (see 189 :ref:`MCUmgr callbacks <mcumgr_callbacks>`), which allows for allowing or 190 declining access to reading/writing a particular file, or for rewriting the 191 path supplied by the client. 192 193File upload request 194=================== 195 196File upload request header: 197 198.. table:: 199 :align: center 200 201 +--------+--------------+----------------+ 202 | ``OP`` | ``Group ID`` | ``Command ID`` | 203 +========+==============+================+ 204 | ``2`` | ``8`` | ``0`` | 205 +--------+--------------+----------------+ 206 207CBOR data of request: 208 209.. code-block:: none 210 211 { 212 (str)"off" : (uint) 213 (str)"data" : (str) 214 (str)"name" : (str) 215 (str,opt)"len" : (uint) 216 } 217 218where: 219 220.. table:: 221 :align: center 222 223 +-----------------------+---------------------------------------------------+ 224 | "off" | offset to start/continue upload at. | 225 +-----------------------+---------------------------------------------------+ 226 | "data" | chunk of data to write to the file; | 227 | | it is CBOR encoded with length embedded. | 228 +-----------------------+---------------------------------------------------+ 229 | "name" | absolute path to a file. | 230 +-----------------------+---------------------------------------------------+ 231 | "len" | length of file, this field is only mandatory | 232 | | when "off" is 0. | 233 +-----------------------+---------------------------------------------------+ 234 235File upload response 236==================== 237 238File upload response header: 239 240.. table:: 241 :align: center 242 243 +--------+--------------+----------------+ 244 | ``OP`` | ``Group ID`` | ``Command ID`` | 245 +========+==============+================+ 246 | ``3`` | ``8`` | ``0`` | 247 +--------+--------------+----------------+ 248 249CBOR data of successful response: 250 251.. code-block:: none 252 253 { 254 (str)"off" : (uint) 255 } 256 257In case of error the CBOR data takes the form: 258 259.. .. tabs:: 260 261 .. group-tab:: SMP version 2 262 263 .. code-block:: none 264 265 { 266 (str)"err" : { 267 (str)"group" : (uint) 268 (str)"rc" : (uint) 269 } 270 } 271 272 .. group-tab:: SMP version 1 (and non-group SMP version 2) 273 274 .. code-block:: none 275 276 { 277 (str)"rc" : (int) 278 } 279 280where: 281 282.. table:: 283 :align: center 284 285 +------------------+-------------------------------------------------------------------------+ 286 | "off" | offset of last successfully written data. | 287 +------------------+-------------------------------------------------------------------------+ 288 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 289 | | appears if an error is returned when using SMP version 2. | 290 +------------------+-------------------------------------------------------------------------+ 291 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 292 | | non-zero (error condition) when using SMP version 2. | 293 +------------------+-------------------------------------------------------------------------+ 294 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 295 | | using SMP version 1 or for SMP errors when using SMP version 2. | 296 +------------------+-------------------------------------------------------------------------+ 297 298File status 299*********** 300 301Command allows to retrieve status of an existing file from specified path 302of a target device. 303 304File status request 305=================== 306 307File status request header: 308 309.. table:: 310 :align: center 311 312 +--------+--------------+----------------+ 313 | ``OP`` | ``Group ID`` | ``Command ID`` | 314 +========+==============+================+ 315 | ``0`` | ``8`` | ``1`` | 316 +--------+--------------+----------------+ 317 318CBOR data of request: 319 320.. code-block:: none 321 322 { 323 (str)"name" : (str) 324 } 325 326where: 327 328.. table:: 329 :align: center 330 331 +-----------------------+---------------------------------------------------+ 332 | "name" | absolute path to a file. | 333 +-----------------------+---------------------------------------------------+ 334 335File status response 336==================== 337 338File status response header: 339 340.. table:: 341 :align: center 342 343 +--------+--------------+----------------+ 344 | ``OP`` | ``Group ID`` | ``Command ID`` | 345 +========+==============+================+ 346 | ``1`` | ``8`` | ``1`` | 347 +--------+--------------+----------------+ 348 349CBOR data of successful response: 350 351.. code-block:: none 352 353 { 354 (str)"len" : (uint) 355 } 356 357In case of error the CBOR data takes form: 358 359.. tabs:: 360 361 .. group-tab:: SMP version 2 362 363 .. code-block:: none 364 365 { 366 (str)"err" : { 367 (str)"group" : (uint) 368 (str)"rc" : (uint) 369 } 370 } 371 372 .. group-tab:: SMP version 1 (and non-group SMP version 2) 373 374 .. code-block:: none 375 376 { 377 (str)"rc" : (int) 378 } 379 380where: 381 382.. table:: 383 :align: center 384 385 +------------------+-------------------------------------------------------------------------+ 386 | "len" | length of file (in bytes). | 387 +------------------+-------------------------------------------------------------------------+ 388 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 389 | | appears if an error is returned when using SMP version 2. | 390 +------------------+-------------------------------------------------------------------------+ 391 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 392 | | non-zero (error condition) when using SMP version 2. | 393 +------------------+-------------------------------------------------------------------------+ 394 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 395 | | using SMP version 1 or for SMP errors when using SMP version 2. | 396 +------------------+-------------------------------------------------------------------------+ 397 398File hash/checksum 399****************** 400 401Command allows to generate a hash/checksum of an existing file at a specified 402path on a target device. Note that kernel heap memory is required for buffers to 403be allocated for this to function, and large stack memory buffers are required 404for generation of the output hash/checksum. 405Requires :kconfig:option:`CONFIG_MCUMGR_GRP_FS_CHECKSUM_HASH` to be enabled for 406the base functionality, supported hash/checksum are opt-in with 407:kconfig:option:`CONFIG_MCUMGR_GRP_FS_CHECKSUM_IEEE_CRC32` or 408:kconfig:option:`CONFIG_MCUMGR_GRP_FS_HASH_SHA256`. 409 410File hash/checksum request 411========================== 412 413File hash/checksum request header: 414 415.. table:: 416 :align: center 417 418 +--------+--------------+----------------+ 419 | ``OP`` | ``Group ID`` | ``Command ID`` | 420 +========+==============+================+ 421 | ``0`` | ``8`` | ``2`` | 422 +--------+--------------+----------------+ 423 424CBOR data of request: 425 426.. code-block:: none 427 428 { 429 (str)"name" : (str) 430 (str,opt)"type" : (str) 431 (str,opt)"off" : (uint) 432 (str,opt)"len" : (uint) 433 } 434 435where: 436 437.. table:: 438 :align: center 439 440 +-----------------------+---------------------------------------------------+ 441 | "name" | absolute path to a file. | 442 +-----------------------+---------------------------------------------------+ 443 | "type" | type of hash/checksum to perform | 444 | | :ref:`mcumgr_group_8_hash_checksum_types` or omit | 445 | | to use default. | 446 +-----------------------+---------------------------------------------------+ 447 | "off" | offset to start hash/checksum calculation at | 448 | | (optional, 0 if not provided). | 449 +-----------------------+---------------------------------------------------+ 450 | "len" | maximum length of data to read from file to | 451 | | generate hash/checksum with (optional, full file | 452 | | size if not provided). | 453 +-----------------------+---------------------------------------------------+ 454 455.. _mcumgr_group_8_hash_checksum_types: 456 457Hash/checksum types 458=================== 459 460.. table:: 461 :align: center 462 463 +-------------+--------------------------------------+-------------+--------------+ 464 | String name | Hash/checksum | Byte string | Size (bytes) | 465 +=============+======================================+=============+==============+ 466 | ``crc32`` | IEEE CRC32 checksum | No | 4 | 467 +-------------+--------------------------------------+-------------+--------------+ 468 | ``sha256`` | SHA256 (Secure Hash Algorithm) | Yes | 32 | 469 +-------------+--------------------------------------+-------------+--------------+ 470 471Note that the default type will be crc32 if it is enabled, or sha256 if crc32 is 472not enabled. 473 474File hash/checksum response 475=========================== 476 477File hash/checksum response header: 478 479.. table:: 480 :align: center 481 482 +--------+--------------+----------------+ 483 | ``OP`` | ``Group ID`` | ``Command ID`` | 484 +========+==============+================+ 485 | ``1`` | ``8`` | ``2`` | 486 +--------+--------------+----------------+ 487 488CBOR data of successful response: 489 490.. code-block:: none 491 492 { 493 (str)"type" : (str) 494 (str,opt)"off" : (uint) 495 (str)"len" : (uint) 496 (str)"output" : (uint or bstr) 497 } 498 499In case of error the CBOR data takes the form: 500 501.. tabs:: 502 503 .. group-tab:: SMP version 2 504 505 .. code-block:: none 506 507 { 508 (str)"err" : { 509 (str)"group" : (uint) 510 (str)"rc" : (uint) 511 } 512 } 513 514 .. group-tab:: SMP version 1 (and non-group SMP version 2) 515 516 .. code-block:: none 517 518 { 519 (str)"rc" : (int) 520 } 521 522where: 523 524.. table:: 525 :align: center 526 527 +------------------+-------------------------------------------------------------------------+ 528 | "type" | type of hash/checksum that was performed | 529 | | :ref:`mcumgr_group_8_hash_checksum_types`. | 530 +------------------+-------------------------------------------------------------------------+ 531 | "off" | offset that hash/checksum calculation started at (only present if not | 532 | | 0). | 533 +------------------+-------------------------------------------------------------------------+ 534 | "len" | length of input data used for hash/checksum generation (in bytes). | 535 +------------------+-------------------------------------------------------------------------+ 536 | "output" | output hash/checksum. | 537 +------------------+-------------------------------------------------------------------------+ 538 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 539 | | appears if an error is returned when using SMP version 2. | 540 +------------------+-------------------------------------------------------------------------+ 541 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 542 | | non-zero (error condition) when using SMP version 2. | 543 +------------------+-------------------------------------------------------------------------+ 544 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 545 | | using SMP version 1 or for SMP errors when using SMP version 2. | 546 +------------------+-------------------------------------------------------------------------+ 547 548Supported file hash/checksum types 549********************************** 550 551Command allows listing which hash and checksum types are available on a device. 552Requires Kconfig :kconfig:option:`CONFIG_MCUMGR_GRP_FS_CHECKSUM_HASH_SUPPORTED_CMD` 553to be enabled. 554 555Supported file hash/checksum types request 556========================================== 557 558Supported file hash/checksum types request header: 559 560.. table:: 561 :align: center 562 563 +--------+--------------+----------------+ 564 | ``OP`` | ``Group ID`` | ``Command ID`` | 565 +========+==============+================+ 566 | ``0`` | ``8`` | ``3`` | 567 +--------+--------------+----------------+ 568 569The command sends empty CBOR map as data. 570 571Supported file hash/checksum types response 572=========================================== 573 574Supported file hash/checksum types response header: 575 576.. table:: 577 :align: center 578 579 +--------+--------------+----------------+ 580 | ``OP`` | ``Group ID`` | ``Command ID`` | 581 +========+==============+================+ 582 | ``1`` | ``8`` | ``3`` | 583 +--------+--------------+----------------+ 584 585CBOR data of successful response: 586 587.. code-block:: none 588 589 { 590 (str)"types" : { 591 (str)<hash_checksum_name> : { 592 (str)"format" : (uint) 593 (str)"size" : (uint) 594 } 595 ... 596 } 597 } 598 599In case of error the CBOR data takes form: 600 601.. tabs:: 602 603 .. group-tab:: SMP version 2 604 605 .. code-block:: none 606 607 { 608 (str)"err" : { 609 (str)"group" : (uint) 610 (str)"rc" : (uint) 611 } 612 } 613 614 .. group-tab:: SMP version 1 (and non-group SMP version 2) 615 616 .. code-block:: none 617 618 { 619 (str)"rc" : (int) 620 } 621 622where: 623 624.. table:: 625 :align: center 626 627 +----------------------+-------------------------------------------------------------------------+ 628 | <hash_checksum_name> | name of the hash/checksum type | 629 | | :ref:`mcumgr_group_8_hash_checksum_types`. | 630 +----------------------+-------------------------------------------------------------------------+ 631 | "format" | format that the hash/checksum returns where 0 is for numerical and 1 is | 632 | | for byte array. | 633 +----------------------+-------------------------------------------------------------------------+ 634 | "size" | size (in bytes) of output hash/checksum response. | 635 +----------------------+-------------------------------------------------------------------------+ 636 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 637 | | appears if an error is returned when using SMP version 2. | 638 +----------------------+-------------------------------------------------------------------------+ 639 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 640 | | non-zero (error condition) when using SMP version 2. | 641 +----------------------+-------------------------------------------------------------------------+ 642 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 643 | | using SMP version 1 or for SMP errors when using SMP version 2. | 644 +----------------------+-------------------------------------------------------------------------+ 645 646File close 647********** 648 649Command allows closing any open file handles held by fs_mgmt upload/download 650requests that might have stalled or be incomplete. 651 652File close request 653================== 654 655File close request header: 656 657.. table:: 658 :align: center 659 660 +--------+--------------+----------------+ 661 | ``OP`` | ``Group ID`` | ``Command ID`` | 662 +========+==============+================+ 663 | ``2`` | ``8`` | ``4`` | 664 +--------+--------------+----------------+ 665 666The command sends empty CBOR map as data. 667 668File close response 669=================== 670 671File close response header: 672 673.. table:: 674 :align: center 675 676 +--------+--------------+----------------+ 677 | ``OP`` | ``Group ID`` | ``Command ID`` | 678 +========+==============+================+ 679 | ``3`` | ``8`` | ``4`` | 680 +--------+--------------+----------------+ 681 682The command sends an empty CBOR map as data if successful. 683In case of error the CBOR data takes the form: 684 685.. tabs:: 686 687 .. group-tab:: SMP version 2 688 689 .. code-block:: none 690 691 { 692 (str)"err" : { 693 (str)"group" : (uint) 694 (str)"rc" : (uint) 695 } 696 } 697 698 .. group-tab:: SMP version 1 (and non-group SMP version 2) 699 700 .. code-block:: none 701 702 { 703 (str)"rc" : (int) 704 } 705 706where: 707 708.. table:: 709 :align: center 710 711 +------------------+-------------------------------------------------------------------------+ 712 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 713 | | appears if an error is returned when using SMP version 2. | 714 +------------------+-------------------------------------------------------------------------+ 715 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 716 | | non-zero (error condition) when using SMP version 2. | 717 +------------------+-------------------------------------------------------------------------+ 718 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 719 | | using SMP version 1 or for SMP errors when using SMP version 2. | 720 +------------------+-------------------------------------------------------------------------+ 721
