Skip to content

Commit 399118f

Browse files
trevorwsleetrevorwslee
committed
updated
1 parent f6b39aa commit 399118f

File tree

1 file changed

+175
-87
lines changed

1 file changed

+175
-87
lines changed

‎README.md‎

Lines changed: 175 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
12
# DumbDisplay MicroPython Library (v0.5.0)
23

34
DumbDisplay MicroPython Library -- workable with Python 3 -- is a port of the [DumbDisplay Arduino Library](https://github.com/trevorwslee/Arduino-DumbDisplay)
@@ -7,18 +8,26 @@ For a video introduction, please watch the YouTube video: [Introducing DumbDispl
78
with ESP32, Raspberry Pi Pico, and Raspberry Pi Zero](https://www.youtube.com/watch?v=KVU26FyXs5M)
89

910
Although the porting is work in progress, nevertheless, most of the core of DumbDisplay functionalities have been ported.
10-
Hopefully, this should already be helpful for friends that develop programs for microcontroller boards in Micro-Python.
11+
Hopefully, this should already be helpful for friends that develop programs for microcontroller boards in MicroPython.
1112

12-
As hinted previously, even it is originally targeted for MicroPython, it should be useful with regular Python 3, like in Raspberry Pi environment
13+
As hinted previously, even DumbDisplay MicroPython Library is originally targeted for MicroPython, it should be useable with regular Python 3, like in Raspberry Pi environment
1314
or even with desktop / laptop.
14-
Consequently, it might be an alternative way to prototype simple Android app driven remotely with Python 3 from desktop / laptop, say for displaying experiment result data and getting simple interaction with the user.
15+
16+
Consequently, DumbDisplay MicroPython Library might be an alternative way to prototype simple Android app driven remotely with Python 3 from desktop / laptop, say for displaying experiment result data and getting simple interaction with the user.
1517

1618

1719
Enjoy
1820

1921
- [DumbDisplay MicroPython Library (v0.5.0)](#dumbdisplay-micropython-library-v050)
2022
- [Installation](#installation)
2123
- [Getting Started](#getting-started)
24+
- [More Details](#more-details)
25+
- [IO Mechanism](#io-mechanism)
26+
- [Layers](#layers)
27+
- [Auto-Pinning of Layers](#auto-pinning-of-layers)
28+
- [Feedback](#feedback)
29+
- [Poll for Feedback](#poll-for-feedback)
30+
- [Callback for Feedback](#callback-for-feedback)
2231
- [Selected Demos](#selected-demos)
2332
- [Notes](#notes)
2433
- [Thank You!](#thank-you)
@@ -61,97 +70,176 @@ The basic Python script setup is:
6170
- you can import the "core" components with ```from dumbdisplay.core import *```
6271
- or you can choose to import "all" components (including layers to be mentioned later) with ```from dumbdisplay.full import *```
6372
2. import IO mechanism, for creating IO object [to pass to DumbDisplay object], like
64-
- `io4Inet` (the default) -- Python networking support (not available for MicroPython)
65-
- `io4Wifi` -- MicroPython WiFi support (for Raspberry Pi Pico W, ESP32, etc.)
6673
<br>e.g.
6774
```
6875
from dumbdisplay.core import *
69-
from dumbdisplay.io_inet import *
70-
dd = DumbDisplay(io4Wifi("ssid", "password"))
76+
from dumbdisplay.ios import *
77+
dd = DumbDisplay(io4Wifi("ssid", "password")) # the default is io4Inet()
7178
```
79+
- the default IO mechanism is `io4Inet()`, which uses Python networking support (not available for MicroPython)
7280
3. import layers, for creating layer objects [passing DumbDisplay object to them]
73-
- `LayerLedGrid` -- a single LED, or a grid of multiple LEDs (**n** columns by **m** rows)
74-
<br>e.g.
75-
```
76-
from dumbdisplay.core import *
77-
from dumbdisplay.layer_ledgrid import *
78-
dd = DumbDisplay()
79-
l = LayerLedGrid(dd)
80-
```
81-
|[`demo_LayerLedGrid()` in `dd_demo.py`](dd_demo.py)|
82-
|:--:|
83-
|<img style="width: 300px; height: 300px;" src="screenshots/layer_ledgrid_2x2.png"></img>|
84-
85-
- `LayerLcd` -- a TEXT based LCD with configurable number of lines of configurable number of characters
86-
<br>e.g.
87-
```
88-
from dumbdisplay.core import *
89-
from dumbdisplay.layer_lcd import *
90-
dd = DumbDisplay()
91-
l = LayerLcd(dd)
92-
```
93-
|[`demo_LayerLcd()` in `dd_demo.py`](dd_demo.py)|
94-
|:--:|
95-
|<img style="width: 300px; height: 300px;" src="screenshots/layer_lcd.png"></img>|
96-
97-
- `LayerGraphical` -- a graphical LCD that you can draw to, with common drawing operations
98-
<br>e.g.
99-
```
100-
from dumbdisplay.core import *
101-
from dumbdisplay.layer_graphical import *
102-
dd = DumbDisplay()
103-
l = LayerGraphical(dd)
104-
```
105-
|[`demo_LayerGraphical()` in `dd_demo.py`](dd_demo.py)|
106-
|:--:|
107-
|<img style="width: 300px; height: 300px;" src="screenshots/layer_graphical.png"></img>|
108-
109-
- `LayerSelection` -- a group / grid of TEXT based LCD mostly for showing selection choices
110-
<br>e.g.
111-
```
112-
from dumbdisplay.core import *
113-
from dumbdisplay.layer_selection import *
114-
dd = DumbDisplay()
115-
l = LayerSelection(dd)
116-
```
117-
|[`demo_LayerSelection()` in `dd_demo.py`](dd_demo.py)|
118-
|:--:|
119-
|<img style="width: 300px; height: 300px;" src="screenshots/layer_selection_1x3.png"></img>|
120-
121-
- `Layer7SegmentRow` -- a single 7-segment digit, or a row of **n** 7-segments digits
122-
<br>e.g.
123-
```
124-
from dumbdisplay.core import *
125-
from dumbdisplay.layer_7segrow import *
126-
dd = DumbDisplay()
127-
l = Layer7SegmentRow(dd)
128-
```
129-
|[`demo_Layer7SegmentRow()` in `dd_demo.py`](dd_demo.py)|
130-
|:--:|
131-
|<img style="width: 300px; height: 300px;" src="screenshots/layer_7segment_3d.png"></img>|
132-
133-
- `LayerPlotter` -- a "plotter"
134-
<br>e.g.
135-
```
136-
from dumbdisplay.core import *
137-
from dumbdisplay.layer_plotter import *
138-
dd = DumbDisplay()
139-
l = LayerPlotter(dd)
140-
```
141-
|[`demo_LayerPlotter()` in `dd_demo.py`](dd_demo.py)|
142-
|:--:|
143-
|<img style="width: 300px; height: 300px;" src="screenshots/layer_plotter.png"></img>|
144-
145-
4. if you have multiple layers, you can "auto pin" them together; otherwise, multiple layers will be stacked on top of each other
146-
<br>e.g.
147-
```
148-
AutoPin('V', AutoPin('H', l_ledgrid, l_lcd), AutoPin('H', l_selection, l_7segmentrow), l_graphical).pin(dd)
149-
```
150-
|[`demo_AutoPin()` in `dd_demo.py`](dd_demo.py)|
151-
|:--:|
152-
|<img style="width: 400px; height: 400px;" src="screenshots/autopin_layers.png"></img>|
81+
<br>e.g.
82+
```
83+
from dumbdisplay.core import *
84+
from dumbdisplay.layer_ledgrid import *
85+
dd = DumbDisplay()
86+
l = LayerLedGrid(dd)
87+
```
88+
- you can choose to import "all" layers with ```from dumbdisplay.full import *```
15389
15490
91+
# More Details
92+
93+
## IO Mechanism
94+
95+
When create a `DumbDisplay` object, an IO object is needed (even though there is a default IO object)
96+
- `io4Inet` (the default) -- Python networking support (not available for MicroPython)
97+
- `io4Wifi` -- MicroPython WiFi support (for Raspberry Pi Pico W, ESP32, etc.)
98+
- `io4Ble` -- MicroPython BLE support (for Raspberry Pi Pico W, ESP32, etc.)
99+
- `io4Uart` -- MicroPython UART support (for Raspberry Pi Pico W, ESP32, etc.)
100+
101+
E.g.
102+
```
103+
from dumbdisplay.core import *
104+
from dumbdisplay.ios import *
105+
dd = DumbDisplay(io4Wifi("ssid", "password"))
106+
```
107+
108+
## Layers
109+
110+
Other then the `DumbDisplay`, you will need to create one or more layer objects to represent the UI:
111+
- `LayerLedGrid` -- a single LED, or a grid of multiple LEDs (**n** columns by **m** rows)
112+
<br>e.g.
113+
```
114+
from dumbdisplay.core import *
115+
from dumbdisplay.layer_ledgrid import *
116+
dd = DumbDisplay()
117+
l = LayerLedGrid(dd)
118+
```
119+
|[`demo_LayerLedGrid()` in `dd_demo.py`](dd_demo.py)|
120+
|:--:|
121+
|<img style="width: 300px; height: 300px;" src="screenshots/layer_ledgrid_2x2.png"></img>|
122+
123+
- `LayerLcd` -- a TEXT based LCD with configurable number of lines of configurable number of characters
124+
<br>e.g.
125+
```
126+
from dumbdisplay.core import *
127+
from dumbdisplay.layer_lcd import *
128+
dd = DumbDisplay()
129+
l = LayerLcd(dd)
130+
```
131+
|[`demo_LayerLcd()` in `dd_demo.py`](dd_demo.py)|
132+
|:--:|
133+
|<img style="width: 300px; height: 300px;" src="screenshots/layer_lcd.png"></img>|
134+
135+
- `LayerGraphical` -- a graphical LCD that you can draw to, with common drawing operations
136+
<br>e.g.
137+
```
138+
from dumbdisplay.core import *
139+
from dumbdisplay.layer_graphical import *
140+
dd = DumbDisplay()
141+
l = LayerGraphical(dd)
142+
```
143+
|[`demo_LayerGraphical()` in `dd_demo.py`](dd_demo.py)|
144+
|:--:|
145+
|<img style="width: 300px; height: 300px;" src="screenshots/layer_graphical.png"></img>|
146+
147+
- `LayerSelection` -- a group / grid of TEXT based LCD mostly for showing selection choices
148+
<br>e.g.
149+
```
150+
from dumbdisplay.core import *
151+
from dumbdisplay.layer_selection import *
152+
dd = DumbDisplay()
153+
l = LayerSelection(dd)
154+
```
155+
|[`demo_LayerSelection()` in `dd_demo.py`](dd_demo.py)|
156+
|:--:|
157+
|<img style="width: 300px; height: 300px;" src="screenshots/layer_selection_1x3.png"></img>|
158+
159+
- `Layer7SegmentRow` -- a single 7-segment digit, or a row of **n** 7-segments digits
160+
<br>e.g.
161+
```
162+
from dumbdisplay.core import *
163+
from dumbdisplay.layer_7segrow import *
164+
dd = DumbDisplay()
165+
l = Layer7SegmentRow(dd)
166+
```
167+
|[`demo_Layer7SegmentRow()` in `dd_demo.py`](dd_demo.py)|
168+
|:--:|
169+
|<img style="width: 300px; height: 300px;" src="screenshots/layer_7segment_3d.png"></img>|
170+
171+
- `LayerPlotter` -- a "plotter"
172+
<br>e.g.
173+
```
174+
from dumbdisplay.core import *
175+
from dumbdisplay.layer_plotter import *
176+
dd = DumbDisplay()
177+
l = LayerPlotter(dd)
178+
```
179+
|[`demo_LayerPlotter()` in `dd_demo.py`](dd_demo.py)|
180+
|:--:|
181+
|<img style="width: 300px; height: 300px;" src="screenshots/layer_plotter.png"></img>|
182+
183+
## Auto-Pinning of Layers
184+
185+
In case of multiple layers, you can "auto pin" them together; otherwise, multiple layers will be stacked on top of each other
186+
187+
E.g.
188+
```
189+
AutoPin('V', AutoPin('H', l_ledgrid, l_lcd), AutoPin('H', l_selection, l_7segmentrow), l_graphical).pin(dd)
190+
```
191+
|[`demo_AutoPin()` in `dd_demo.py`](dd_demo.py)|
192+
|:--:|
193+
|<img style="width: 400px; height: 400px;" src="screenshots/autopin_layers.png"></img>|
194+
195+
## Feedback
196+
197+
Certain user interaction, like pressing, with the layers (the UI) can trigger feedback to the corresponding layer objects
198+
199+
Given a layer `l`, normally you enable feedback like
200+
```
201+
l.enable_feedback()
202+
```
203+
or to enable feedback with auto flashing (UI feedback) of the layer by provide options like `"fl"` like
204+
```
205+
l.enable_feedback("fl")
206+
```
207+
208+
There are two ways feedback of the layer can be received -- polling or callback
209+
210+
### Poll for Feedback
211+
212+
After creating the layer, a loop can be implemented to poll for feedback like
213+
```
214+
while True:
215+
fb = l.getFeedback()
216+
if fb:
217+
print(f"* Feedback: {fb.type} at ({fb.x}, {fb.y})")
218+
```
219+
- fb is of type `DDFeedback`
220+
- `DDFeedback.type`: the type of feedback, like `"click"`, `"doubleclick"`, `"longpress"`
221+
- `DDFeedback.x`, `DDFeedback.y`: the "coordinates" of the feedback
222+
<br>Here, what "coordinates" refers to depends on the type of layer
223+
* E.g, for `LayerLedGrid`, "coordinates" refers to which LED
224+
* E.g, for `LayerGraphical`, "coordinates" refers to the pixel coordinates
225+
* E.g, for `LayerSelection`, "coordinates" refers to which selection
226+
227+
Please take [`demo_Feedback()` in `dd_demo.py`](dd_demo.py) as an example.
228+
229+
### Callback for Feedback
230+
231+
When enabling the layer for feedback, a callback / handler can be supplied like
232+
```
233+
l.enableFeedback("fa", feedback_handler=lambda layer, type, x, y: print(f"* Feedback: {type} at ({x}, {y})"))
234+
```
235+
The parameters passed to the callback `lambda`:
236+
- `layer`: the layer object that received the feedback
237+
- `type`: the type of feedback (as mentioned above)
238+
- `x`, `y`: the "coordinates" of the feedback (as mentioned above)
239+
240+
Please take [`demo_Feedback_callback()` in `dd_demo.py`](dd_demo.py) as an example.
241+
242+
155243
# Selected Demos
156244
157245
Here is a few Raspberry Pi Pico PIO demos that might interest you

0 commit comments

Comments
 (0)