.. _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 | Zephyr |               |            |         |
        +================================================================================+=========+=======+=====+========+==========+========+===========+=====+====+=====+======+==========+====+=======+========+===============+============+=========+
        | `AuTerm <https://github.com/thedjnK/AuTerm/>`_                                 | ✓       | ✓     | ✓   | ✕      | ✕        | ✓      | ✓         | ✓   | ✓  | ✓   | ✓    | ✓        | ✓  | ✓     | ✓      | Application   | C++ (Qt)   | GPLv3   |
        +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+--------+---------------+------------+---------+
        | `mcumgr-client <https://github.com/vouch-opensource/mcumgr-client/>`_          | ✓       | ✓     | ✓   | ✕      | ✕        | ✓      | ✕         | ✕   | ✕  | ✓   | ✕    | ✕        | ✕  | ✕     | ✕      | Application   | Rust       | BSD     |
        +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+--------+---------------+------------+---------+
        | `mcumgr-web <https://github.com/boogie/mcumgr-web/>`_                          | ✓       | ✓     | ✓   | ✕      | ✕        | ✕      | ✓         | ✕   | ✕  | ✓   | ✕    | ✕        | ✕  | ✕     | ✕      | Web page      | Javascript | MIT     |
        |                                                                                |         |       |     |        |          |        |           |     |    |     |      |          |    |       |        | (chrome only) |            |         |
        +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+--------+---------------+------------+---------+
        | nRF Connect Device Manager: |br|                                               |         |       |     |        |          |        |           |     |    |     |      |          |    |       |        |               |            |         |
        | `Android                                                                       | ✕       | ✕     | ✕   | ✓      | ✕        | ✕      | ✓         | ✕   | ✓  | ✓   | ✓    | ✓        | ✓  | ✓     | ✓      | Library and   | Java,      | Apache  |
        | <https://github.com/NordicSemiconductor/Android-nRF-Connect-Device-Manager/>`_ |         |       |     |        |          |        |           |     |    |     |      |          |    |       |        | application   | Kotlin,    |         |
        | and `iOS                                                                       |         |       |     |        |          |        |           |     |    |     |      |          |    |       |        |               | Swift      |         |
        | <https://github.com/NordicSemiconductor/IOS-nRF-Connect-Device-Manager>`_      |         |       |     |        |          |        |           |     |    |     |      |          |    |       |        |               |            |         |
        +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+--------+---------------+------------+---------+
        | Zephyr MCUmgr client (in-tree)                                                 | ✕       | ✓     | ✕   | ✕      | ✓        | ✓      | ✓         | ✓   | ✓  | ✓   | ✕    | ✕        | ✕  | ✕     | ✕      | Library       | C          | Apache  |
        +--------------------------------------------------------------------------------+---------+-------+-----+--------+----------+--------+-----------+-----+----+-----+------+----------+----+-------+--------+---------------+------------+---------+

.. 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 | 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>`_      |               |                 |    |     |      |          |    |       |        |               |            |
        +--------------------------------------------------------------------------------+---------------+-----------------+----+-----+------+----------+----+-------+--------+---------------+------------+
        | 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