https://github.com/micropython/micropython-esp32-ulp
ESP32 ULP Co-Processor toolchain implemented in MicroPython
https://github.com/micropython/micropython-esp32-ulp
assembler esp32 micropython ulp
Last synced: 8 months ago
JSON representation
ESP32 ULP Co-Processor toolchain implemented in MicroPython
- Host: GitHub
- URL: https://github.com/micropython/micropython-esp32-ulp
- Owner: micropython
- License: mit
- Created: 2018-03-11T17:02:15.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-12-15T14:54:59.000Z (11 months ago)
- Last Synced: 2025-03-28T07:04:29.007Z (8 months ago)
- Topics: assembler, esp32, micropython, ulp
- Language: Python
- Size: 186 KB
- Stars: 123
- Watchers: 17
- Forks: 25
- Open Issues: 16
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGES
- License: LICENSE
- Authors: AUTHORS
Awesome Lists containing this project
README
.. 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
=====================
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) [#f1]_ [#f2]_
* 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
.. [#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 `_) 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!
Quick start
-----------
To get going run the following directly on the ESP32:
.. code-block:: python
# 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 counter
The `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 `_.