Skip to content

Latest commit

 

History

History
123 lines (89 loc) · 4.11 KB

README.md

File metadata and controls

123 lines (89 loc) · 4.11 KB
Raw

esp-flasher-stub

GitHub Workflow Status MSRV Matrix

Rust implementation of the esptool flasher stub.

Supports the ESP32, ESP32-C2/C3/C6, ESP32-H2, and ESP32-S2/S3. Currently, UART and USB Serial JTAG are the supported transport modes, and support for other modes is planned.

Quickstart

To ease the building process we have included a build subcommand in the xtask package which will apply all the appropriate build configurations for one or more devices:

cd xtask/
cargo run -- build esp32
cargo run -- build esp32c2 esp32c3

In order to build the flasher stub manually, you must specify the appropriate toolchain, provide a feature to cargo selecting the device, and additionally specify the target:

# ESP32
cargo +esp build --release --features=esp32 --target=xtensa-esp32-none-elf

# ESP32-C2
cargo +nightly build --release --features=esp32c2 --target=riscv32imc-unknown-none-elf

# ESP32-C3
cargo +nightly build --release --features=esp32c3 --target=riscv32imc-unknown-none-elf

# ESP32-C6
cargo +nightly build --release --features=esp32c6 --target=riscv32imac-unknown-none-elf

# ESP32-H2
cargo +nightly build --release --features=esp32h2 --target=riscv32imac-unknown-none-elf

# ESP32-S2
cargo +esp build --release --features=esp32s2 --target=xtensa-esp32s2-none-elf

# ESP32-S3
cargo +esp build --release --features=esp32s3 --target=xtensa-esp32s3-none-elf

In order to generate the JSON and TOML stub files for one or more devices, you can again use the xtask package:

cd xtask/
cargo run -- wrap esp32c3
cargo run -- wrap esp32 esp32s2 esp32s3

JSON stub files will be generated in the project root directory.

Testing

In order to run test_esptool.py follow steps below:

  • Build esp-flasher-stub as described in the section above.
  • Clone esptool, if you don't have it yet: 
    git clone https://github.com/espressif/esptool
  • Copy the stub JSON files into esptool installation. You can use the following one-liner: 
    for n in esp*.json; do cp $n $ESPTOOL_PATH/esptool/targets/stub_flasher/2/$n; done
    where ESPTOOL_PATH is set to the location where you have cloned esptool.
  • Set ESPTOOL_STUB_VERSION environment variable to 2.
  • Run tests 
    cd $ESPTOOL_PATH/test
pytest test_esptool.py --port /dev/ttyUSB0 --chip esp32 --baud 115200

Debug logs

In order to add debug logs, you can use the --dprint flag available in the xtask package for build and wrap commands:

cd xtask/
cargo run -- wrap esp32c3 --dprint
cargo run -- build esp32 esp32s2 esp32s3 --dprint

In order to add debug logs when building the flasher stub manually you have to build the project with dprint feature, for example:

cargo build --release --target=riscv32imc-unknown-none-elf --features=esp32c3,dprint

This will print esp-flasher-stub debug messages using UART1. By default, esp-flasher-stub uses the following pins:

  • TX: GPIO 2
  • RX: GPIO 0

Then you can view logs using, for example, screen:

screen /dev/ttyUSB2 115200

Warning

For ESP32 and ESP32-S2, please use a baud rate of 57,600 instead:

screen /dev/ttyUSB2 57600

License

Licensed under either of:

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.