1This is the source of the software flasher stub.
2
3esptool.py loads the flasher stub into memory and executes it to:
4
5* Add features that the Espressif chips bootloader ROMs do not have.
6
7* Add features to the ESP8266 bootloader ROM which are only in the ROM of newer chips.
8
9* Improve flashing performance over the ROM bootloaders.
10
11* Work around bugs in the ESP8266 ROM bootloader.
12
13Thanks to [Cesanta](http://cesanta.com/) who provided the original ESP8266 stub loader upon which this loader is based.
14
15# To Use
16
17The stub loader is already automatically integrated into esptool.py. You don't need to do anything special to use it.
18
19# To Build
20
21If you want to build the stub to test modifications or updates, here's how:
22
23* You will need an ESP8266 gcc toolchain (xtensa-lx106-elf-) and toolchains for ESP32 and later chips (xtensa-esp32-elf-, riscv32-esp-elf-) on your PATH. If you are developing the stub flasher and plan to send a pull request, please use the latest toolchains available.
24
25* Set the environment variables SDK_PATH to the path to an ESP8266 IoT NON-OS SDK directory (last stub was built with SDK v1.5.1).
26
27* Set the environment variable IDF_PATH to the path to an ESP-IDF directory.
28
29* Set any other environment variables you'd like to override in the Makefile.
30
31* To build type `make`. To build only for the ESP32 family, type `make esp32` (this negates the need of an ESP8266 toolchain).
32
33Activating an ESP-IDF environment takes care of most of these steps (only the ESP8266 gcc toolchain has to be manually added to PATH).
34
35# To Test
36
37To test the built stub, you can run `make embed` (or `make embed_esp32`), which will update the stubs in `esptool.py` to the newly compiled ones. Or there are some convenience wrappers to make testing quicker to iterate on:
38
39* Running `esptool_test_stub.py` is the same as running `esptool.py`, only it uses the just-compiled stubs from the build directory.
40
41* Running `run_tests_with_stub.sh` is the same as running `pytest test/test_esptool.py`, only it uses the just-compiled stubs from the build directory. See the [Automated Integration Tests](https://docs.espressif.com/projects/esptool/en/latest/contributing.html#automated-integration-tests) docs for more information.
42