Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit1b1b1d8

Browse files
committed
restructure documentation into short README and detailed docs
The README now only covers the most important - mainly what thisproject is and how to get started. It then references the documentationfor more detail.The documentation in turn contains more detail.
1 parent26048c8 commit1b1b1d8

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 esp32importULP
45+
# step 2: run an example
46+
# first, upload examples/counter.py to the ESP32
47+
import counter
11748
118-
ulp= ULP()
119-
withopen('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-
# configurehowoften 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 showshowto
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-
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 esp32importULP
133+
134+
ulp= ULP()
135+
withopen('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)
[8]ページ先頭
©2009-2025 Movatter.jp