micropython-esp32-ulp
micropython-esp32-ulp is an assembler toolchain for the ESP32 ULP (Ultra Low-Power) Co-Processor, written in MicroPython.
It can translate small assembly language programs to a loadable/executable ULP-FSM (not RISC-V) machine code binary, directly on a ESP32 microcontroller.
This is intended as an alternative approach to assembling such programs using the binutils-gdb toolchain (esp32-elf-as) from Espressif on a development machine.
It can also be useful in cases where esp32-elf-as is not available.
Features
The following features are supported:
- the entire ESP32 ULP instruction set
- the entire ESP32-S2 ULP instruction set (this also covers the ESP32-S3) [1] [2]
- constants defined with
.set - constants defined with
#define - expressions in assembly code and constant definitions
- RTC convenience macros (e.g.
WRITE_RTC_REG) - many ESP32 ULP code examples found on the web will work unmodified
- a simple disassembler is also provided
| [1] | Note: the ESP32-S2 and ESP32-S3 have the same ULP binary format between each other
but the binary format is different than that of the original ESP32 ULP. You need to
select the esp32s2 cpu (see docs) when assembling code for
use on an ESP32-S2/S3. |
| [2] | Note: The ESP32-S2 and ESP32-S3 have the same ULP binary format, but the peripheral
register addresses (those accessed with REG_RD and REG_WR) are different. For best
results, use the correct peripheral register addresses for the specific variant you
are working with. The assembler (when used with cpu=esp32s2) will accept
addresses for any of the 3 variants, because they are translated into relative
offsets anyway and many registers live at the same relative offset on all 3 variants.
This conveniently means that the same assembly code can assembled unmodified for each
variant and produce a correctly working binary - as long as only peripheral registers
are used, which have the same relative offset across the variants. Use with care! |
Quick start
To get going run the following directly on the ESP32:
# IMPORTANT: Ensure the ESP32 is connected to a network with internet connectivity.
# Step 1: Install micropython-esp32-ulp (for MicroPython v1.20 or newer)
import mip
mip.install('github:micropython/micropython-esp32-ulp')
# Step 1: Install micropython-esp32-ulp (for MicroPython older than v1.20)
import upip
upip.install('micropython-esp32-ulp')
# Step 2: Run an example
# First, upload examples/counter.py to the ESP32.
import counterThe examples/counter.py example shows how to assemble code, load and run the resulting binary and exchange data between the ULP and the main CPU.
Documentation
See docs/index.rst.
Requirements
The minimum supported version of MicroPython is v1.12. (For ESP32-S2 and S3
devices, a version greater than v1.20 is required as versions before that
did not enable the esp32.ULP class).
An ESP32 device is required to run the ULP machine code binary produced by micropython-esp32-ulp.
License
This project is released under the MIT License.