kopia lustrzana https://github.com/peterhinch/micropython-nano-gui
Fixes to docs.
rodzic
d92470cb45
commit
dc9d2e87de
44
DRIVERS.md
44
DRIVERS.md
|
@ -12,6 +12,8 @@ All drivers provide a display class subclassed from the built-in
|
|||
It should be noted that in the interests of conserving RAM these drivers offer
|
||||
a bare minimum of functionality required to support the above.
|
||||
|
||||
###### [Main README](./README.md#1-introduction)
|
||||
|
||||
# Contents
|
||||
|
||||
1. [Introduction](./DRIVERS.md#1-introduction)
|
||||
|
@ -43,7 +45,7 @@ a bare minimum of functionality required to support the above.
|
|||
8. [EPD Asynchronous support](./DRIVERS.md#8-epd-asynchronous-support)
|
||||
9. [Writing device drivers](./DRIVERS.md#8-writing-device-drivers)
|
||||
|
||||
###### [Main README](./README.md)
|
||||
###### [Main README](./README.md#1-introduction)
|
||||
|
||||
# 1. Introduction
|
||||
|
||||
|
@ -91,6 +93,9 @@ specifying custom colors. For detail see the main README
|
|||
|
||||
# 2. Drivers for SSD1351
|
||||
|
||||
This is an OLED driver. The supported displays produce excellent images with
|
||||
extreme contrast and bright colors. Power consumption is low.
|
||||
|
||||
See [Adafruit 1.5" 128*128 OLED display](https://www.adafruit.com/product/1431)
|
||||
and [Adafruit 1.27" 128*96 display](https://www.adafruit.com/product/1673).
|
||||
|
||||
|
@ -158,13 +163,17 @@ For anyone seeking to understand or modify the code, the datasheet para 8.3.2
|
|||
is confusing. They use the colors red, green and blue to represent colors C, B
|
||||
and A. With the setup used in these drivers, C is blue and A is red. The 16 bit
|
||||
color streams sent to the display are:
|
||||
s[x] 1st byte sent b7 b6 b5 b4 b3 g7 g6 g5
|
||||
s[x + 1] 2nd byte sent g4 g3 g2 r7 r6 r5 r4 r3
|
||||
`s[x]` 1st byte sent `b7 b6 b5 b4 b3 g7 g6 g5`
|
||||
`s[x + 1]` 2nd byte sent `g4 g3 g2 r7 r6 r5 r4 r3`
|
||||
|
||||
###### [Contents](./DRIVERS.md#contents)
|
||||
|
||||
# 3. Drivers for SSD1331
|
||||
|
||||
This is an OLED driver for small displays. The supported display produces
|
||||
excellent images with extreme contrast and bright colors. Power consumption is
|
||||
low.
|
||||
|
||||
See [Adafruit 0.96" OLED display](https://www.adafruit.com/product/684). Most
|
||||
of the demos assume a larger screen and will fail. The `color96.py` demo is
|
||||
written for this display.
|
||||
|
@ -207,8 +216,9 @@ def spi_init(spi):
|
|||
|
||||
# 4. Drivers for ST7735R
|
||||
|
||||
These are cross-platform but assume `micropython.viper` capability. They use
|
||||
8-bit or 4-bit color to minimise the RAM used by the frame buffer.
|
||||
This chip is for small TFT displays. Four drivers are provided. All are
|
||||
cross-platform but assume `micropython.viper` capability. They use 8-bit or
|
||||
4-bit color to minimise the RAM used by the frame buffer.
|
||||
|
||||
Drivers for [Adafruit 1.8" display](https://www.adafruit.com/product/358).
|
||||
* `st7735r.py` 8-bit color.
|
||||
|
@ -221,11 +231,11 @@ For [Adafruit 1.44" display](https://www.adafruit.com/product/2088).
|
|||
Users of other ST7735R based displays should beware: there are many variants
|
||||
with differing setup requirements.
|
||||
[This driver](https://github.com/boochow/MicroPython-ST7735/blob/master/ST7735.py)
|
||||
has four different initialisation routines for various display versions. Even
|
||||
the supported Adafruit displays differ in their initialisation settings.
|
||||
|
||||
If your Chinese display doesn't work with my drivers you are on your own: I
|
||||
can't support hardware I don't possess.
|
||||
has four different initialisation routines for various display versions. The
|
||||
supported Adafruit displays differ in their initialisation settings, hence the
|
||||
need for different drivers for the two display types. If your Chinese display
|
||||
doesn't work with my drivers you are on your own: I can't support hardware I
|
||||
don't possess.
|
||||
|
||||
The `color_setup.py` file should initialise the SPI bus with a baudrate of
|
||||
12_000_000. Args `polarity`, `phase`, `bits`, `firstbit` are defaults. Hard or
|
||||
|
@ -612,6 +622,8 @@ The N channel MOSFET must have a low threshold voltage.
|
|||
|
||||
![Image](images/epd_enable.png)
|
||||
|
||||
###### [Contents](./DRIVERS.md#contents)
|
||||
|
||||
## 7.2 Waveshare eInk Display HAT
|
||||
|
||||
This 2.7" 176*274 display is designed for the Raspberry Pi and is detailed
|
||||
|
@ -688,6 +700,8 @@ Pins 26-40 unused and omitted.
|
|||
seconds to enable viewing. This enables generic nanogui demos to be run on an
|
||||
EPD.
|
||||
|
||||
###### [Contents](./DRIVERS.md#contents)
|
||||
|
||||
# 8. EPD Asynchronous support
|
||||
|
||||
Normally when GUI code issues
|
||||
|
@ -710,10 +724,10 @@ application is then free to alter the framebuf contents.
|
|||
|
||||
It is invalid to issue `.refresh()` until the physical display refresh is
|
||||
complete; if this is attempted a `RuntimeError` will occur. The most efficient
|
||||
way to ensure that this cannot occur is to await the `.wait()` prior to any
|
||||
refresh. This method will pause until any physical update is complete.
|
||||
way to ensure that this cannot occur is to await the `.wait()` method prior to
|
||||
a refresh. This method will pause until any physical update is complete.
|
||||
|
||||
The following illustrates the kind of approach which may be used
|
||||
The following illustrates the kind of approach which may be used:
|
||||
```python
|
||||
while True:
|
||||
# Before refresh, ensure that a previous refresh is complete
|
||||
|
@ -729,6 +743,8 @@ The following illustrates the kind of approach which may be used
|
|||
await asyncio.sleep(180)
|
||||
```
|
||||
|
||||
###### [Contents](./DRIVERS.md#contents)
|
||||
|
||||
# 9. Writing device drivers
|
||||
|
||||
Device drivers capable of supporting `nanogui` can be extremely simple: see
|
||||
|
@ -751,7 +767,7 @@ method:
|
|||
```python
|
||||
@staticmethod
|
||||
def rgb(r, g, b):
|
||||
return int((r > 127) or (g > 127) or (b > 127))
|
||||
return int(((r | g | b) & 0x80) > 0)
|
||||
```
|
||||
This ensures compatibility with code written for color displays by converting
|
||||
RGB values to a single bit.
|
||||
|
|
64
README.md
64
README.md
|
@ -1,3 +1,5 @@
|
|||
# MicroPython nano-gui
|
||||
|
||||
A lightweight and minimal MicroPython GUI library for display drivers based on
|
||||
the `FrameBuffer` class. Various display technologies are supported, including
|
||||
small color and monochrome OLED's, color TFT's, ePaper and Sharp units. The GUI
|
||||
|
@ -68,15 +70,17 @@ wiring details, pin names and hardware issues.
|
|||
This library provides a limited set of GUI objects (widgets) for displays whose
|
||||
display driver is subclassed from the `FrameBuffer` class. Such drivers can be
|
||||
tiny as the graphics primitives are supplied by the `FrameBuffer` class. A
|
||||
range of device drivers is provided: [this doc](./DRIVERS.md) provides guidance
|
||||
on selecting the right driver for your display, platform and application.
|
||||
range of device drivers is provided: [the device driver doc](./DRIVERS.md)
|
||||
provides guidance on selecting the right driver for your display, platform and
|
||||
application.
|
||||
|
||||
The GUI is cross-platform. By default it is configured for a Pyboard (1.x or D).
|
||||
This doc explains how to configure for other platforms by adapting a single
|
||||
small file. The GUI supports multiple displays attached to a single target, but
|
||||
bear in mind the RAM requirements for multiple frame buffers. It is tested on
|
||||
the ESP32 reference board without SPIRAM. Running on ESP8266 is possible but
|
||||
frozen bytecode must be used owing to its restricted RAM.
|
||||
The GUI is cross-platform. The device driver doc explains how to configure it
|
||||
for a given display and MicroPython host by adapting a single small file. The
|
||||
GUI supports multiple displays attached to a single target, but bear in mind
|
||||
the RAM requirements for multiple frame buffers. The GUI has been tested on
|
||||
Pyboard 1.1, Pyboard D and on the ESP32 reference board without SPIRAM. Running
|
||||
on ESP8266 is possible but frozen bytecode must be used owing to its restricted
|
||||
RAM.
|
||||
|
||||
It uses synchronous code but is compatible with `uasyncio`. Some demo programs
|
||||
illustrate this. Code is standard MicroPython, but some device drivers use the
|
||||
|
@ -94,14 +98,17 @@ my GUI's employ the American spelling of `color`.
|
|||
|
||||
## 1.1 Change log
|
||||
|
||||
17 Jan 2021 Add ePaper drivers. Ensure monochrome and color setup requirements
|
||||
are identical. Substantial update to docs.
|
||||
16 Dec 2020 Add ILI9341 driver, 4-bit drivers and SPI bus sharing improvements.
|
||||
These mean that `color_setup.py` should now set SPI baudrate.
|
||||
29 Nov 2020 Add ST7735R TFT drivers.
|
||||
17 Nov 2020 Add `Textbox` widget. `Scale` constructor arg `border` replaced by
|
||||
`bdcolor` as per other widgets.
|
||||
|
||||
17 Jan 2021
|
||||
Add ePaper drivers. Ensure monochrome and color setup requirements are
|
||||
identical. Substantial update to docs.
|
||||
16 Dec 2020
|
||||
Add ILI9341 driver, 4-bit drivers and SPI bus sharing improvements. These mean
|
||||
that `color_setup.py` should now set SPI baudrate.
|
||||
29 Nov 2020
|
||||
Add ST7735R TFT drivers.
|
||||
17 Nov 2020
|
||||
Add `Textbox` widget. `Scale` constructor arg `border` replaced by `bdcolor` as
|
||||
per other widgets.
|
||||
5 Nov 2020 - breaking change
|
||||
This library has been refactored as a Python package. This reduces RAM usage:
|
||||
widgets are imported on demand rather than unconditionally. This has enabled
|
||||
|
@ -137,12 +144,13 @@ Compatible and tested display drivers include:
|
|||
* [Adafruit 2.9 inch ePaper display](https://www.adafruit.com/product/4262)
|
||||
documented [here](./DRIVERS.md#71-adafruit-flexible-eink-display).
|
||||
* [Waveshare 2.7 inch ePaper HAT](https://www.waveshare.com/wiki/2.7inch_e-Paper_HAT)
|
||||
documented [here with a warning](./DRIVERS.md#72-waveshare-eink-display-hat).
|
||||
documented [here](./DRIVERS.md#72-waveshare-eink-display-hat). Please note the
|
||||
warning regarding poor quality suspected clone units.
|
||||
|
||||
Widgets are intended for the display of data from physical devices such as
|
||||
sensors. They are drawn using graphics primitives rather than icons to minimise
|
||||
RAM usage. It also enables them to be effciently rendered at arbitrary scale on
|
||||
by hosts with restricted processing power. The approach also enables widgets to
|
||||
RAM usage. It also enables them to be effciently rendered at arbitrary scale by
|
||||
hosts with restricted processing power. The approach also enables widgets to
|
||||
maximise information in ways that are difficult with icons, in particular using
|
||||
dynamic color changes in conjunction with moving elements.
|
||||
|
||||
|
@ -153,7 +161,7 @@ update a 128x128x8 color ssd1351 display on a Pyboard 1.0 is 41ms.
|
|||
|
||||
Drivers based on `FrameBuffer` must allocate contiguous RAM for the buffer. To
|
||||
avoid 'out of memory' errors it is best to instantiate the display before
|
||||
importing other modules. The demos illustrate this.
|
||||
importing other modules. The example `color_setup` files illustrate this.
|
||||
|
||||
## 1.3 Quick start
|
||||
|
||||
|
@ -208,7 +216,7 @@ filesystem.
|
|||
|
||||
The chosen template will need to be edited to match the display in use, the
|
||||
MicroPython target and the electrical connections between display and target.
|
||||
Electrical connections are detailed in the driver source.
|
||||
Electrical connections are detailed in the template source.
|
||||
* `color_setup.py` Hardware setup for the display. As written supports an
|
||||
SSD1351 display connected to a Pyboard.
|
||||
|
||||
|
@ -247,8 +255,7 @@ Demos for larger displays.
|
|||
* `scale_ili.py` A special demo of the asychronous mode of the ILI9341 driver.
|
||||
|
||||
Demos for ePaper displays:
|
||||
* `waveshare_test.py` For the Waveshare eInk Display HAT 2.7" 176*274 portrait
|
||||
mode display.
|
||||
* `waveshare_test.py` For the Waveshare eInk Display HAT 2.7" 176*274 display.
|
||||
* `epd29_test.py` Demo for Adafruit 2.9" eInk display.
|
||||
|
||||
Demos for Sharp displays:
|
||||
|
@ -256,9 +263,9 @@ Demos for Sharp displays:
|
|||
* `clocktest.py` Digital and analog clock demo.
|
||||
* `clock_batt.py` Low power demo of battery operated clock.
|
||||
|
||||
Usage with `uasyncio` is discussed [here](./ASYNC.md). In summary the blocking
|
||||
which occurs during transfer of the framebuffer to the display may affect more
|
||||
demanding `uasyncio` applications. More generally the GUI works well with it.
|
||||
Usage with `uasyncio` is discussed [here](./ASYNC.md). In summary the GUI works
|
||||
well with `uasyncio` but the blocking which occurs during transfer of the
|
||||
framebuffer to the display may affect more demanding applications.
|
||||
|
||||
###### [Contents](./README.md#contents)
|
||||
|
||||
|
@ -301,7 +308,7 @@ copied to the hardware root as `color_setup.py`. Example files:
|
|||
* `st7735r144_setup.py` For a Pyboard with an
|
||||
[Adafruit 1.44 inch TFT display](https://www.adafruit.com/product/2088).
|
||||
* `ili9341_setup.py` A 240*320 ILI9341 display on ESP32.
|
||||
* `waveshare_setup.py` 176*274 portrait mode ePaper display.
|
||||
* `waveshare_setup.py` 176*274 ePaper display.
|
||||
* `epd96_asyn.py` Adafruit 2.9 inch ePaper display, optimised for `uasyncio`.
|
||||
|
||||
## 2.2 Dependencies
|
||||
|
@ -324,9 +331,6 @@ Displays based on the Nokia 5110 (PCD8544 chip) require this driver. It is not
|
|||
in this repo but may be found here:
|
||||
* [PCD8544/Nokia 5110](https://github.com/mcauser/micropython-pcd8544.git)
|
||||
|
||||
The Sharp display is supported in `drivers/sharp`. See
|
||||
[README](./DRIVERS.md#6-drivers-for-sharp-displays) and demos.
|
||||
|
||||
###### [Contents](./README.md#contents)
|
||||
|
||||
## 2.3 Verifying hardware configuration
|
||||
|
|
Ładowanie…
Reference in New Issue