mirror
/
micropython-nano-gui
kopia lustrzana https://github.com/peterhinch/micropython-nano-gui
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

Fixes to docs.

pull/8/head
Peter Hinch 2021-01-17 17:20:54 +00:00
rodzic d92470cb45
commit dc9d2e87de
2 zmienionych plików z 64 dodań i 44 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

44
DRIVERS.md
Wyświetl plik

@ -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 It should be noted that in the interests of conserving RAM these drivers offer
a bare minimum of functionality required to support the above. a bare minimum of functionality required to support the above.
###### [Main README](./README.md#1-introduction)
# Contents # Contents
1. [Introduction](./DRIVERS.md#1-introduction) 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) 8. [EPD Asynchronous support](./DRIVERS.md#8-epd-asynchronous-support)
9. [Writing device drivers](./DRIVERS.md#8-writing-device-drivers) 9. [Writing device drivers](./DRIVERS.md#8-writing-device-drivers)
###### [Main README](./README.md) ###### [Main README](./README.md#1-introduction)
# 1. Introduction # 1. Introduction
@ -91,6 +93,9 @@ specifying custom colors. For detail see the main README
# 2. Drivers for SSD1351 # 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) 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). 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 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 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: color streams sent to the display are:
s[x] 1st byte sent b7 b6 b5 b4 b3 g7 g6 g5 `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 + 1]` 2nd byte sent `g4 g3 g2 r7 r6 r5 r4 r3`
###### [Contents](./DRIVERS.md#contents) ###### [Contents](./DRIVERS.md#contents)
# 3. Drivers for SSD1331 # 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 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 of the demos assume a larger screen and will fail. The `color96.py` demo is
written for this display. written for this display.
@ -207,8 +216,9 @@ def spi_init(spi):
# 4. Drivers for ST7735R # 4. Drivers for ST7735R
These are cross-platform but assume `micropython.viper` capability. They use This chip is for small TFT displays. Four drivers are provided. All are
8-bit or 4-bit color to minimise the RAM used by the frame buffer. 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). Drivers for [Adafruit 1.8" display](https://www.adafruit.com/product/358).
* `st7735r.py` 8-bit color. * `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 Users of other ST7735R based displays should beware: there are many variants
with differing setup requirements. with differing setup requirements.
[This driver](https://github.com/boochow/MicroPython-ST7735/blob/master/ST7735.py) [This driver](https://github.com/boochow/MicroPython-ST7735/blob/master/ST7735.py)
has four different initialisation routines for various display versions. Even has four different initialisation routines for various display versions. The
the supported Adafruit displays differ in their initialisation settings. supported Adafruit displays differ in their initialisation settings, hence the
need for different drivers for the two display types. If your Chinese display
If your Chinese display doesn't work with my drivers you are on your own: I doesn't work with my drivers you are on your own: I can't support hardware I
can't support hardware I don't possess. don't possess.
The `color_setup.py` file should initialise the SPI bus with a baudrate of 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 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) ![Image](images/epd_enable.png)
###### [Contents](./DRIVERS.md#contents)
## 7.2 Waveshare eInk Display HAT ## 7.2 Waveshare eInk Display HAT
This 2.7" 176*274 display is designed for the Raspberry Pi and is detailed 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 seconds to enable viewing. This enables generic nanogui demos to be run on an
EPD. EPD.
###### [Contents](./DRIVERS.md#contents)
# 8. EPD Asynchronous support # 8. EPD Asynchronous support
Normally when GUI code issues 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 It is invalid to issue `.refresh()` until the physical display refresh is
complete; if this is attempted a `RuntimeError` will occur. The most efficient 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 way to ensure that this cannot occur is to await the `.wait()` method prior to
refresh. This method will pause until any physical update is complete. 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 ```python
while True: while True:
# Before refresh, ensure that a previous refresh is complete # 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) await asyncio.sleep(180)
``` ```
###### [Contents](./DRIVERS.md#contents)
# 9. Writing device drivers # 9. Writing device drivers
Device drivers capable of supporting `nanogui` can be extremely simple: see Device drivers capable of supporting `nanogui` can be extremely simple: see
@ -751,7 +767,7 @@ method:
```python ```python
@staticmethod @staticmethod
def rgb(r, g, b): 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 This ensures compatibility with code written for color displays by converting
RGB values to a single bit. RGB values to a single bit.

64
README.md
Wyświetl plik

@ -1,3 +1,5 @@
# MicroPython nano-gui
A lightweight and minimal MicroPython GUI library for display drivers based on A lightweight and minimal MicroPython GUI library for display drivers based on
the `FrameBuffer` class. Various display technologies are supported, including the `FrameBuffer` class. Various display technologies are supported, including
small color and monochrome OLED's, color TFT's, ePaper and Sharp units. The GUI 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 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 display driver is subclassed from the `FrameBuffer` class. Such drivers can be
tiny as the graphics primitives are supplied by the `FrameBuffer` class. A tiny as the graphics primitives are supplied by the `FrameBuffer` class. A
range of device drivers is provided: [this doc](./DRIVERS.md) provides guidance range of device drivers is provided: [the device driver doc](./DRIVERS.md)
on selecting the right driver for your display, platform and application. 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). The GUI is cross-platform. The device driver doc explains how to configure it
This doc explains how to configure for other platforms by adapting a single for a given display and MicroPython host by adapting a single small file. The
small file. The GUI supports multiple displays attached to a single target, but GUI supports multiple displays attached to a single target, but bear in mind
bear in mind the RAM requirements for multiple frame buffers. It is tested on the RAM requirements for multiple frame buffers. The GUI has been tested on
the ESP32 reference board without SPIRAM. Running on ESP8266 is possible but Pyboard 1.1, Pyboard D and on the ESP32 reference board without SPIRAM. Running
frozen bytecode must be used owing to its restricted RAM. 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 It uses synchronous code but is compatible with `uasyncio`. Some demo programs
illustrate this. Code is standard MicroPython, but some device drivers use the 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 ## 1.1 Change log
17 Jan 2021 Add ePaper drivers. Ensure monochrome and color setup requirements 17 Jan 2021
are identical. Substantial update to docs. Add ePaper drivers. Ensure monochrome and color setup requirements are
16 Dec 2020 Add ILI9341 driver, 4-bit drivers and SPI bus sharing improvements. identical. Substantial update to docs.
These mean that `color_setup.py` should now set SPI baudrate. 16 Dec 2020
29 Nov 2020 Add ST7735R TFT drivers. Add ILI9341 driver, 4-bit drivers and SPI bus sharing improvements. These mean
17 Nov 2020 Add `Textbox` widget. `Scale` constructor arg `border` replaced by that `color_setup.py` should now set SPI baudrate.
`bdcolor` as per other widgets. 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 5 Nov 2020 - breaking change
This library has been refactored as a Python package. This reduces RAM usage: This library has been refactored as a Python package. This reduces RAM usage:
widgets are imported on demand rather than unconditionally. This has enabled 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) * [Adafruit 2.9 inch ePaper display](https://www.adafruit.com/product/4262)
documented [here](./DRIVERS.md#71-adafruit-flexible-eink-display). 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) * [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 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 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 RAM usage. It also enables them to be effciently rendered at arbitrary scale by
by hosts with restricted processing power. The approach also enables widgets to hosts with restricted processing power. The approach also enables widgets to
maximise information in ways that are difficult with icons, in particular using maximise information in ways that are difficult with icons, in particular using
dynamic color changes in conjunction with moving elements. 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 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 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 ## 1.3 Quick start
@ -208,7 +216,7 @@ filesystem.
The chosen template will need to be edited to match the display in use, the 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. 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 * `color_setup.py` Hardware setup for the display. As written supports an
SSD1351 display connected to a Pyboard. 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. * `scale_ili.py` A special demo of the asychronous mode of the ILI9341 driver.
Demos for ePaper displays: Demos for ePaper displays:
* `waveshare_test.py` For the Waveshare eInk Display HAT 2.7" 176*274 portrait * `waveshare_test.py` For the Waveshare eInk Display HAT 2.7" 176*274 display.
mode display.
* `epd29_test.py` Demo for Adafruit 2.9" eInk display. * `epd29_test.py` Demo for Adafruit 2.9" eInk display.
Demos for Sharp displays: Demos for Sharp displays:
@ -256,9 +263,9 @@ Demos for Sharp displays:
* `clocktest.py` Digital and analog clock demo. * `clocktest.py` Digital and analog clock demo.
* `clock_batt.py` Low power demo of battery operated clock. * `clock_batt.py` Low power demo of battery operated clock.
Usage with `uasyncio` is discussed [here](./ASYNC.md). In summary the blocking Usage with `uasyncio` is discussed [here](./ASYNC.md). In summary the GUI works
which occurs during transfer of the framebuffer to the display may affect more well with `uasyncio` but the blocking which occurs during transfer of the
demanding `uasyncio` applications. More generally the GUI works well with it. framebuffer to the display may affect more demanding applications.
###### [Contents](./README.md#contents) ###### [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 * `st7735r144_setup.py` For a Pyboard with an
[Adafruit 1.44 inch TFT display](https://www.adafruit.com/product/2088). [Adafruit 1.44 inch TFT display](https://www.adafruit.com/product/2088).
* `ili9341_setup.py` A 240*320 ILI9341 display on ESP32. * `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`. * `epd96_asyn.py` Adafruit 2.9 inch ePaper display, optimised for `uasyncio`.
## 2.2 Dependencies ## 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: in this repo but may be found here:
* [PCD8544/Nokia 5110](https://github.com/mcauser/micropython-pcd8544.git) * [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) ###### [Contents](./README.md#contents)
## 2.3 Verifying hardware configuration ## 2.3 Verifying hardware configuration