From 95f17883474ad65363230bdff310f4645d6247f0 Mon Sep 17 00:00:00 2001 From: Daniel Thompson Date: Thu, 14 May 2020 21:41:02 +0100 Subject: [PATCH] drivers: st7789: Finalize docstrings --- docs/wasp.rst | 1 - wasp/drivers/st7789.py | 113 ++++++++++++++++++++++++++++++++++++++--- 2 files changed, 105 insertions(+), 9 deletions(-) diff --git a/docs/wasp.rst b/docs/wasp.rst index 8026a51..3c3d77e 100644 --- a/docs/wasp.rst +++ b/docs/wasp.rst @@ -53,7 +53,6 @@ Device drivers .. automodule:: drivers.st7789 :members: - :undoc-members: .. automodule:: drivers.vibrator :members: diff --git a/wasp/drivers/st7789.py b/wasp/drivers/st7789.py index aca89db..013ee1b 100644 --- a/wasp/drivers/st7789.py +++ b/wasp/drivers/st7789.py @@ -1,11 +1,14 @@ # SPDX-License-Identifier: LGPL-3.0-or-later # 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 -currently this driver only has support for SPI interfaces. However it is -structured such that other serial protocols can easily be added. +.. note:: + + 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 @@ -29,13 +32,23 @@ _COLMOD = const(0x3a) _MADCTL = const(0x36) class ST7789(object): + """Sitronix ST7789 display driver + + .. automethod:: __init__ + """ 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.height = height self.linebuffer = bytearray(2 * width) self.init_display() def init_display(self): + """Reset and initialize the display.""" self.reset() self.write_cmd(_SLPOUT) @@ -56,34 +69,54 @@ class ST7789(object): # From the point we sent the SLPOUT there must be a # 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). #sleep_ms(125) def poweroff(self): + """Put the display into sleep mode.""" self.write_cmd(_SLPIN) sleep_ms(125) def poweron(self): + """Wake the display and leave sleep mode.""" self.write_cmd(_SLPOUT) sleep_ms(125) - def contrast(self, contrast): - pass - def invert(self, invert): + """Invert the display. + + :param bool invert: True to invert the display, False for normal mode. + """ if invert: self.write_cmd(_INVON) else: self.write_cmd(_INVOFF) 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: self.write_cmd(_DISPOFF) else: self.write_cmd(_DISPON) 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: width = self.width if not height: @@ -99,10 +132,33 @@ class ST7789(object): self.write_cmd(_RAMWR) 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.write_data(buf) 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: w = self.width - x if not h: @@ -120,7 +176,27 @@ class ST7789(object): self.write_data(buf) 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): + """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.cs = cs.value self.dc = dc.value @@ -136,6 +212,11 @@ class ST7789_SPI(ST7789): super().__init__(width, height) 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: self.res(0) sleep_ms(10) @@ -145,6 +226,11 @@ class ST7789_SPI(ST7789): sleep_ms(125) 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 cs = self.cs @@ -155,13 +241,24 @@ class ST7789_SPI(ST7789): dc(1) 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(0) self.quick_write(buf) cs(1) 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) def quick_end(self): + """Complete an optimized write sequence.""" self.cs(1)