8000 small cleanups/improvements to the documentation · lmarkrol/micropython-esp32-ulp@df882c8 · GitHub
[go: up one dir, main page]
Skip to content 8000

Commit df882c8

Browse files
wnienhauswnienhaus
committed
small cleanups/improvements to the documentation
Mostly nicer/better phrasing. Add a Table of Contents to the documentation. Also change the Advanced Usage description from implying that "real-world" applications should use this approach to instead suggesting that this might be useful for "some" applications.
1 parent 1b1b1d8 commit df882c8

File tree

2 files changed

+43
-36
lines changed

2 files changed

+43
-36
lines changed

‎README.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,17 +33,17 @@ The following features are supported:
3333
Quick start
3434
-----------
3535

36-
You can get going, run the following directly on the ESP32:
36+
To get going run the following directly on the ESP32:
3737

3838
.. code-block:: python
3939
40-
# step 1: install py-esp32-ulp
41-
# important: ensure the ESP32 is connected to a network with internet connectivity
40+
# Step 1: Install py-esp32-ulp
41+
# IMPORTANT: Ensure the ESP32 is connected to a network with internet connectivity.
4242
import upip
4343
upip.install('micropython-py-esp32-ulp')
4444
45-
# step 2: run an example
46-
# first, upload examples/counter.py to the ESP32
45+
# Step 2: Run an example
46+
# First, upload examples/counter.py to the ESP32.
4747
import counter
4848
4949
The `counter.py </examples/counter.py>`_ example shows how to assemble code, load

‎docs/index.rst

Lines changed: 38 additions & 31 deletions
< 57AE td data-grid-cell-id="diff-8d068e8797e88947c320f79e856c3e16a72b730124a8f9d7031e2c4680dfa534-149-155-0" data-selected="false" role="gridcell" style="background-color:var(--bgColor-default);text-align:center" tabindex="-1" valign="top" class="focusable-grid-cell diff-line-number position-relative diff-line-number-neutral left-side">149
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,15 @@ py-esp32-ulp Documentation
44
py-esp32-ulp is an assembler toolchain for the ESP32 ULP (Ultra Low-Power)
55
Co-Processor, written in MicroPython.
66

7+
.. contents:: Table of Contents
8+
79

810
What is it useful for?
911
----------------------
1012

11-
It can translate small assembly language programs to a loadable/executable
12-
ULP machine code binary, directly on the ESP32 microcontroller.
13+
py-esp32-ulp can translate small assembly language programs to a
14+
loadable/executable ULP machine code binary, directly on the ESP32
15+
microcontroller.
1316

1417
This is intended as an alternative approach to assembling such programs using
1518
the binutils-esp32ulp toolchain from Espressif on a development machine.
@@ -55,30 +58,31 @@ On the ESP32, install using upip:
5558
On a PC, simply ``git clone`` this repo.
5659

5760

58-
Examples
59-
--------
61+
Getting started
62+
---------------
6063

61-
Quick start
62-
+++++++++++
63-
The quickest way to get started is to try one of the `examples </examples/>`_.
64+
On the ESP32
65+
++++++++++++
6466

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.
67+
The simplest example to try on the ESP32 is `counter.py </examples/counter.py>`_.
68+
It shows how to assemble code, load and run the resulting binary and exchange
69+
data between the ULP and the main CPU.
6870

6971
Run the ``counter.py`` example:
7072

7173
1. Install py-esp32-ulp onto the ESP32 as shown above
72-
2. Upload the `counter.py </examples/counter.py>`_ file to the ESP32
74+
2. Upload the `examples/counter.py </examples/counter.py>`_ file to the ESP32
7375
3. Run with ``import counter``
7476

7577
You can also try the `blink.py </examples/blink.py>`_ example, which shows how to
7678
let the ULP blink an LED.
7779

7880
Look inside each example for a more detailed description.
7981

80-
Using on a PC
81-
+++++++++++++
82+
83+
On a PC
84+
+++++++
85+
8286
On a PC with the unix port of MicroPython, you can assemble source code as
8387
follows:
8488

@@ -88,9 +92,11 @@ follows:
8892
cd py-esp32-ulp
8993
micropython -m esp32_ulp path/to/code.S # this results in path/to/code.ulp
9094
95+
9196
More examples
9297
+++++++++++++
93-
More ULP examples from around the web:
98+
99+
Other ULP examples from around the web:
94100

95101
* https://github.com/espressif/esp-iot-solution/tree/master/examples/ulp_examples
96102
* https://github.com/duff2013/ulptool
@@ -100,30 +106,30 @@ More ULP examples from around the web:
100106
Advanced usage
101107
--------------
102108

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
109+
In some applications you might want to separate the assembly stage from the
110+
loading/running stage, to avoid having to assemble the code on every startup.
111+
This can be useful in battery-powered applications where every second of sleep
106112
time matters.
107113

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.
114+
Splitting the assembly and load stage can be combined with other techniques,
115+
for example to implement a caching mechansim for the ULP binary that
116+
automatically updates the binary every time the assembly source code changes.
111117

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.
118+
The ``esp32_ulp.assemble_file`` function can be used to assemble and link an
119+
assembly source file into a machine code binary file with a ``.ulp`` extension.
120+
That file can then be loaded directly without assembling the source again.
115121

116-
1. Create/upload an assembly source file and run the following to get a loadable
117-
ULP binary as a ``.ulp`` file:
122+
1. Create/upload an assembly source file and run the following to get a
123+
loadable ULP binary as a ``.ulp`` file:
118124

119125
.. code-block:: python
120126
121127
import esp32_ulp
122128
esp32_ulp.assemble_file('code.S') # this results in code.ulp
123129
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.
130+
2. The above prints out the offsets of all global symbols/labels. For the next
131+
step, you will need to note down the offset of the label, which represents
132+
the entry point to your code.
127133

128134
3. Now load and run the resulting binary as follows:
129135

@@ -147,9 +153,10 @@ assembling the source again.
147153
# 2 words * 4 = 8 bytes
148154
ulp.run(2*4) # specify the offset of the entry point label
155
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.
156+
To update the binary every time the source code changes, you would need a
157+
mechanism to detect that the source code changed. This could trigger a re-run
158+
of the ``assemble_file`` function to update the binary. Manually re-running
159+
this function as needed would also work.
153160

154161

155162
Preprocessor

0 commit comments

Comments
 (0)
2A23
0