Nov 4, 2025 · Oct 7, 2025 · Oct 7, 2025 · Oct 7, 2025 · Oct 7, 2025 · Oct 8, 2025
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
 name: Publish Python Package

 on:
  #trigger when publishing a release
  #Trigger when publishing a release.
  release:
    types: [published]

  #also allow triggering this workflow manually for testing
  #Also allow triggering this workflow manually for testing.
  workflow_dispatch:

 jobs:
    - name: Checkout
      uses: actions/checkout@v3
      with:
        #just fetching 1 commit is not enough for setuptools-scm, so we fetch all
        #Fetching a single commit is not enough for setuptools-scm, so we fetch all commits.
        fetch-depth: 0
    - name: Set up Python
      uses: actions/setup-python@v2
    - name: Build package
      run: |
        python setup.py sdist
        rm dist/*.orig  #clean sdist_upip noise
        rm dist/*.orig  #Remove sdist_upip noise.
    - name: Publish to Test PyPI
      uses: pypa/gh-action-pypi-publish@release/v1
      with:
diff --git a/.github/workflows/run_tests.yaml b/.github/workflows/run_tests.yaml
    - name: Build MicroPython
      id: build_micropython
      run: |
        echo "Buildingmicropython"
        echo "BuildingMicroPython"
        git clone --depth 1 https://github.com/micropython/micropython.git
        pushd micropython/mpy-cross
        make
    - name: Fetch binutils-esp32ulp
      id: fetch_binutils
      run: |
        echo "Fetching URL ofpre-built esp32ulp-elf binaries"
        ## URL topre-built binaries is published inesp-idf
        echo "Fetching URL ofprebuilt esp32ulp-elf binaries"
        ##TheURL toprebuilt binaries is published inESP-IDF
        IDFVER=v5.0.1
        curl -s \
          -o tools.json \
diff --git a/AUTHORS b/AUTHORS
 E-mail addresses listed here are not intended for support.
 Email addresses listed here are not intended for support requests.

 micropython-esp32-ulp authors
 -----------------------------
diff --git a/CHANGES b/CHANGES
 ChangeLog
 =========
 Change log
 ==========

 1.2.0,release 2022-03-26
 1.2.0,released 2022-03-26

 -project moved tomicropythonorganization
 -project renamed from py-esp32-ulp to micropython-esp32-ulp
 - (no functional changes)
 -Project moved tothe MicroPythonorganization.
 -Project renamed from py-esp32-ulp to micropython-esp32-ulp.
 - (No functional changes.)

 1.1.0, released 2021-12-03

 1.1.0, release 2021-12-03

 - first pypi release
 - First PyPI release.

diff --git a/README.rst b/README.rst
 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 ona ESP32 microcontroller.
 ULP-FSM (not RISC-V) machine code binary, directly onan 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>`_
 * 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 differentthan that of the original ESP32 ULP. You need to
         select the ``esp32s2``cpu (`see docs </docs/index.rst>`_) when assembling code for
 .. [#f1] Note: the ESP32-S2 and ESP32-S3 have the same ULP binary format,
         but the binary format is differentfrom 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
         offsets anyway, and many registers live at the same relative offset on all 3 variants.
         This conveniently means that the same assembly code canbeassembled 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:
 To get going, run the following directly on the ESP32:

 .. code-block:: python

   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.
 load and run the resulting binary, and exchange data between the ULP and the main CPU.


 Documentation
 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 versionsbefore that
 did notenable the ``esp32.ULP`` class).
 The minimum supported version of MicroPython is v1.12. (For ESP32-S2 andESP32-S3
 devices, a version greater than v1.20 is required, asearlierversionsdid not
 enable the ``esp32.ULP`` class).

 An ESP32 device is required to run the ULP machine code binary produced by
 micropython-esp32-ulp.
diff --git a/demo.S b/demo.S
            rsh r0, r1, 42
            move r0, r1
            move r0, 42
            move r0, textstart  #moves abs addr of textstart to r0
            move r0, textstart  #Move the absolute address of textstart to r0
            move r0, constant42
            stage_rst
            stage_inc 42
 data2:      .skip 4
 dataw:      .word 1, 2, 3, 4
 datal:      .long 1, 2, 3, 4
 datab:      .byte 1, 2, 3  #test alignment/ fill upof section
 datab:      .byte 1, 2, 3  #Test alignmentand fill upthe section
 dataend:

            .bss
 bss0:       .skip 4
 bss1:       .skip 2  #test alignment/ fill upof section
 bss1:       .skip 2  #Test alignmentand fill upthe section
 bssend:
diff --git a/docs/disassembler.rst b/docs/disassembler.rst
 The simplest and default mode of the disassembler is to disassemble the
 specified file.

 Note that the ULP header isvalidates and files with unknown magic bytes will be
 Note that the ULP header isvalidated and files with unknown magic bytes will be
 rejected. The correct 4 magic bytes at the start of a ULP binary are ``ulp\x00``.

 Example disassembling an ESP32 ULP binary:
 Disassembling a byte sequence
 -----------------------------

 The ``-m`` option allows disassembling asequences hex letters representing
 The ``-m`` option allows disassembling asequence of hex letters representing
 ULP instructions.

 This option expects the actual instructions directly, without any ULP header.

 The sequence must contain a number of hex letters exactly divisible by 8, i.e.
 8, 16, 24, etc, because each 32-bit word is made up of 8 hex letters. Spaces
 8, 16, 24, etc., because each 32-bit word is made up of 8 hex letters. Spaces
 can be included in the sequence and they are ignored.

 The typical use case for this feature is to copy/paste some instructions from

 To use the disassembler on a real device:

 *ensure ``micropython-esp32-ulp`` is installed on the device (see `docs/index.rst </docs/index.rst>`_).
 *upload ``tools/disassemble.py`` ``tools/decode.py`` and ``tools/decode_s2.py`` to the device
 *Ensure ``micropython-esp32-ulp`` is installed on the device (see `docs/index.rst </docs/index.rst>`_).
 *Upload ``tools/disassemble.py``, ``tools/decode.py``, and ``tools/decode_s2.py`` to the device
  (any directory will do, as long as those 3 files are in the same directory)
 *the following example code assumes you placed the 3 files into the device's "root" directory
 *run the following (note, we must specify whichthe cpu the binary is for):
 *The following example code assumes you placed the 3 files into the device's "root" directory
 *Run the following (note, we must specify whichCPU the binary is for):

  .. code-block:: python

diff --git a/docs/index.rst b/docs/index.rst
 ++++++++++++

 The simplest example to try on the ESP32 is `counter.py </examples/counter.py>`_.
 It shows how to assemble code, load and run the resulting binary and exchange
 It shows how to assemble code, load and run the resulting binary, and exchange
 data between the ULP and the main CPU.

 Run the ``counter.py`` example:
   micropython -m esp32_ulp path/to/code.S  # this results in path/to/code.ulp

 The assembler supports selecting a CPU to assemble for using the ``-c`` option
 (validcpu's are ``esp32`` and ``esp32s2``):
 (validCPUs are ``esp32`` and ``esp32s2``):

 .. code-block:: shell

 time matters.

 Splitting the assembly and load stage can be combined with other techniques,
 for example to implement a cachingmechansim for the ULP binary that
 for example, to implement a cachingmechanism for the ULP binary that
 automatically updates the binary every time the assembly source code changes.

 The ``esp32_ulp.assemble_file`` function can be used to assemble and link an
          # start the ULP
          # assemble_file printed offsets in number of 32-bit words.
          # ulp.run() expects an offset in number of bytes.
          # Thus, multiply the offsetto our entry point by 4.
          # Thus, multiply the offsetof our entry point by 4.
          # e.g. for an offset of 2:
          #   2 words * 4 = 8 bytes
          ulp.run(2*4)  # specify the offset of the entry point label
 -------

 There are unit tests and also compatibility tests that check whether the binary
 output is identicalwith what Espressif's esp32-elf-as (from their `binutils-gdb fork
 output is identicalto what Espressif's esp32-elf-as (from their `binutils-gdb fork
 <https://github.com/espressif/binutils-gdb/tree/esp32ulp-elf-2.35>`_) produces.

 micropython-esp32-ulp has been tested on the Unix port of MicroPython and on real ESP32
 devices with the chip type ESP32D0WDQ6 (revision 1) without SPIRAM as well as ESP32-S2
 (ESP32-S2FH4) and ESP32-S3 (ESP32-S3R8) devices.

 Consult theGithub Actions `workflow definition file </.github/workflows/run_tests.yaml>`_
 Consult theGitHub Actions `workflow definition file </.github/workflows/run_tests.yaml>`_
 for how to run the different tests.


diff --git a/docs/preprocess.rst b/docs/preprocess.rst
 framework's include files (such as ``RTC_GPIO_IN_REG``), to make reading
 and writing from/to peripheral registers much easier.

 In order to do this the preprocessor has two capabilities:
 In order to do this, the preprocessor has two capabilities:

 1. Parse and replace identifiers defined with ``#define``
 2. Recognise the ``WRITE_RTC_*`` and ``READ_RTC_*`` macros and expand
 Usage
 ------------------------

 Normally the assembler is called as follows
 Normally the assembler is called as follows:

 ..code-block::python

 Because the micropython-esp32-ulp assembler was built for running on the ESP32
 microcontroller with limited RAM, the preprocessor aims to work there too.

 To handle large number of defined constants (such as the ``RTC_*`` constants from
 the ESP-IDF) the preprocessor can use a database (based onBerkleyDB) stored on the
 To handlealarge number of defined constants (such as the ``RTC_*`` constants from
 the ESP-IDF) the preprocessor can use a database (based onBerkeley DB) stored on the
 device's filesystem for looking up defines.

 The database needs to be populated before preprocessing. (Usually, when only using
   database from include files. The resulting file will be called
   ``defines.db``.

   (The followingassume running on a PC. To do this on device, refer to the
   (The followingassumes running on a PC. To do this on device, refer to the
   `esp32_ulp/parse_to_db.py<../esp32_ulp/parse_to_db.py>`_ file.)

   ..code-block::bash

 # if file system space is not a concern, the following can be convenient
 # by including all relevant include files from the ESP-IDF framework.
 # This results in an approximately2MB large database.
 # This results in an approximately2 MB large database.
      micropython -m esp32_ulp.parse_to_db \
        esp-idf/components/soc/esp32/include/soc/*.h \
        esp-idf/components/esp_common/include/*.h

 # most ULP code uses only 5 include files. Parsing only those into the
 # database should thus allow assembling virtually all ULP code one would
 # find or want to write.
 # This results in an approximately250kB large database.
 # This results in an approximately250 kB large database.
      micropython -m esp32_ulp.parse_to_db \
        esp-idf/components/soc/esp32/include/soc/{soc,soc_ulp,rtc_cntl_reg,rtc_io_reg,sens_reg}.h


   ..warning::

 `:warning:`Ensure that you include the header files for the correct
      Ensure that you include the header files for the correct
      variant you are working with. In the example code above, simply switch
      ``esp32`` to ``esp32s2`` or ``esp32s3`` in the path to the include files.

   is taken not to create an empty database file, cluttering up the filesystem,
   when not needed).

   If you do not want the preprocessoruse use a DefinesDB, pass ``False`` to
   If you do not want the preprocessorto use a DefinesDB, pass ``False`` to
   the ``use_defines_db`` argument of the ``preprocess`` convenience function,
   or instantiate the ``Preprocessor`` class directly, without passing it a
   DefinesDB instance via ``use_db``.

 The preprocessor does not support:

 1. Functionstyle macros such as:code:`#define f(a,b) (a+b)`
 1. Function-style macros such as:code:`#define f(a,b) (a+b)`

   This is not important, because there are only few RTC macros that need
   to be supported and they are simply implemented as Python functions.
diff --git a/esp32_ulp/__main__.py b/esp32_ulp/__main__.py
 ifsys.argv[1]in ('-c','--mcpu'):
 cpu=sys.argv[2].lower()
 ifcpunotin ('esp32','esp32s2'):
 raiseValueError('Invalidcpu')
 raiseValueError('InvalidCPU')
 filename=sys.argv[3]
 main(filename,cpu)

diff --git a/esp32_ulp/assemble.py b/esp32_ulp/assemble.py
        elif cpu == 'esp32s2':
            opcode_module = 'opcodes_s2'
        else:
            raise ValueError('Invalidcpu')
            raise ValueError('InvalidCPU')

        relative_import = 1 if '/' in __file__ else 0
        self.opcodes = __import__(opcode_module, None, None, [], relative_import)
        # regex for parsing assembly lines
        # format: [[whitespace]label:][whitespace][opcode[whitespace arg[,arg...]]]
        # where [] means optional
        #initialised here once, instead of compiling once per line
        #initialized here once, instead of compiling once per line
        self.line_regex = re.compile(r'^(\s*([a-zA-Z0-9_$.]+):)?\s*((\S*)\s*(.*))$')

    def init(self, a_pass):
diff --git a/esp32_ulp/preprocess.py b/esp32_ulp/preprocess.py
        identifier, value = parts
        tmp = identifier.split('(', 1)
        if len(tmp) == 2:
            # skipparameterised defines (macros)
            # skipparameterized defines (macros)
            return {}
        value = "".join(nocomment.remove_comments(value)).strip()
        return {identifier: value}

    def expand_defines(self, line):
        found = True
        while found:  # do as manypassed as needed, until nothingwas replaced anymore
        while found:  # do as manypasses as needed, until nothingis replaced anymore
            found = False
            tokens = split_tokens(line)
            line = ""
        if macro_fn is None:
            return line

        macro_args, _ = macro_args.rsplit(')', 1)  # trim away right bracket. safe as comments already stripped
        macro_args = macro_args.split(',')  # not safe when args contain ',' but we should not have those
        macro_args, _ = macro_args.rsplit(')', 1)  # trim awaytheright bracket; safe as comments are already stripped
        macro_args = macro_args.split(',')  # not safe when args contain ','; we should not have those
        macro_args = [x.strip() for x in macro_args]

        return macro_fn(*macro_args)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -8,11 +8,11 @@
		name: Publish Python Package

		on:
		#trigger when publishing a release
		#Trigger when publishing a release.
		release:
		types: [published]

		#also allow triggering this workflow manually for testing
		#Also allow triggering this workflow manually for testing.
		workflow_dispatch:

		jobs:
Expand All		@@ -24,7 +24,7 @@ jobs:
		- name: Checkout
		uses: actions/checkout@v3
		with:
		#just fetching 1 commit is not enough for setuptools-scm, so we fetch all
		#Fetching a single commit is not enough for setuptools-scm, so we fetch all commits.
		fetch-depth: 0
		- name: Set up Python
		uses: actions/setup-python@v2
Expand All		@@ -36,7 +36,7 @@ jobs:
		- name: Build package
		run: \|
		python setup.py sdist
		rm dist/*.orig #clean sdist_upip noise
		rm dist/*.orig #Remove sdist_upip noise.
		- name: Publish to Test PyPI
		uses: pypa/gh-action-pypi-publish@release/v1
		with:
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -32,7 +32,7 @@ jobs:
		- name: Build MicroPython
		id: build_micropython
		run: \|
		echo "Buildingmicropython"
		echo "BuildingMicroPython"
		git clone --depth 1 https://github.com/micropython/micropython.git
		pushd micropython/mpy-cross
		make
Expand All		@@ -50,8 +50,8 @@ jobs:
		- name: Fetch binutils-esp32ulp
		id: fetch_binutils
		run: \|
		echo "Fetching URL ofpre-built esp32ulp-elf binaries"
		## URL topre-built binaries is published inesp-idf
		echo "Fetching URL ofprebuilt esp32ulp-elf binaries"
		##TheURL toprebuilt binaries is published inESP-IDF
		IDFVER=v5.0.1
		curl -s \
		-o tools.json \
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,4 @@
		E-mail addresses listed here are not intended for support.
		Email addresses listed here are not intended for support requests.

		micropython-esp32-ulp authors
		-----------------------------
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,14 +1,13 @@
		ChangeLog
		=========
		Change log
		==========

		1.2.0,release 2022-03-26
		1.2.0,released 2022-03-26

		-project moved tomicropythonorganization
		-project renamed from py-esp32-ulp to micropython-esp32-ulp
		- (no functional changes)
		-Project moved tothe MicroPythonorganization.
		-Project renamed from py-esp32-ulp to micropython-esp32-ulp.
		- (No functional changes.)

		1.1.0, released 2021-12-03

		1.1.0, release 2021-12-03

		- first pypi release
		- First PyPI release.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -15,7 +15,7 @@ micropython-esp32-ulp is an assembler toolchain for the ESP32 ULP (Ultra Low-Pow
		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 ona ESP32 microcontroller.
		ULP-FSM (not RISC-V) machine code binary, directly onan 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>`_
Expand All		@@ -39,26 +39,26 @@ The following features are supported:
		* 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 differentthan that of the original ESP32 ULP. You need to
		select the ``esp32s2``cpu (`see docs </docs/index.rst>`_) when assembling code for
		.. [#f1] Note: the ESP32-S2 and ESP32-S3 have the same ULP binary format,
		but the binary format is differentfrom 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
		offsets anyway, and many registers live at the same relative offset on all 3 variants.
		This conveniently means that the same assembly code canbeassembled 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:
		To get going, run the following directly on the ESP32:

		.. code-block:: python

Expand All		@@ -77,7 +77,7 @@ To get going run the following directly on the ESP32:
		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.
		load and run the resulting binary, and exchange data between the ULP and the main CPU.


		Documentation
Expand All		@@ -88,9 +88,9 @@ See `docs/index.rst </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 versionsbefore that
		did notenable the ``esp32.ULP`` class).
		The minimum supported version of MicroPython is v1.12. (For ESP32-S2 andESP32-S3
		devices, a version greater than v1.20 is required, asearlierversionsdid not
		enable the ``esp32.ULP`` class).

		An ESP32 device is required to run the ULP machine code binary produced by
		micropython-esp32-ulp.
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -27,7 +27,7 @@ textstart: ld r0, r1, 0 # a comment!
		rsh r0, r1, 42
		move r0, r1
		move r0, 42
		move r0, textstart #moves abs addr of textstart to r0
		move r0, textstart #Move the absolute address of textstart to r0
		move r0, constant42
		stage_rst
		stage_inc 42
Expand DownExpand Up		@@ -70,10 +70,10 @@ data1: .space 4, 0x42
		data2: .skip 4
		dataw: .word 1, 2, 3, 4
		datal: .long 1, 2, 3, 4
		datab: .byte 1, 2, 3 #test alignment/ fill upof section
		datab: .byte 1, 2, 3 #Test alignmentand fill upthe section
		dataend:

		.bss
		bss0: .skip 4
		bss1: .skip 2 #test alignment/ fill upof section
		bss1: .skip 2 #Test alignmentand fill upthe section
		bssend:
Original file line number	Diff line number	Diff line change
Expand Up		@@ -42,7 +42,7 @@ Disassembling a file
		The simplest and default mode of the disassembler is to disassemble the
		specified file.

		Note that the ULP header isvalidates and files with unknown magic bytes will be
		Note that the ULP header isvalidated and files with unknown magic bytes will be
		rejected. The correct 4 magic bytes at the start of a ULP binary are ``ulp\x00``.

		Example disassembling an ESP32 ULP binary:
Expand DownExpand Up		@@ -75,13 +75,13 @@ Example disassembling an ESP32-S2 ULP binary:
		Disassembling a byte sequence
		-----------------------------

		The ``-m`` option allows disassembling asequences hex letters representing
		The ``-m`` option allows disassembling asequence of hex letters representing
		ULP instructions.

		This option expects the actual instructions directly, without any ULP header.

		The sequence must contain a number of hex letters exactly divisible by 8, i.e.
		8, 16, 24, etc, because each 32-bit word is made up of 8 hex letters. Spaces
		8, 16, 24, etc., because each 32-bit word is made up of 8 hex letters. Spaces
		can be included in the sequence and they are ignored.

		The typical use case for this feature is to copy/paste some instructions from
Expand DownExpand Up		@@ -148,11 +148,11 @@ The disassembler also works when used on an ESP32 device.

		To use the disassembler on a real device:

		*ensure ``micropython-esp32-ulp`` is installed on the device (see `docs/index.rst </docs/index.rst>`_).
		*upload ``tools/disassemble.py`` ``tools/decode.py`` and ``tools/decode_s2.py`` to the device
		*Ensure ``micropython-esp32-ulp`` is installed on the device (see `docs/index.rst </docs/index.rst>`_).
		*Upload ``tools/disassemble.py``, ``tools/decode.py``, and ``tools/decode_s2.py`` to the device
		(any directory will do, as long as those 3 files are in the same directory)
		*the following example code assumes you placed the 3 files into the device's "root" directory
		*run the following (note, we must specify whichthe cpu the binary is for):
		*The following example code assumes you placed the 3 files into the device's "root" directory
		*Run the following (note, we must specify whichCPU the binary is for):

		.. code-block:: python

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -37,7 +37,7 @@ On the ESP32
		++++++++++++

		The simplest example to try on the ESP32 is `counter.py </examples/counter.py>`_.
		It shows how to assemble code, load and run the resulting binary and exchange
		It shows how to assemble code, load and run the resulting binary, and exchange
		data between the ULP and the main CPU.

		Run the ``counter.py`` example:
Expand DownExpand Up		@@ -65,7 +65,7 @@ follows:
		micropython -m esp32_ulp path/to/code.S # this results in path/to/code.ulp

		The assembler supports selecting a CPU to assemble for using the ``-c`` option
		(validcpu's are ``esp32`` and ``esp32s2``):
		(validCPUs are ``esp32`` and ``esp32s2``):

		.. code-block:: shell

Expand All		@@ -91,7 +91,7 @@ This can be useful in battery-powered applications where every second of sleep
		time matters.

		Splitting the assembly and load stage can be combined with other techniques,
		for example to implement a cachingmechansim for the ULP binary that
		for example, to implement a cachingmechanism for the ULP binary that
		automatically updates the binary every time the assembly source code changes.

		The ``esp32_ulp.assemble_file`` function can be used to assemble and link an
Expand DownExpand Up		@@ -128,7 +128,7 @@ That file can then be loaded directly without assembling the source again.
		# start the ULP
		# assemble_file printed offsets in number of 32-bit words.
		# ulp.run() expects an offset in number of bytes.
		# Thus, multiply the offsetto our entry point by 4.
		# Thus, multiply the offsetof our entry point by 4.
		# e.g. for an offset of 2:
		# 2 words * 4 = 8 bytes
		ulp.run(2*4) # specify the offset of the entry point label
Expand DownExpand Up		@@ -173,14 +173,14 @@ Testing
		-------

		There are unit tests and also compatibility tests that check whether the binary
		output is identicalwith what Espressif's esp32-elf-as (from their `binutils-gdb fork
		output is identicalto what Espressif's esp32-elf-as (from their `binutils-gdb fork
		<https://github.com/espressif/binutils-gdb/tree/esp32ulp-elf-2.35>`_) produces.

		micropython-esp32-ulp has been tested on the Unix port of MicroPython and on real ESP32
		devices with the chip type ESP32D0WDQ6 (revision 1) without SPIRAM as well as ESP32-S2
		(ESP32-S2FH4) and ESP32-S3 (ESP32-S3R8) devices.

		Consult theGithub Actions `workflow definition file </.github/workflows/run_tests.yaml>`_
		Consult theGitHub Actions `workflow definition file </.github/workflows/run_tests.yaml>`_
		for how to run the different tests.


Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -11,7 +11,7 @@ provided by the ESP-IDF framework, along with constants defined in the
		framework's include files (such as ``RTC_GPIO_IN_REG``), to make reading
		and writing from/to peripheral registers much easier.

		In order to do this the preprocessor has two capabilities:
		In order to do this, the preprocessor has two capabilities:

		1. Parse and replace identifiers defined with ``#define``
		2. Recognise the ``WRITE_RTC_`` and ``READ_RTC_`` macros and expand
Expand All		@@ -21,7 +21,7 @@ In order to do this the preprocessor has two capabilities:
		Usage
		------------------------

		Normally the assembler is called as follows
		Normally the assembler is called as follows:

		..code-block::python

Expand DownExpand Up		@@ -49,8 +49,8 @@ Using a "Defines Database"
		Because the micropython-esp32-ulp assembler was built for running on the ESP32
		microcontroller with limited RAM, the preprocessor aims to work there too.

		To handle large number of defined constants (such as the ``RTC_*`` constants from
		the ESP-IDF) the preprocessor can use a database (based onBerkleyDB) stored on the
		To handlealarge number of defined constants (such as the ``RTC_*`` constants from
		the ESP-IDF) the preprocessor can use a database (based onBerkeley DB) stored on the
		device's filesystem for looking up defines.

		The database needs to be populated before preprocessing. (Usually, when only using
Expand All		@@ -67,7 +67,7 @@ are not needed on the device either.)
		database from include files. The resulting file will be called
		``defines.db``.

		(The followingassume running on a PC. To do this on device, refer to the
		(The followingassumes running on a PC. To do this on device, refer to the
		`esp32_ulp/parse_to_db.py<../esp32_ulp/parse_to_db.py>`_ file.)

		..code-block::bash
Expand All		@@ -83,22 +83,22 @@ are not needed on the device either.)

		# if file system space is not a concern, the following can be convenient
		# by including all relevant include files from the ESP-IDF framework.
		# This results in an approximately2MB large database.
		# This results in an approximately2 MB large database.
		micropython -m esp32_ulp.parse_to_db \
		esp-idf/components/soc/esp32/include/soc/*.h \
		esp-idf/components/esp_common/include/*.h

		# most ULP code uses only 5 include files. Parsing only those into the
		# database should thus allow assembling virtually all ULP code one would
		# find or want to write.
		# This results in an approximately250kB large database.
		# This results in an approximately250 kB large database.
		micropython -m esp32_ulp.parse_to_db \
		esp-idf/components/soc/esp32/include/soc/{soc,soc_ulp,rtc_cntl_reg,rtc_io_reg,sens_reg}.h


		..warning::

		`:warning:`Ensure that you include the header files for the correct
		Ensure that you include the header files for the correct
		variant you are working with. In the example code above, simply switch
		``esp32`` to ``esp32s2`` or ``esp32s3`` in the path to the include files.

Expand All		@@ -118,7 +118,7 @@ are not needed on the device either.)
		is taken not to create an empty database file, cluttering up the filesystem,
		when not needed).

		If you do not want the preprocessoruse use a DefinesDB, pass ``False`` to
		If you do not want the preprocessorto use a DefinesDB, pass ``False`` to
		the ``use_defines_db`` argument of the ``preprocess`` convenience function,
		or instantiate the ``Preprocessor`` class directly, without passing it a
		DefinesDB instance via ``use_db``.
Expand All		@@ -129,7 +129,7 @@ Design choices

		The preprocessor does not support:

		1. Functionstyle macros such as:code:`#define f(a,b) (a+b)`
		1. Function-style macros such as:code:`#define f(a,b) (a+b)`

		This is not important, because there are only few RTC macros that need
		to be supported and they are simply implemented as Python functions.
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -20,7 +20,7 @@ def main(fn, cpu):
		ifsys.argv[1]in ('-c','--mcpu'):
		cpu=sys.argv[2].lower()
		ifcpunotin ('esp32','esp32s2'):
		raiseValueError('Invalidcpu')
		raiseValueError('InvalidCPU')
		filename=sys.argv[3]
		main(filename,cpu)