uploaded 1 year ago
Serial flasher component provides portable library for flashing or loading ram loadble app to Espressif SoCs from other host microcontroller

readme

# Serial flasher

## Overview

Serial flasher component provides portable library for flashing or loading ram loadble app to Espressif SoCs from other host microcontroller. Espressif SoCs are normally programmed via serial interface (UART). Port layer for given host microcontroller has to be implemented, if not available. Details can be found in section below.

Supported **host** microcontrollers:

- STM32
- Raspberry Pi
- ESP32
- MCU running Zephyr OS

Supported **target** microcontrollers:

- ESP32
- ESP8266
- ESP32-S2
- ESP32-S3
- ESP32-C3
- ESP32-C2
- ESP32-H4 (Beta1 and Beta2)

## Supporting new host target

In order to support new target, following function has to be implemented by user:

- loader_port_serial_read()
- loader_port_serial_write()
- loader_port_enter_bootloader()
- loader_port_delay_ms()
- loader_port_start_timer()
- loader_port_remaining_time()

Following functions are part of serial_io.h header for convenience, however, user does not have to strictly follow function signatures, as there are not called directly from library.

- loader_port_change_baudrate()
- loader_port_reset_target()
- loader_port_debug_print()

Prototypes of all function mentioned above can be found in [serial_io.h](include/serial_io.h).
Please refer to ports in `port` directory. Currently, only ports for [ESP32 port](port/esp32_port.c), [STM32 port](port/stm32_port.c), and [Zephyr port](port/zephyr_port.c) are available.

## Configuration

These are the configuration toggles available to the user:
* MD5_ENABLED

If enabled, serial flasher is capable of verifying flash integrity after writing to memory.

Default: Enabled
> Warning: As ROM bootloader of ESP8266 does not support MD5_CHECK, this option has to be disabled!

* SERIAL_FLASHER_RESET_HOLD_TIME_MS

This is the time for which the reset pin is asserted when doing a hard reset in milliseconds.

Default: 100

* SERIAL_FLASHER_BOOT_HOLD_TIME_MS

This is the time for which the boot pin is asserted when doing a hard reset in milliseconds.

Default: 50

Configuration can be passed to `cmake` via command line:

```
cmake -DMD5_ENABLED=1 .. && cmake --build .
```

### STM32 support

STM32 port make use of STM32 HAL libraries, that does not come with CMake support. In order to compile the project, `stm32-cmake` (`cmake` support package) has to be pulled as submodule.

```
git clone --recursive https://github.com/espressif/esp-serial-flasher.git
```

If you have cloned this repository without the `--recursive` flag, you can initialize the submodule using the following command:

```
git submodule update --init
```

In addition to configuration parameters mentioned above, following definitions has to be set:

- TOOLCHAIN_PREFIX: path to arm toolchain (i.e /home/user/gcc-arm-none-eabi-9-2019-q4-major)
- STM32Cube_DIR: path to STM32 Cube libraries (i.e /home/user/STM32Cube/Repository/STM32Cube_FW_F4_V1.25.0)
- STM32_CHIP: name of STM32 for which project should be compiled (i.e STM32F407VG)
- PORT: STM32

This can be achieved by passing definition to command line, such as:

```
cmake -DTOOLCHAIN_PREFIX="/path_to_toolchain" -DSTM32Cube_DIR="path_to_stm32Cube" -DSTM32_CHIP="STM32F407VG" -DPORT="STM32" .. && cmake --build .
```

Alternatively, set those variables in top level `cmake` directory:

```
set(TOOLCHAIN_PREFIX    path_to_toolchain)
set(STM32Cube_DIR       path_to_stm32_HAL)
set(STM32_CHIP          STM32F407VG)
set(PORT                STM32)
```

### Zephyr support

The Zephyr port is ready to be integrated into your Zephyr app as a Zephyr module. In the manifest file (west.yml), add:

```
    - name: esp-flasher
      url: https://github.com/espressif/esp-serial-flasher
      revision: master
      path: modules/lib/esp_flasher
```

And add

```
CONFIG_ESP_SERIAL_FLASHER=y
CONFIG_CONSOLE_GETCHAR=y
CONFIG_SERIAL_FLASHER_MD5_ENABLED=y
```

to your project configuration `prj.conf`.

For your C/C++ source code, you can use the example code provided in `examples/zephyr_example` as a starting point.

## Licence

Code is distributed under Apache 2.0 license.

## Known limitations

Size of new binary image has to be known before flashing.

readme of esp32_example example

                                        
                                        # Flash multiple partitions example

## Overview

Example demonstrates how to flash ESP32/ESP32-S2/ESP8266 from another (host) MCU using esp_serial_flash component API. In this case, ESP32 is also used as host MCU. Binaries to be flashed from host MCU to another Espressif SoC can be found in `binaries` folder and are converted into C-array during build process.

Following steps are performed in order to re-program target's memory:

1. Filesystem is initialized and mounted.
2. UART1 through which new binary will be transfered is initialized.
3. Host puts slave device into boot mode tries to connect by calling `esp_loader_connect()`.
4. Binary file is opened and its size is acquired, as it has to be known before flashing.
5. Then `esp_loader_flash_start()` is called to enter flashing mode and erase amount of memory to be flashed.
6. `esp_loader_flash_write()` function is called repeatedly until the whole binary image is transfered.

Note: In addition, to steps mentioned above, `esp_loader_change_baudrate`  is called after connection is established in order to increase flashing speed. This does not apply for ESP8266, as its bootloader does not support this command. However, ESP8266 is capable of detecting baud rate during connection phase, and can be changed before calling `esp_loader_connect`, if necessary.

## SPI pin initialization

In majority of cases `ESP_LOADER_CONNECT_DEFAULT` helper macro is used in order to initialize `loader_connect_args_t` data structure passed to `esp_loader_connect`. Helper macro sets `spi_pin_config` field of the data structure to zero, thus, default SPI pins are used to connect to FLASH memory. In special cases, such as custom design in which FLASH is connected to different pins, `spi_pin_config` field has to be set accordingly. For more detailed information refer to [serial protocol](https://docs.espressif.com/projects/esptool/en/latest/esp32s3/advanced-topics/serial-protocol.html).

## Hardware Required

* Two development boards with ESP32 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.).
* One or two USB cables for power supply and programming.

## Hardware connection

Table below shows connection between two ESP32 devices.

| ESP32 (host) | ESP32 (slave) |
|:------------:|:-------------:|
|    IO26      |      IO0      |
|    IO25      |     RESET     |
|    IO4       |      RX0      |
|    IO5       |      TX0      |

Note: interconnection is the same for all three targets (slaves). 

## Build and flash

To run the example, type the following command:

```CMake
idf.py -p PORT flash monitor
```

(To exit the serial monitor, type ``Ctrl-]``.)

See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

## Configuration

For details about available configuration option, please refer to top level [README.md](../../README.md). 
Compile definitions can be specified on command line when running `idf.py`, for example:

```
idf.py build -DMD5_ENABLED=1
```
Binaries to be flashed are placed in separate folder (binaries.c) for each possible target and converted to C-array. Without explicitly enabling MD5 check, flash integrity verification is disabled by default.

## Example output

Here is the example's console output:

```
...
I (342) example: Initializing SPIFFS
I (482) example: Image size: 144672
I (902) example: Connected to target
I (1732) example: Start programming
I (1832) example: packet: 0  written: 1024 B
I (1932) example: packet: 1  written: 1024 B
...
I (16052) example: packet: 140  written: 1024 B
I (16152) example: packet: 141  written: 288 B
I (16152) example: Finished programming
```

                                    

Links

Supports all targets

License: Apache-2.0

To add this component to your project, run:

idf.py add-dependency "espressif/esp-serial-flasher^0.0.7"

or download archive

Examples:

esp32_example

more details

To create a project from this example, run:

idf.py create-project-from-example "espressif/esp-serial-flasher^0.0.7:esp32_example"

or download archive

esp32_load_ram_example

To create a project from this example, run:

idf.py create-project-from-example "espressif/esp-serial-flasher^0.0.7:esp32_load_ram_example"

or download archive

Stats

  • Downloaded in total
    Downloaded in total 46.3k times
  • Downloaded this version
    This version: 311 times

Badge

espressif/esp-serial-flasher version: 0.0.7
|