.. start-badges
.. image:: ../../actions/workflows/run_tests.yaml/badge.svg :height: 20px :target: ../../actions/workflows/run_tests.yaml :alt: Build Status
.. end-badges
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 <https://github.com/espressif/binutils-gdb/tree/esp32ulp-elf-2.35>
_
(esp32-elf-as) from Espressif on a development machine.
It can also be useful in cases where esp32-elf-as is not available.
The following features are supported:
ESP32 ULP instruction set <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/ulp_instruction_set.html>
_ESP32-S2 ULP instruction set <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/system/ulp_instruction_set.html>
(this also covers the ESP32-S3) [#f1] [#f2]_.set
#define
WRITE_RTC_REG
).. [#f1] 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 </docs/index.rst>
_) when assembling code for
use on an ESP32-S2/S3.
.. [#f2] 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!
To get going run the following directly on the ESP32:
.. code-block:: python
import mip mip.install('github:micropython/micropython-esp32-ulp')
import upip upip.install('micropython-esp32-ulp')
import counter
The examples/counter.py </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.
See docs/index.rst </docs/index.rst>
_.
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.
This project is released under the MIT License </LICENSE>
_.