Add support for I2C/SPI backpack with MCP23008 and 74LS595. New Character_LCD_I2C and Character_LCD_SPI classes.

Author: tdicola

.gitignore

@@ -0,0 +1,2 @@
+*.mpy
+

adafruit_character_lcd/__init__.py

@@ -1,2 +1,2 @@
-from adafruit_character_lcd.character_lcd import Character_LCD
+from adafruit_character_lcd.character_lcd import Character_LCD, Character_LCD_I2C, Character_LCD_SPI
 from adafruit_character_lcd.character_lcd_RGB import Character_LCD_RGB

adafruit_character_lcd/character_lcd.py

@@ -37,9 +37,11 @@
 """
 import time
 import math
+
 import digitalio
 from board import *
 
+
 # Commands
 LCD_CLEARDISPLAY        = const(0x01)
 LCD_RETURNHOME          = const(0x02)
@@ -81,6 +83,34 @@
 # Offset for up to 4 rows.
 LCD_ROW_OFFSETS         = (0x00, 0x40, 0x14, 0x54)
 
+# MCP23008 I2C backpack pin mapping from LCD logical pin to MCP23008 pin.
+_MCP23008_LCD_RS         = const(1)
+_MCP23008_LCD_EN         = const(2)
+_MCP23008_LCD_D4         = const(3)
+_MCP23008_LCD_D5         = const(4)
+_MCP23008_LCD_D6         = const(5)
+_MCP23008_LCD_D7         = const(6)
+_MCP23008_LCD_BACKLIGHT  = const(7)
+
+# 74LS595 SPI backpack pin mapping from LCD logical pin to 74LS595 pin.
+_74LS595_LCD_RS          = const(1)
+_74LS595_LCD_EN          = const(2)
+_74LS595_LCD_D4          = const(6)
+_74LS595_LCD_D5          = const(5)
+_74LS595_LCD_D6          = const(4)
+_74LS595_LCD_D7          = const(3)
+_74LS595_LCD_BACKLIGHT   = const(7)
+
+
+def _set_bit(byte_value, position, val):
+    # Given the specified byte_value set the bit at position to the provided
+    # boolean value val and return the modified byte.
+    if val:
+        return byte_value | (1 << position)
+    else:
+        return byte_value & ~(1 << position)
+
+
 class Character_LCD(object):
     """ Interfaces with a character LCD
           :param ~digitalio.DigitalInOut rs: The reset data line
@@ -280,3 +310,119 @@ def create_char(self, location, pattern):
         self._write8(LCD_SETCGRAMADDR | (location << 3))
         for i in range(8):
             self._write8(pattern[i], char_mode=True)
+
+
+class Character_LCD_I2C(Character_LCD):
+    """Character LCD connected to I2C/SPI backpack using its I2C connection.
+    This is a subclass of Character_LCD and implements all of the same
+    functions and functionality.
+    """
+
+    def __init__(self, i2c, cols, lines):
+        """Initialize character LCD connectedto backpack using I2C connection
+        on the specified I2C bus and of the specified number of columns and
+        lines on the display.
+        """
+        # Import the MCP23008 module here when the class is used
+        # to keep memory usage low.  If you attempt to import globally at the
+        # top of this file you WILL run out of memory on the M0, even with
+        # MPY files.  The amount of code and classes implicitly imported
+        # by all the SPI and I2C code is too high.  Thus import on demand.
+        import adafruit_character_lcd.mcp23008 as mcp23008
+        self._mcp = mcp23008.MCP23008(i2c, address)
+        # Setup pins for I2C backpack, see diagram:
+        #   https://learn.adafruit.com/assets/35681
+        rs = self._mcp.DigitalInOut(_MCP23008_LCD_RS, self._mcp)
+        en = self._mcp.DigitalInOut(_MCP23008_LCD_EN, self._mcp)
+        d4 = self._mcp.DigitalInOut(_MCP23008_LCD_D4, self._mcp)
+        d5 = self._mcp.DigitalInOut(_MCP23008_LCD_D5, self._mcp)
+        d6 = self._mcp.DigitalInOut(_MCP23008_LCD_D6, self._mcp)
+        d7 = self._mcp.DigitalInOut(_MCP23008_LCD_D7, self._mcp)
+        backlight = self._mcp.DigitalInOut(_MCP23008_LCD_BACKLIGHT, self._mcp)
+        # Call superclass initializer with MCP23008 pins.
+        super().__init__(rs, en, d4, d5, d6, d7, cols, lines,
+                         backlight=backlight)
+
+    def _write8(self, value, char_mode=False):
+        # Optimize a command write by changing all GPIO pins at once instead
+        # of letting the super class try to set each one invidually (far too
+        # slow with overhead of I2C communication).
+        gpio = self._mcp.gpio
+        # Make sure enable is low.
+        gpio = _set_bit(gpio, _MCP23008_LCD_EN, False)
+        # Set character/data bit. (charmode = False).
+        gpio = _set_bit(gpio, _MCP23008_LCD_RS, char_mode)
+        # Set upper 4 bits.
+        gpio = _set_bit(gpio, _MCP23008_LCD_D4, ((value >> 4) & 1) > 0)
+        gpio = _set_bit(gpio, _MCP23008_LCD_D5, ((value >> 5) & 1) > 0)
+        gpio = _set_bit(gpio, _MCP23008_LCD_D6, ((value >> 6) & 1) > 0)
+        gpio = _set_bit(gpio, _MCP23008_LCD_D7, ((value >> 7) & 1) > 0)
+        self._mcp.gpio = gpio
+        # Send command.
+        self._pulse_enable()
+        # Now repeat for lower 4 bits.
+        gpio = self._mcp.gpio
+        gpio = _set_bit(gpio, _MCP23008_LCD_EN, False)
+        gpio = _set_bit(gpio, _MCP23008_LCD_RS, char_mode)
+        gpio = _set_bit(gpio, _MCP23008_LCD_D4, (value & 1) > 0)
+        gpio = _set_bit(gpio, _MCP23008_LCD_D5, ((value >> 1) & 1) > 0)
+        gpio = _set_bit(gpio, _MCP23008_LCD_D6, ((value >> 2) & 1) > 0)
+        gpio = _set_bit(gpio, _MCP23008_LCD_D7, ((value >> 3) & 1) > 0)
+        self._mcp.gpio = gpio
+        self._pulse_enable()
+
+
+class Character_LCD_SPI(Character_LCD):
+    """Character LCD connected to I2C/SPI backpack using its SPI connection.
+    This is a subclass of Character_LCD and implements all of the same
+    functions and functionality.
+    """
+
+    def __init__(self, spi, latch, cols, lines):
+        """Initialize character LCD connectedto backpack using SPI connection
+        on the specified SPI bus and latch line with the specified number of
+        columns and lines on the display.
+        """
+        # See comment above on I2C class for why this is imported here:
+        import adafruit_character_lcd.shift_reg_74ls595 as shift_reg_74ls595
+        self._sr = shift_reg_74ls595.ShiftReg74LS595(spi, latch)
+        # Setup pins for SPI backpack, see diagram:
+        #   https://learn.adafruit.com/assets/35681
+        rs = self._sr.DigitalInOut(_74LS595_LCD_RS, self._sr)
+        en = self._sr.DigitalInOut(_74LS595_LCD_EN, self._sr)
+        d4 = self._sr.DigitalInOut(_74LS595_LCD_D4, self._sr)
+        d5 = self._sr.DigitalInOut(_74LS595_LCD_D5, self._sr)
+        d6 = self._sr.DigitalInOut(_74LS595_LCD_D6, self._sr)
+        d7 = self._sr.DigitalInOut(_74LS595_LCD_D7, self._sr)
+        backlight = self._sr.DigitalInOut(_74LS595_LCD_BACKLIGHT, self._sr)
+        # Call superclass initializer with shift register pins.
+        super().__init__(rs, en, d4, d5, d6, d7, cols, lines,
+                         backlight=backlight)
+
+    def _write8(self, value, char_mode=False):
+        # Optimize a command write by changing all GPIO pins at once instead
+        # of letting the super class try to set each one invidually (far too
+        # slow with overhead of SPI communication).
+        gpio = self._sr.gpio
+        # Make sure enable is low.
+        gpio = _set_bit(gpio, _74LS595_LCD_EN, False)
+        # Set character/data bit. (charmode = False).
+        gpio = _set_bit(gpio, _74LS595_LCD_RS, char_mode)
+        # Set upper 4 bits.
+        gpio = _set_bit(gpio, _74LS595_LCD_D4, ((value >> 4) & 1) > 0)
+        gpio = _set_bit(gpio, _74LS595_LCD_D5, ((value >> 5) & 1) > 0)
+        gpio = _set_bit(gpio, _74LS595_LCD_D6, ((value >> 6) & 1) > 0)
+        gpio = _set_bit(gpio, _74LS595_LCD_D7, ((value >> 7) & 1) > 0)
+        self._sr.gpio = gpio
+        # Send command.
+        self._pulse_enable()
+        # Now repeat for lower 4 bits.
+        gpio = self._sr.gpio
+        gpio = _set_bit(gpio, _74LS595_LCD_EN, False)
+        gpio = _set_bit(gpio, _74LS595_LCD_RS, char_mode)
+        gpio = _set_bit(gpio, _74LS595_LCD_D4, (value & 1) > 0)
+        gpio = _set_bit(gpio, _74LS595_LCD_D5, ((value >> 1) & 1) > 0)
+        gpio = _set_bit(gpio, _74LS595_LCD_D6, ((value >> 2) & 1) > 0)
+        gpio = _set_bit(gpio, _74LS595_LCD_D7, ((value >> 3) & 1) > 0)
+        self._sr.gpio = gpio
+        self._pulse_enable()

adafruit_character_lcd/mcp23008.py

@@ -0,0 +1,147 @@
+# MCP23008 I2C GPIO Extender Driver
+# Bare-bones driver for the MCP23008 driver, as used by the character LCD
+# backpack.  This exposes the MCP2308 and its pins as standard CircuitPython
+# digitalio pins.  Currently this is integrated in the character LCD class for
+# simplicity and reduction in dependent imports, but it could be broken out
+# into a standalone library later.
+# Author: Tony DiCola
+import digitalio
+
+import adafruit_bus_device.i2c_device as i2c_device
+
+
+# Registers and other constants:
+_MCP23008_ADDRESS       = const(0x20)
+_MCP23008_IODIR         = const(0x00)
+_MCP23008_IPOL          = const(0x01)
+_MCP23008_GPINTEN       = const(0x02)
+_MCP23008_DEFVAL        = const(0x03)
+_MCP23008_INTCON        = const(0x04)
+_MCP23008_IOCON         = const(0x05)
+_MCP23008_GPPU          = const(0x06)
+_MCP23008_INTF          = const(0x07)
+_MCP23008_INTCAP        = const(0x08)
+_MCP23008_GPIO          = const(0x09)
+_MCP23008_OLAT          = const(0x0A)
+
+
+class MCP23008:
+
+    # Class-level buffer for reading and writing registers with the device.
+    # This reduces memory allocations but makes the code non-reentrant/thread-
+    # safe!
+    _BUFFER = bytearray(2)
+
+    class DigitalInOut:
+        """Digital input/output of the MCP23008.  The interface is exactly the
+        same as the digitalio.DigitalInOut class (however the MCP23008 does not
+        support pull-down resistors and an exception will be thrown
+        attempting to set one).
+        """
+
+        def __init__(self, pin_number, mcp23008):
+            """Specify the pin number of the MCP23008 (0...7) and MCP23008
+            instance.
+            """
+            self._pin = pin_number
+            self._mcp = mcp23008
+
+        def switch_to_output(value=False, **kwargs):
+            self.direction = digitalio.Direction.OUTPUT
+            self.value = value
+
+        def switch_to_input(self, pull=None, **kwargs):
+            self.direction = digitalio.Direction.INPUT
+            self.pull = pull
+
+        @property
+        def value(self):
+            gpio = self._mcp.gpio
+            return bool(gpio & (1 << self._pin))
+
+        @value.setter
+        def value(self, val):
+            gpio = self._mcp.gpio
+            if val:
+                gpio |= (1 << self._pin)
+            else:
+                gpio &= ~(1 << self._pin)
+            self._mcp.gpio = gpio
+
+        @property
+        def direction(self):
+            iodir = self._mcp._read_u8(_MCP23008_IODIR)
+            if iodir & (1 << self._pin) > 0:
+                return digitalio.Direction.INPUT
+            else:
+                return digitalio.Direction.OUTPUT
+
+        @direction.setter
+        def direction(self, val):
+            iodir = self._mcp._read_u8(_MCP23008_IODIR)
+            if val == digitalio.Direction.INPUT:
+                iodir |= (1 << self._pin)
+            elif val == digitalio.Direction.OUTPUT:
+                iodir &= ~(1 << self._pin)
+            else:
+                raise ValueError('Expected INPUT or OUTPUT direction!')
+            self._mcp._write_u8(_MCP23008_IODIR, iodir)
+
+        @property
+        def pull(self):
+            gppu = self._mcp._read_u8(_MCP23008_GPPU)
+            if gppu & (1 << self._pin) > 0:
+                return digitalio.Pull.UP
+            else:
+                return None
+
+        @pull.setter
+        def pull(self, val):
+            gppu = self._mcp._read_u8(_MCP23008_GPPU)
+            if val is None:
+                gppu &= ~(1 << self._pin)  # Disable pull-up
+            elif val == digitalio.Pull.UP:
+                gppu |= (1 << self._pin)
+            elif val == digitalio.Pull.DOWN:
+                raise ValueError('Pull-down resistors are not supported!')
+            else:
+                raise ValueError('Expected UP, DOWN, or None for pull state!')
+            self._mcp._write_u8(_MCP23008_GPPU, gppu)
+
+    def __init__(self, i2c, address=_MCP23008_ADDRESS):
+        """Initialize MCP23008 instance on specified I2C bus and optionally
+        at the specified I2C address.
+        """
+        self._device = i2c_device.I2CDevice(i2c, address)
+        # Reset device state to all pins as inputs (safest option).
+        with self._device as device:
+            # Write to MCP23008_IODIR register 0xFF followed by 9 zeros
+            # for defaults of other registers.
+            device.write('\x00\xFF\x00\x00\x00\x00\x00\x00\x00\x00\x00')
+
+    def _read_u8(self, register):
+        # Read an unsigned 8 bit value from the specified 8-bit register.
+        with self._device as i2c:
+            self._BUFFER[0] = register & 0xFF
+            i2c.write(self._BUFFER, end=1, stop=False)
+            i2c.readinto(self._BUFFER, end=1)
+            return self._BUFFER[0]
+
+    def _write_u8(self, register, val):
+        # Write an 8 bit value to the specified 8-bit register.
+        with self._device as i2c:
+            self._BUFFER[0] = register & 0xFF
+            self._BUFFER[1] = val & 0xFF
+            i2c.write(self._BUFFER)
+
+    @property
+    def gpio(self):
+        """Get and set the raw GPIO output register.  Each bit represents the
+        output value of the associated pin (0 = low, 1 = high), assuming that
+        pin has been configured as an output previously.
+        """
+        return self._read_u8(_MCP23008_GPIO)
+
+    @gpio.setter
+    def gpio(self, val):
+        self._write_u8(_MCP23008_GPIO, val)