samples/subsys/mgmt/mcumgr/smp_svr/README.html · samples/subsys/mgmt/mcumgr/smp_svr/README.rst 공식 원문 ↗

Zephyr 3.7.0 · Samples · Management · MCUmgr

SMP 서버

Shell·Bluetooth·UDP로 device를 관리하고 signed firmware를 test·confirm하는 전 과정을 구성합니다.

Official pathsamples/subsys/mgmt/mcumgr/smp_svr/README.html
Source filesamples/subsys/mgmt/mcumgr/smp_svr/README.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

MCUmgr SMP server의 command group과 다섯 build flavor, MCUboot image 배포, slot mapping 및 filesystem download를 다룹니다.

Transports

Shell · Bluetooth · UDP

Groups

FS · Image · OS · Stat · Shell

DFU

Upload → Test → Reset → Confirm

Boot

MCUboot slot 0 · slot 1

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 7F726247265EF7123C57A4768CBE439E4BE66A667FD24458FC8A80F479BEA5AB
.. zephyr:code-sample:: smp-svr
   :name: SMP server

   Implement a Simple Management Protocol (SMP) server.

Overview
********

This sample application implements a Simple Management Protocol (SMP) server.
SMP is a basic transfer encoding for use with the MCUmgr management protocol.
For more information about MCUmgr and SMP, please see :ref:`device_mgmt`.

This sample application supports the following mcumgr transports by default:

    * Shell
    * Bluetooth
    * UDP

``smp_svr`` enables support for the following command groups:

    * ``fs_mgmt``
    * ``img_mgmt``
    * ``os_mgmt``
    * ``stat_mgmt``
    * ``shell_mgmt``

Caveats
*******

* The MCUboot bootloader is required for ``img_mgmt`` to function
  properly. More information about the Device Firmware Upgrade subsystem and
  MCUboot can be found in :ref:`mcuboot`.

Prerequisites
*************

Use of a tool
=============

To interact remotely with the management subsystem on a device, a tool is required to interact with
it. There are various tools available which are listed on the :ref:`mcumgr_tools_libraries` page
of the Management subsystem documentation.

Building a BLE Controller
=========================

.. note::
   This section is only relevant for Linux users

If you want to try out Device Firmware Upgrade (DFU) over the air using
Bluetooth Low Energy (BLE) and do not have a built-in or pluggable BLE radio,
you can build one and use it following the instructions in
:ref:`bluetooth-hci-uart-bluez`.

Building and flashing MCUboot
*****************************

The below steps describe how to build and run the MCUboot bootloader.
Detailed instructions can be found in the :ref:`mcuboot` documentation page.

The Zephyr port of MCUboot is essentially a normal Zephyr application, which means that
it can be built and flashed like normal using ``west``, like so:

.. code-block:: console

   west build -b <board> -d build_mcuboot bootloader/mcuboot/boot/zephyr
   west flash -d build_mcuboot

Substitute <board> for one of the boards supported by the sample, see
:file:`sample.yaml`.

.. _smp_svr_sample_build:

Building the sample application
*******************************

The below steps describe how to build and run the ``smp_svr`` sample in
Zephyr. The ``smp_svr`` sample comes in different flavours.

.. tabs::

   .. group-tab:: Bluetooth

      To build the bluetooth sample:

      .. code-block:: console

         west build \
            -b nrf52dk/nrf52832 \
            samples/subsys/mgmt/mcumgr/smp_svr \
            -- \
            -DEXTRA_CONF_FILE=overlay-bt.conf

   .. group-tab:: Serial

      To build the serial sample with file-system and shell management support:

      .. code-block:: console

         west build \
            -b frdm_k64f \
            samples/subsys/mgmt/mcumgr/smp_svr \
            -- \
            -DEXTRA_CONF_FILE='overlay-serial.conf;overlay-fs.conf;overlay-shell-mgmt.conf'

   .. group-tab:: USB CDC_ACM

      To build the serial sample with USB CDC_ACM backend:

      .. code-block:: console

         west build \
            -b nrf52840dk/nrf52840 \
            samples/subsys/mgmt/mcumgr/smp_svr \
            -- \
            -DEXTRA_CONF_FILE=overlay-cdc.conf \
            -DDTC_OVERLAY_FILE=usb.overlay

   .. group-tab:: Shell

      To build the shell sample:

      .. code-block:: console

         west build \
            -b frdm_k64f \
            samples/subsys/mgmt/mcumgr/smp_svr \
            -- \
            -DEXTRA_CONF_FILE='overlay-shell.conf'

   .. group-tab:: UDP

      The UDP transport for SMP supports both IPv4 and IPv6.
      In the sample, both IPv4 and IPv6 are enabled, but they can be
      enabled and disabled separately.

      To build the UDP sample:

      .. code-block:: console

         west build \
            -b frdm_k64f \
            samples/subsys/mgmt/mcumgr/smp_svr \
            -- \
            -DEXTRA_CONF_FILE=overlay-udp.conf

.. _smp_svr_sample_sign:

Signing the sample image
************************

A key feature of MCUboot is that images must be signed before they can be successfully
uploaded and run on a target. To sign images, the MCUboot tool :file:`imgtool` can be used.

To sign the sample image built in the previous step:

.. code-block:: console

    west sign -t imgtool -- --key bootloader/mcuboot/root-rsa-2048.pem

The above command creates an image file called :file:`zephyr.signed.bin` in the
build directory.

For more information on image signing and ``west sign``, see the :ref:`west-sign`
documentation.

Flashing the sample image
*************************

Upload the :file:`zephyr.signed.bin` file from the previous to image slot-0 of your
board.  See :ref:`flash_map_api` for details on flash partitioning.

To upload the initial image file to an empty slot-0, use ``west flash`` like normal.
``west flash`` will automatically detect slot-0 address and confirm the image.

.. code-block:: console

    west flash --bin-file build/zephyr/zephyr.signed.bin

The *signed* image file needs to be used specifically, otherwise the non-signed version
will be used and the image won't be runnable.

Sample image: hello world!
==========================

The ``smp_svr`` app is ready to run.  Just reset your board and test the app
with your choice of tool's ``echo`` functionality, which will
send a string to the remote target device and have it echo it back.

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 Nordic
``nrf52840dk``) 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.

Device Firmware Upgrade (DFU)
*****************************

Now that the SMP server is running on your board and you are able to communicate
with it using :file:`mcumgr`, you might want to test what is commonly called
"OTA DFU", or Over-The-Air Device Firmware Upgrade. This works for both BT and UDP.

The general sequence of a DFU process is as follows:

* Build an MCUboot enabled application, see :ref:`smp_svr_sample_build`
* Sign the application image, see :ref:`smp_svr_sample_sign`
* Upload the signed image using :file:`mcumgr`
* Listing the images on the device using :file:`mcumgr`
* Mark the uploaded image for testing using :file:`mcumgr`
* Reset the device remotely using :file:`mcumgr`
* Confirm the uploaded image using :file:`mcumgr` (optional)

Direct image upload and Image mapping to MCUboot slot
=====================================================

Currently the mcumgr supports, for direct upload, 4 target images, of which first two are mapped
into MCUboot primary (slot-0) and secondary (slot-1) respectively.

For clarity, here is DTS label to slot to ``<image>`` translation table:

    +-----------+--------+------------+
    | DTS label | Slot   | -n <image> |
    +===========+========+============+
    | "image-0" | slot-0 |     1      |
    +-----------+--------+------------+
    | "image-1" | slot-1 |     0, 1   |
    +-----------+--------+------------+
    | "image-2" |        |     2      |
    +-----------+--------+------------+
    | "image-3" |        |     3      |
    +-----------+--------+------------+

Upload the signed image
=======================

To upload the signed image, refer to the documentation for your chosen tool, select the new
firmware file to upload and begin the upload.

.. note::

   At the beginning of the upload process, the target might start erasing
   the image slot, taking several dozen seconds for some targets.

List the images
===============

A list of images (slot-0 and slot-1) that are present can now be obtained on the remote target device using
the tool of your choice, which should print the status and hash values of each of the images
present.

Test the image
==============

In order to instruct MCUboot to swap the images, the image needs to be tested first, making sure it
boots, see the instructions in the tool of your choice. Upon reboot, MCUBoot will swap to the new
image.

.. note::
   There is not yet any way of getting the image hash without actually uploading the
   image and getting the hash.

Reset remotely
==============

The device can be reset remotely to observe (use the console output) how MCUboot swaps the images,
check the documentation in the tool of your choice. Upon reset MCUboot will swap slot-0 and
slot-1.

Confirm new image
=================

The new image is now loaded into slot-0, but it will be swapped back into slot-1 on the next
reset unless the image is confirmed. Confirm the image using the tool of your choice.

Note that if you try to send the very same image that is already flashed in
slot-0 then the procedure will not complete successfully since the hash values
for both slots will be identical.

Download file from File System
******************************

SMP server supports downloading files from File System on device via
:file:`mcumgr`. This is useful with FS log backend, when files are stored in
non-volatile memory. Build and flash both MCUboot and smp_svr applications and
then use the tool of your choice to download files from the file system.

Part 3

한국어 전문 번역

개요

이 sample application은 Simple Management Protocol(SMP) server를 구현합니다. SMP는 MCUmgr management protocol에서 사용하는 기본 transfer encoding입니다.

기본 설정은 Shell, Bluetooth, UDP transport를 지원합니다. smp_svr가 활성화하는 command group은 filesystem 관리용 fs_mgmt, image 관리용 img_mgmt, 운영체제 관리용 os_mgmt, 통계용 stat_mgmt, shell command 실행용 shell_mgmt입니다.

주의 사항

img_mgmt가 올바르게 동작하려면 MCUboot bootloader가 필요합니다. Device Firmware Upgrade(DFU), image slot과 signing 설정을 MCUboot build와 application build에서 일치시켜야 합니다.

사전 준비

도구 사용

Device의 management subsystem과 원격으로 통신하려면 SMP request를 만들고 응답을 해석할 client tool이 필요합니다. Management subsystem 문서의 MCUmgr tools and libraries 목록에서 원하는 transport와 기능을 지원하는 도구를 선택합니다.

BLE Controller 빌드

이 절은 Linux 사용자에게만 해당합니다. Bluetooth Low Energy(BLE) 내장 radio나 plug-in radio가 없는 상태에서 OTA DFU를 시험하려면, Zephyr Bluetooth HCI UART controller를 build해 BlueZ host와 함께 사용할 수 있습니다.

MCUboot 빌드 및 플래시

MCUboot의 Zephyr port는 일반 Zephyr application과 같은 방식으로 west를 사용해 build하고 flash할 수 있습니다. <board>는 sample.yaml에 명시된 지원 board 가운데 하나로 바꿉니다.

west build -b <board> -d build_mcuboot bootloader/mcuboot/boot/zephyr
west flash -d build_mcuboot

샘플 애플리케이션 빌드

smp_svr sample은 transport와 backend에 따라 여러 build flavor를 제공합니다.

Bluetooth: nrf52dk/nrf52832에서 BLE SMP transport를 활성화하는 overlay-bt.conf를 사용합니다.

west build \
   -b nrf52dk/nrf52832 \
   samples/subsys/mgmt/mcumgr/smp_svr \
   -- \
   -DEXTRA_CONF_FILE=overlay-bt.conf

Serial: frdm_k64f에서 serial transport와 filesystem·shell management를 함께 활성화합니다. 여러 extra configuration file은 semicolon으로 연결합니다.

west build \
   -b frdm_k64f \
   samples/subsys/mgmt/mcumgr/smp_svr \
   -- \
   -DEXTRA_CONF_FILE='overlay-serial.conf;overlay-fs.conf;overlay-shell-mgmt.conf'

USB CDC_ACM: nrf52840dk/nrf52840에서 CDC ACM serial backend와 usb.overlay devicetree overlay를 사용합니다.

west build \
   -b nrf52840dk/nrf52840 \
   samples/subsys/mgmt/mcumgr/smp_svr \
   -- \
   -DEXTRA_CONF_FILE=overlay-cdc.conf \
   -DDTC_OVERLAY_FILE=usb.overlay

Shell: frdm_k64f에서 shell transport를 활성화하는 overlay-shell.conf를 사용합니다.

west build \
   -b frdm_k64f \
   samples/subsys/mgmt/mcumgr/smp_svr \
   -- \
   -DEXTRA_CONF_FILE='overlay-shell.conf'

UDP: SMP UDP transport는 IPv4와 IPv6를 모두 지원합니다. Sample은 두 protocol을 모두 활성화하지만 각각 독립적으로 켜거나 끌 수 있습니다.

west build \
   -b frdm_k64f \
   samples/subsys/mgmt/mcumgr/smp_svr \
   -- \
   -DEXTRA_CONF_FILE=overlay-udp.conf

샘플 이미지 서명

MCUboot의 핵심 조건은 target에 upload하고 실행할 image가 미리 서명되어 있어야 한다는 점입니다. MCUboot의 imgtool을 호출하는 west sign으로 앞 단계의 application image를 서명합니다.

west sign -t imgtool -- --key bootloader/mcuboot/root-rsa-2048.pem

이 command는 build directory에 zephyr.signed.bin을 만듭니다. 사용한 root-rsa-2048.pem private key는 MCUboot가 포함한 public key와 대응해야 합니다.

샘플 이미지 플래시

앞 단계의 zephyr.signed.bin을 board의 primary image slot인 slot 0에 올립니다. 빈 slot 0에 처음 설치할 때는 일반 west flash를 사용할 수 있으며, tool이 slot 0 address를 자동으로 찾아 image를 confirmed 상태로 만듭니다.

west flash --bin-file build/zephyr/zephyr.signed.bin

반드시 signed image file을 지정해야 합니다. 서명되지 않은 기본 image가 flash되면 MCUboot 검증을 통과하지 못해 실행할 수 없습니다.

샘플 이미지: Hello World

이제 smp_svr application을 실행할 수 있습니다. Board를 reset한 뒤 선택한 client tool의 echo 기능으로 문자열을 remote target에 보내고 같은 문자열이 되돌아오는지 확인합니다.

J-Link Virtual MSD 상호작용 참고

CDC와 MSC를 모두 지원하는 J-Link OB가 장착된 board에서는 virtual Mass Storage Device(MSD, drag-and-drop) 기능이 CDC UART의 mcumgr command를 방해할 수 있습니다. J-Link firmware의 USB endpoint 구성 때문에 maximum packet size가 제한되는 현상이며, nrf52840dk에서 firmware update용 image management command를 보낼 때 특히 나타날 가능성이 큽니다.

이 문제가 발생하면 J-Link device의 MSD 기능을 끕니다. Nordic SEGGER MSD disable 절차를 따라 MSC endpoint를 비활성화한 뒤 CDC UART transport를 다시 시험합니다.

Device Firmware Upgrade(DFU)

Board에서 SMP server가 실행되고 mcumgr client와 통신할 수 있다면 OTA DFU를 시험할 수 있습니다. 이 흐름은 Bluetooth와 UDP transport 모두에서 동작합니다.

일반적인 DFU 순서는 MCUboot-enabled application build → application image signing → signed image upload → device image 목록과 hash 확인 → uploaded image를 test 상태로 표시 → remote reset → 새 image confirm(선택)입니다.

직접 이미지 업로드와 MCUboot 슬롯 매핑

현재 mcumgr direct upload는 target image 네 개를 지원합니다. 앞의 두 image는 각각 MCUboot primary slot(slot 0)과 secondary slot(slot 1)에 mapping됩니다. Tool의 -n <image> 번호는 DTS label과 다음처럼 연결됩니다.

DTS labelSlot-n <image>
image-0slot 01
image-1slot 10, 1
image-2지정 없음2
image-3지정 없음3

서명된 이미지 업로드

선택한 client tool의 문서에 따라 새 signed firmware file을 지정하고 upload를 시작합니다. Upload가 시작될 때 target이 image slot을 먼저 erase할 수 있으며, 일부 target에서는 이 작업에 수십 초가 걸립니다.

이미지 목록 조회

Client tool로 remote target의 slot 0과 slot 1 image 목록을 가져옵니다. 각 image의 상태와 hash 값이 표시되어 upload 결과 및 이후 test·confirm 대상의 identity를 확인할 수 있어야 합니다.

이미지 테스트

MCUboot가 image를 swap하도록 하려면 먼저 uploaded image를 test 대상으로 표시해야 합니다. Client tool의 image test 절차를 사용하면 다음 reboot에서 MCUboot가 새 image로 전환합니다.

현재는 image를 실제로 upload하고 device에서 조회하기 전에는 image hash를 얻을 방법이 없습니다. 따라서 tool이 요구하는 hash는 upload 이후 image list 결과에서 가져옵니다.

원격 리셋

Client tool로 device를 remote reset하고 console output에서 MCUboot가 image를 바꾸는 과정을 관찰합니다. Reset 시 MCUboot는 slot 0과 slot 1의 image를 swap합니다.

새 이미지 확인

새 image는 이제 slot 0에서 실행되지만 confirm하지 않으면 다음 reset 때 slot 1로 되돌아갑니다. 선택한 tool로 새 image를 confirm해 permanent 상태로 만듭니다.

이미 slot 0에 flash된 것과 완전히 같은 image를 다시 보내면 두 slot의 hash가 같아져 절차가 성공적으로 완료되지 않습니다. 새 build 또는 다른 version의 signed image를 사용해야 합니다.

파일 시스템에서 파일 다운로드

SMP server는 mcumgr를 통해 device filesystem의 file을 download하는 기능도 지원합니다. Non-volatile memory에 log file을 저장하는 filesystem log backend와 함께 사용할 때 유용합니다. MCUboot와 smp_svr application을 모두 build·flash한 뒤 선택한 tool의 filesystem download 기능을 사용합니다.

Source

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.