micropython/ports/esp32
Damien George cfcce4b531 esp32/README: Specify that only IDF v5.0.2 is supported.
Signed-off-by: Damien George <damien@micropython.org>
2023-07-25 12:59:02 +10:00
..
boards esp32/boards: Remove references to the IDF version in board.md files. 2023-07-25 12:35:21 +10:00
main_esp32 esp32: Re-enable mDNS after move to IDF v5.0.2. 2023-07-11 15:58:15 +10:00
main_esp32c3 esp32: Re-enable mDNS after move to IDF v5.0.2. 2023-07-11 15:58:15 +10:00
main_esp32s2 esp32: Re-enable mDNS after move to IDF v5.0.2. 2023-07-11 15:58:15 +10:00
main_esp32s3 esp32: Re-enable mDNS after move to IDF v5.0.2. 2023-07-11 15:58:15 +10:00
modules esp32/modules/inisetup.py: Format partition as FAT if its label is ffat. 2023-06-25 16:09:46 +10:00
.gitignore esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
CMakeLists.txt esp32/CMakeLists: Enable multiple extra component directories in build. 2023-07-21 00:13:10 +10:00
Makefile esp32/Makefile: Provide more IDF shortcuts. 2023-06-23 15:34:37 +10:00
README.md esp32/README: Specify that only IDF v5.0.2 is supported. 2023-07-25 12:59:02 +10:00
README.ulp.md esp32: Add support for the esp32's ULP. 2018-05-01 16:19:37 +10:00
esp32_common.cmake esp32: Collect properties from IDF-managed components as well. 2023-07-20 23:54:53 +10:00
esp32_nvs.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
esp32_partition.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
esp32_rmt.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
esp32_ulp.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
fatfs_port.c all: Update to point to files in new shared/ directory. 2021-07-12 17:08:10 +10:00
gccollect.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
gccollect.h esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
help.c ports: Standardise docs link in help text. 2023-06-02 11:48:46 +10:00
machine_adc.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
machine_adc.h esp32/machine_adcblock: Add new machine.ADCBlock class and update ADC. 2022-01-21 22:55:24 +11:00
machine_adcblock.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
machine_adcblock.h esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
machine_bitstream.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
machine_dac.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
machine_hw_spi.c esp32/machine_hw_spi: Check for valid SPI id in constructor, not init. 2023-07-25 11:33:51 +10:00
machine_i2c.c esp32: Use always machine_pin_get_id for getting a Pin id. 2023-07-20 17:33:04 +10:00
machine_i2s.c esp32: Use always machine_pin_get_id for getting a Pin id. 2023-07-20 17:33:04 +10:00
machine_pin.c esp32: Add support for board-named pins and the Pin.board dict. 2023-07-20 18:17:36 +10:00
machine_pin.h esp32: Add support for board-named pins and the Pin.board dict. 2023-07-20 18:17:36 +10:00
machine_pwm.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
machine_rtc.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
machine_rtc.h esp32/modesp32: Add wake_on_ulp() so ULP can wake CPU from deepsleep. 2022-06-23 17:31:01 +10:00
machine_sdcard.c esp32: Use always machine_pin_get_id for getting a Pin id. 2023-07-20 17:33:04 +10:00
machine_timer.c esp32/machine_timer: Switch from legacy driver to timer HAL. 2023-07-14 10:02:42 +10:00
machine_touchpad.c esp32/machine_touchpad: Fix TouchPad for ESP32S2, ESP32S3. 2022-12-14 13:46:41 +11:00
machine_uart.c esp32: Use always machine_pin_get_id for getting a Pin id. 2023-07-20 17:33:04 +10:00
machine_wdt.c esp32/machine_wdt: Allow feeding WDT from threads. 2023-07-24 23:29:53 +10:00
main.c esp32/main: Remove unused mbedtls debug function. 2023-07-24 23:28:16 +10:00
makeimg.py esp32: Create .uf2 binaries for S2 and S3 chips. 2022-02-02 23:47:49 +11:00
memory.h ports: Update for move of crypto-algorithms, uzlib to lib. 2021-07-12 16:37:20 +10:00
modesp.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
modesp32.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
modesp32.h esp32/modesp32: Properly define RTC_VALID_EXT_PINS on S2/S3 variants. 2022-04-14 16:17:52 +10:00
modespnow.c esp32: In recv_cb, get espnow rssi from recv_info->rx_ctrl. 2023-06-23 15:34:22 +10:00
modespnow.h esp32,esp8266: Add support for the Espressif ESP-NOW protocol. 2023-05-01 16:47:21 +10:00
modmachine.c esp32/modmachine: Add generic machine.bootloader(). 2023-07-20 23:55:21 +10:00
modmachine.h esp32/modmachine: Add generic machine.bootloader(). 2023-07-20 23:55:21 +10:00
modnetwork.h esp32/network_wlan: Wait for STA/AP START/STOP event in wlan.active. 2023-07-13 11:49:14 +10:00
modnetwork_globals.h esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
modos.c all: Rename *umodule*.c to remove the "u" prefix. 2023-06-08 17:54:17 +10:00
modsocket.c esp32: Re-enable mDNS after move to IDF v5.0.2. 2023-07-11 15:58:15 +10:00
modtime.c all: Rename *umodule*.c to remove the "u" prefix. 2023-06-08 17:54:17 +10:00
mpconfigport.h py/mpconfig: Add MICROPY_PY_PLATFORM, enabled at extra features level. 2023-07-24 23:53:20 +10:00
mphalport.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
mphalport.h esp32: Use always machine_pin_get_id for getting a Pin id. 2023-07-20 17:33:04 +10:00
mpnimbleport.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
mpthreadport.c ports: Rename thread_t to mp_thread_t. 2022-05-24 00:51:23 +10:00
mpthreadport.h esp32: Add new port to Espressif ESP32 SoC. 2017-12-13 14:48:53 +11:00
network_common.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
network_lan.c esp32/network_wlan: Wait for STA/AP START/STOP event in wlan.active. 2023-07-13 11:49:14 +10:00
network_ppp.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
network_wlan.c esp32/network_wlan: Wait for STA/AP START/STOP event in wlan.active. 2023-07-13 11:49:14 +10:00
partitions-2MiB.csv esp32/partitions-2MiB.csv: Update table so firmware fits. 2021-06-11 17:57:40 +10:00
partitions-8MiB.csv esp32: Add support for ESP32-S3 SoCs. 2021-09-16 22:58:47 +10:00
partitions-16MiB-ota.csv esp32/boards: Add Silicognition wESP32 board configuration. 2021-08-07 12:50:13 +10:00
partitions-16MiB.csv esp32/partitions-16MiB.csv: Increase 14MiB filesystem to maximum size. 2022-02-08 12:25:10 +11:00
partitions-32MiB-ota.csv esp32: Add 32MiB partition table templates. 2022-11-09 10:57:44 +11:00
partitions-32MiB.csv esp32: Add 32MiB partition table templates. 2022-11-09 10:57:44 +11:00
partitions-ota.csv esp32/makeimg.py: Load sizes from partition table and verify data fits. 2021-06-11 15:43:49 +10:00
partitions.csv esp32/partitions: Increase size of app-part from 0x180000 to 0x1F0000. 2022-01-27 16:44:13 +11:00
ppp_set_auth.c esp32/ppp_set_auth: Add pppapi_set_auth from ESP-IDF. 2023-06-23 15:34:22 +10:00
ppp_set_auth.h esp32/ppp_set_auth: Add pppapi_set_auth from ESP-IDF. 2023-06-23 15:34:22 +10:00
qstrdefsport.h all: Add *FORMAT-OFF* in various places. 2020-02-28 10:31:07 +11:00
uart.c esp32: Switch from UART driver to UART HAL. 2023-06-23 15:34:22 +10:00
uart.h esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
usb.c esp32/usb: Add custom TinyUSB callback support. 2023-07-20 23:55:35 +10:00
usb.h esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
usb_serial_jtag.c esp32: Update port to support IDF v5.0.2. 2023-06-23 15:34:22 +10:00
usb_serial_jtag.h esp32/boards: Add GENERIC_C3_USB board with USB serial/JTAG support. 2021-08-31 00:12:41 +10:00

README.md

MicroPython port to the ESP32

This is a port of MicroPython to the Espressif ESP32 series of microcontrollers. 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 approximately 100k 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.
  • Bluetooth low-energy (BLE) support via the bluetooth module.

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

Setting up ESP-IDF and the build environment

MicroPython on ESP32 requires the Espressif IDF version 5 (IoT development framework, aka SDK). The ESP-IDF includes the libraries and RTOS needed to manage the ESP32 microcontroller, as well as a way to manage the required build environment and toolchains needed to build the firmware.

The ESP-IDF changes quickly and MicroPython only supports certain versions. Currently MicroPython supports only v5.0.2.

To install the ESP-IDF the full instructions can be found at the Espressif Getting Started guide.

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 instructions rather than the Windows instructions.

The Espressif instructions will guide you through using the install.sh (or install.bat) script to download the toolchain and set up your environment. The steps to take are summarised below.

To check out a copy of the IDF use git clone:

$ git clone -b v5.0.2 --recursive https://github.com/espressif/esp-idf.git

You can replace v5.0.2 with any other supported version. (You don't need a full recursive clone; see the ci_esp32_setup function in tools/ci.sh in this repository for more detailed set-up commands.)

If you already have a copy of the IDF then checkout a version compatible with MicroPython and update the submodules using:

$ cd esp-idf
$ git checkout v5.0.2
$ git submodule update --init --recursive

After you've cloned and checked out the IDF to the correct version, run the install.sh script:

$ cd esp-idf
$ ./install.sh       # (or install.bat on Windows)
$ source export.sh   # (or export.bat on Windows)

The install.sh step only needs to be done once. You will need to source export.sh for every new session.

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

Then to build MicroPython for the ESP32 run:

$ cd ports/esp32
$ make submodules
$ make

This will produce a combined firmware.bin image in the build-GENERIC/ subdirectory (this firmware image is made up of: bootloader.bin, partitions.bin and micropython.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. 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. (Note: on some distributions this may be the uucp group, run ls -la /dev/ttyUSB0 to check.)

$ 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

The default ESP32 board build by the above commands is the GENERIC one, which should work on most ESP32 modules. You can specify a different board by passing BOARD=<board> to the make commands, for example:

$ make BOARD=GENERIC_SPIRAM

Note: the above "make" commands are thin wrappers for the underlying idf.py build tool that is part of the ESP-IDF. You can instead use idf.py directly, for example:

$ idf.py build
$ idf.py -D MICROPY_BOARD=GENERIC_SPIRAM build
$ idf.py flash

Getting a Python prompt on the device

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

or

$ miniterm.py /dev/ttyUSB0 115200

You can also use idf.py monitor.

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)

Defining a custom ESP32 board

The default ESP-IDF configuration settings are provided by the GENERIC board definition in the directory boards/GENERIC. For a custom configuration you can define your own board directory. Start a new board configuration by copying an existing one (like GENERIC) and modifying it to suit your board.

MicroPython specific configuration values are defined in the board-specific mpconfigboard.h file, which is included by mpconfigport.h. Additional settings are put in mpconfigboard.cmake, including a list of sdkconfig files that configure ESP-IDF settings. Some standard sdkconfig files are provided in the boards/ directory, like boards/sdkconfig.ble. You can also define custom ones in your board directory.

See existing board definitions for further examples of configuration.

Configuration Troubleshooting

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