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:
Supported target microcontrollers:
In order to support new target, following function has to be implemented by user:
Following functions are part of io.h header for convenience, however, user does not have to strictly follow function signatures, as there are not called directly from library.
Prototypes of all function mentioned above can be found in io.h.
Please refer to ports in port
directory. Currently, ports for ESP32, STM32, and Zephyr are available.
These are the configuration toggles available to the user:
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!
This is the time for which the reset pin is asserted when doing a hard reset in milliseconds.
Default: 100
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 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:
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)
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.
Code is distributed under Apache 2.0 license.
Size of new binary image has to be known before flashing.
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:
esp_loader_connect()
.esp_loader_flash_start()
is called to enter flashing mode and erase amount of memory to be flashed.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_transmission_rate
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.
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.
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).
To run the example, type the following command:
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.
For details about available configuration option, please refer to top level 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.
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
Copy to Clipboard
idf.py add-dependency "espressif/esp-serial-flasher^0.0.11"
To create a project from this example, run:
Copy to Clipboard
idf.py create-project-from-example "espressif/esp-serial-flasher^0.0.11:binaries/RAM_APP/source"
To create a project from this example, run:
Copy to Clipboard
idf.py create-project-from-example "espressif/esp-serial-flasher^0.0.11:esp32_example"
To create a project from this example, run:
Copy to Clipboard
idf.py create-project-from-example "espressif/esp-serial-flasher^0.0.11:esp32_load_ram_example"
Copy to Clipboard
Copy to Clipboard