1:orphan:
2
3.. zephyr:code-sample:: smp-svr
4   :name: SMP server
5
6   Implement a Simple Management Protocol (SMP) server.
7
8Overview
9********
10
11This sample application implements a Simple Management Protocol (SMP) server.
12SMP is a basic transfer encoding for use with the MCUmgr management protocol.
13For more information about MCUmgr and SMP, please see :ref:`device_mgmt`.
14
15This sample application supports the following mcumgr transports by default:
16
17    * Shell
18    * Bluetooth
19    * UDP
20
21``smp_svr`` enables support for the following command groups:
22
23    * ``fs_mgmt``
24    * ``img_mgmt``
25    * ``os_mgmt``
26    * ``stat_mgmt``
27    * ``shell_mgmt``
28
29Caveats
30*******
31
32* The MCUboot bootloader is required for ``img_mgmt`` to function
33  properly. More information about the Device Firmware Upgrade subsystem and
34  MCUboot can be found in :ref:`mcuboot`.
35
36Prerequisites
37*************
38
39Use of a tool
40=============
41
42To interact remotely with the management subsystem on a device, a tool is required to interact with
43it. There are various tools available which are listed on the :ref:`mcumgr_tools_libraries` page
44of the Management subsystem documentation.
45
46Building a BLE Controller
47=========================
48
49.. note::
50   This section is only relevant for Linux users
51
52If you want to try out Device Firmware Upgrade (DFU) over the air using
53Bluetooth Low Energy (BLE) and do not have a built-in or pluggable BLE radio,
54you can build one and use it following the instructions in
55:ref:`bluetooth-hci-uart-bluez`.
56
57Building and flashing MCUboot
58*****************************
59
60The below steps describe how to build and run the MCUboot bootloader.
61Detailed instructions can be found in the :ref:`mcuboot` documentation page.
62
63The Zephyr port of MCUboot is essentially a normal Zephyr application, which means that
64it can be built and flashed like normal using ``west``, like so:
65
66.. code-block:: console
67
68   west build -b <board> -d build_mcuboot bootloader/mcuboot/boot/zephyr
69   west flash -d build_mcuboot
70
71Substitute <board> for one of the boards supported by the sample, see
72:file:`sample.yaml`.
73
74.. _smp_svr_sample_build:
75
76Building the sample application
77*******************************
78
79The below steps describe how to build and run the ``smp_svr`` sample in
80Zephyr. The ``smp_svr`` sample comes in different flavours.
81
82.. tabs::
83
84   .. group-tab:: Bluetooth
85
86      To build the bluetooth sample:
87
88      .. code-block:: console
89
90         west build \
91            -b nrf52dk/nrf52832 \
92            samples/subsys/mgmt/mcumgr/smp_svr \
93            -- \
94            -DEXTRA_CONF_FILE=overlay-bt.conf
95
96   .. group-tab:: Serial
97
98      To build the serial sample with file-system and shell management support:
99
100      .. code-block:: console
101
102         west build \
103            -b frdm_k64f \
104            samples/subsys/mgmt/mcumgr/smp_svr \
105            -- \
106            -DEXTRA_CONF_FILE='overlay-serial.conf;overlay-fs.conf;overlay-shell-mgmt.conf'
107
108   .. group-tab:: USB CDC_ACM
109
110      To build the serial sample with USB CDC_ACM backend:
111
112      .. code-block:: console
113
114         west build \
115            -b nrf52840dk/nrf52840 \
116            samples/subsys/mgmt/mcumgr/smp_svr \
117            -- \
118            -DEXTRA_CONF_FILE=overlay-cdc.conf \
119            -DDTC_OVERLAY_FILE=usb.overlay
120
121   .. group-tab:: Shell
122
123      To build the shell sample:
124
125      .. code-block:: console
126
127         west build \
128            -b frdm_k64f \
129            samples/subsys/mgmt/mcumgr/smp_svr \
130            -- \
131            -DEXTRA_CONF_FILE='overlay-shell.conf'
132
133   .. group-tab:: UDP
134
135      The UDP transport for SMP supports both IPv4 and IPv6.
136      In the sample, both IPv4 and IPv6 are enabled, but they can be
137      enabled and disabled separately.
138
139      To build the UDP sample:
140
141      .. code-block:: console
142
143         west build \
144            -b frdm_k64f \
145            samples/subsys/mgmt/mcumgr/smp_svr \
146            -- \
147            -DEXTRA_CONF_FILE=overlay-udp.conf
148
149.. _smp_svr_sample_sign:
150
151Signing the sample image
152************************
153
154A key feature of MCUboot is that images must be signed before they can be successfully
155uploaded and run on a target. To sign images, the MCUboot tool :file:`imgtool` can be used.
156
157To sign the sample image built in the previous step:
158
159.. code-block:: console
160
161    west sign -t imgtool -- --key bootloader/mcuboot/root-rsa-2048.pem
162
163The above command creates an image file called :file:`zephyr.signed.bin` in the
164build directory.
165
166For more information on image signing and ``west sign``, see the :ref:`west-sign`
167documentation.
168
169Flashing the sample image
170*************************
171
172Upload the :file:`zephyr.signed.bin` file from the previous to image slot-0 of your
173board.  See :ref:`flash_map_api` for details on flash partitioning.
174
175To upload the initial image file to an empty slot-0, use ``west flash`` like normal.
176``west flash`` will automatically detect slot-0 address and confirm the image.
177
178.. code-block:: console
179
180    west flash --bin-file build/zephyr/zephyr.signed.bin
181
182The *signed* image file needs to be used specifically, otherwise the non-signed version
183will be used and the image won't be runnable.
184
185Sample image: hello world!
186==========================
187
188The ``smp_svr`` app is ready to run.  Just reset your board and test the app
189with your choice of tool's ``echo`` functionality, which will
190send a string to the remote target device and have it echo it back.
191
192J-Link Virtual MSD Interaction Note
193***********************************
194
195On boards where a J-Link OB is present which has both CDC and MSC (virtual Mass
196Storage Device, also known as drag-and-drop) support, the MSD functionality can
197prevent mcumgr commands over the CDC UART port from working due to how USB
198endpoints are configured in the J-Link firmware (for example on the Nordic
199``nrf52840dk``) because of limiting the maximum packet size (most likely to occur
200when using image management commands for updating firmware). This issue can be
201resolved by disabling MSD functionality on the J-Link device, follow the
202instructions on :ref:`nordic_segger_msd` to disable MSD support.
203
204Device Firmware Upgrade (DFU)
205*****************************
206
207Now that the SMP server is running on your board and you are able to communicate
208with it using :file:`mcumgr`, you might want to test what is commonly called
209"OTA DFU", or Over-The-Air Device Firmware Upgrade. This works for both BT and UDP.
210
211The general sequence of a DFU process is as follows:
212
213* Build an MCUboot enabled application, see :ref:`smp_svr_sample_build`
214* Sign the application image, see :ref:`smp_svr_sample_sign`
215* Upload the signed image using :file:`mcumgr`
216* Listing the images on the device using :file:`mcumgr`
217* Mark the uploaded image for testing using :file:`mcumgr`
218* Reset the device remotely using :file:`mcumgr`
219* Confirm the uploaded image using :file:`mcumgr` (optional)
220
221Direct image upload and Image mapping to MCUboot slot
222=====================================================
223
224Currently the mcumgr supports, for direct upload, 4 target images, of which first two are mapped
225into MCUboot primary (slot-0) and secondary (slot-1) respectively.
226
227For clarity, here is DTS label to slot to ``<image>`` translation table:
228
229    +-----------+--------+------------+
230    | DTS label | Slot   | -n <image> |
231    +===========+========+============+
232    | "image-0" | slot-0 |     1      |
233    +-----------+--------+------------+
234    | "image-1" | slot-1 |     0, 1   |
235    +-----------+--------+------------+
236    | "image-2" |        |     2      |
237    +-----------+--------+------------+
238    | "image-3" |        |     3      |
239    +-----------+--------+------------+
240
241Upload the signed image
242=======================
243
244To upload the signed image, refer to the documentation for your chosen tool, select the new
245firmware file to upload and begin the upload.
246
247.. note::
248
249   At the beginning of the upload process, the target might start erasing
250   the image slot, taking several dozen seconds for some targets.
251
252List the images
253===============
254
255A list of images (slot-0 and slot-1) that are present can now be obtained on the remote target device using
256the tool of your choice, which should print the status and hash values of each of the images
257present.
258
259Test the image
260==============
261
262In order to instruct MCUboot to swap the images, the image needs to be tested first, making sure it
263boots, see the instructions in the tool of your choice. Upon reboot, MCUBoot will swap to the new
264image.
265
266.. note::
267   There is not yet any way of getting the image hash without actually uploading the
268   image and getting the hash.
269
270Reset remotely
271==============
272
273The device can be reset remotely to observe (use the console output) how MCUboot swaps the images,
274check the documentation in the tool of your choice. Upon reset MCUboot will swap slot-0 and
275slot-1.
276
277Confirm new image
278=================
279
280The new image is now loaded into slot-0, but it will be swapped back into slot-1 on the next
281reset unless the image is confirmed. Confirm the image using the tool of your choice.
282
283Note that if you try to send the very same image that is already flashed in
284slot-0 then the procedure will not complete successfully since the hash values
285for both slots will be identical.
286
287Download file from File System
288******************************
289
290SMP server supports downloading files from File System on device via
291:file:`mcumgr`. This is useful with FS log backend, when files are stored in
292non-volatile memory. Build and flash both MCUboot and smp_svr applications and
293then use the tool of your choice to download files from the file system.
294