| .. _mcu_mgr: |
| |
| MCUmgr |
| ####### |
| |
| Overview |
| ******** |
| |
| The management subsystem allows remote management of Zephyr-enabled devices. |
| The following management operations are available: |
| |
| * Image management |
| * File System management |
| * OS management |
| * Settings (config) management |
| * Shell management |
| * Statistic management |
| * Zephyr management |
| |
| over the following transports: |
| |
| * BLE (Bluetooth Low Energy) |
| * Serial (UART) |
| * UDP over IP |
| |
| The management subsystem is based on the Simple Management Protocol (SMP) |
| provided by `MCUmgr`_, an open source project that provides a |
| management subsystem that is portable across multiple real-time operating |
| systems. |
| |
| The management subsystem is located in :zephyr_file:`subsys/mgmt/` inside of |
| the Zephyr tree. |
| |
| Additionally, there is a :zephyr:code-sample:`sample <smp-svr>` server that provides |
| management functionality over BLE and serial. |
| |
| .. _mcumgr_tools_libraries: |
| |
| Tools/libraries |
| *************** |
| |
| There are various tools and libraries available which enable usage of MCUmgr functionality on a |
| device which are listed below. Note that these tools are not part of or related to the Zephyr |
| project. |
| |
| .. only:: html |
| |
| .. table:: Tools and Libraries for MCUmgr |
| :align: center |
| |
| +--------------------------------------------------------------------------------+-------------------------------------------+--------------------------+---------------------------------------------------------+---------------+------------+------------+ |
| | Name | OS support | Transports | Groups | Type | Language | License | |
| | +---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+ | | | |
| | | Windows | Linux | mac | Mobile | Embedded | Serial | Bluetooth | UDP | OS | IMG | Stat | Settings | FS | Shell | Enum | Zephyr | | | | |
| +================================================================================+=========+=======+=====+========+==========+========+===========+=====+====+=====+======+==========+====+=======+======+========+===============+============+============+ |
| | `AuTerm <https://github.com/thedjnK/AuTerm/>`_ | ✓ | ✓ | ✓ | ✕ | ✕ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | Application | C++ (Qt) | GPL-3.0 | |
| +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ |
| | `mcumgr-client <https://github.com/vouch-opensource/mcumgr-client/>`_ | ✓ | ✓ | ✓ | ✕ | ✕ | ✓ | ✕ | ✕ | ✕ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | Application | Rust | Apache-2.0 | |
| +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ |
| | `mcumgr-web <https://github.com/boogie/mcumgr-web/>`_ | ✓ | ✓ | ✓ | ✕ | ✕ | ✕ | ✓ | ✕ | ✕ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | Web page | Javascript | MIT | |
| | | | | | | | | | | | | | | | | | | (chrome only) | | | |
| +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ |
| | nRF Connect Device Manager: |br| | | | | | | | | | | | | | | | | | | | | |
| | `Android | ✕ | ✕ | ✕ | ✓ | ✕ | ✕ | ✓ | ✕ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library and | Java, | Apache-2.0 | |
| | <https://github.com/NordicSemiconductor/Android-nRF-Connect-Device-Manager/>`_ | | | | | | | | | | | | | | | | | application | Kotlin, | | |
| | and `iOS | | | | | | | | | | | | | | | | | | Swift | | |
| | <https://github.com/NordicSemiconductor/IOS-nRF-Connect-Device-Manager>`_ | | | | | | | | | | | | | | | | | | | | |
| +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ |
| | `smp <https://pypi.org/project/smp/>`_ | ✓ | ✓ | ✓ | ✓ | ✕ | N/A | N/A | N/A | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library | Python | Apache-2.0 | |
| +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ |
| | `smpclient <https://pypi.org/project/smpclient/>`_ | ✓ | ✓ | ✓ | ✕ | ✕ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library | Python | Apache-2.0 | |
| +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ |
| | Zephyr MCUmgr client (in-tree) | ✕ | ✓ | ✕ | ✕ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | Library | C | Apache-2.0 | |
| +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+------+--------+---------------+------------+------------+ |
| |
| .. only:: latex |
| |
| .. raw:: latex |
| |
| \begin{landscape} |
| |
| .. table:: Tools and Libraries for MCUmgr |
| :align: center |
| |
| +--------------------------------------------------------------------------------+---------------+-----------------+---------------------------------------------------------+---------------+------------+ |
| | Name | OS support | Transports | Groups | Type | Language | |
| | | | +----+-----+------+----------+----+-------+------+--------+ | | |
| | | | | OS | IMG | Stat | Settings | FS | Shell | Enum | Zephyr | | | |
| +================================================================================+===============+=================+====+=====+======+==========+====+=======+======+========+===============+============+ |
| | `AuTerm <https://github.com/thedjnK/AuTerm/>`_ | Windows, |br| | Serial, |br| | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | App | C++ (Qt) | |
| | | Linux, |br| | Bluetooth, |br| | | | | | | | | | | | |
| | | macOS | UDP | | | | | | | | | | | |
| +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ |
| | `mcumgr-client <https://github.com/vouch-opensource/mcumgr-client/>`_ | Windows, |br| | Serial | ✕ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | App | Rust | |
| | | Linux, |br| | | | | | | | | | | | | |
| | | macOS | | | | | | | | | | | | |
| +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ |
| | `mcumgr-web <https://github.com/boogie/mcumgr-web/>`_ | Windows, |br| | Bluetooth | ✕ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | Web (chrome | Javascript | |
| | | Linux, |br| | | | | | | | | | | only) | | |
| | | macOS | | | | | | | | | | | | |
| +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ |
| | nRF Connect Device Manager: |br| | iOS, |br| | Bluetooth | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library, App | Java, | |
| | `Android | Android | | | | | | | | | | | Kotlin, | |
| | <https://github.com/NordicSemiconductor/Android-nRF-Connect-Device-Manager/>`_ | | | | | | | | | | | | Swift | |
| | and `iOS | | | | | | | | | | | | | |
| | <https://github.com/NordicSemiconductor/IOS-nRF-Connect-Device-Manager>`_ | | | | | | | | | | | | | |
| +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ |
| | `smp <https://pypi.org/project/smp/>`_ | Windows, |br| | N/A | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library | Python | |
| | | Linux, |br| | | | | | | | | | | | | |
| | | macOS, |br| | | | | | | | | | | | | |
| | | iOS, |br| | | | | | | | | | | | | |
| | | Android | | | | | | | | | | | | |
| +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ |
| | `smpclient <https://pypi.org/project/smpclient/>`_ | Windows, |br| | Serial, |br| | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | ✓ | Library | Python | |
| | | Linux, |br| | Bluetooth, |br| | | | | | | | | | | | |
| | | macOS | UDP | | | | | | | | | | | |
| +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ |
| | Zephyr MCUmgr client (in-tree) | Linux, |br| | Serial, |br| | ✓ | ✓ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | Library | C | |
| | | Zephyr | Bluetooth, |br| | | | | | | | | | | | |
| | | | UDP | | | | | | | | | | | |
| +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+------+--------+---------------+------------+ |
| |
| .. raw:: latex |
| |
| \end{landscape} |
| |
| Note that a tick for a particular group indicates basic support for that group in the code, it is |
| possible that not all commands/features of a group are supported by the implementation. |
| |
| .. _mcumgr_jlink_ob_virtual_msd: |
| |
| J-Link Virtual MSD Interaction Note |
| *********************************** |
| |
| On boards where a J-Link OB is present which has both CDC and MSC (virtual Mass |
| Storage Device, also known as drag-and-drop) support, the MSD functionality can |
| prevent MCUmgr commands over the CDC UART port from working due to how USB |
| endpoints are configured in the J-Link firmware (for example on the |
| :ref:`Nordic nrf52840dk/nrf52840 board <nrf52840dk_nrf52840>`) because of |
| limiting the maximum packet size (most likely to occur when using image |
| management commands for updating firmware). This issue can be |
| resolved by disabling MSD functionality on the J-Link device, follow the |
| instructions on :ref:`nordic_segger_msd` to disable MSD support. |
| |
| Bootloader Integration |
| ********************** |
| |
| The :ref:`dfu` subsystem integrates the management subsystem with the |
| bootloader, providing the ability to send and upgrade a Zephyr image to a |
| device. |
| |
| Currently only the MCUboot bootloader is supported. See :ref:`mcuboot` for more |
| information. |
| |
| .. _MCUmgr: https://github.com/apache/mynewt-mcumgr |
| .. _MCUboot design: https://github.com/mcu-tools/mcuboot/blob/main/docs/design.md |
| |
| Discord channel |
| *************** |
| |
| Developers welcome! |
| |
| * Discord mcumgr channel: https://discord.com/invite/Ck7jw53nU2 |
| |
| API Reference |
| ************* |
| |
| .. doxygengroup:: mcumgr_mgmt_api |
