8000 restructure documentation into short README and detailed docs · lmarkrol/micropython-esp32-ulp@1b1b1d8 · GitHub
[go: up one dir, main page]
Skip to content

Commit 1b1b1d8

Browse files
wnienhauswnienhaus
committed
restructure documentation into short README and detailed docs
The README now only covers the most important - mainly what this project is and how to get started. It then references the documentation for more detail. The documentation in turn contains more detail.
1 parent 26048c8 commit 1b1b1d8

File tree

2 files changed

+214
-134
lines changed

2 files changed

+214
-134
lines changed

‎README.rst

Lines changed: 25 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -17,43 +17,8 @@ This is intended as an alternative approach to assembling such programs using
1717
the binutils-esp32ulp toolchain from Espressif on a development machine.
1818

1919

20-
Installation
21-
------------
22-
23-
On the ESP32, install using upip:
24-
25-
.. code-block:: python
26-
27-
# ensure the ESP32 is connected to a network with internet connectivity
28-
import upip
29-
upip.install('micropython-py-esp32-ulp')
30-
31-
On a PC, simply ``git clone`` this repo.
32-
33-
34-
Getting Started
35-
---------------
36-
37-
The quickest way to get started is to try one of the `examples <examples/>`_.
38-
39-
The simplest example is `counter.py <examples/counter.py>`_. It shows how to
40-
assemble code, load and run the resulting binary and exchange data between the
41-
ULP and the main CPU.
42-
43-
Run the ``counter.py`` example:
44-
45-
1. Install py-esp32-ulp onto the ESP32 as shown above
46-
2. Upload the `counter.py <examples/counter.py>`_ file to the ESP32
47-
3. Run with ``import counter``
48-
49-
You can also try the `blink.py <examples/blink.py>`_ example, which shows how to
50-
let the ULP blink an LED.
51-
52-
Look inside each example for a more detailed description.
53-
54-
55-
Support
56-
-------
20+
Features
21+
--------
5722

5823
The following features are supported:
5924

@@ -64,119 +29,45 @@ The following features are supported:
6429
* RTC convenience macros (e.g. WRITE_RTC_REG)
6530
* many ESP32 ULP code examples found on the web will work unmodified
6631

67-
Currently not supported:
68-
69-
* assembler macros using ``.macro``
70-
* preprocessor macros using ``#define A(x,y) ...``
71-
* including files using ``#include``
72-
* ESP32-S2 (not binary compatible with the ESP32)
73-
74-
75-
Requirements
76-
------------
77-
78-
The minimum supported version of MicroPython is v1.12.
79-
80-
py-esp32-ulp has been tested on the Unix port of MicroPython and on real ESP32
81-
devices with the chip type ESP32D0WDQ6 (revision 1) without SPIRAM.
82-
83-
84-
Advanced usage
85-
--------------
86-
87-
In real world applications, you might want to separate the assembly stage from
88-
the loading/running stage, to avoid having to assemble the code on every startup.
89-
This can be useful for battery-powered applications, where every second of sleep
90-
time matters.
91-
92-
Splitting the assembly and load stage can be combined with other techniques to
93-
for example implement a caching mechansim for the ULP binary, which automatically
94-
updates the binary every time the assembly source code changes.
95-
96-
The ``esp32_ulp.assemble_file`` function stores the assembled and linked binary
97-
into a file with a ``.ulp`` extension, which can later be loaded directly without
98-
assembling the source again.
99-
100-
1. Create/upload an assembly source file and run the following to get a loadable
101-
ULP binary as a ``.ulp`` file:
10232

103-
.. code-block:: python
33+
Quick start
34+
-----------
10435

105-
import esp32_ulp
106-
esp32_ulp.assemble_file('code.S') # this results in code.ulp
36+
You can get going, run the following directly on the ESP32:
10737

108-
2. The above prints out the offsets of all global symbols/labels. For the next step,
109-
you will need to note down the offset of the label, which represents the entry
110-
point to your code.
111-
112-
3. Now load and run the resulting binary as follows:
38+
.. code-block:: python
11339
114-
.. code-block:: python
40+
# step 1: install py-esp32-ulp
41+
# important: ensure the ESP32 is connected to a network with internet connectivity
42+
import upip
43+
upip.install('micropython-py-esp32-ulp')
11544
116-
from esp32 import ULP
45+
# step 2: run an example
46+
# first, upload examples/counter.py to the ESP32
47+
import counter
11748
118-
ulp = ULP()
119-
with open('test.ulp', 'r') as f:
120-
# load the binary into RTC memory
121-
ulp.load_binary(0, f.read())
49+
The `counter.py </examples/counter.py>`_ example shows how to assemble code, load
50+
and run the resulting binary and exchange data between the ULP and the main CPU.
12251

123-
F438 # configure how often the ULP should wake up
124-
ulp.set_wakeup_period(0, 500000) # 500k usec == 0.5 sec
52+
You can also try the `blink.py </examples/blink.py>`_ example, which shows how to
53+
let the ULP blink an LED.
12554

126-
# start the ULP
127-
# assemble_file printed offsets in number of 32-bit words.
128-
# ulp.run() expects an offset in number of bytes.
129-
# Thus, multiply the offset to our entry point by 4.
130-
# e.g. for an offset of 2:
131-
# 2 words * 4 = 8 bytes
132-
ulp.run(2*4) # specify the offset of the entry point label
13355

134-
To update the binary every time the source code changes, you would need a mechanism
135-
to detect that the source code changed. Whenever needed, manually re-running the
136-
``assemble_file`` function as shown above, would also work.
56+
Documentation
57+
-------------
58+
See `docs/index.rst </docs/index.rst>`_.
13759

13860

139-
Preprocessor
61+
Requirements
14062
------------
14163

142-
There is a simple preprocessor that understands just enough to allow assembling
143-
ULP source files containing convenience macros such as WRITE_RTC_REG. This is
144-
especially useful for assembling ULP examples from Espressif or other ULP code
145-
found as part of Arduino/ESP-IDF projects.
146-
147-
The preprocessor and how to use it is documented here: `Preprocessor support <docs/preprocess.rst>`_.
148-
149-
150-
Testing
151-
-------
152-
153-
There are unit tests and also compatibility tests that check whether the binary
154-
output is identical with what binutils-esp32ulp produces.
155-
156-
Consult the Github Actions `workflow definition file <.github/workflows/run_tests.yaml>`_
157-
for how to run the different tests.
158-
159-
160-
10000 Links
161-
-----
162-
163-
Espressif documentation:
164-
165-
* `ESP32 ULP coprocessor instruction set <https://esp-idf.readthedocs.io/en/latest/api-guides/ulp_instruction_set.html>`_
166-
* `ESP32 Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_
167-
168-
GNU Assembler "as" documentation (we try to be compatible for all features that are implemented)
169-
170-
* `GNU Assembler manual <https://sourceware.org/binutils/docs/as/index.html>`_
171-
172-
More ULP examples:
64+
The minimum supported version of MicroPython is v1.12.
17365

174-
* https://github.com/espressif/esp-iot-solution/tree/master/examples/ulp_examples
175-
* https://github.com/duff2013/ulptool
176-
* https://github.com/joba-1/Blink-ULP/blob/master/main/ulp/
66+
An ESP32 is required to run the ULP machine code binary produced by py-esp32-ulp
67+
(the ESP32-S2 will not work as it is not binary compatible with the ESP32).
17768

17869

17970
License
18071
-------
18172

182-
This project is released under the `MIT License <LICENSE>`_.
73+
This project is released under the `MIT License </LICENSE>`_.

‎docs/index.rst

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
py-esp32-ulp Documentation
2+
==========================
3+
4+
py-esp32-ulp is an assembler toolchain for the ESP32 ULP (Ultra Low-Power)
5+
Co-Processor, written in MicroPython.
6+
7+
8+
What is it useful for?
9+
----------------------
10+
11+
It can translate small assembly language programs to a loadable/executable
12+
ULP machine code binary, directly on the ESP32 microcontroller.
13+
14+
This is intended as an alternative approach to assembling such programs using
15+
the binutils-esp32ulp toolchain from Espressif on a development machine.
16+
17+
It can also be useful in cases where binutils-esp32ulp is not available.
18+
19+
20+
Features
21+
--------
22+
23+
The following features are supported:
24+
25+
* the entire `ESP32 ULP instruction set <https://esp-idf.readthedocs.io/en/latest/api-guides/ulp_instruction_set.html>`_
26+
* constants defined with ``.set``
27+
* constants defined with ``#define``
28+
* expressions in assembly code and constant definitions
29+
* RTC convenience macros (e.g. WRITE_RTC_REG)
30+
* many ESP32 ULP code examples found on the web will work unmodified
31+
32+
33+
Limitations
34+
-----------
35+
36+
Currently the following are not supported:
37+
38+
* assembler macros using ``.macro``
39+
* preprocessor macros using ``#define A(x,y) ...``
40+
* including files using ``#include``
41+
* ESP32-S2 (not binary compatible with the ESP32)
42+
43+
44+
Installation
45+
------------
46+
47+
On the ESP32, install using upip:
48+
49+
.. code-block:: python
50+
51+
# ensure the ESP32 is connected to a network with internet connectivity
52+
import upip
53+
upip.install('micropython-py-esp32-ulp')
54+
55+
On a PC, simply ``git clone`` this repo.
56+
57+
58+
Examples
59+
--------
60+
61+
Quick start
62+
+++++++++++
63+
The quickest way to get started is to try one of the `examples </examples/>`_.
64+
65+
The simplest example is `counter.py </examples/counter.py>`_. It shows how to
66+
assemble code, load and run the resulting binary and exchange data between the
67+
ULP and the main CPU.
68+
69+
Run the ``counter.py`` example:
70+
71+
1. Install py-esp32-ulp onto the ESP32 as shown above
72+
2. Upload the `counter.py </examples/counter.py>`_ file to the ESP32
73+
3. Run with ``import counter``
74+
75+
You can also try the `blink.py </examples/blink.py>`_ example, which shows how to
76+
let the ULP blink an LED.
77+
78+
Look inside each example for a more detailed description.
79+
80+
Using on a PC
81+
+++++++++++++
82+
On a PC with the unix port of MicroPython, you can assemble source code as
83+
follows:
84+
85+
.. code-block:: shell
86+
87+
git clone https://github.com/ThomasWaldmann/py-esp32-ulp.git
88+
cd py-esp32-ulp
89+
micropython -m esp32_ulp path/to/code.S # this results in path/to/code.ulp
90+
91+
More examples
92+
+++++++++++++
93+
More ULP examples from around the web:
94+
95+
* https://github.com/espressif/esp-iot-solution/tree/master/examples/ulp_examples
96+
* https://github.com/duff2013/ulptool
97+
* https://github.com/joba-1/Blink-ULP/blob/master/main/ulp/
98+
99+
100+
Advanced usage
101+
--------------
102+
103+
In real world applications, you might want to separate the assembly stage from
104+
the loading/running stage, to avoid having to assemble the code on every startup.
105+
This can be useful for battery-powered applications, where every second of sleep
106+
time matters.
107+
108+
Splitting the assembly and load stage can be combined with other techniques to
109+
for example implement a caching mechansim for the ULP binary, which automatically
110+
updates the binary every time the assembly source code changes.
111+
112+
The ``esp32_ulp.assemble_file`` function stores the assembled and linked binary
113+
into a file with a ``.ulp`` extension, which can later be loaded directly without
114+
assembling the source again.
115+
116+
1. Create/upload an assembly source file and run the following to get a loadable
117+
ULP binary as a ``.ulp`` file:
118+
119+
.. code-block:: python
120+
121+
import esp32_ulp
122+
esp32_ulp.assemble_file('code.S') # this results in code.ulp
123+
124+
2. The above prints out the offsets of all global symbols/labels. For the next step,
125+
you will need to note down the offset of the label, which represents the entry
126+
point to your code.
127+
128+
3. Now load and run the resulting binary as follows:
129+
130+
.. code-block:: python
131+
132+
from esp32 import ULP
133+
134+
ulp = ULP()
135+
with open('test.ulp', 'r') as f:
136+
# load the binary into RTC memory
137+
ulp.load_binary(0, f.read())
138+
139+
# configure how often the ULP should wake up
140+
ulp.set_wakeup_period(0, 500000) # 500k usec == 0.5 sec
141+
142+
# start the ULP
143+
# assemble_file printed offsets in number of 32-bit words.
144+
# ulp.run() expects an offset in number of bytes.
145+
# Thus, multiply the offset to our entry point by 4.
146+
# e.g. for an offset of 2:
147+
# 2 words * 4 = 8 bytes
148+
ulp.run(2*4) # specify the offset of the entry point label
149+
150+
To update the binary every time the source code changes, you would need a mechanism
151+
to detect that the source code changed. Whenever needed, manually re-running the
152+
``assemble_file`` function as shown above, would also work.
153+
154+
155+
Preprocessor
156+
------------
157+
158+
There is a simple preprocessor that understands just enough to allow assembling
159+
ULP source files containing convenience macros such as WRITE_RTC_REG. This is
160+
especially useful for assembling ULP examples from Espressif or other ULP code
161+
found as part of Arduino/ESP-IDF projects.
162+
163+
The preprocessor and how to use it is documented here: `Preprocessor support </docs/preprocess.rst>`_.
164+
165+
166+
Testing
167+
-------
168+
169+
There are unit tests and also compatibility tests that check whether the binary
170+
output is identical with what binutils-esp32ulp produces.
171+
172+
py-esp32-ulp has been tested on the Unix port of MicroPython and on real ESP32
173+
devices with the chip type ESP32D0WDQ6 (revision 1) without SPIRAM.
174+
175+
Consult the Github Actions `workflow definition file </.github/workflows/run_tests.yaml>`_
176+
for how to run the different tests.
177+
178+
179+
Links
180+
-----
181+
182+
Espressif documentation:
183+
184+
* `ESP32 ULP coprocessor instruction set <https://esp-idf.readthedocs.io/en/latest/api-guides/ulp_instruction_set.html>`_
185+
* `ESP32 Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_
186+
187+
GNU Assembler "as" documentation (we try to be compatible for all features that are implemented)
188+
189+
* `GNU Assembler manual <https://sourceware.org/binutils/docs/as/index.html>`_

0 commit comments

Comments
 (0)
0