1<!--
2  - SPDX-License-Identifier: Apache-2.0
3
4  - Copyright (c) 2022 Nordic Semiconductor ASA
5
6  - Original license:
7
8  - Licensed to the Apache Software Foundation (ASF) under one
9  - or more contributor license agreements.  See the NOTICE file
10  - distributed with this work for additional information
11  - regarding copyright ownership.  The ASF licenses this file
12  - to you under the Apache License, Version 2.0 (the
13  - "License"); you may not use this file except in compliance
14  - with the License.  You may obtain a copy of the License at
15
16  -  http://www.apache.org/licenses/LICENSE-2.0
17
18  - Unless required by applicable law or agreed to in writing,
19  - software distributed under the License is distributed on an
20  - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21  - KIND, either express or implied.  See the License for the
22  - specific language governing permissions and limitations
23  - under the License.
24-->
25
26# Serial recovery
27
28MCUboot implements a Simple Management Protocol (SMP) server.
29SMP is a basic transfer encoding for use with the MCUmgr management protocol.
30See the Zephyr [Device Management](https://docs.zephyrproject.org/latest/services/device_mgmt/index.html#device-mgmt) documentation for more information about MCUmgr and SMP.
31
32MCUboot supports the following subset of the MCUmgr commands:
33* echo (OS group)
34* reset (OS group)
35* image list (IMG group)
36* image upload (IMG group)
37
38It can also support system-specific MCUmgr commands depending on the given mcuboot-port
39if the ``MCUBOOT_PERUSER_MGMT_GROUP_ENABLED`` option is enabled.
40
41The serial recovery feature can use any serial interface provided by the platform.
42
43## Image uploading
44
45Uploading an image is targeted to the primary slot by default.
46
47An image can be loaded to other slots only when the ``MCUBOOT_SERIAL_DIRECT_IMAGE_UPLOAD`` option is enabled for the platform.
48
49MCUboot supports progressive erasing of a slot to which an image is uploaded to if the ``MCUBOOT_ERASE_PROGRESSIVELY`` option is enabled.
50As a result, a device can receive images smoothly, and can erase required part of a flash automatically.
51
52## Configuration of serial recovery
53
54How to enable and configure the serial recovery feature depends on the given mcuboot-port implementation.
55Refer to the respective documentation and source code for more details.
56
57## Entering serial recovery mode
58
59Entering the serial recovery mode is usually possible right after a device reset, for instance as a reaction on a GPIO pin state.
60Refer to the given mcuboot-port details to get information on how to enter the serial recovery mode.
61
62## Serial recovery mode usage
63
64### MCU Manager CLI installation
65
66The MCUmgr command line tool can be used as an SMP client for evaluation purposes.
67The tool is available under the [MCU Manager](https://github.com/apache/mynewt-mcumgr-cli)
68Github page and is described in the Zephyr
69[MCU Manager CLI](https://docs.zephyrproject.org/latest/services/device_mgmt/mcumgr.html#mcumgr-cli) documentation.
70
71Use the following command to install the MCU Manager CLI tool:
72``` console
73go install github.com/apache/mynewt-mcumgr-cli/mcumgr@latest
74```
75Enter serial recovery mode in the device and use an SMP client application for communication with the MCUboot's SMP server.
76
77### Connection configuration
78
79Use the following command to set the connection configuration,
80for linux:
81``` console
82mcumgr conn add serial_1 type="serial" connstring="dev=/dev/ttyACM0,baud=115200"
83```
84for windows:
85``` console
86mcumgr conn add serial_1 type="serial" connstring="COM1,baud=115200"
87```
88
89### Image management
90
91The connection configuration must be established to perform the following image-related commands:
92
93* Upload the image:
94  ``` console
95  mcumgr image upload <path-to-signed-image-bin-file> -c serial_1
96  ```
97
98  Once done successfully, the following notification will be displayed:
99  ``` console
100  20.25 KiB / 20.25 KiB [=================================] 100.00% 3.08 KiB/s 6s
101  Done
102  ```
103
104* List all images:
105  ``` console
106  mcumgr image list -c serial_1
107  ```
108  The terminal will show the response from the module:
109  ``` console
110  Images:
111   image=0 slot=0
112      version: 0.0.0.0
113      bootable: false
114      flags:
115      hash: Unavailable
116  Split status: N/A (0)
117  ```
118
119### Device reset
120
121Reset your device with the following command:
122``` console
123mcumgr reset -c serial_1
124```
125The terminal should respond:
126``` console
127Done
128```
129