drivers: st7789: Finalize docstrings

This commit is contained in:
Daniel Thompson 2020-05-14 21:41:02 +01:00
parent 9274d8cc2d
commit 95f1788347
2 changed files with 105 additions and 9 deletions

View file

@ -53,7 +53,6 @@ Device drivers
.. automodule:: drivers.st7789 .. automodule:: drivers.st7789
:members: :members:
:undoc-members:
.. automodule:: drivers.vibrator .. automodule:: drivers.vibrator
:members: :members:

View file

@ -1,11 +1,14 @@
# SPDX-License-Identifier: LGPL-3.0-or-later # SPDX-License-Identifier: LGPL-3.0-or-later
# Copyright (C) 2020 Daniel Thompson # Copyright (C) 2020 Daniel Thompson
"""Sitronix ST7789 display driver for MicroPython. """Sitronix ST7789 display driver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note: Although the ST7789 supports a variety of communication protocols .. note::
currently this driver only has support for SPI interfaces. However it is
structured such that other serial protocols can easily be added. Although the ST7789 supports a variety of communication protocols currently
this driver only has support for SPI interfaces. However it is structured
such that other serial protocols can easily be added.
""" """
import micropython import micropython
@ -29,13 +32,23 @@ _COLMOD = const(0x3a)
_MADCTL = const(0x36) _MADCTL = const(0x36)
class ST7789(object): class ST7789(object):
"""Sitronix ST7789 display driver
.. automethod:: __init__
"""
def __init__(self, width, height): def __init__(self, width, height):
"""Configure the size of the display.
:param int width: Display width, in pixels
:param int height: Display height in pixels
"""
self.width = width self.width = width
self.height = height self.height = height
self.linebuffer = bytearray(2 * width) self.linebuffer = bytearray(2 * width)
self.init_display() self.init_display()
def init_display(self): def init_display(self):
"""Reset and initialize the display."""
self.reset() self.reset()
self.write_cmd(_SLPOUT) self.write_cmd(_SLPOUT)
@ -56,34 +69,54 @@ class ST7789(object):
# From the point we sent the SLPOUT there must be a # From the point we sent the SLPOUT there must be a
# 120ms gap before any subsequent SLPIN. In most cases # 120ms gap before any subsequent SLPIN. In most cases
# (i.e. wen the SPI baud rate is slower than 8M then # (i.e. when the SPI baud rate is slower than 8M then
# that time already elapsed as we zeroed the RAM). # that time already elapsed as we zeroed the RAM).
#sleep_ms(125) #sleep_ms(125)
def poweroff(self): def poweroff(self):
"""Put the display into sleep mode."""
self.write_cmd(_SLPIN) self.write_cmd(_SLPIN)
sleep_ms(125) sleep_ms(125)
def poweron(self): def poweron(self):
"""Wake the display and leave sleep mode."""
self.write_cmd(_SLPOUT) self.write_cmd(_SLPOUT)
sleep_ms(125) sleep_ms(125)
def contrast(self, contrast):
pass
def invert(self, invert): def invert(self, invert):
"""Invert the display.
:param bool invert: True to invert the display, False for normal mode.
"""
if invert: if invert:
self.write_cmd(_INVON) self.write_cmd(_INVON)
else: else:
self.write_cmd(_INVOFF) self.write_cmd(_INVOFF)
def mute(self, mute): def mute(self, mute):
"""Mute the display.
When muted the display will be entirely black.
:param bool mute: True to mute the display, False for normal mode.
"""
if mute: if mute:
self.write_cmd(_DISPOFF) self.write_cmd(_DISPOFF)
else: else:
self.write_cmd(_DISPON) self.write_cmd(_DISPON)
def set_window(self, x=0, y=0, width=None, height=None): def set_window(self, x=0, y=0, width=None, height=None):
"""Set the clipping rectangle.
All writes to the display will be wrapped at the edges of the rectangle.
:param x: X coordinate of the left-most pixels of the rectangle
:param y: Y coordinate of the top-most pixels of the rectangle
:param w: Width of the rectangle, defaults to None (which means select
the right-most pixel of the display)
:param h: Height of the rectangle, defaults to None (which means select
the bottom-most pixel of the display)
"""
if not width: if not width:
width = self.width width = self.width
if not height: if not height:
@ -99,10 +132,33 @@ class ST7789(object):
self.write_cmd(_RAMWR) self.write_cmd(_RAMWR)
def rawblit(self, buf, x, y, width, height): def rawblit(self, buf, x, y, width, height):
"""Blit raw pixels to the display.
:param buf: Pixel buffer
:param x: X coordinate of the left-most pixels of the rectangle
:param y: Y coordinate of the top-most pixels of the rectangle
:param w: Width of the rectangle, defaults to None (which means select
the right-most pixel of the display)
:param h: Height of the rectangle, defaults to None (which means select
the bottom-most pixel of the display)
"""
self.set_window(x, y, width, height) self.set_window(x, y, width, height)
self.write_data(buf) self.write_data(buf)
def fill(self, bg, x=0, y=0, w=None, h=None): def fill(self, bg, x=0, y=0, w=None, h=None):
"""Draw a solid colour rectangle.
If no arguments a provided the whole display will be filled with
the background colour (typically black).
:param bg: Background colour (in RGB565 format)
:param x: X coordinate of the left-most pixels of the rectangle
:param y: Y coordinate of the top-most pixels of the rectangle
:param w: Width of the rectangle, defaults to None (which means select
the right-most pixel of the display)
:param h: Height of the rectangle, defaults to None (which means select
the bottom-most pixel of the display)
"""
if not w: if not w:
w = self.width - x w = self.width - x
if not h: if not h:
@ -120,7 +176,27 @@ class ST7789(object):
self.write_data(buf) self.write_data(buf)
class ST7789_SPI(ST7789): class ST7789_SPI(ST7789):
"""
.. method:: quick_write(buf)
Send data to the display as part of an optimized write sequence.
:param bytearray buf: Data, must be in a form that can be directly
consumed by the SPI bus.
"""
def __init__(self, width, height, spi, cs, dc, res=None, rate=8000000): def __init__(self, width, height, spi, cs, dc, res=None, rate=8000000):
"""Configure the display.
:param int width: Width of the display
:param int height: Height of the display
:param machine.SPI spi: SPI controller
:param machine.Pin cs: Pin (or signal) to use as the chip select
:param machine.Pin cs: Pin (or signal) to use to switch between data
and command mode.
:param machine.Pin res: Pin (or signal) to, optionally, use to reset
the display.
:param int rate: SPI bus frequency
"""
self.quick_write = spi.write self.quick_write = spi.write
self.cs = cs.value self.cs = cs.value
self.dc = dc.value self.dc = dc.value
@ -136,6 +212,11 @@ class ST7789_SPI(ST7789):
super().__init__(width, height) super().__init__(width, height)
def reset(self): def reset(self):
"""Reset the display.
Uses the hardware reset pin if there is one, otherwise it will issue
a software reset command.
"""
if self.res: if self.res:
self.res(0) self.res(0)
sleep_ms(10) sleep_ms(10)
@ -145,6 +226,11 @@ class ST7789_SPI(ST7789):
sleep_ms(125) sleep_ms(125)
def write_cmd(self, cmd): def write_cmd(self, cmd):
"""Send a command opcode to the display.
:param sequence cmd: Command, will be automatically converted so it can
be issued to the SPI bus.
"""
dc = self.dc dc = self.dc
cs = self.cs cs = self.cs
@ -155,13 +241,24 @@ class ST7789_SPI(ST7789):
dc(1) dc(1)
def write_data(self, buf): def write_data(self, buf):
"""Send data to the display.
:param bytearray buf: Data, must be in a form that can be directly
consumed by the SPI bus.
"""
cs = self.cs cs = self.cs
cs(0) cs(0)
self.quick_write(buf) self.quick_write(buf)
cs(1) cs(1)
def quick_start(self): def quick_start(self):
"""Prepare for an optimized write sequence.
Optimized write sequences allow applications to produce data in chunks
without having any overhead managing the chip select.
"""
self.cs(0) self.cs(0)
def quick_end(self): def quick_end(self):
"""Complete an optimized write sequence."""
self.cs(1) self.cs(1)