patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 8 Packages Projects Releases Wiki Activity

doc: service: device_mgmt: Tidy documentation

Browse source 
Tidies and corrects some minor documentation issues.

Signed-off-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
This commit is contained in:
Jamie McCrae 2023-05-16 11:56:48 +01:00 committed by Carles Cufí
parent 9cc6a7f060
commit cfbcd45afb
2 changed files with 40 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
doc/services/device_mgmt/mcumgr.rst
View file

@ -11,9 +11,10 @@ The following management operations are available:
* Image management
* File System management
* Log management (currently disabled)
* OS management
* Shell management
* Statistic management
* Zephyr-basic management
over the following transports:
@ -26,14 +27,11 @@ 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 split in two different locations in the Zephyr tree:
The management subsystem is located in :zephyr_file:`subsys/mgmt/` inside of
the Zephyr tree.
* `zephyrproject-rtos/mcumgr repo <https://github.com/zephyrproject-rtos/mcumgr>`_
contains a clean import of the MCUmgr project
* :zephyr_file:`subsys/mgmt/` contains the Zephyr-specific bindings to MCUmgr
Additionally there is a :ref:`sample <smp_svr_sample>` that provides management
functionality over BLE and serial.
Additionally, there is a :ref:`sample <smp_svr_sample>` that provides
management functionality over BLE and serial.
.. _mcumgr_cli:
@ -238,7 +236,7 @@ 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
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
@ -279,7 +277,7 @@ An image can be manually erased using::
mcumgr <connection-options> image erase
The behavior of ``erase`` is defined by the server (``mcumgr`` in the device).
The behavior of ``erase`` is defined by the server (``MCUmgr`` in the device).
The current implementation is limited to erasing the image in the secondary
partition.
@ -519,9 +517,10 @@ Filesystem Management
*********************
The filesystem module is disabled by default due to security concerns:
because of a lack of access control every file in the FS will be accessible,
including secrets, etc. To enable it :kconfig:option:`CONFIG_MCUMGR_GRP_FS` must
be set (``y``). Once enabled the following sub-commands can be used::
because of a lack of access control by default, every file in the FS will be
accessible, including secrets, etc. To enable it
:kconfig:option:`CONFIG_MCUMGR_GRP_FS` must be set (``y``). Once enabled the
following sub-commands can be used::
mcumgr <connection-options> fs download <remote-file> <local-file>
mcumgr <connection-options> fs upload <local-file> <remote-file>
@ -575,6 +574,13 @@ saving RAM resources.
:kconfig:option:`CONFIG_MCUMGR_GRP_FS_PATH_LEN` sets the maximum PATH accepted for a file
name. It might require tweaking for longer file names.
.. note::
To add security to the filesystem management group, callbacks for MCUmgr
hooks can be registered by a user application when the upload/download
functions are ran which allows the application to control if access to a
file is allowed or denied. See the :ref:`mcumgr_callbacks` section for
details.
Bootloader Integration
**********************

41
doc/services/device_mgmt/smp_protocol.rst
View file

@ -4,19 +4,24 @@ SMP Protocol Specification
##########################
This is description of Simple Management Protocol, SMP, that is used by
mcumgr to pass requests to devices and receive responses from them.
MCUmgr to pass requests to devices and receive responses from them.
SMP is an application layer protocol. The underlying transport layer is not
in scope of this documentation.
.. note::
SMP in this context refers to SMP for MCUmgr (Simple Management Protocol),
it is unrelated to SMP in Bluetooth (Security Manager Protocol), but there
is an MCUmgr SMP transport for Bluetooth.
Frame: The envelope
*******************
Each frame consists of header and following it data. The ``Data Length``" field in
the header may be used for reassembly purposes if underlying transport layer supports
Each frame consists of a header and data. The ``Data Length`` field in the
header may be used for reassembly purposes if underlying transport layer supports
fragmentation.
Frame is encoded in "Big Endian" (Network endianness), where field is more than
one byte lone, and takes the following form:
Frames are encoded in "Big Endian" (Network endianness) when fields are more than
one byte long, and takes the following form:
.. _mcumgr_smp_protocol_frame:
@ -39,14 +44,14 @@ one byte lone, and takes the following form:
.. note::
The original specification states that SMP should support receiving
both the "Little-endian" and "Big-endian" frames but in reality the
mcumgr library is hardcoded to always treat "Network" side as
MCUmgr library is hardcoded to always treat "Network" side as
"Big-endian".
The Data is optional and is not present when ``Data Length`` is zero.
Data is optional and is not present when ``Data Length`` is zero.
The encoding of data depends on the target of group/ID.
Where meaning of fields is:
A description of the various fields and their meaning:
.. table::
:align: center
@ -54,7 +59,7 @@ Where meaning of fields is:
+-------------------+---------------------------------------------------+
| Field | Description |
+===================+===================================================+
| ``Res`` | This is reserved, not-used field and should be |
| ``Res`` | This is reserved, not-used field and must be |
| | always set to 0. |
+-------------------+---------------------------------------------------+
| ``Ver`` (Version) | This indicates the version of the protocol being |
@ -62,7 +67,7 @@ Where meaning of fields is:
| | SMP transport where error codes are more detailed |
| | and returned in the map, otherwise left as 0b00 |
| | to use the legacy SMP protocol. Versions 0b10 and |
| | 0x11 are reserved for future use and should not |
| | 0b11 are reserved for future use and should not |
| | be used. |
+-------------------+---------------------------------------------------+
| ``OP`` | :c:enum:`mcumgr_op_t`, determines whether |
@ -94,20 +99,16 @@ Where meaning of fields is:
+-------------------+---------------------------------------------------+
.. note::
Contents of a ``Data`` depends on a value of an ``OP``, a ``Group ID``,
Contents of ``Data`` depends on a value of an ``OP``, a ``Group ID``,
and a ``Command ID``.
.. note::
The ``Res`` field may be repurposed by Zephyr for protocol version
in the future.
.. _mcumgr_smp_protocol_group_ids:
Management ``Group ID``'s
=========================
The SMP protocol supports predefined common groups and allows user defined
groups. Below table presents list of common groups:
groups. The following table presents a list of common groups:
.. table::
@ -147,15 +148,15 @@ groups. Below table presents list of common groups:
| | an application specific management groups. |
+---------------+-----------------------------------------------+
The payload for above groups, except for ``64`` which is not defined,
is always CBOR encoded. The group ``64``, and above, are free to be defined
by application developers and are not defined within this documentation.
The payload for above groups, except for user groups (``64`` and above) is
always CBOR encoded. The group ``64``, and above can define their own scheme
for data communication.
Minimal response
****************
Regardless of a command issued, as long as there is SMP client on the
other side of a request, a response should be issued containing header
other side of a request, a response should be issued containing the header
followed by CBOR map container.
Lack of response is only allowed when there is no SMP service or device is
non-responsive.