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 which can be used as a client for a Zephyr MCUmgr SMP
45server.
46
47Building a BLE Controller
48=========================
49
50.. note::
51   This section is only relevant for Linux users
52
53If you want to try out Device Firmware Upgrade (DFU) over the air using
54Bluetooth Low Energy (BLE) and do not have a built-in or pluggable BLE radio,
55you can build one and use it following the instructions in
56:ref:`bluetooth-hci-uart-bluez`.
57
58.. _smp_svr_sample_build:
59
60Building the sample application
61*******************************
62
63The below steps describe how to build and run the ``smp_svr`` sample in Zephyr with ``MCUboot``
64included. The ``smp_svr`` sample comes in different flavours.
65
66.. tabs::
67
68   .. group-tab:: Bluetooth
69
70      To build the bluetooth sample:
71
72      .. zephyr-app-commands::
73         :tool: west
74         :zephyr-app: samples/subsys/mgmt/mcumgr/smp_svr
75         :board: nrf52dk/nrf52832
76         :goals: build
77         :west-args: --sysbuild
78         :gen-args: -DEXTRA_CONF_FILE="overlay-bt.conf"
79         :compact:
80
81   .. group-tab:: Serial
82
83      To build the serial sample with file-system and shell management support:
84
85      .. zephyr-app-commands::
86         :tool: west
87         :zephyr-app: samples/subsys/mgmt/mcumgr/smp_svr
88         :board: frdm_k64f
89         :goals: build
90         :west-args: --sysbuild
91         :gen-args: -DEXTRA_CONF_FILE="overlay-serial.conf;overlay-fs.conf;overlay-shell-mgmt.conf"
92         :compact:
93
94   .. group-tab:: USB CDC_ACM
95
96      To build the serial sample with USB CDC_ACM backend:
97
98      .. zephyr-app-commands::
99         :tool: west
100         :zephyr-app: samples/subsys/mgmt/mcumgr/smp_svr
101         :board: nrf52840dk/nrf52840
102         :goals: build
103         :west-args: --sysbuild
104         :gen-args: -DEXTRA_CONF_FILE="overlay-cdc.conf" -DEXTRA_DTC_OVERLAY_FILE="usb.overlay"
105         :compact:
106
107   .. group-tab:: Shell
108
109      To build the shell sample:
110
111      .. zephyr-app-commands::
112         :tool: west
113         :zephyr-app: samples/subsys/mgmt/mcumgr/smp_svr
114         :board: frdm_k64f
115         :goals: build
116         :west-args: --sysbuild
117         :gen-args: -DEXTRA_CONF_FILE="overlay-shell.conf"
118         :compact:
119
120   .. group-tab:: UDP
121
122      The UDP transport for SMP supports both IPv4 and IPv6.
123      In the sample, both IPv4 and IPv6 are enabled, but they can be
124      enabled and disabled separately.
125
126      To build the UDP sample:
127
128      .. zephyr-app-commands::
129         :tool: west
130         :zephyr-app: samples/subsys/mgmt/mcumgr/smp_svr
131         :board: frdm_k64f
132         :goals: build
133         :west-args: --sysbuild
134         :gen-args: -DEXTRA_CONF_FILE="overlay-udp.conf"
135         :compact:
136
137Flashing the sample image
138*************************
139
140The original application will be built for slot-0, see :ref:`flash_map_api` for details on flash
141partitioning. Flash both MCUboot and the sample application:
142
143.. code-block:: console
144
145    west flash
146
147Sample image: hello world!
148==========================
149
150The ``smp_svr`` app is ready to run.  Just reset your board and test the app
151with your choice of tool's ``echo`` functionality, which will
152send a string to the remote target device and have it echo it back.
153
154J-Link Virtual MSD Interaction Note
155***********************************
156
157On boards where a J-Link OB is present which has both CDC and MSC (virtual Mass
158Storage Device, also known as drag-and-drop) support, the MSD functionality can
159prevent mcumgr commands over the CDC UART port from working due to how USB
160endpoints are configured in the J-Link firmware (for example on the Nordic
161``nrf52840dk``) because of limiting the maximum packet size (most likely to occur
162when using image management commands for updating firmware). This issue can be
163resolved by disabling MSD functionality on the J-Link device, follow the
164instructions on :ref:`nordic_segger_msd` to disable MSD support.
165
166Device Firmware Upgrade (DFU)
167*****************************
168
169Now that the SMP server is running on your board and you are able to communicate with it using a
170client, you might want to test what is commonly called "OTA DFU", or Over-The-Air Device Firmware
171Upgrade. This works for both BT and UDP.
172
173The general sequence of a DFU process is as follows:
174
175* Build an MCUboot enabled application using sysbuild, see :ref:`smp_svr_sample_build`
176* Upload the signed image using an MCUmgr client
177* Listing the images on the device using an MCUmgr client
178* Mark the uploaded image for testing using an MCUmgr client
179* Reset the device remotely using an MCUmgr client
180* Confirm the uploaded image using an MCUmgr client (optional)
181
182Direct image upload and Image mapping to MCUboot slot
183=====================================================
184
185Currently MCUmgr supports, for direct upload, 4 target images, of which first two are mapped
186into MCUboot primary (slot-0) and secondary (slot-1) respectively.
187
188For clarity, here is DTS label to slot to ``<image>`` translation table:
189
190    +-----------+--------+------------+
191    | DTS label | Slot   | -n <image> |
192    +===========+========+============+
193    | "image-0" | slot-0 |     1      |
194    +-----------+--------+------------+
195    | "image-1" | slot-1 |     0, 1   |
196    +-----------+--------+------------+
197    | "image-2" |        |     2      |
198    +-----------+--------+------------+
199    | "image-3" |        |     3      |
200    +-----------+--------+------------+
201
202.. note::
203
204   There is a slot info command that can be used to see information on all slots and get the
205   upload ``image`` ID to use to update that slot, see :ref:`mcumgr_smp_group_1_slot_info` for
206   details.
207
208Upload the signed image
209=======================
210
211To upload the signed image, refer to the documentation for your chosen tool, select the new
212firmware file to upload and begin the upload.
213
214.. note::
215
216   At the beginning of the upload process, the target might start erasing the image slot, taking
217   several dozen seconds for some targets.
218
219List the images
220===============
221
222A list of images (slot-0 and slot-1) that are present can now be obtained on the remote target
223device using the tool of your choice, which should print the status and hash values of each of
224the images present.
225
226Test the image
227==============
228
229In order to instruct MCUboot to swap the images, the image needs to be tested first, making sure it
230boots, see the instructions in the tool of your choice. Upon reboot, MCUBoot will swap to the new
231image.
232
233.. note::
234
235   Some tools may allow for listing the hash of an image without needing to upload them.
236   ``imgtool`` can also be used to list the image hash, albeit in a C hex-array format, by using
237   the ``dumpinfo`` command on the signed update file, e.g.
238
239   .. code-block:: console
240
241       imgtool dumpinfo smp_svr/zephyr/zephyr.signed.bin
242
243       Printing content of signed image: zephyr.signed.bin
244
245       #### Image header (offset: 0x0) ############################
246       magic:              0x96f3b83d
247       ...
248       #### TLV area (offset: 0xbfa0) #############################
249       magic:     0x6907
250       area size: 0x150
251               ---------------------------------------------
252               type: SHA256 (0x10)
253               len:  0x20
254               data: 0x9b 0xa9 0x84 0x48 0xe5 0x4d 0xac 0x40
255                     0x62 0x29 0xe2 0x11 0x17 0x96 0x66 0xd9
256                     0xae 0x83 0x9a 0x37 0x71 0x00 0xfc 0xe2
257                     0xc0 0x30 0x30 0x4f 0xfc 0x40 0x58 0xaa
258               ---------------------------------------------
259       ...
260
261   The full SHA256 hash for the above output would be:
262   9ba98448e54dac406229e211179666d9ae839a377100fce2c030304ffc4058aa
263
264Reset remotely
265==============
266
267The device can be reset remotely to observe (use the console output) how MCUboot swaps the images,
268check the documentation in the tool of your choice. Upon reset MCUboot will swap slot-0 and
269slot-1.
270
271Confirm new image
272=================
273
274The new image is now loaded into slot-0, but it will be swapped back into slot-1 on the next
275reset unless the image is confirmed. Confirm the image using the tool of your choice.
276
277.. note::
278
279   If you try to send the very same image that is already flashed in slot-0 then the procedure
280   will not complete successfully since the hash values for both slots will be identical.
281
282Download files from/upload files to file system
283***********************************************
284
285SMP server supports downloading files from/uploading files to the on-device
286:ref:`file_system_api`, this is useful with e.g. FS log backend, when files are stored in
287non-volatile memory. Build and flash ``smp_svr`` using sysbuild and then use the tool of your
288choice to download files from the file system. The full path of the file on the device must be
289known and used.
290