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

DRIVERS.md: ILIxxx sections are now adjacent.

pull/98/head
Peter Hinch 2025-02-05 14:29:23 +00:00
rodzic 77f58af1fa
commit 701149bc3a
1 zmienionych plików z 114 dodań i 114 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

228
DRIVERS.md
Wyświetl plik

@ -39,12 +39,12 @@ access via the `Writer` and `CWriter` classes is documented
2.3 [Drivers for SSD1327](./DRIVERS.md#23-drivers-for-ssd1327) Greyscale OLEDs
3. [Color TFT displays](./DRIVERS.md#3-color-tft-displays)
3.1 [Drivers for ST7735R](./DRIVERS.md#31-drivers-for-st7735r) Small TFTs
3.2 [Drivers for ILI9341](./DRIVERS.md#32-drivers-for-ili9341) Large TFTs
3.3 [Drivers for ST7789](./DRIVERS.md#33-drivers-for-st7789) Small high density TFTs
     3.3.1 [TTGO T Display](./DRIVERS.md#331-ttgo-t-display) Low cost ESP32 with integrated display
     3.3.2 [Waveshare Pico Res Touch](./DRIVERS.md#332-waveshare-pico-res-touch)
     3.3.3 [Waveshare Pico LCD 2](./DRIVERS.md#333-waveshare-pico-lcd-2)
     3.3.4 [Troubleshooting](./DRIVERS.md#334-troubleshooting)
3.2 [Drivers for ST7789](./DRIVERS.md#32-drivers-for-st7789) Small high density TFTs
     3.2.1 [TTGO T Display](./DRIVERS.md#321-ttgo-t-display) Low cost ESP32 with integrated display
     3.2.2 [Waveshare Pico Res Touch](./DRIVERS.md#322-waveshare-pico-res-touch)
     3.2.3 [Waveshare Pico LCD 2](./DRIVERS.md#323-waveshare-pico-lcd-2)
     3.2.4 [Troubleshooting](./DRIVERS.md#324-troubleshooting)
3.3 [Drivers for ILI9341](./DRIVERS.md#33-drivers-for-ili9341) Large TFTs
3.4 [Driver for ILI94xx](./DRIVERS.md#34-driver-for-ili94xx) Generic ILI94xx and HX8357D driver for large displays.
3.5 [Driver for gc9a01](./DRIVERS.md#35-driver-for-gc9a01) Round 240x240 displays.
4. [Drivers for sharp displays](./DRIVERS.md#4-drivers-for-sharp-displays) Large low power monochrome displays
@ -389,110 +389,7 @@ def spi_init(spi):
###### [Contents](./DRIVERS.md#contents)
## 3.2 Drivers for ILI9341
Adafruit make several displays using this chip, for example
[this 3.2 inch unit](https://www.adafruit.com/product/1743). This display is
large by microcontroller standards. See below for discussion of which hosts can
be expected to work.
The `color_setup.py` file should initialise the SPI bus with a baudrate of
10_000_000. Args `polarity`, `phase`, `bits`, `firstbit` are defaults. Hard or
soft SPI may be used but hard may be faster. See note on overclocking below.
#### ILI9341 Constructor args:
* `spi` An initialised SPI bus instance. The device can support clock rates of
upto 10MHz.
* `cs` An initialised output pin. Initial value should be 1.
* `dc` An initialised output pin. Initial value should be 0.
* `rst` An initialised output pin. Initial value should be 1.
* `height=240` Display dimensions in pixels. For portrait mode exchange
`height` and `width` values.
* `width=320`
* `usd=False` Upside down: set `True` to invert display.
* `init_spi=False` Allow bus sharing. See note below.
* `mod=None` Set to a number from 0 to 7 to correct garbled display on some
Chinese units.
* `bgr=False` If `True` use BGR color rendition in place of RGB.
#### Method (4-bit driver only)
* `greyscale(gs=None)` Setting `gs=True` enables the screen to be used to show
a full screen monochrome image. By default the frame buffer contents are
interpreted as color values. In greyscale mode the contents are treated as
greyscale values. This mode persists until the method is called with
`gs=False`. The method returns the current greyscale state. It is possible to
superimpose widgets on an image, but the mapping of colors onto the greyscale
may yield unexpected shades of grey. `WHITE` and `BLACK` work well. In
[micro-gui](https://github.com/peterhinch/micropython-micro-gui) and
[micropython-touch](https://github.com/peterhinch/micropython-touch) the
`after_open` method should be used to render the image to the framebuf and to
overlay any widgets.
The 4-bit driver uses four bits per pixel to conserve RAM. Even with this
adaptation the buffer size is 37.5KiB which is too large for some platforms. On
a Pyboard 1.1 the `scale.py` demo ran with 34.5K free with no modules frozen,
and with 47K free with `gui` and contents frozen. An ESP32 with SPIRAM has been
tested. On an ESP32 without SPIRAM, `nano-gui` runs but
[micro-gui](https://github.com/peterhinch/micropython-micro-gui) requires
frozen bytecode. The RP2 Pico runs both GUI's.
See [Color handling](./DRIVERS.md#11-color-handling) for details of the
implications of 4-bit color. The 8-bit driver enables color image display on
platforms with sufficient RAM: see [IMAGE_DISPLAY.md](./IMAGE_DISPLAY.md).
The drivers use the `micropython.viper` decorator. If your platform does not
support this, the Viper code will need to be rewritten with a substantial hit
to performance.
#### Use with asyncio
A full refresh blocks for ~200ms. If this is acceptable, no special precautions
are required. However this period may be unacceptable for some `asyncio`
applications. The driver provides an asynchronous `do_refresh(split=4)` method.
If this is run the display will be refreshed, but will periodically yield to
the scheduler enabling other tasks to run. This is documented
[here](./ASYNC.md). [micro-gui](https://github.com/peterhinch/micropython-micro-gui)
uses this automatically.
Another option to reduce blocking is overclocking the SPI bus.
#### Overclocking SPI
The ILI9341 datasheet section 19.3.4 specifies a minimum clock cycle time of
100ns for write cycles. It seems that every man and his dog overclocks this,
even the normally conservative Adafruit
[use 24MHz](https://learn.adafruit.com/adafruit-2-8-and-3-2-color-tft-touchscreen-breakout-v2/python-usage)
and [rdagger](https://github.com/rdagger/micropython-ili9341/blob/master/demo_fonts.py)
uses 40MHz. I have successfully run my display at 40MHz. My engineering
training makes me baulk at exceeding datasheet limits but the choice is yours.
I raised [this isse](https://github.com/adafruit/Adafruit_CircuitPython_ILI9341/issues/24).
The response may be of interest.
### The init_spi constructor arg
This optional arg enables flexible options in configuring the SPI bus. The
default assumes exclusive access to the bus. In this normal case,
`color_setup.py` initialises it and the settings will be left in place. If the
bus is shared with devices which require different settings, a callback function
should be passed. It will be called prior to each SPI bus write. The callback
will receive a single arg being the SPI bus instance. It will typically be a
one-liner or lambda initialising the bus. A minimal example is this function:
```python
def spi_init(spi):
spi.init(baudrate=10_000_000)
```
#### Troubleshooting
Some Chinese modules produce garbled displays. Please try the
[ILI9486 driver](./DRIVERS.md#34-driver-for-ili94xx) with the `mirror`
constructor arg set `True`. Patch and testing provided by
[Abel Deuring](https://github.com/peterhinch/micropython-micro-gui/issues/25#issuecomment-1475329104).
###### [Contents](./DRIVERS.md#contents)
## 3.3 Drivers for ST7789
## 3.2 Drivers for ST7789
The chip supports sizes up to 240x320 pixels. To keep the buffer size down, the
normal driver uses 4-bit color with dynamic conversion to 16 bit RGB565 at
@ -640,7 +537,7 @@ At a 60MHz baudrate this equates to
This suggests that about 80% of the latency results from the Python code. An
option may be to overclock.
### 3.3.1 TTGO T Display
### 3.2.1 TTGO T Display
Thanks to [Ihor Nehrutsa](https://github.com/IhorNehrutsa) who wrote much of
the setup file for this device.
@ -660,7 +557,7 @@ URL's. More in `st7789_ttgo.py`
[Another MicroPython driver](https://github.com/jikegong/TTGO-Esp32-ST7789-Display-MicroPython/blob/2ed1816c41f25c8993038c35ef40b2efeb225dcc/st7789.py)
[Factory test (C)](https://github.com/Xinyuan-LilyGO/TTGO-T-Display/blob/master/TFT_eSPI/examples/FactoryTest/FactoryTest.ino)
### 3.3.2 Waveshare Pico Res Touch
### 3.2.2 Waveshare Pico Res Touch
This is a "plug and play" 2.8" color TFT for nano-gui and the Pi Pico. Users of
micro-gui will need to find a way to connect pushbuttons, either using stacking
@ -701,7 +598,7 @@ driver which may be found in the MicroPython source tree in
`drivers/sdcard/sdcard.py`. I am not an expert on SD cards. Mine worked fine at
31.25MHz but this may or may not be universally true.
### 3.3.3 Waveshare Pico LCD 2
### 3.2.3 Waveshare Pico LCD 2
Support for this display resulted from a collaboration with Mike Wilson
(@MikeTheGent).
@ -728,7 +625,7 @@ pdc = Pin(8, Pin.OUT, value=0)
ssd = SSD(spi, height=240, width=320, dc=pdc, cs=pcs, rst=prst, disp_mode=LANDSCAPE, display=PI_PICO_LCD_2)
```
### 3.3.4 Troubleshooting
### 3.2.4 Troubleshooting
If your display shows garbage, check the following (I have seen both):
* SPI baudrate too high for your physical layout.
@ -737,6 +634,109 @@ If your display shows garbage, check the following (I have seen both):
###### [Contents](./DRIVERS.md#contents)
## 3.3 Drivers for ILI9341
Adafruit make several displays using this chip, for example
[this 3.2 inch unit](https://www.adafruit.com/product/1743). This display is
large by microcontroller standards. See below for discussion of which hosts can
be expected to work.
The `color_setup.py` file should initialise the SPI bus with a baudrate of
10_000_000. Args `polarity`, `phase`, `bits`, `firstbit` are defaults. Hard or
soft SPI may be used but hard may be faster. See note on overclocking below.
#### ILI9341 Constructor args:
* `spi` An initialised SPI bus instance. The device can support clock rates of
upto 10MHz.
* `cs` An initialised output pin. Initial value should be 1.
* `dc` An initialised output pin. Initial value should be 0.
* `rst` An initialised output pin. Initial value should be 1.
* `height=240` Display dimensions in pixels. For portrait mode exchange
`height` and `width` values.
* `width=320`
* `usd=False` Upside down: set `True` to invert display.
* `init_spi=False` Allow bus sharing. See note below.
* `mod=None` Set to a number from 0 to 7 to correct garbled display on some
Chinese units.
* `bgr=False` If `True` use BGR color rendition in place of RGB.
#### Method (4-bit driver only)
* `greyscale(gs=None)` Setting `gs=True` enables the screen to be used to show
a full screen monochrome image. By default the frame buffer contents are
interpreted as color values. In greyscale mode the contents are treated as
greyscale values. This mode persists until the method is called with
`gs=False`. The method returns the current greyscale state. It is possible to
superimpose widgets on an image, but the mapping of colors onto the greyscale
may yield unexpected shades of grey. `WHITE` and `BLACK` work well. In
[micro-gui](https://github.com/peterhinch/micropython-micro-gui) and
[micropython-touch](https://github.com/peterhinch/micropython-touch) the
`after_open` method should be used to render the image to the framebuf and to
overlay any widgets.
The 4-bit driver uses four bits per pixel to conserve RAM. Even with this
adaptation the buffer size is 37.5KiB which is too large for some platforms. On
a Pyboard 1.1 the `scale.py` demo ran with 34.5K free with no modules frozen,
and with 47K free with `gui` and contents frozen. An ESP32 with SPIRAM has been
tested. On an ESP32 without SPIRAM, `nano-gui` runs but
[micro-gui](https://github.com/peterhinch/micropython-micro-gui) requires
frozen bytecode. The RP2 Pico runs both GUI's.
See [Color handling](./DRIVERS.md#11-color-handling) for details of the
implications of 4-bit color. The 8-bit driver enables color image display on
platforms with sufficient RAM: see [IMAGE_DISPLAY.md](./IMAGE_DISPLAY.md).
The drivers use the `micropython.viper` decorator. If your platform does not
support this, the Viper code will need to be rewritten with a substantial hit
to performance.
#### Use with asyncio
A full refresh blocks for ~200ms. If this is acceptable, no special precautions
are required. However this period may be unacceptable for some `asyncio`
applications. The driver provides an asynchronous `do_refresh(split=4)` method.
If this is run the display will be refreshed, but will periodically yield to
the scheduler enabling other tasks to run. This is documented
[here](./ASYNC.md). [micro-gui](https://github.com/peterhinch/micropython-micro-gui)
uses this automatically.
Another option to reduce blocking is overclocking the SPI bus.
#### Overclocking SPI
The ILI9341 datasheet section 19.3.4 specifies a minimum clock cycle time of
100ns for write cycles. It seems that every man and his dog overclocks this,
even the normally conservative Adafruit
[use 24MHz](https://learn.adafruit.com/adafruit-2-8-and-3-2-color-tft-touchscreen-breakout-v2/python-usage)
and [rdagger](https://github.com/rdagger/micropython-ili9341/blob/master/demo_fonts.py)
uses 40MHz. I have successfully run my display at 40MHz. My engineering
training makes me baulk at exceeding datasheet limits but the choice is yours.
I raised [this isse](https://github.com/adafruit/Adafruit_CircuitPython_ILI9341/issues/24).
The response may be of interest.
### The init_spi constructor arg
This optional arg enables flexible options in configuring the SPI bus. The
default assumes exclusive access to the bus. In this normal case,
`color_setup.py` initialises it and the settings will be left in place. If the
bus is shared with devices which require different settings, a callback function
should be passed. It will be called prior to each SPI bus write. The callback
will receive a single arg being the SPI bus instance. It will typically be a
one-liner or lambda initialising the bus. A minimal example is this function:
```python
def spi_init(spi):
spi.init(baudrate=10_000_000)
```
#### Troubleshooting
Some Chinese modules produce garbled displays. Please try the
[ILI9486 driver](./DRIVERS.md#34-driver-for-ili94xx) with the `mirror`
constructor arg set `True`. Patch and testing provided by
[Abel Deuring](https://github.com/peterhinch/micropython-micro-gui/issues/25#issuecomment-1475329104).
###### [Contents](./DRIVERS.md#contents)
## 3.4 Driver for ILI94xx
This was developed for the ILI9486 but its application is more wide ranging.