cpu/esp32: doc changes for esptool.py

cpu/esp32/doc.txt

@@ -202,7 +202,7 @@ The implementation of RIOT-OS for ESP32 SOCs has the following limitations at th
 Following software components are required for compilation:
 
 - <b>Xtensa GCC</b> compiler suite for ESP32
-- <b>ESP-IDF</b> SDK which includes all ESP32 SOC definitions, the hardware abstraction library <b>```libhal.a```</b>, and the flash programmer tool <b>```esptool.py```</b>
+- <b>ESP-IDF</b> SDK which includes all ESP32 SOC definitions, basic libraries and the hardware abstraction library <b>`libhal.a`</b>
 
 There are two options to install the Toolchain:
 
@@ -216,7 +216,12 @@ The easiest way to use install the toolchain is the RIOT Docker image ```riotdoc
 1. making the RIOT application in Docker with command ```make BOARD= ...```
 2. flashing the RIOT application on the host computer with command ```make flash-only BOARD=...```
 
-where step 2 requires that the flasher program ```esptool.py``` is installed.
+where step 2 requires that the ESP flash programmer `esptool.py` is installed.
+Both steps can also be performed with a single command on the host system
+using the `BUILD_IN_DOCKER` variable:
+```
+BUILD_IN_DOCKER=1 make BOARD=... flash
+```
 
 ### <a name="esp32_preparing_the_environment"> Preparing the Environment </a> &nbsp;[[TOC](#esp32_toc)]
 
@@ -224,30 +229,14 @@ Using RIOT Docker requires at least the following software:
 
 - <b>```Docker```</b> container virtualization software
 - RIOT Docker (<b>```riotdocker```</b>) image
-- flasher tool <b>```esptool.py```</b>
+- ESP flash programmer tool <b>`esptool.py`</b>
 
 For information about installing Docker on your host, refer to the appropriate manuals for your operating system. For example, the easiest way to install Docker on the Ubuntu/Debian system is:
 ```
 sudo apt-get install docker.io
 ```
-
+For information on how to install `esptool.py`, see section
-The ESP flasher program <b>```esptool.py```</b> is available at [GitHub](https://github.com/espressif/esptool). Don't use the the ```esptool``` package of your OS. ```esptool.py``` requires either Python 2.7 or Python 3.4 or later. The latest stable version of ```esptool.py``` can be installed with ```pip```:
+[Installation of `esptool.py`](#esp32_installation_of_esptool).
-```
-pip install esptool
-```
-
-<b>```esptool.py```</b> depends on ```pySerial``` which can be installed either using ```pip```
-
-```
-pip install pyserial
-```
-or the package manager of your OS, for example on Debian/Ubuntu systems:
-```
-apt-get install pyserial
-```
-For more information on ```esptool.py```, please refer the [git repository](https://github.com/espressif/esptool)
-
-Please make sure that ```esptool.py``` is in your ```PATH``` variable.
 
 ### <a name="esp32_generating_docker_image"> Generating a riotdocker Image </a> &nbsp;[[TOC](#esp32_toc)]
 
@@ -345,6 +334,32 @@ Since we only use a few header files, ESP-IDF does not need to be compiled in an
 export ESP32_SDK_DIR=$HOME/esp/esp-idf
 ```
 
+### <a name="esp32_installation_of_esptool"> Installation of `esptool.py` (ESP flash programmer tool) </a> &nbsp;[[TOC](#esp32_toc)]
+
+The RIOT port does not work with the `esptool.py` ESP flasher program
+available on [GitHub](https://github.com/espressif/esptool) or
+as a package for your OS. Instead, a modified version is required.
+
+To avoid the installation of the complete ESP-IDF SDK, for example,
+because RIOT Docker `riotdocker` is used for compilation, `esptool.py`
+has been extracted from the SDK and placed in RIOT's
+directory `dist/tools/esptool`.
+For convenience, the build system uses always the version from this directory.
+
+Therefore, it is **not necessary to install** `esptool.py` explicitly. However
+`esptool.py` depends on `pySerial` which can be installed either
+using `pip`
+
+```
+sudo pip install pyserial
+```
+or the package manager of your OS, for example on Debian/Ubuntu systems:
+```
+apt install python-pyserial
+```
+For more information on `esptool.py`, please refer to the
+[git repository](https://github.com/espressif/esptool).
+
 
 # <a name="esp32_flashing_the_device"> Flashing the Device </a> &nbsp;[[TOC](#esp32_toc)]