micropython/ports/esp32
Amir Gonnen 995f9cfdfc esp32: Pin MicroPython tasks to a specific core.
On this port the GIL is enabled and everything works under the assumption
of the GIL, ie that a given task has exclusive access to the uPy state, and
any ISRs interrupt the current task and therefore the ISR inherits
exclusive access to the uPy state for the duration of its execution.

If the MicroPython tasks are not pinned to a specific core then an ISR may
be executed on a different core to the task, making it possible for the
main task and an ISR to execute in parallel, breaking the assumption of the
GIL.

The easiest and safest fix for this is to pin all MicroPython related code
to the same CPU core, as done by this patch.  Then any ISR that accesses
MicroPython state must be registered from a MicroPython task, to ensure it
is invoked on the same core.

See issue #4895.
2019-07-25 15:33:47 +10:00
..
boards esp32/boards/sdkconfig: Disable WDT check of idle task on CPU1. 2019-04-05 12:25:21 +11:00
modules esp32/modules/neopixel.py: Change NeoPixel to different default timings. 2019-01-23 14:22:38 +11:00
Makefile esp32/Makefile: Simplify include of IDF source by using wildcards. 2019-07-20 14:07:18 +10:00
README.md esp32: Update to use ESP IDF v3.3-beta3. 2019-06-19 14:32:15 +10:00
README.ulp.md esp32: Add support for the esp32's ULP. 2018-05-01 16:19:37 +10:00
esp32_ulp.c esp32: Add support for the esp32's ULP. 2018-05-01 16:19:37 +10:00
espneopixel.c esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
esponewire.c esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
fatfs_port.c esp32/fatfs_port: Implement get_fattime so FAT files have a timestamp. 2018-06-13 14:13:34 +10:00
gccollect.c esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
gccollect.h esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
help.c esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
machine_adc.c esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
machine_dac.c esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
machine_hw_spi.c esp32/machine_hw_spi: Make HW SPI objects statically allocated. 2019-01-23 23:47:36 +11:00
machine_i2c.c esp32: Add support for hardware I2C. 2019-07-19 16:31:25 +10:00
machine_pin.c esp32/machine_pin: Rework pull mode config to fix GPIO hold feature. 2019-03-26 15:21:23 +11:00
machine_pwm.c esp32/machine_pwm: On deinit stop routing PWM signal to the pin. 2018-12-06 17:05:16 +11:00
machine_rtc.c esp32/machine_rtc: Fix locals dict entry, init qstr points to init meth. 2018-09-20 17:52:16 +10:00
machine_rtc.h esp32/machine_rtc: Move export declaration from .c to common .h file. 2018-02-17 00:52:55 +11:00
machine_sdcard.c esp32/machine_sdcard: Fix bug in SPI slot number selection. 2019-06-17 12:36:22 +10:00
machine_timer.c esp32/machine_timer: Reuse Timer handles, deallocate only on soft-reset. 2019-05-31 14:55:07 +10:00
machine_touchpad.c esp32/machine_touchpad: Use HW timer for FSM to enable wake-on-touch. 2019-05-28 11:14:34 +10:00
machine_uart.c esp32/machine_uart: Implement UART.deinit() method. 2019-05-15 17:01:54 +10:00
machine_wdt.c esp32/machine_wdt: Add timeout arg to select interval, make WDT panic. 2019-04-30 16:53:05 +10:00
main.c esp32: Pin MicroPython tasks to a specific core. 2019-07-25 15:33:47 +10:00
makeimg.py esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
memory.h esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
modesp.c esp32/modesp: Add osdebug() function to disable or change IDF logging. 2017-12-13 14:48:53 +11:00
modesp.h esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
modesp32.c esp32/modesp32: Add hall_sensor() function. 2018-10-19 17:28:02 +11:00
modesp32.h esp32: Add support for the esp32's ULP. 2018-05-01 16:19:37 +10:00
modmachine.c esp32: Add machine.SDCard class using built-in HW SD/MMC controller. 2019-06-03 00:37:41 +10:00
modmachine.h esp32: Add machine.SDCard class using built-in HW SD/MMC controller. 2019-06-03 00:37:41 +10:00
modnetwork.c esp32/modnetwork: Still try to reconnect to WLAN even with AUTH_FAIL. 2019-06-22 21:50:49 +10:00
modnetwork.h esp32/network_ppp: Add PPPoS functionality. 2018-10-19 23:32:02 +11:00
modsocket.c esp32/modsocket: Raise EAGAIN when accept fails in non-blocking mode. 2019-05-28 17:43:00 +10:00
moduos.c esp32: Add support for and enable uos.dupterm(). 2018-04-27 23:51:45 +10:00
modutime.c esp32/modutime.c: Add localtime and mktime functions. 2017-12-13 14:48:53 +11:00
mpconfigport.h esp32: Add support for hardware I2C. 2019-07-19 16:31:25 +10:00
mphalport.c ports: Provide mp_hal_stdio_poll for sys.stdio polling where needed. 2019-07-01 17:10:12 +10:00
mphalport.h esp32: Pin MicroPython tasks to a specific core. 2019-07-25 15:33:47 +10:00
mpthreadport.c esp32: Pin MicroPython tasks to a specific core. 2019-07-25 15:33:47 +10:00
mpthreadport.h esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
network_lan.c esp32/network_lan: Make power arg to constructor optional. 2019-02-21 23:29:10 +11:00
network_ppp.c esp32: Pin MicroPython tasks to a specific core. 2019-07-25 15:33:47 +10:00
partitions.csv esp32: Add custom partitions.csv file with uPy specific size. 2017-12-13 15:51:04 +11:00
qstrdefsport.h esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
uart.c esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
uart.h esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00

README.md

MicroPython port to the ESP32

This is an experimental port of MicroPython to the Espressif ESP32 microcontroller. It uses the ESP-IDF framework and MicroPython runs as a task under FreeRTOS.

Supported features include:

  • REPL (Python prompt) over UART0.
  • 16k stack for the MicroPython task and 96k Python heap.
  • Many of MicroPython's features are enabled: unicode, arbitrary-precision integers, single-precision floats, complex numbers, frozen bytecode, as well as many of the internal modules.
  • Internal filesystem using the flash (currently 2M in size).
  • The machine module with GPIO, UART, SPI, software I2C, ADC, DAC, PWM, TouchPad, WDT and Timer.
  • The network module with WLAN (WiFi) support.

Development of this ESP32 port was sponsored in part by Microbric Pty Ltd.

Setting up the toolchain and ESP-IDF

There are two main components that are needed to build the firmware:

  • the Xtensa cross-compiler that targets the CPU in the ESP32 (this is different to the compiler used by the ESP8266)
  • the Espressif IDF (IoT development framework, aka SDK)

The ESP-IDF changes quickly and MicroPython only supports a certain version. The git hash of this version can be found by running make without a configured ESPIDF. Then you can fetch only the given esp-idf using the following command:

$ git clone https://github.com/espressif/esp-idf.git
$ git checkout <Current supported ESP-IDF commit hash>
$ git submodule update --init --recursive

The binary toolchain (binutils, gcc, etc.) can be installed using the following guides:

If you are on a Windows machine then the Windows Subsystem for Linux is the most efficient way to install the ESP32 toolchain and build the project. If you use WSL then follow the Linux guidelines 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:

$ pip install pyserial pyparsing

Once everything is set up you should have a functioning toolchain with 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 the following commands on (at least) Linux:

$ export PATH=$PATH:$HOME/esp/crosstool-NG/builds/xtensa-esp32-elf/bin

You can put this command in your .profile or .bash_login.

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, or at the command line when calling make, or in your own custom makefile. The last option is recommended as it allows you to easily configure other variables for the build. In that case, create a new file in the esp32 directory called makefile and add the following lines to that file:

ESPIDF = <path to root of esp-idf repository>
#PORT = /dev/ttyUSB0
#FLASH_MODE = qio
#FLASH_SIZE = 4MB
#CROSS_COMPILE = xtensa-esp32-elf-
#SDKCONFIG = boards/sdkconfig.spiram

include Makefile

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). 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 CROSS_COMPILE variable to set its location. Other options of interest are PORT for the serial port of your esp32 module, and FLASH_MODE (which may need to be dio for some modules) and FLASH_SIZE. See the Makefile for further information.

The default ESP IDF configuration settings are provided in the file boards/sdkconfig, and this file is specified in the build by the make variable SDKCONFIG. To use a custom configuration either set SDKCONFIG in your custom makefile (or GNUmakefile) or set this variable on the command line:

$ make SDKCONFIG=sdkconfig.myboard

The file boards/sdkconfig.spiram is provided for ESP32 modules that have external SPIRAM.

Building the firmware

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 this repository):

$ make -C mpy-cross

The ESP32 port has a dependency on Berkeley DB, which is an external dependency (git submodule). You'll need to have git initialize that module using the commands:

$ git submodule init lib/berkeley-db-1.xx
$ git submodule update

Then to build MicroPython for the ESP32 run:

$ cd ports/esp32
$ make

This will produce binary firmware images in the build/ subdirectory (three of them: bootloader.bin, partitions.bin and application.bin).

To flash the firmware you must have your ESP32 module in the bootloader mode and connected to a serial port on your PC. Refer to the documentation for your particular ESP32 module for how to do this. The serial port and flash settings are set in the Makefile, and can be overridden in your local makefile; see above for more details.

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, and rebooting or logging out and in again.

$ sudo adduser <username> dialout

If you are installing MicroPython to your module for the first time, or after installing any other firmware, you should first erase the flash completely:

$ make erase

To flash the MicroPython firmware to your ESP32 use:

$ make deploy

This will use the esptool.py script (provided by ESP-IDF) to download the binary images.

Getting a Python prompt

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 115200 and you can use a command such as:

$ picocom -b 115200 /dev/ttyUSB0

Configuring the WiFi and using the board

The ESP32 port is designed to be (almost) equivalent to the ESP8266 in terms of the modules and user-facing API. There are some small differences, notably that the ESP32 does not automatically connect to the last access point when booting up. But for the most part the documentation and tutorials for the ESP8266 should apply to the ESP32 (at least for the components that are implemented).

See http://docs.micropython.org/en/latest/esp8266/esp8266/quickref.html for a quick reference, and http://docs.micropython.org/en/latest/esp8266/esp8266/tutorial/intro.html for a tutorial.

The following function can be used to connect to a WiFi access point (you can either pass in your own SSID and password, or change the defaults so you can quickly call wlan_connect() and it just works):

def wlan_connect(ssid='MYSSID', password='MYPASS'):
    import network
    wlan = network.WLAN(network.STA_IF)
    if not wlan.active() or not wlan.isconnected():
        wlan.active(True)
        print('connecting to:', ssid)
        wlan.connect(ssid, password)
        while not wlan.isconnected():
            pass
    print('network config:', wlan.ifconfig())

Note that some boards require you to configure the WiFi antenna before using the WiFi. On Pycom boards like the LoPy and WiPy 2.0 you need to execute the following code to select the internal antenna (best to put this line in your boot.py file):

import machine
antenna = machine.Pin(16, machine.Pin.OUT, value=0)

Troubleshooting

  • Continuous reboots after programming: Ensure FLASH_MODE is correct for your board (e.g. ESP-WROOM-32 should be DIO). Then perform a make clean, rebuild, redeploy.