From 114fdf73f37894fade239ec744127429464fe5e7 Mon Sep 17 00:00:00 2001 From: Gunar Schorcht Date: Sat, 17 Aug 2019 16:12:40 +0200 Subject: [PATCH] cpu/esp32/doc_ clarify esptool.py install --- cpu/esp32/doc.txt | 83 +++++++++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 28 deletions(-) diff --git a/cpu/esp32/doc.txt b/cpu/esp32/doc.txt index 148fda9cb86a7..e63ba1b7cf71a 100644 --- a/cpu/esp32/doc.txt +++ b/cpu/esp32/doc.txt @@ -203,52 +203,43 @@ The implementation of RIOT-OS for ESP32 SOCs has the following limitations at th Following software components are required for compilation: - Xtensa GCC compiler suite for ESP32 -- ESP-IDF SDK which includes all ESP32 SOC definitions, the hardware abstraction library ```libhal.a```, and the flash programmer tool ```esptool.py``` +- ESP-IDF SDK which includes all ESP32 SOC definitions and the hardware +abstraction library `libhal.a` +- ESP flash programmer tool `esptool.py` There are two options to install the Toolchain: -- riotdocker image, see section [RIOT Docker Toolchain (riotdocker)](#esp32_riot_docker_toolchain) +- using a riotdocker image, see section [RIOT Docker Toolchain (riotdocker)](#esp32_riot_docker_toolchain) - manual installation, see section [Manual Toolchain Installation](#esp32_manual_toolchain_installation) +In both cases, the ESP flash programmer tool `esptool.py` has to be installed. + ## RIOT Docker Toolchain (riotdocker)  [[TOC](#esp32_toc)] -The easiest way to use install the toolchain is the RIOT Docker image ```riotdocker```. The compilation process using Docker consists of two steps +The easiest way to use install the toolchain is the RIOT Docker image +`riotdocker`. The compilation process using Docker consists of two steps -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=...``` +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 tool `esptool.py` is installed. ### Preparing the Environment  [[TOC](#esp32_toc)] -Using RIOT Docker requires at least the following software: +Using RIOT Docker requires at least the following software components: -- ```Docker``` container virtualization software -- RIOT Docker (```riotdocker```) image -- flasher tool ```esptool.py``` +- `Docker` container virtualization software +- RIOT Docker (`riotdocker`) image +- ESP flash programmer tool `esptool.py` -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: +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 ``` -The ESP flasher program ```esptool.py``` 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```: -``` -pip install esptool -``` - -```esptool.py``` 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. +For information on how to install `esptool.py`, see section +[Installation of `esptool.py`](#esp32_installation_of_esptool). ### Generating a riotdocker Image  [[TOC](#esp32_toc)] @@ -283,6 +274,7 @@ or the [riot/riotbuild](https://hub.docker.com/r/riot/riotbuild/) Docker image ( cd /path/to/RIOT docker run -i -t --privileged -v /dev:/dev -u $UID -v $(pwd):/data/riotbuild riot/riotbuild ``` + ### Make Process with Docker Image  [[TOC](#esp32_toc)] Using Docker, the make process consists of the following two steps: @@ -346,6 +338,41 @@ 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 ``` +### Installation of `esptool.py` (ESP flash programmer tool)  [[TOC](#esp32_toc)] + +The minumum required version of the ESP flash programmer tool +`esptool.py` is version 2.2. If your OS bundles a package with at +least this version, you can simply use the package manager of your OS to +install `esptool.py`, for example on Debian/Ubuntu systems: + +``` +apt-get install esptool +``` + +Otherwise, you have to install the latest stable version of `esptool.py` either +from [GitHub](https://github.com/espressif/esptool) or using the `pip` command: + +``` +pip install esptool +``` + +`esptool.py` requires either Python 2.7, Python 3.4 or later. Furthermore, +it 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. # Flashing the Device  [[TOC](#esp32_toc)]