1.. _mcumgr_smp_group_0: 2 3Default/OS Management Group 4########################### 5 6OS management group defines following commands: 7 8.. table:: 9 :align: center 10 11 +-------------------+-----------------------------------------------+ 12 | ``Command ID`` | Command description | 13 +===================+===============================================+ 14 | ``0`` | Echo | 15 +-------------------+-----------------------------------------------+ 16 | ``1`` | Console/Terminal echo control; | 17 | | unimplemented by Zephyr | 18 +-------------------+-----------------------------------------------+ 19 | ``2`` | Task Statistics | 20 +-------------------+-----------------------------------------------+ 21 | ``3`` | Memory pool statistics | 22 +-------------------+-----------------------------------------------+ 23 | ``4`` | Date-time string; unimplemented by Zephyr | 24 +-------------------+-----------------------------------------------+ 25 | ``5`` | System reset | 26 +-------------------+-----------------------------------------------+ 27 | ``6`` | MCUMGR parameters | 28 +-------------------+-----------------------------------------------+ 29 | ``7`` | OS/Application info | 30 +-------------------+-----------------------------------------------+ 31 | ``8`` | Bootloader information | 32 +-------------------+-----------------------------------------------+ 33 34Echo command 35************ 36 37Echo command responses by sending back string that it has received. 38 39Echo request 40============ 41 42Echo request header fields: 43 44.. table:: 45 :align: center 46 47 +--------------------+--------------+----------------+ 48 | ``OP`` | ``Group ID`` | ``Command ID`` | 49 +====================+==============+================+ 50 | ``0`` or ``2`` | ``0`` | ``0`` | 51 +--------------------+--------------+----------------+ 52 53CBOR data of request: 54 55.. code-block:: none 56 57 { 58 (str)"d" : (str) 59 } 60 61where: 62 63.. table:: 64 :align: center 65 66 +-----------------------+---------------------------------------------------+ 67 | "d" | string to be replied by echo service. | 68 +-----------------------+---------------------------------------------------+ 69 70Echo response 71============= 72 73Echo response header fields: 74 75.. table:: 76 :align: center 77 78 +--------+--------------+----------------+----------------------------------+ 79 | ``OP`` | ``Group ID`` | ``Command ID`` | Note | 80 +========+==============+================+==================================+ 81 | ``1`` | ``0`` | ``0`` | When request ``OP`` was ``0`` | 82 +--------+--------------+----------------+----------------------------------+ 83 | ``3`` | ``0`` | ``0`` | When request ``OP`` was ``2`` | 84 +--------+--------------+----------------+----------------------------------+ 85 86CBOR data of successful response: 87 88.. code-block:: none 89 90 { 91 (str)"r" : (str) 92 } 93 94In case of error the CBOR data takes the form: 95 96.. tabs:: 97 98 .. group-tab:: SMP version 2 99 100 .. code-block:: none 101 102 { 103 (str)"err" : { 104 (str)"group" : (uint) 105 (str)"rc" : (uint) 106 } 107 } 108 109 .. group-tab:: SMP version 1 (and non-group SMP version 2) 110 111 .. code-block:: none 112 113 { 114 (str)"rc" : (int) 115 } 116 117where: 118 119.. table:: 120 :align: center 121 122 +------------------+-------------------------------------------------------------------------+ 123 | "r" | replying echo string. | 124 +------------------+-------------------------------------------------------------------------+ 125 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 126 | | appears if an error is returned when using SMP version 2. | 127 +------------------+-------------------------------------------------------------------------+ 128 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 129 | | non-zero (error condition) when using SMP version 2. | 130 +------------------+-------------------------------------------------------------------------+ 131 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 132 | | using SMP version 1 or for SMP errors when using SMP version 2. | 133 +------------------+-------------------------------------------------------------------------+ 134 135Task statistics command 136*********************** 137 138The command responds with some system statistics. 139 140Task statistics request 141======================= 142 143Task statistics request header fields: 144 145.. table:: 146 :align: center 147 148 +--------+--------------+----------------+ 149 | ``OP`` | ``Group ID`` | ``Command ID`` | 150 +========+==============+================+ 151 | ``0`` | ``0`` | ``2`` | 152 +--------+--------------+----------------+ 153 154The command sends an empty CBOR map as data. 155 156 157Task statistics response 158======================== 159 160Task statistics response header fields: 161 162.. table:: 163 :align: center 164 165 +--------+--------------+----------------+ 166 | ``OP`` | ``Group ID`` | ``Command ID`` | 167 +========+==============+================+ 168 | ``1`` | ``0`` | ``2`` | 169 +--------+--------------+----------------+ 170 171CBOR data of successful response: 172 173.. code-block:: none 174 175 { 176 (str)"tasks" : { 177 (str)<task_name> : { 178 (str)"prio" : (uint) 179 (str)"tid" : (uint) 180 (str)"state" : (uint) 181 (str)"stkuse" : (uint) 182 (str)"stksiz" : (uint) 183 (str)"cswcnt" : (uint) 184 (str)"runtime" : (uint) 185 (str)"last_checkin" : (uint) 186 (str)"next_checkin" : (uint) 187 } 188 ... 189 } 190 } 191 192In case of error the CBOR data takes the form: 193 194.. tabs:: 195 196 .. group-tab:: SMP version 2 197 198 .. code-block:: none 199 200 { 201 (str)"err" : { 202 (str)"group" : (uint) 203 (str)"rc" : (uint) 204 } 205 } 206 207 .. group-tab:: SMP version 1 (and non-group SMP version 2) 208 209 .. code-block:: none 210 211 { 212 (str)"rc" : (int) 213 } 214 215where: 216 217.. table:: 218 :align: center 219 220 +------------------+-------------------------------------------------------------------------+ 221 | <task_name> | string identifying task. | 222 +------------------+-------------------------------------------------------------------------+ 223 | "prio" | task priority. | 224 +------------------+-------------------------------------------------------------------------+ 225 | "tid" | numeric task ID. | 226 +------------------+-------------------------------------------------------------------------+ 227 | "state" | numeric task state. | 228 +------------------+-------------------------------------------------------------------------+ 229 | "stkuse" | task's/thread's stack usage. | 230 +------------------+-------------------------------------------------------------------------+ 231 | "stksiz" | task's/thread's stack size. | 232 +------------------+-------------------------------------------------------------------------+ 233 | "cswcnt" | task's/thread's context switches. | 234 +------------------+-------------------------------------------------------------------------+ 235 | "runtime" | task's/thread's runtime in "ticks". | 236 +------------------+-------------------------------------------------------------------------+ 237 | "last_checkin" | set to 0 by Zephyr. | 238 +------------------+-------------------------------------------------------------------------+ 239 | "next_checkin" | set to 0 by Zephyr. | 240 +------------------+-------------------------------------------------------------------------+ 241 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 242 | | appears if an error is returned when using SMP version 2. | 243 +------------------+-------------------------------------------------------------------------+ 244 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 245 | | non-zero (error condition) when using SMP version 2. | 246 +------------------+-------------------------------------------------------------------------+ 247 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 248 | | using SMP version 1 or for SMP errors when using SMP version 2. | 249 +------------------+-------------------------------------------------------------------------+ 250 251.. note:: 252 The unit for "stkuse" and "stksiz" is system dependent and in case of Zephyr 253 this is number of 4 byte words. 254 255Memory pool statistics 256********************** 257 258The command is used to obtain information on memory pools active in running 259system. 260 261Memory pool statistic request 262============================= 263 264Memory pool statistics request header fields: 265 266.. table:: 267 :align: center 268 269 +--------+--------------+----------------+ 270 | ``OP`` | ``Group ID`` | ``Command ID`` | 271 +========+==============+================+ 272 | ``0`` | ``0`` | ``3`` | 273 +--------+--------------+----------------+ 274 275The command sends an empty CBOR map as data. 276 277Memory pool statistics response 278=============================== 279 280Memory pool statistics response header fields: 281 282.. table:: 283 :align: center 284 285 +--------+--------------+----------------+ 286 | ``OP`` | ``Group ID`` | ``Command ID`` | 287 +========+==============+================+ 288 | ``1`` | ``0`` | ``3`` | 289 +--------+--------------+----------------+ 290 291CBOR data of successful response: 292 293.. code-block:: none 294 295 { 296 (str)<pool_name> { 297 (str)"blksiz" : (int) 298 (str)"nblks" : (int) 299 (str)"nfree" : (int) 300 (str)"min' : (int) 301 } 302 ... 303 } 304 305In case of error the CBOR data takes the form: 306 307.. tabs:: 308 309 .. group-tab:: SMP version 2 310 311 .. code-block:: none 312 313 { 314 (str)"err" : { 315 (str)"group" : (uint) 316 (str)"rc" : (uint) 317 } 318 } 319 320 .. group-tab:: SMP version 1 (and non-group SMP version 2) 321 322 .. code-block:: none 323 324 { 325 (str)"rc" : (int) 326 } 327 328where: 329 330.. table:: 331 :align: center 332 333 +------------------+-------------------------------------------------------------------------+ 334 | <pool_name> | string representing the pool name, used as a key for dictionary with | 335 | | pool statistics data. | 336 +------------------+-------------------------------------------------------------------------+ 337 | "blksiz" | size of the memory block in the pool. | 338 +------------------+-------------------------------------------------------------------------+ 339 | "nblks" | number of blocks in the pool. | 340 +------------------+-------------------------------------------------------------------------+ 341 | "nfree" | number of free blocks. | 342 +------------------+-------------------------------------------------------------------------+ 343 | "min" | lowest number of free blocks the pool reached during run-time. | 344 +------------------+-------------------------------------------------------------------------+ 345 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 346 | | appears if an error is returned when using SMP version 2. | 347 +------------------+-------------------------------------------------------------------------+ 348 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 349 | | non-zero (error condition) when using SMP version 2. | 350 +------------------+-------------------------------------------------------------------------+ 351 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 352 | | using SMP version 1 or for SMP errors when using SMP version 2. | 353 +------------------+-------------------------------------------------------------------------+ 354 355Date-time command 356***************** 357 358The command allows to obtain string representing current time-date on a device 359or set a new time to a device. 360The time format used, by both set and get operations, is: 361 362 "yyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ" 363 364Date-time get 365============= 366 367The command allows to obtain date-time from a device. 368 369Date-time get request 370--------------------- 371 372Date-time request header fields: 373 374.. table:: 375 :align: center 376 377 +--------+--------------+----------------+ 378 | ``OP`` | ``Group ID`` | ``Command ID`` | 379 +========+==============+================+ 380 | ``0`` | ``0`` | ``4`` | 381 +--------+--------------+----------------+ 382 383The command sends an empty CBOR map as data. 384 385Date-time get response 386---------------------- 387 388Date-time get response header fields: 389 390.. table:: 391 :align: center 392 393 +--------+--------------+----------------+ 394 | ``OP`` | ``Group ID`` | ``Command ID`` | 395 +========+==============+================+ 396 | ``1`` | ``0`` | ``4`` | 397 +--------+--------------+----------------+ 398 399CBOR data of successful response: 400 401.. code-block:: none 402 403 { 404 (str)"datetime" : (str) 405 } 406 407In case of error the CBOR data takes the form: 408 409.. tabs:: 410 411 .. group-tab:: SMP version 2 412 413 .. code-block:: none 414 415 { 416 (str)"err" : { 417 (str)"group" : (uint) 418 (str)"rc" : (uint) 419 } 420 } 421 422 .. group-tab:: SMP version 1 (and non-group SMP version 2) 423 424 .. code-block:: none 425 426 { 427 (str)"rc" : (int) 428 } 429 430where: 431 432.. table:: 433 :align: center 434 435 +------------------+-------------------------------------------------------------------------+ 436 | "datetime" | String in format: ``yyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ``. | 437 +------------------+-------------------------------------------------------------------------+ 438 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 439 | | appears if an error is returned when using SMP version 2. | 440 +------------------+-------------------------------------------------------------------------+ 441 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 442 | | non-zero (error condition) when using SMP version 2. | 443 +------------------+-------------------------------------------------------------------------+ 444 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 445 | | using SMP version 1 or for SMP errors when using SMP version 2. | 446 +------------------+-------------------------------------------------------------------------+ 447 448 449Date-time set 450============= 451 452The command allows to set date-time to a device. 453 454Date-time set request 455--------------------- 456 457Date-time set request header fields: 458 459.. table:: 460 :align: center 461 462 +--------+--------------+----------------+ 463 | ``OP`` | ``Group ID`` | ``Command ID`` | 464 +========+==============+================+ 465 | ``2`` | ``0`` | ``4`` | 466 +--------+--------------+----------------+ 467 468CBOR data of response: 469 470.. code-block:: none 471 472 { 473 (str)"datetime" : (str) 474 } 475 476where: 477 478.. table:: 479 :align: center 480 481 +---------------+----------------------------------------------------------+ 482 | "datetime" | String in format: ``yyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ``. | 483 +---------------+----------------------------------------------------------+ 484 485Date-time set response 486---------------------- 487 488Date-time set response header fields: 489 490.. table:: 491 :align: center 492 493 +--------+--------------+----------------+ 494 | ``OP`` | ``Group ID`` | ``Command ID`` | 495 +========+==============+================+ 496 | ``3`` | ``0`` | ``4`` | 497 +--------+--------------+----------------+ 498 499The command sends an empty CBOR map as data if successful. In case of error the 500CBOR data takes the form: 501 502.. tabs:: 503 504 .. group-tab:: SMP version 2 505 506 .. code-block:: none 507 508 { 509 (str)"err" : { 510 (str)"group" : (uint) 511 (str)"rc" : (uint) 512 } 513 } 514 515 .. group-tab:: SMP version 1 (and non-group SMP version 2) 516 517 .. code-block:: none 518 519 { 520 (str)"rc" : (int) 521 } 522 523where: 524 525.. table:: 526 :align: center 527 528 +------------------+-------------------------------------------------------------------------+ 529 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 530 | | appears if an error is returned when using SMP version 2. | 531 +------------------+-------------------------------------------------------------------------+ 532 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 533 | | non-zero (error condition) when using SMP version 2. | 534 +------------------+-------------------------------------------------------------------------+ 535 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 536 | | using SMP version 1 or for SMP errors when using SMP version 2. | 537 +------------------+-------------------------------------------------------------------------+ 538 539System reset 540************ 541 542Performs reset of system. The device should issue response before resetting so 543that the SMP client could receive information that the command has been 544accepted. By default, this command is accepted in all conditions, however if 545the :kconfig:option:`CONFIG_MCUMGR_GRP_OS_RESET_HOOK` is enabled and an 546application registers a callback, the callback will be called when this command 547is issued and can be used to perform any necessary tidy operations prior to the 548module rebooting, or to reject the reset request outright altogether with an 549error response. For details on this functionality, see `ref:`mcumgr_callbacks`. 550 551System reset request 552==================== 553 554System reset request header fields: 555 556.. table:: 557 :align: center 558 559 +--------+--------------+----------------+ 560 | ``OP`` | ``Group ID`` | ``Command ID`` | 561 +========+==============+================+ 562 | ``2`` | ``0`` | ``5`` | 563 +--------+--------------+----------------+ 564 565Normally the command sends an empty CBOR map as data, but if a previous reset 566attempt has responded with "rc" equal to :c:enum:`MGMT_ERR_EBUSY` then the 567following map may be sent to force a reset: 568 569.. code-block:: none 570 571 { 572 (opt)"force" : (int) 573 } 574 575where: 576 577.. table:: 578 :align: center 579 580 +-----------------------+---------------------------------------------------+ 581 | "force" | Force reset if value > 0, optional if 0. | 582 +-----------------------+---------------------------------------------------+ 583 584 585System reset response 586===================== 587 588System reset response header fields 589 590.. table:: 591 :align: center 592 593 +--------+--------------+----------------+ 594 | ``OP`` | ``Group ID`` | ``Command ID`` | 595 +========+==============+================+ 596 | ``3`` | ``0`` | ``5`` | 597 +--------+--------------+----------------+ 598 599The command sends an empty CBOR map as data if successful. In case of error the 600CBOR data takes the form: 601 602.. tabs:: 603 604 .. group-tab:: SMP version 2 605 606 .. code-block:: none 607 608 { 609 (str)"err" : { 610 (str)"group" : (uint) 611 (str)"rc" : (uint) 612 } 613 } 614 615 .. group-tab:: SMP version 1 (and non-group SMP version 2) 616 617 .. code-block:: none 618 619 { 620 (str)"rc" : (int) 621 } 622 623where: 624 625.. table:: 626 :align: center 627 628 +------------------+-------------------------------------------------------------------------+ 629 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 630 | | appears if an error is returned when using SMP version 2. | 631 +------------------+-------------------------------------------------------------------------+ 632 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 633 | | non-zero (error condition) when using SMP version 2. | 634 +------------------+-------------------------------------------------------------------------+ 635 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 636 | | using SMP version 1 or for SMP errors when using SMP version 2. | 637 +------------------+-------------------------------------------------------------------------+ 638 639MCUmgr Parameters 640***************** 641 642Used to obtain parameters of mcumgr library. 643 644MCUmgr Parameters Request 645========================= 646 647MCUmgr parameters request header fields: 648 649.. table:: 650 :align: center 651 652 +--------+--------------+----------------+ 653 | ``OP`` | ``Group ID`` | ``Command ID`` | 654 +========+==============+================+ 655 | ``0`` | ``0`` | ``6`` | 656 +--------+--------------+----------------+ 657 658The command sends an empty CBOR map as data. 659 660MCUmgr Parameters Response 661========================== 662 663MCUmgr parameters response header fields 664 665.. table:: 666 :align: center 667 668 +--------+--------------+----------------+ 669 | ``OP`` | ``Group ID`` | ``Command ID`` | 670 +========+==============+================+ 671 | ``1`` | ``0`` | ``6`` | 672 +--------+--------------+----------------+ 673 674CBOR data of successful response: 675 676.. code-block:: none 677 678 { 679 (str)"buf_size" : (uint) 680 (str)"buf_count" : (uint) 681 } 682 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 | "buf_size" | Single SMP buffer size, this includes SMP header and CBOR payload. | 713 +------------------+-------------------------------------------------------------------------+ 714 | "buf_count" | Number of SMP buffers supported. | 715 +------------------+-------------------------------------------------------------------------+ 716 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 717 | | appears if an error is returned when using SMP version 2. | 718 +------------------+-------------------------------------------------------------------------+ 719 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 720 | | non-zero (error condition) when using SMP version 2. | 721 +------------------+-------------------------------------------------------------------------+ 722 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 723 | | using SMP version 1 or for SMP errors when using SMP version 2. | 724 +------------------+-------------------------------------------------------------------------+ 725 726.. _mcumgr_os_application_info: 727 728OS/Application Info 729******************* 730 731Used to obtain information on running image, similar functionality to the linux 732uname command, allowing details such as kernel name, kernel version, build 733date/time, processor type and application-defined details to be returned. This 734functionality can be enabled with :kconfig:option:`CONFIG_MCUMGR_GRP_OS_INFO`. 735 736OS/Application Info Request 737=========================== 738 739OS/Application info request header fields: 740 741.. table:: 742 :align: center 743 744 +--------+--------------+----------------+ 745 | ``OP`` | ``Group ID`` | ``Command ID`` | 746 +========+==============+================+ 747 | ``0`` | ``0`` | ``7`` | 748 +--------+--------------+----------------+ 749 750CBOR data of request: 751 752.. code-block:: none 753 754 { 755 (str,opt)"format" : (str) 756 } 757 758where: 759 760.. table:: 761 :align: center 762 763 +----------+-------------------------------------------------------------------+ 764 | "format" | Format specifier of returned response, fields are appended in | 765 | | their natural ascending index order, not the order of | 766 | | characters that are received by the command. Format | 767 | | specifiers: |br| | 768 | | * ``s`` Kernel name |br| | 769 | | * ``n`` Node name |br| | 770 | | * ``r`` Kernel release |br| | 771 | | * ``v`` Kernel version |br| | 772 | | * ``b`` Build date and time (requires | 773 | | :kconfig:option:`CONFIG_MCUMGR_GRP_OS_INFO_BUILD_DATE_TIME`) |br| | 774 | | * ``m`` Machine |br| | 775 | | * ``p`` Processor |br| | 776 | | * ``i`` Hardware platform |br| | 777 | | * ``o`` Operating system |br| | 778 | | * ``a`` All fields (shorthand for all above options) |br| | 779 | | If this option is not provided, the ``s`` Kernel name option | 780 | | will be used. | 781 +----------+-------------------------------------------------------------------+ 782 783OS/Application Info Response 784============================ 785 786OS/Application info response header fields 787 788.. table:: 789 :align: center 790 791 +--------+--------------+----------------+ 792 | ``OP`` | ``Group ID`` | ``Command ID`` | 793 +========+==============+================+ 794 | ``1`` | ``0`` | ``7`` | 795 +--------+--------------+----------------+ 796 797CBOR data of successful response: 798 799.. code-block:: none 800 801 { 802 (str)"output" : (str) 803 } 804 805In case of error the CBOR data takes the form: 806 807.. tabs:: 808 809 .. group-tab:: SMP version 2 810 811 .. code-block:: none 812 813 { 814 (str)"err" : { 815 (str)"group" : (uint) 816 (str)"rc" : (uint) 817 } 818 } 819 820 .. group-tab:: SMP version 1 (and non-group SMP version 2) 821 822 .. code-block:: none 823 824 { 825 (str)"rc" : (int) 826 } 827 828where: 829 830.. table:: 831 :align: center 832 833 +------------------+-------------------------------------------------------------------------+ 834 | "output" | Text response including requested parameters. | 835 +------------------+-------------------------------------------------------------------------+ 836 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 837 | | appears if an error is returned when using SMP version 2. | 838 +------------------+-------------------------------------------------------------------------+ 839 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 840 | | non-zero (error condition) when using SMP version 2. | 841 +------------------+-------------------------------------------------------------------------+ 842 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 843 | | using SMP version 1 or for SMP errors when using SMP version 2. | 844 +------------------+-------------------------------------------------------------------------+ 845 846Bootloader Information 847********************** 848 849Allows retrieving information about the on-board bootloader and its parameters. 850 851Bootloader Information Request 852============================== 853 854Bootloader information request header: 855 856.. table:: 857 :align: center 858 859 +--------+--------------+----------------+ 860 | ``OP`` | ``Group ID`` | ``Command ID`` | 861 +========+==============+================+ 862 | ``0`` | ``0`` | ``8`` | 863 +--------+--------------+----------------+ 864 865CBOR data of request: 866 867.. code-block:: none 868 869 { 870 (str,opt)"query" : (str) 871 } 872 873where: 874 875.. table:: 876 :align: center 877 878 +--------------+-----------------------------------------------+ 879 | "query" | Is string representing query for parameters, | 880 | | with no restrictions how the query looks like | 881 | | as processing of query is left for bootloader | 882 | | backend. | 883 | | If there is no query, then response will | 884 | | return string identifying the bootloader. | 885 +--------------+-----------------------------------------------+ 886 887Bootloader Information Response 888=============================== 889 890Bootloader information response header: 891 892.. table:: 893 :align: center 894 895 +--------+--------------+----------------+ 896 | ``OP`` | ``Group ID`` | ``Command ID`` | 897 +========+==============+================+ 898 | ``1`` | ``0`` | ``8`` | 899 +--------+--------------+----------------+ 900 901In case when no "query" has been provided in request, 902CBOR data of response: 903 904.. code-block:: none 905 906 { 907 (str)"bootloader" : (str) 908 } 909 910where: 911 912.. table:: 913 :align: center 914 915 +--------------+-----------------------------------------------+ 916 | "bootloader" | String representing bootloader name | 917 +--------------+-----------------------------------------------+ 918 919In case when "query" is provided: 920 921.. code-block:: none 922 923 { 924 (str,opt)<response> : () 925 ... 926 } 927 928where: 929 930.. table:: 931 :align: center 932 933 +------------------+-------------------------------------------------------------------------+ 934 | <response> | Response to "query". This is optional and may be left out in case when | 935 | | query yields no response, SMP version 2 error code of | 936 | | `OS_MGMT_ERR_QUERY_YIELDS_NO_ANSWER` is expected. | 937 | | Response may have more than one parameter reported back or it may be | 938 | | a map, that is dependent on bootloader backednd and query. | 939 +------------------+-------------------------------------------------------------------------+ 940 | ... | Parameter characteristic information. | 941 +------------------+-------------------------------------------------------------------------+ 942 943Parameter may be accompanied by additional, parameter specific, information keywords with 944assigned values. 945 946In case of error the CBOR data takes the form: 947 948.. tabs:: 949 950 .. group-tab:: SMP version 2 951 952 .. code-block:: none 953 954 { 955 (str)"err" : { 956 (str)"group" : (uint) 957 (str)"rc" : (uint) 958 } 959 } 960 961 .. group-tab:: SMP version 1 (and non-group SMP version 2) 962 963 .. code-block:: none 964 965 { 966 (str)"rc" : (int) 967 } 968 969where: 970 971.. table:: 972 :align: center 973 974 +------------------+-------------------------------------------------------------------------+ 975 | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only | 976 | | appears if an error is returned when using SMP version 2. | 977 +------------------+-------------------------------------------------------------------------+ 978 | "err" -> "rc" | contains the index of the group-based error code. Only appears if | 979 | | non-zero (error condition) when using SMP version 2. | 980 +------------------+-------------------------------------------------------------------------+ 981 | "rc" | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when | 982 | | using SMP version 1 or for SMP errors when using SMP version 2. | 983 +------------------+-------------------------------------------------------------------------+ 984 985Bootloader Information: MCUboot 986=============================== 987 988In case when MCUboot is application bootloader, empty request will 989be responded with: 990 991.. code-block:: none 992 993 { 994 (str)"bootloader" : (str)"MCUboot" 995 } 996 997Currently "MCUboot" supports querying for mode of operation: 998 999.. code-block:: none 1000 1001 { 1002 (str)"query" : (str)"mode" 1003 } 1004 1005Response to "mode" is: 1006 1007.. code-block:: none 1008 1009 { 1010 (str)"mode" : (int) 1011 (str,opt)"no-downgrade" : (bool) 1012 } 1013 1014where "mode" is one of: 1015 1016.. table:: 1017 :align: center 1018 1019 +-----+-----------------------------------------------------+ 1020 | -1 | Unknown mode of MCUboot. | 1021 +-----+-----------------------------------------------------+ 1022 | 0 | MCUboot is in single application mode. | 1023 +-----+-----------------------------------------------------+ 1024 | 1 | MCUboot is in swap using scratch partition mode. | 1025 +-----+-----------------------------------------------------+ 1026 | 2 | MCUboot is in overwrite (upgrade-only) mode. | 1027 +-----+-----------------------------------------------------+ 1028 | 3 | MCUboot is in swap without scratch mode. | 1029 +-----+-----------------------------------------------------+ 1030 | 4 | MCUboot is in DirectXIP without revert mode. | 1031 +-----+-----------------------------------------------------+ 1032 | 5 | MCUboot is in DirectXIP with revert mode. | 1033 +-----+-----------------------------------------------------+ 1034 | 6 | MCUboot is in RAM loader mode. | 1035 +-----+-----------------------------------------------------+ 1036 1037The ``no-downgrade`` field is a flag, which is always sent when true, indicating that MCUboot has 1038downgrade prevention enabled; downgrade prevention means that if the uploaded image has a lower 1039version than the currently running application, it will not be used for an update by MCUboot. 1040 1041MCUmgr may reject images with a lower version in this configuration. 1042
