1.. _stub:
2
3Flasher Stub
4============
5
6``esptool.py`` is a serial flasher utility. It communicates with the ROM bootloader in `Espressif SoCs <https://www.espressif.com/en/products/hardware/socs>`_ in order to load user applications or read chip data via serial port.
7
8The ROM bootloader is burned into the ESP chip during manufacturing and cannot be updated. A new version is issued only when a new chip revision is released.
9
10``esptool.py`` works around the limitations imposed by a fixed ROM bootloader by implementing a flasher stub (also known as "stub loader" or just "stub"). It is a small application used as a temporary substitute or extension for the ROM.
11
12When ``esptool.py`` connects to a chip, it first uploads the flasher stub, which basically replaces the original bootloader. All following operations are then handled by the stub.
13
14Benefits
15--------
16
17The flasher stub behaves the same as the original bootloader, but uses more heavily optimized UART routines.
18
19The main benefit is improved performance of flashing and some other operations (like reading flash). Additionally, there are a few commands which are only available when using the stub loader (such as :ref:`erase_flash and erase_region <erase_flash>`). It also allows to work around any bugs in ROM bootloaders.
20
21Disabling the Stub Loader
22-------------------------
23
24There might be cases where it is necessary to disable the stub loader (e.g. debugging). To do that, run ``esptool.py`` with the ``--no-stub`` argument. All operations will then be handled by the original ROM bootloader. See the related :ref:`advanced options page <disable_stub>`.
25