From dc9d2e87de4c2272a06239c9f635f39a082d8f2c Mon Sep 17 00:00:00 2001 From: Peter Hinch Date: Sun, 17 Jan 2021 17:20:54 +0000 Subject: [PATCH] Fixes to docs. --- DRIVERS.md | 44 +++++++++++++++++++++++++------------ README.md | 64 +++++++++++++++++++++++++++++------------------------- 2 files changed, 64 insertions(+), 44 deletions(-) diff --git a/DRIVERS.md b/DRIVERS.md index 19b4e2a..1fd77b9 100644 --- a/DRIVERS.md +++ b/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. diff --git a/README.md b/README.md index efa8f7e..5e0fdfa 100644 --- a/README.md +++ b/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