Add driver and example for ESP32 (#15)

* Add driver and example for ESP32
* Update documentation for ESP32

Author: Synapski

README.md

@@ -34,6 +34,8 @@ Files
 
 | File                          | Description                           |
 | -----                         | -----------                           |
+| esp32_gpio_lcd.py             | ESP32 GPIO HAL                        |
+| esp32_gpio_lcd_test.py        | ESP32 test using 4-bit GPIO           |
 | esp8266_i2c_lcd.py            | ESP8266 PCF8574 I2C HAL               |
 | esp8266_i2c_lcd_test.py       | ESP8266 test using PCF8574 backpack   |
 | i2c_lcd.py                    | Linux PCF8574 I2C HAL                 |

lcd/esp32_gpio_lcd.py

@@ -0,0 +1,168 @@
+"""Implements a HD44780 character LCD connected via ESP32 GPIO pins."""
+
+from lcd_api import LcdApi
+from machine import Pin
+from utime import sleep_ms, sleep_us
+
+
+class GpioLcd(LcdApi):
+    """Implements a HD44780 character LCD connected via ESP32 GPIO pins."""
+
+    def __init__(self, rs_pin, enable_pin, d0_pin=None, d1_pin=None,
+                 d2_pin=None, d3_pin=None, d4_pin=None, d5_pin=None,
+                 d6_pin=None, d7_pin=None, rw_pin=None, backlight_pin=None,
+                 num_lines=2, num_columns=16):
+        """Constructs the GpioLcd object. All of the arguments must be machine.Pin
+        objects which describe which pin the given line from the LCD is
+        connected to.
+
+        When used in 4-bit mode, only D4, D5, D6, and D7 are physically
+        connected to the LCD panel. This function allows you call it like
+        GpioLcd(rs, enable, D4, D5, D6, D7) and it will interpret that as
+        if you had actually called:
+        GpioLcd(rs, enable, d4=D4, d5=D5, d6=D6, d7=D7)
+
+        The enable 8-bit mode, you need pass d0 through d7.
+
+        The rw pin isn't used by this library, but if you specify it, then
+        it will be set low.
+        """
+        self.rs_pin = rs_pin
+        self.enable_pin = enable_pin
+        self.rw_pin = rw_pin
+        self.backlight_pin = backlight_pin
+        self._4bit = True
+        if d4_pin and d5_pin and d6_pin and d7_pin:
+            self.d0_pin = d0_pin
+            self.d1_pin = d1_pin
+            self.d2_pin = d2_pin
+            self.d3_pin = d3_pin
+            self.d4_pin = d4_pin
+            self.d5_pin = d5_pin
+            self.d6_pin = d6_pin
+            self.d7_pin = d7_pin
+            if self.d0_pin and self.d1_pin and self.d2_pin and self.d3_pin:
+                self._4bit = False
+        else:
+            # This is really 4-bit mode, and the 4 data pins were just
+            # passed as the first 4 arguments, so we switch things around.
+            self.d0_pin = None
+            self.d1_pin = None
+            self.d2_pin = None
+            self.d3_pin = None
+            self.d4_pin = d0_pin
+            self.d5_pin = d1_pin
+            self.d6_pin = d2_pin
+            self.d7_pin = d3_pin
+        self.rs_pin.init(Pin.OUT)
+        self.rs_pin.value(0)
+        if self.rw_pin:
+            self.rw_pin.init(Pin.OUT)
+            self.rw_pin.value(0)
+        self.enable_pin.init(Pin.OUT)
+        self.enable_pin.value(0)
+        self.d4_pin.init(Pin.OUT)
+        self.d5_pin.init(Pin.OUT)
+        self.d6_pin.init(Pin.OUT)
+        self.d7_pin.init(Pin.OUT)
+        self.d4_pin.value(0)
+        self.d5_pin.value(0)
+        self.d6_pin.value(0)
+        self.d7_pin.value(0)
+        if not self._4bit:
+            self.d0_pin.init(Pin.OUT)
+            self.d1_pin.init(Pin.OUT)
+            self.d2_pin.init(Pin.OUT)
+            self.d3_pin.init(Pin.OUT)
+            self.d0_pin.value(0)
+            self.d1_pin.value(0)
+            self.d2_pin.value(0)
+            self.d3_pin.value(0)
+        if self.backlight_pin is not None:
+            self.backlight_pin.init(Pin.OUT)
+            self.backlight_pin.value(0)
+
+        # See about splitting this into begin
+
+        sleep_ms(20)   # Allow LCD time to powerup
+        # Send reset 3 times
+        self.hal_write_init_nibble(self.LCD_FUNCTION_RESET)
+        sleep_ms(5)    # need to delay at least 4.1 msec
+        self.hal_write_init_nibble(self.LCD_FUNCTION_RESET)
+        sleep_ms(1)
+        self.hal_write_init_nibble(self.LCD_FUNCTION_RESET)
+        sleep_ms(1)
+        cmd = self.LCD_FUNCTION
+        if not self._4bit:
+            cmd |= self.LCD_FUNCTION_8BIT
+        self.hal_write_init_nibble(cmd)
+        sleep_ms(1)
+        LcdApi.__init__(self, num_lines, num_columns)
+        if num_lines > 1:
+            cmd |= self.LCD_FUNCTION_2LINES
+        self.hal_write_command(cmd)
+
+    def hal_pulse_enable(self):
+        """Pulse the enable line high, and then low again."""
+        self.enable_pin.value(0)
+        sleep_us(1)
+        self.enable_pin.value(1)
+        sleep_us(1)       # Enable pulse needs to be > 450 nsec
+        self.enable_pin.value(0)
+        sleep_us(100)     # Commands need > 37us to settle
+
+    def hal_write_init_nibble(self, nibble):
+        """Writes an initialization nibble to the LCD.
+
+        This particular function is only used during initialization.
+        """
+        self.hal_write_4bits(nibble >> 4)
+
+    def hal_backlight_on(self):
+        """Allows the hal layer to turn the backlight on."""
+        if self.backlight_pin:
+            self.backlight_pin.value(1)
+
+    def hal_backlight_off(self):
+        """Allows the hal layer to turn the backlight off."""
+        if self.backlight_pin:
+            self.backlight_pin.value(0)
+
+    def hal_write_command(self, cmd):
+        """Writes a command to the LCD.
+
+        Data is latched on the falling edge of E.
+        """
+        self.rs_pin.value(0)
+        self.hal_write_8bits(cmd)
+        if cmd <= 3:
+            # The home and clear commands require a worst
+            # case delay of 4.1 msec
+            sleep_ms(5)
+
+    def hal_write_data(self, data):
+        """Write data to the LCD."""
+        self.rs_pin.value(1)
+        self.hal_write_8bits(data)
+
+    def hal_write_8bits(self, value):
+        """Writes 8 bits of data to the LCD."""
+        if self.rw_pin:
+            self.rw_pin.value(0)
+        if self._4bit:
+            self.hal_write_4bits(value >> 4)
+            self.hal_write_4bits(value)
+        else:
+            self.d3_pin.value(value & 0x08)
+            self.d2_pin.value(value & 0x04)
+            self.d1_pin.value(value & 0x02)
+            self.d0_pin.value(value & 0x01)
+            self.hal_write_4bits(value >> 4)
+
+    def hal_write_4bits(self, nibble):
+        """Writes 4 bits of data to the LCD."""
+        self.d7_pin.value(nibble & 0x08)
+        self.d6_pin.value(nibble & 0x04)
+        self.d5_pin.value(nibble & 0x02)
+        self.d4_pin.value(nibble & 0x01)
+        self.hal_pulse_enable()

lcd/esp32_gpio_lcd_test.py

@@ -0,0 +1,55 @@
+"""Implements a HD44780 character LCD connected via ESP32 GPIO pins."""
+
+from machine import Pin
+from esp32_gpio_lcd import GpioLcd
+from utime import sleep_ms, ticks_ms
+
+# Wiring used for this example:
+#
+#  1 - Vss (aka Ground) - Connect to one of the ground pins on you pyboard.
+#  2 - VDD - I connected to VIN which is 5 volts when your pyboard is powered via USB
+#  3 - VE (Contrast voltage) - I'll discuss this below
+#  4 - RS (Register Select) connect to G4 (as per call to GpioLcd)
+#  5 - RW (Read/Write) - connect to ground
+#  6 - EN (Enable) connect to G11 (as per call to GpioLcd)
+#  7 - D0 - leave unconnected
+#  8 - D1 - leave unconnected
+#  9 - D2 - leave unconnected
+# 10 - D3 - leave unconnected
+# 11 - D4 - connect to G5 (as per call to GpioLcd)
+# 12 - D5 - connect to G18 (as per call to GpioLcd)
+# 13 - D6 - connect to G21 (as per call to GpioLcd)
+# 14 - D7 - connect to G22 (as per call to GpioLcd)
+# 15 - A (BackLight Anode) - Connect to VIN
+# 16 - K (Backlight Cathode) - Connect to Ground
+#
+# On 14-pin LCDs, there is no backlight, so pins 15 & 16 don't exist.
+#
+# The Contrast line (pin 3) typically connects to the center tap of a
+# 10K potentiometer, and the other 2 legs of the 10K potentiometer are
+# connected to pins 1 and 2 (Ground and VDD)
+#
+# The wiring diagram on the following page shows a typical "base" wiring:
+# http://www.instructables.com/id/How-to-drive-a-character-LCD-displays-using-DIP-sw/step2/HD44780-pinout/
+# Add to that the EN, RS, and D4-D7 lines.
+
+
+def test_main():
+    """Test function for verifying basic functionality."""
+    print("Running test_main")
+    lcd = GpioLcd(rs_pin=Pin(4),
+                  enable_pin=Pin(17),
+                  d4_pin=Pin(5),
+                  d5_pin=Pin(18),
+                  d6_pin=Pin(21),
+                  d7_pin=Pin(22),
+                  num_lines=2, num_columns=20)
+    lcd.putstr("It Works!\nSecond Line\nThird Line\nFourth Line")
+    sleep_ms(3000)
+    lcd.clear()
+    count = 0
+    while True:
+        lcd.move_to(0, 0)
+        lcd.putstr("%7d" % (ticks_ms() // 1000))
+        sleep_ms(1000)
+        count += 1