lcd_api.py

   1 import time
   2
   3 class LcdApi:
   4
   5     # Implements the API for talking with HD44780 compatible character LCDs.
   6     # This class only knows what commands to send to the LCD, and not how to get
   7     # them to the LCD.
   8     #
   9     # It is expected that a derived class will implement the hal_xxx functions.
  10     #
  11     # The following constant names were lifted from the avrlib lcd.h header file,
  12     # with bit numbers changed to bit masks.
  13
  14     # HD44780 LCD controller command set
  15     LCD_CLR             = 0x01  # DB0: clear display
  16     LCD_HOME            = 0x02  # DB1: return to home position
  17
  18     LCD_ENTRY_MODE      = 0x04  # DB2: set entry mode
  19     LCD_ENTRY_INC       = 0x02  # DB1: increment
  20     LCD_ENTRY_SHIFT     = 0x01  # DB0: shift
  21
  22     LCD_ON_CTRL         = 0x08  # DB3: turn lcd/cursor on
  23     LCD_ON_DISPLAY      = 0x04  # DB2: turn display on
  24     LCD_ON_CURSOR       = 0x02  # DB1: turn cursor on
  25     LCD_ON_BLINK        = 0x01  # DB0: blinking cursor
  26
  27     LCD_MOVE            = 0x10  # DB4: move cursor/display
  28     LCD_MOVE_DISP       = 0x08  # DB3: move display (0-> move cursor)
  29     LCD_MOVE_RIGHT      = 0x04  # DB2: move right (0-> left)
  30
  31     LCD_FUNCTION        = 0x20  # DB5: function set
  32     LCD_FUNCTION_8BIT   = 0x10  # DB4: set 8BIT mode (0->4BIT mode)
  33     LCD_FUNCTION_2LINES = 0x08  # DB3: two lines (0->one line)
  34     LCD_FUNCTION_10DOTS = 0x04  # DB2: 5x10 font (0->5x7 font)
  35     LCD_FUNCTION_RESET  = 0x30  # See "Initializing by Instruction" section
  36
  37     LCD_CGRAM           = 0x40  # DB6: set CG RAM address
  38     LCD_DDRAM           = 0x80  # DB7: set DD RAM address
  39
  40     LCD_RS_CMD          = 0
  41     LCD_RS_DATA         = 1
  42
  43     LCD_RW_WRITE        = 0
  44     LCD_RW_READ         = 1
  45
  46     def __init__(self, num_lines, num_columns):
  47         self.num_lines = num_lines
  48         if self.num_lines > 4:
  49             self.num_lines = 4
  50         self.num_columns = num_columns
  51         if self.num_columns > 40:
  52             self.num_columns = 40
  53         self.cursor_x = 0
  54         self.cursor_y = 0
  55         self.implied_newline = False
  56         self.backlight = True
  57         self.display_off()
  58         self.backlight_on()
  59         self.clear()
  60         self.hal_write_command(self.LCD_ENTRY_MODE | self.LCD_ENTRY_INC)
  61         self.hide_cursor()
  62         self.display_on()
  63
  64     def clear(self):
  65         # Clears the LCD display and moves the cursor to the top left corner
  66         self.hal_write_command(self.LCD_CLR)
  67         self.hal_write_command(self.LCD_HOME)
  68         self.cursor_x = 0
  69         self.cursor_y = 0
  70
  71     def show_cursor(self):
  72         # Causes the cursor to be made visible
  73         self.hal_write_command(self.LCD_ON_CTRL | self.LCD_ON_DISPLAY |
  74                                self.LCD_ON_CURSOR)
  75
  76     def hide_cursor(self):
  77         # Causes the cursor to be hidden
  78         self.hal_write_command(self.LCD_ON_CTRL | self.LCD_ON_DISPLAY)
  79
  80     def blink_cursor_on(self):
  81         # Turns on the cursor, and makes it blink
  82         self.hal_write_command(self.LCD_ON_CTRL | self.LCD_ON_DISPLAY |
  83                                self.LCD_ON_CURSOR | self.LCD_ON_BLINK)
  84
  85     def blink_cursor_off(self):
  86         # Turns on the cursor, and makes it no blink (i.e. be solid)
  87         self.hal_write_command(self.LCD_ON_CTRL | self.LCD_ON_DISPLAY |
  88                                self.LCD_ON_CURSOR)
  89
  90     def display_on(self):
  91         # Turns on (i.e. unblanks) the LCD
  92         self.hal_write_command(self.LCD_ON_CTRL | self.LCD_ON_DISPLAY)
  93
  94     def display_off(self):
  95         # Turns off (i.e. blanks) the LCD
  96         self.hal_write_command(self.LCD_ON_CTRL)
  97
  98     def backlight_on(self):
  99         # Turns the backlight on.
 100
 101         # This isn't really an LCD command, but some modules have backlight
 102         # controls, so this allows the hal to pass through the command.
 103         self.backlight = True
 104         self.hal_backlight_on()
 105
 106     def backlight_off(self):
 107         # Turns the backlight off.
 108
 109         # This isn't really an LCD command, but some modules have backlight
 110         # controls, so this allows the hal to pass through the command.
 111         self.backlight = False
 112         self.hal_backlight_off()
 113
 114     def move_to(self, cursor_x, cursor_y):
 115         # Moves the cursor position to the indicated position. The cursor
 116         # position is zero based (i.e. cursor_x == 0 indicates first column).
 117         self.cursor_x = cursor_x
 118         self.cursor_y = cursor_y
 119         addr = cursor_x & 0x3f
 120         if cursor_y & 1:
 121             addr += 0x40    # Lines 1 & 3 add 0x40
 122         if cursor_y & 2:    # Lines 2 & 3 add number of columns
 123             addr += self.num_columns
 124         self.hal_write_command(self.LCD_DDRAM | addr)
 125
 126     def putchar(self, char):
 127         # Writes the indicated character to the LCD at the current cursor
 128         # position, and advances the cursor by one position.
 129         if char == '\n':
 130             if self.implied_newline:
 131                 # self.implied_newline means we advanced due to a wraparound,
 132                 # so if we get a newline right after that we ignore it.
 133                 pass
 134             else:
 135                 self.cursor_x = self.num_columns
 136         else:
 137             self.hal_write_data(ord(char))
 138             self.cursor_x += 1
 139         if self.cursor_x >= self.num_columns:
 140             self.cursor_x = 0
 141             self.cursor_y += 1
 142             self.implied_newline = (char != '\n')
 143         if self.cursor_y >= self.num_lines:
 144             self.cursor_y = 0
 145         self.move_to(self.cursor_x, self.cursor_y)
 146
 147     def putstr(self, string):
 148         # Write the indicated string to the LCD at the current cursor
 149         # position and advances the cursor position appropriately.
 150         for char in string:
 151             self.putchar(char)
 152
 153     def custom_char(self, location, charmap):
 154         # Write a character to one of the 8 CGRAM locations, available
 155         # as chr(0) through chr(7).
 156         location &= 0x7
 157         self.hal_write_command(self.LCD_CGRAM | (location << 3))
 158         self.hal_sleep_us(40)
 159         for i in range(8):
 160             self.hal_write_data(charmap[i])
 161             self.hal_sleep_us(40)
 162         self.move_to(self.cursor_x, self.cursor_y)
 163
 164     def hal_backlight_on(self):
 165         # Allows the hal layer to turn the backlight on.
 166         # If desired, a derived HAL class will implement this function.
 167         pass
 168
 169     def hal_backlight_off(self):
 170         # Allows the hal layer to turn the backlight off.
 171         # If desired, a derived HAL class will implement this function.
 172         pass
 173
 174     def hal_write_command(self, cmd):
 175         # Write a command to the LCD.
 176         # It is expected that a derived HAL class will implement this function.
 177         raise NotImplementedError
 178
 179     def hal_write_data(self, data):
 180         # Write data to the LCD.
 181         # It is expected that a derived HAL class will implement this function.
 182         raise NotImplementedError
 183
 184     def hal_sleep_us(self, usecs):
 185         # Sleep for some time (given in microseconds)
 186         time.sleep_us(usecs)