Source code for RPLCD.pigpio

# -*- coding: utf-8 -*-
"""
Copyright (C) 2013-2018 Danilo Bargen
Copyright (C) 2018 Stephan Helma

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

"""
from __future__ import division, absolute_import, unicode_literals

from collections import namedtuple

import pigpio

from . import common as c
from .lcd import BaseCharLCD
from .compat import range


# https://diarmuid.ie/blog/pwm-exponential-led-fading-on-arduino-or-other-platforms/
# p 101 .. maximum value of the PWM cycle
# m 100 .. number of steps the LED will fade over
# r = m*LOG(2)/LOG(p) = 12.5
# dc = 2**(x/r)-1 with x[0..1] and y[0..255]
PWM = 0.125

PinConfig = namedtuple('PinConfig', 'rs rw e e2 d0 d1 d2 d3 d4 d5 d6 d7 backlight contrast')


[docs]class CharLCD(BaseCharLCD): def __init__(self, pi, pin_rs=None, pin_rw=None, pin_e=None, pin_e2=None, pins_data=None, pin_backlight=None, backlight_mode='active_low', backlight_pwm=False, backlight_enabled=True, pin_contrast=None, contrast_mode='active_high', contrast_pwm=None, contrast=0.5, cols=20, rows=4, dotsize=8, charmap='A02', auto_linebreaks=True): """ Character LCD controller. The pin numbers are based on the BCM numbering scheme! You can save 1 pin by not using RW. Set ``pin_rw`` to ``None`` if you want this. :param pi: A pigpio.pi object to access the GPIOs. :type pi: pigpio.pi object :param pin_rs: Pin for register select (RS). Default: ``15``. :type pin_rs: int :param pin_rw: Pin for selecting read or write mode (R/W). Set this to ``None`` for read only mode. Default: ``18``. :type pin_rw: int :param pin_e: Pin to start data read or write (E). Default: ``16``. :type pin_e: int :param pins_data: List of data bus pins in 8 bit mode (DB0-DB7) or in 4 bit mode (DB4-DB7) in ascending order. Default: ``[21, 22, 23, 24]``. :type pins_data: list of int :param pin_backlight: Pin for controlling backlight on/off. Set this to ``None`` for no backlight control. Default: ``None``. :type pin_backlight: int :param backlight_mode: Set this to either ``active_high`` or ``active_low`` to configure the operating control for the backlight. Has no effect if pin_backlight is ``None``. :type backlight_mode: str :param backlight_pwm: Set this to ``True``, if you want to enable PWM for the backlight with the default PWM frequency. Set this to the frequency (in Hz) of the PWM for the backlight or to ``False`` to disable PWM for the backlight. Default: ``False``. Has no effect if pin_backlight is ``None``. :type backlight_pwm: bool or int :param backlight_enabled: Whether the backlight is enabled initially. If backlight_pwm is ``True``, this can be a value between 0 and 1, specifying the initial backlight level. Default: ``True``. Has no effect if pin_backlight is ``None``. :type backlight_enabled: bool or float :param pin_contrast: Pin for controlling LCD contrast. Set this to ``None`` for no contrast control. Default: ``None``. :type pin_contrast: int :param contrast_mode: Set this to either ``active_high`` or ``active_low`` to configure the operating control for the LCD contrast. Has no effect if pin_contrast is ``None``. :type contrast_mode: str :param contrast_pwm: Set this to the frequency (in Hz) of the PWM for the LCD contrast if you want to change the default value. Has no effect if pin_contrast is ``None``. :type contrast_pwm: int :param contrast: A value between 0 and 1, specifying the initial LCD contrast. Default: 0.5. Has no effect if pin_contrast is ``None`` :type contrast: float :param rows: Number of display rows (usually 1, 2 or 4). Default: ``4``. :type rows: int :param cols: Number of columns per row (usually 16 or 20). Default ``20``. :type cols: int :param dotsize: Some 1 line displays allow a font height of 10px. Allowed: ``8`` or ``10``. Default: ``8``. :type dotsize: int :param charmap: The character map used. Depends on your LCD. This must be either ``A00`` or ``A02``. Default: ``A02``. :type charmap: str :param auto_linebreaks: Whether or not to automatically insert line breaks. Default: ``True``. :type auto_linebreaks: bool """ # Save the pigpio.pi object self.pi = pi # Set attributes if pin_rs is None: raise ValueError('pin_rs is not defined.') if pin_e is None: raise ValueError('pin_e is not defined.') if len(pins_data) == 4: # 4 bit mode self.data_bus_mode = c.LCD_4BITMODE block1 = [None] * 4 elif len(pins_data) == 8: # 8 bit mode self.data_bus_mode = c.LCD_8BITMODE block1 = pins_data[:4] else: raise ValueError('There should be exactly 4 or 8 data pins.') block2 = pins_data[-4:] self.pins = PinConfig(rs=pin_rs, rw=pin_rw, e=pin_e, e2=pin_e2, d0=block1[0], d1=block1[1], d2=block1[2], d3=block1[3], d4=block2[0], d5=block2[1], d6=block2[2], d7=block2[3], backlight=pin_backlight, contrast=pin_contrast) self.backlight_mode = backlight_mode self.backlight_pwm = backlight_pwm self.contrast_mode = contrast_mode self.contrast_pwm = contrast_pwm # Call superclass super(CharLCD, self).__init__(cols, rows, dotsize, charmap=charmap, auto_linebreaks=auto_linebreaks) # Set backlight status if pin_backlight is not None: self.backlight_enabled = backlight_enabled # Set contrast self.contrast = contrast def _init_connection(self): # Setup GPIO for pin in list(filter(None, self.pins)): self.pi.set_mode(pin, pigpio.OUTPUT) # Setup PWM if self.pins.backlight and self.backlight_pwm: if self.backlight_pwm is not True: self.pi.set_PWM_frequency(self.pins.backlight, self.backlight_pwm) if self.pins.contrast: if self.backlight_pwm not in (None, False, True): self.pi.set_PWM_frequency(self.pins.contrast, self.contrast_pwm) # Initialization c.msleep(50) self.pi.write(self.pins.rs, 0) self.pi.write(self.pins.e, 0) if self.pins.e2 is not None: self.pi.write(self.pins.e2, 0) if self.pins.rw is not None: self.pi.write(self.pins.rw, 0) # pigpio script to pulse the enable flag to process data enablepulse = [ 'write {pin.e} 0', 'mics 1', 'trig {pin.e} 1 1', 'mics 100'] # Commands need > 37us to settle # pigpio script to write data to the LCD piscript = ['write {pin.rs} p0'] # Choose instruction or data mode if self.pins.rw is not None: # If the RW pin is used, set it to low piscript.append('write {pin.rw} 0') if self.data_bus_mode == c.LCD_8BITMODE: # Script to write 8 bits of data into the data bus. piscript.extend( # Write data in 1 chunk of 8 bits ['write {pin.d0} p1', # Write 8 bits of data into the data bus 'write {pin.d1} p2', 'write {pin.d2} p3', 'write {pin.d3} p4', 'write {pin.d4} p5', 'write {pin.d5} p6', 'write {pin.d6} p7', 'write {pin.d7} p8']) piscript.extend(enablepulse) # Process data else: piscript.extend( # Write data in 2 chunks of 4 bits ['write {pin.d4} p5', # Write 4 bits of data into the data bus 'write {pin.d5} p6', 'write {pin.d6} p7', 'write {pin.d7} p8']) piscript.extend(enablepulse) # Process data piscript.extend( ['write {pin.d4} p1', # Write 4 bits of data into the data bus 'write {pin.d5} p2', 'write {pin.d6} p3', 'write {pin.d7} p4']) piscript.extend(enablepulse) # Process data # Make one string and insert the pin values piscript = ' '.join(piscript).format(pin=self.pins) # Send the string to pigpiod (it expects a byte string) self._writescript = self.pi.store_script(bytes(piscript, 'utf-8')) def _close_connection(self): while self.pi.script_status(self._writescript) == pigpio.PI_SCRIPT_RUNNING: c.msleep(10) self.pi.delete_script(self._writescript) self.pi.stop() # Properties def _get_backlight_enabled(self): if self.pins.backlight is None: raise ValueError('You did not configure a GPIO pin for backlight control!') if self.backlight_pwm: return self._backlight_enabled else: return bool(self._backlight_enabled) def _set_backlight_enabled(self, value): if self.pins.backlight is None: raise ValueError('You did not configure a GPIO pin for backlight control!') if self.backlight_pwm: if not ((0 <= value <= 1) or isinstance(value, bool)): raise ValueError( 'backlight_enabled must be set to a value ' 'between 0 and 1 or to ``True`` or ``False``, ' 'if PWM is enabled; got {}'.format(value)) else: if not isinstance(value, bool): raise ValueError( 'backlight_enabled must be set to ``True`` or ``False``, ' 'if PWM is not enabled; got: {}'.format(value)) self._backlight_enabled = value if self.backlight_pwm: # Convert perceived brightness (as requested by `value`) to duty # cycle (see comment above definition of PWM): dc = 2**(value / PWM) - 1 if self.backlight_mode == 'active_low': dc = 255 - dc self.pi.set_PWM_dutycycle(self.pins.backlight, round(dc)) else: self.pi.write(self.pins.backlight, value ^ (self.backlight_mode == 'active_low')) backlight_enabled = property(_get_backlight_enabled, _set_backlight_enabled, doc='Turn on/off or set the brightness of the backlight.') def _get_contrast(self): # We could probably read the current GPIO output state via sysfs, but # for now let's just store the state in the class if self.pins.contrast is None: raise ValueError('You did not configure a GPIO pin for contrast control!') return self._contrast def _set_contrast(self, value): if self.pins.contrast is None: raise ValueError('You did not configure a GPIO pin for contrast control!') if not (0 <= value <= 1): raise ValueError('contrast must be between 0 and 1; got {}'.format(value)) self._contrast = value dc = 255 * value if self.contrast_mode == 'active_low': dc = 255 - dc self.pi.set_PWM_dutycycle(self.pins.contrast, round(dc)) contrast = property(_get_contrast, _set_contrast, doc='Set the LCD contrast.') # Low level commands def _send(self, value, mode): """Send the specified value to the display with automatic 4bit / 8bit selection. The rs_mode is either ``RS_DATA`` or ``RS_INSTRUCTION``.""" # Assemble the parameters sent to the pigpio script params = [mode] params.extend([(value >> i) & 0x01 for i in range(8)]) # Switch off pigpio's exceptions, so that we get the return codes pigpio.exceptions = False while True: ret = self.pi.run_script(self._writescript, params) if ret >= 0: break elif ret != pigpio.PI_SCRIPT_NOT_READY: raise pigpio.error(pigpio.error_text(ret)) # If pigpio script is not ready, sleep and try again c.usleep(1) # Switch on pigpio's exceptions pigpio.exceptions = True def _send_data(self, value): """Send data to the display. """ self._send(value, c.RS_DATA) def _send_instruction(self, value): """Send instruction to the display. """ self._send(value, c.RS_INSTRUCTION)