1.. _mcu_mgr: 2 3MCUmgr 4####### 5 6Overview 7******** 8 9The management subsystem allows remote management of Zephyr-enabled devices. 10The following management operations are available: 11 12* Image management 13* File System management 14* OS management 15* Settings (config) management 16* Shell management 17* Statistic management 18* Zephyr management 19 20over the following transports: 21 22* BLE (Bluetooth Low Energy) 23* Serial (UART) 24* UDP over IP 25 26The management subsystem is based on the Simple Management Protocol (SMP) 27provided by `MCUmgr`_, an open source project that provides a 28management subsystem that is portable across multiple real-time operating 29systems. 30 31The management subsystem is located in :zephyr_file:`subsys/mgmt/` inside of 32the Zephyr tree. 33 34Additionally, there is a :zephyr:code-sample:`sample <smp-svr>` server that provides 35management functionality over BLE and serial. 36 37.. _mcumgr_tools_libraries: 38 39Tools/libraries 40*************** 41 42There are various tools and libraries available which enable usage of MCUmgr functionality on a 43device which are listed below. Note that these tools are not part of or related to the Zephyr 44project. 45 46.. only:: html 47 48 .. table:: Tools and Libraries for MCUmgr 49 :align: center 50 51 +--------------------------------------------------------------------------------+-------------------------------------------+--------------------------+---------------------------------------------------------+---------------+------------+------------+ 52 | Name | OS support | Transports | Groups | Type | Language | License | 53 | +---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+ | | | 54 | | Windows | Linux | mac | Mobile | Embedded | Serial | Bluetooth | UDP | OS | IMG | Stat | Settings | FS | Shell | Enum | Zephyr | | | | 55 +================================================================================+=========+=======+=====+========+==========+========+===========+=====+====+=====+======+==========+====+=======+======+========+===============+============+============+ 56 | `AuTerm <https://github.com/thedjnK/AuTerm/>`_ | ✓ | ✓ | ✓ | ✕ | ✕ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | Application | C++ (Qt) | GPL-3.0 | 57 +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ 58 | `mcumgr-client <https://github.com/vouch-opensource/mcumgr-client/>`_ | ✓ | ✓ | ✓ | ✕ | ✕ | ✓ | ✕ | ✕ | ✕ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | Application | Rust | Apache-2.0 | 59 +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ 60 | `mcumgr-web <https://github.com/boogie/mcumgr-web/>`_ | ✓ | ✓ | ✓ | ✕ | ✕ | ✕ | ✓ | ✕ | ✕ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | Web page | Javascript | MIT | 61 | | | | | | | | | | | | | | | | | | (chrome only) | | | 62 +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ 63 | nRF Connect Device Manager: |br| | | | | | | | | | | | | | | | | | | | | 64 | `Android | ✕ | ✕ | ✕ | ✓ | ✕ | ✕ | ✓ | ✕ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library and | Java, | Apache-2.0 | 65 | <https://github.com/NordicSemiconductor/Android-nRF-Connect-Device-Manager/>`_ | | | | | | | | | | | | | | | | | application | Kotlin, | | 66 | and `iOS | | | | | | | | | | | | | | | | | | Swift | | 67 | <https://github.com/NordicSemiconductor/IOS-nRF-Connect-Device-Manager>`_ | | | | | | | | | | | | | | | | | | | | 68 +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ 69 | `smp <https://pypi.org/project/smp/>`_ | ✓ | ✓ | ✓ | ✓ | ✕ | N/A | N/A | N/A | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library | Python | Apache-2.0 | 70 +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ 71 | `smpclient <https://pypi.org/project/smpclient/>`_ | ✓ | ✓ | ✓ | ✕ | ✕ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library | Python | Apache-2.0 | 72 +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ 73 | Zephyr MCUmgr client (in-tree) | ✕ | ✓ | ✕ | ✕ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | Library | C | Apache-2.0 | 74 +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ 75 76.. only:: latex 77 78 .. raw:: latex 79 80 \begin{landscape} 81 82 .. table:: Tools and Libraries for MCUmgr 83 :align: center 84 85 +--------------------------------------------------------------------------------+---------------+-----------------+---------------------------------------------------------+---------------+------------+ 86 | Name | OS support | Transports | Groups | Type | Language | 87 | | | +----+-----+------+----------+----+-------+------+--------+ | | 88 | | | | OS | IMG | Stat | Settings | FS | Shell | Enum | Zephyr | | | 89 +================================================================================+===============+=================+====+=====+======+==========+====+=======+======+========+===============+============+ 90 | `AuTerm <https://github.com/thedjnK/AuTerm/>`_ | Windows, |br| | Serial, |br| | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | App | C++ (Qt) | 91 | | Linux, |br| | Bluetooth, |br| | | | | | | | | | | | 92 | | macOS | UDP | | | | | | | | | | | 93 +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ 94 | `mcumgr-client <https://github.com/vouch-opensource/mcumgr-client/>`_ | Windows, |br| | Serial | ✕ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | App | Rust | 95 | | Linux, |br| | | | | | | | | | | | | 96 | | macOS | | | | | | | | | | | | 97 +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ 98 | `mcumgr-web <https://github.com/boogie/mcumgr-web/>`_ | Windows, |br| | Bluetooth | ✕ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | Web (chrome | Javascript | 99 | | Linux, |br| | | | | | | | | | | only) | | 100 | | macOS | | | | | | | | | | | | 101 +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ 102 | nRF Connect Device Manager: |br| | iOS, |br| | Bluetooth | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library, App | Java, | 103 | `Android | Android | | | | | | | | | | | Kotlin, | 104 | <https://github.com/NordicSemiconductor/Android-nRF-Connect-Device-Manager/>`_ | | | | | | | | | | | | Swift | 105 | and `iOS | | | | | | | | | | | | | 106 | <https://github.com/NordicSemiconductor/IOS-nRF-Connect-Device-Manager>`_ | | | | | | | | | | | | | 107 +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ 108 | `smp <https://pypi.org/project/smp/>`_ | Windows, |br| | N/A | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library | Python | 109 | | Linux, |br| | | | | | | | | | | | | 110 | | macOS, |br| | | | | | | | | | | | | 111 | | iOS, |br| | | | | | | | | | | | | 112 | | Android | | | | | | | | | | | | 113 +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ 114 | `smpclient <https://pypi.org/project/smpclient/>`_ | Windows, |br| | Serial, |br| | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library | Python | 115 | | Linux, |br| | Bluetooth, |br| | | | | | | | | | | | 116 | | macOS | UDP | | | | | | | | | | | 117 +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ 118 | Zephyr MCUmgr client (in-tree) | Linux, |br| | Serial, |br| | ✓ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | Library | C | 119 | | Zephyr | Bluetooth, |br| | | | | | | | | | | | 120 | | | UDP | | | | | | | | | | | 121 +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ 122 123 .. raw:: latex 124 125 \end{landscape} 126 127Note that a tick for a particular group indicates basic support for that group in the code, it is 128possible that not all commands/features of a group are supported by the implementation. 129 130.. _mcumgr_jlink_ob_virtual_msd: 131 132J-Link Virtual MSD Interaction Note 133*********************************** 134 135On boards where a J-Link OB is present which has both CDC and MSC (virtual Mass 136Storage Device, also known as drag-and-drop) support, the MSD functionality can 137prevent MCUmgr commands over the CDC UART port from working due to how USB 138endpoints are configured in the J-Link firmware (for example on the 139:ref:`Nordic nrf52840dk/nrf52840 board <nrf52840dk_nrf52840>`) because of 140limiting the maximum packet size (most likely to occur when using image 141management commands for updating firmware). This issue can be 142resolved by disabling MSD functionality on the J-Link device, follow the 143instructions on :ref:`nordic_segger_msd` to disable MSD support. 144 145Bootloader Integration 146********************** 147 148The :ref:`dfu` subsystem integrates the management subsystem with the 149bootloader, providing the ability to send and upgrade a Zephyr image to a 150device. 151 152Currently only the MCUboot bootloader is supported. See :ref:`mcuboot` for more 153information. 154 155.. _MCUmgr: https://github.com/apache/mynewt-mcumgr 156.. _MCUboot design: https://github.com/mcu-tools/mcuboot/blob/main/docs/design.md 157 158Discord channel 159*************** 160 161Developers welcome! 162 163* Discord mcumgr channel: https://discord.com/invite/Ck7jw53nU2 164 165API Reference 166************* 167 168.. doxygengroup:: mcumgr_mgmt_api 169
