djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

esp32/README.md: Update build instructions for newer toolchain.

Browse Source 
Also fix Espressif links to the specific version they apply to.
This commit is contained in:
Jim Mussared 2020-03-02 12:06:11 +11:00 committed by Damien George
parent 0cd13081df
commit 9715905b18
1 changed files with 161 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

228
ports/esp32/README.md
View File

@ -26,91 +26,169 @@ There are two main components that are needed to build the firmware:
different to the compiler used by the ESP8266) different to the compiler used by the ESP8266)
- the Espressif IDF (IoT development framework, aka SDK) - the Espressif IDF (IoT development framework, aka SDK)
The ESP-IDF changes quickly and MicroPython only supports certain versions. The If you are on a Windows machine then the [Windows Subsystem for
git hash of these versions (one for 3.x, one for 4.x) can be found by running Linux](https://msdn.microsoft.com/en-au/commandline/wsl/install_guide) is the
`make` without a configured `ESPIDF`. Then you can fetch only the given esp-idf most efficient way to install the ESP32 toolchain and build the project. If
using the following command: you use WSL then follow the Linux instructions rather than the Windows
instructions.
$ git clone https://github.com/espressif/esp-idf.git The ESP-IDF changes quickly and MicroPython only supports certain versions.
$ git checkout <Current supported ESP-IDF commit hash> The git hash of these versions (one for 3.x, one for 4.x) can be found by
$ git submodule update --init --recursive running `make` without a configured `ESPIDF`. Then you can fetch the
required IDF using the following command:
Note: The ESP IDF v4.x support is currently experimental.
The binary toolchain (binutils, gcc, etc.) can be installed using the following
guides:
* [Linux installation](https://docs.espressif.com/projects/esp-idf/en/stable/get-started/linux-setup.html)
* [MacOS installation](https://docs.espressif.com/projects/esp-idf/en/stable/get-started/macos-setup.html)
* [Windows installation](https://docs.espressif.com/projects/esp-idf/en/stable/get-started/windows-setup.html)
If you are on a Windows machine then the
[Windows Subsystem for Linux](https://msdn.microsoft.com/en-au/commandline/wsl/install_guide)
is the most efficient way to install the ESP32 toolchain and build the project.
If you use WSL then follow the
[Linux guidelines](https://esp-idf.readthedocs.io/en/latest/get-started/linux-setup.html)
for the ESP-IDF instead of the Windows ones.
You will also need either Python 2 or Python 3, along with the `pyserial` and
`pyparsing` packages installed for the version of Python that you will be using
(when building you can use, eg, `make PYTHON=python2` to specify the version
used). To install the required packages do:
```bash ```bash
$ pip install pyserial 'pyparsing<2.4' $ cd ports/esp32
$ make ESPIDF= # This will print the supported hashes, copy the one you want.
$ export ESPIDF=$HOME/src/github.com/espressif/esp-idf # Or any path you like.
$ mkdir -p $ESPIDF
$ cd $ESPIDF
$ git clone https://github.com/espressif/esp-idf.git $ESPIDF
$ git checkout <Current supported ESP-IDF commit hash>
$ git submodule update --init --recursive
``` ```
It is recommended to use a Python virtual environment if your system package Note: The ESP IDF v4.x support is currently experimental. It does not
manager already provides these libraries, especially as the IDF v4.x is currently support PPP or wired Ethernet.
currently incompatible with pyparsing 2.4 and higher.
Once everything is set up you should have a functioning toolchain with Python dependencies
prefix xtensa-esp32-elf- (or otherwise if you configured it differently) ===================
as well as a copy of the ESP-IDF repository. You will need to update your `PATH`
environment variable to include the ESP32 toolchain. For example, you can issue You will also need other dependencies from the IDF, see
the following commands on (at least) Linux: `$ESPIDF/requirements.txt`, but at a minimum you need `pyserial>=3.0` and
`pyparsing>=2.0.3,<2.4.0`.
You can use Python 2 or Python 3. If you need to override the system default
add (for example) `PYTHON=python3` to any of the `make` commands below.
It is recommended to use a Python virtual environment. Even if your system
package manager already provides these libraries, the IDF v4.x is currently
incompatible with pyparsing 2.4 and higher.
For example, to set up a Python virtual environment from scratch:
```bash
$ cd ports/esp32
$ python3 -m venv build-venv
$ source build-venv/bin/activate
$ pip install --upgrade pip
$ pip install path/to/esp-idf/requirements.txt
```
To re-enter this virtual environment in future sessions, you only need to
source the `activate` script, i.e.:
```bash
$ cd ports/esp32
$ source build-venv/bin/activate
```
Then, to install the toolchain (which includes the GCC compiler, linker, binutils,
etc), there are two options:
1. Using the IDF scripts to install the toolchain (IDF 4.x only)
================================================================
Follow the steps at the [Espressif Getting Started guide](https://docs.espressif.com/projects/esp-idf/en/v4.0/get-started/index.html#step-3-set-up-the-tools).
This will guide you through using the `install.sh` (or `install.bat`) script
to download the toolchain and add it to your `PATH`. The steps are summarised
below:
After you've cloned and checked out the IDF to the correct version (see
above), run the `install.sh` script:
```bash
$ cd $ESPIDF
$ ./install.sh # (or install.bat on Windows)
```
Then in the `ports/esp32` directory, source the `export.sh` script to set the
`PATH`.
```bash
$ cd micropython/ports/esp32
$ source $ESPIDF/export.sh # (or path\to\esp-idf\export.bat on Windows)
$ # Run make etc, see below.
```
The `install.sh` step only needs to be done once. You will need to source
`export.sh` for every new session.
Note: If you get an error about `--no-site-packages`, then modify
`$ESPIDF/tools/idf_tools.py` and make the same change as [this
commit](https://github.com/espressif/esp-idf/commit/7a18f02acd7005f7c56e62175a8d1968a1a9019d).
2. or, Downloading pre-built toolchain manually (IDF 3.x and 4.x)
=============================================================
Note: while this works with 4.x, if you're using the 4.x IDF, it's much
simpler to use the guide above, which will also get a more recent version of
the toolchain.
You can follow the 3.x guide at:
* [Linux installation](https://docs.espressif.com/projects/esp-idf/en/v3.3.1/get-started/linux-setup.html)
* [MacOS installation](https://docs.espressif.com/projects/esp-idf/en/v3.3.1/get-started/macos-setup.html)
* [Windows installation](https://docs.espressif.com/projects/esp-idf/en/v3.3.1/get-started/windows-setup.html)
You will need to update your `PATH` environment variable to include the ESP32
toolchain. For example, you can issue the following commands on (at least)
Linux:
$ export PATH=$PATH:$HOME/esp/crosstool-NG/builds/xtensa-esp32-elf/bin $ export PATH=$PATH:$HOME/esp/crosstool-NG/builds/xtensa-esp32-elf/bin
You can put this command in your `.profile` or `.bash_login`. You can put this command in your `.profile` or `.bash_login`, or do it manually.
Configuring the MicroPython build
---------------------------------
You then need to set the `ESPIDF` environment/makefile variable to point to You then need to set the `ESPIDF` environment/makefile variable to point to
the root of the ESP-IDF repository. You can set the variable in your PATH, the root of the ESP-IDF repository. The recommended way to do this is to have
or at the command line when calling make, or in your own custom `makefile`. a custom `makefile` in `ports/esp32` which sets any additional variables, then
The last option is recommended as it allows you to easily configure other includes the main `Makefile`. Note that GNU Make will preferentially run
variables for the build. In that case, create a new file in the esp32 `GNUmakefile`, then `makefile`, then `Makefile`, which is what allows this to
directory called `makefile` and add the following lines to that file: work. On case-insensitive filesystems, you'll need to use `GNUmakefile` rather
than `makefile`.
Create a new file in the esp32 directory called `makefile` (or `GNUmakefile`)
and add the following lines to that file:
``` ```
ESPIDF = <path to root of esp-idf repository> ESPIDF ?= <path to root of esp-idf repository>
BOARD = GENERIC BOARD ?= GENERIC
#PORT = /dev/ttyUSB0 #PORT ?= /dev/ttyUSB0
#FLASH_MODE = qio #FLASH_MODE ?= qio
#FLASH_SIZE = 4MB #FLASH_SIZE ?= 4MB
#CROSS_COMPILE = xtensa-esp32-elf- #CROSS_COMPILE ?= xtensa-esp32-elf-
include Makefile include Makefile
``` ```
Be sure to enter the correct path to your local copy of the IDF repository Be sure to enter the correct path to your local copy of the IDF repository
(and use `$(HOME)`, not tilde, to reference your home directory). (and use `$(HOME)`, not tilde (`~`), to reference your home directory).
If your filesystem is case-insensitive then you'll need to use `GNUmakefile`
instead of `makefile`.
If the Xtensa cross-compiler is not in your path you can use the If the Xtensa cross-compiler is not in your path you can use the
`CROSS_COMPILE` variable to set its location. Other options of interest `CROSS_COMPILE` variable to set its location. Other options of interest are
are `PORT` for the serial port of your esp32 module, and `FLASH_MODE` `PORT` for the serial port of your ESP32 module, and `FLASH_MODE` (which may
(which may need to be `dio` for some modules) need to be `dio` for some modules) and `FLASH_SIZE`. See the Makefile for
and `FLASH_SIZE`. See the Makefile for further information. further information.
The default ESP IDF configuration settings are provided by the `GENERIC` The default ESP IDF configuration settings are provided by the `GENERIC`
board definition in the directory `boards/GENERIC`. For a custom configuration board definition in the directory `boards/GENERIC`. For a custom configuration
you can define your own board directory. you can define your own board directory.
The `BOARD` variable can be set on the make command line: Any of these variables can also be set on the make command line, e.g. to set
the `BOARD` variable, use:
```bash ```bash
$ make BOARD=TINYPICO $ make BOARD=TINYPICO
``` ```
or added to your custom `makefile` (or `GNUmakefile`) described above. There
is also a `GENERIC_SPIRAM` board for for ESP32 modules that have external Note the use of `?=` in the `makefile` which allows them to be overridden on
SPIRAM, but prefer to use a specific board target (or define your own as the command line. There is also a `GENERIC_SPIRAM` board for for ESP32
necessary). modules that have external SPIRAM, but prefer to use a specific board target
(or define your own as necessary).
Building the firmware Building the firmware
--------------------- ---------------------
@ -118,16 +196,20 @@ Building the firmware
The MicroPython cross-compiler must be built to pre-compile some of the The MicroPython cross-compiler must be built to pre-compile some of the
built-in scripts to bytecode. This can be done by (from the root of built-in scripts to bytecode. This can be done by (from the root of
this repository): this repository):
```bash ```bash
$ make -C mpy-cross $ cd mpy-cross
$ make mpy-cross
``` ```
Then to build MicroPython for the ESP32 run: Then to build MicroPython for the ESP32 run:
```bash ```bash
$ cd ports/esp32 $ cd ports/esp32
$ make submodules $ make submodules
$ make $ make
``` ```
This will produce binary firmware images in the `build/` subdirectory This will produce binary firmware images in the `build/` subdirectory
(three of them: bootloader.bin, partitions.bin and application.bin). (three of them: bootloader.bin, partitions.bin and application.bin).
@ -138,8 +220,10 @@ flash settings are set in the `Makefile`, and can be overridden in your
local `makefile`; see above for more details. local `makefile`; see above for more details.
You will also need to have user permissions to access the /dev/ttyUSB0 device. You will also need to have user permissions to access the /dev/ttyUSB0 device.
On Linux, you can enable this by adding your user to the `dialout` group, On Linux, you can enable this by adding your user to the `dialout` group, and
and rebooting or logging out and in again. rebooting or logging out and in again. (Note: on some distributions this may
be the `uucp` group, run `ls -la /dev/ttyUSB0` to check.)
```bash ```bash
$ sudo adduser <username> dialout $ sudo adduser <username> dialout
``` ```
@ -147,27 +231,37 @@ $ sudo adduser <username> dialout
If you are installing MicroPython to your module for the first time, or If you are installing MicroPython to your module for the first time, or
after installing any other firmware, you should first erase the flash after installing any other firmware, you should first erase the flash
completely: completely:
```bash ```bash
$ make erase $ make erase
``` ```
To flash the MicroPython firmware to your ESP32 use: To flash the MicroPython firmware to your ESP32 use:
```bash ```bash
$ make deploy $ make deploy
``` ```
This will use the `esptool.py` script (provided by ESP-IDF) to download the
binary images.
Getting a Python prompt This will use the `esptool.py` script (provided by ESP-IDF) to flash the
----------------------- binary images to the device.
Getting a Python prompt on the device
-------------------------------------
You can get a prompt via the serial port, via UART0, which is the same UART You can get a prompt via the serial port, via UART0, which is the same UART
that is used for programming the firmware. The baudrate for the REPL is that is used for programming the firmware. The baudrate for the REPL is
115200 and you can use a command such as: 115200 and you can use a command such as:
```bash ```bash
$ picocom -b 115200 /dev/ttyUSB0 $ picocom -b 115200 /dev/ttyUSB0
``` ```
or
```bash
$ miniterm.py /dev/ttyUSB0 115200
```
Configuring the WiFi and using the board Configuring the WiFi and using the board
---------------------------------------- ----------------------------------------