|
| 1 | +# LiquidCrystal_I2C Library |
| 2 | + |
| 3 | +This library is for character LCDs based on the HD44780 controller connected |
| 4 | +via I2C bus using the cheap I2C backpack modules based on the PCF8574(T/A). |
| 5 | + |
| 6 | +It is derived from the |
| 7 | +[LiquidCrystal_I2C](https://github.com/fdebrabander/Arduino-LiquidCrystal-I2C-library) |
| 8 | +library as of 09.05.2017 ([commit |
| 9 | +e3701fb](https://github.com/fdebrabander/Arduino-LiquidCrystal-I2C-library/tree/e3701fb3f2398a6d18bfd94a4a7f36e065d57d77)). |
| 10 | +by [Frank de Brabander](https://github.com/fdebrabander). |
| 11 | + |
| 12 | + |
| 13 | +## API |
| 14 | + |
| 15 | +The API is very similar (but, for unknown reasons, not identical) to the API |
| 16 | +used by the Arduino LiquidCrystal library for text LCDs with a parallel |
| 17 | +interface. |
| 18 | + |
| 19 | +This library is a singleton library, it is not possible to use more than one |
| 20 | +instance per sketch. |
| 21 | + |
| 22 | +The API syntax is very similar to the original C++ syntax, thanks to some |
| 23 | +[c preprocessor macro magic](../developer/macro). |
| 24 | + |
| 25 | +Apart from the usual name mangeling for polymorph functions (mostly the |
| 26 | +different variants of the Print::print method) moving the opening bracket at |
| 27 | +the class declarator line and replacing the dots in the method names for |
| 28 | +underscores is all it needs. |
| 29 | + |
| 30 | +The original version of the LiquidCystal_I2C library requires the |
| 31 | +definition of the LCD size and the desired character size (8 or 10 pixel |
| 32 | +height) at the instantiation uses a parameterless begin() method. |
| 33 | + |
| 34 | +This differs slightly from the semantic of the regular Arduino |
| 35 | +LiquidCrystal library using the parallel interface. There, the |
| 36 | +instantiation defines only the electrical connection (the used pin |
| 37 | +numbers) and defines the logical properties (cols, rows, charsize) later |
| 38 | +with the begin method. |
| 39 | + |
| 40 | +As an addition to the Arduino version of this library this port |
| 41 | +supports both initialization styles. |
| 42 | + |
| 43 | + |
| 44 | +Arduino syntax |sduino syntax |
| 45 | +-------------------- |--------------------- |
| 46 | +`LiquidCrystal_I2C lcd(i2c_addr,cols,rows,charsize)` |`LiquidCrystal_I2C (lcd,i2c_addr,rows,cols,charsize)` |
| 47 | +`LiquidCrystal_I2C lcd(i2c_addr,cols,rows)` |`LiquidCrystal_I2C (lcd,i2c_addr,rows)` |
| 48 | +not allowed |`LiquidCrystal_I2C (lcd,i2c_addr)` |
| 49 | +`lcd.init(i2c_addr,cols,rows,charsize)` |`lcd_init(i2c_addr,cols,rows,charsize)` |
| 50 | +`lcd.begin()` |`lcd_begin()` |
| 51 | +not allowed |`lcd_begin_wh(cols,rows)` |
| 52 | +not allowed |`lcd_begin_full(cols,rows,charsize)` |
| 53 | +`lcd.clear()` |`lcd_clear()` |
| 54 | +`lcd.home()` |`lcd_home()` |
| 55 | +`lcd.noDisplay()` |`lcd_noDisplay()` |
| 56 | +`lcd.display()` |`lcd_display()` |
| 57 | +`lcd.noBlink()` |`lcd_noBlink()` |
| 58 | +`lcd.blink()` |`lcd_blink()` |
| 59 | +`lcd.noCursor()` |`lcd_noCursor()` |
| 60 | +`lcd.cursor()` |`lcd_cursor()` |
| 61 | +`lcd.scrollDisplayLeft()` |`lcd_scrollDisplayLeft()` |
| 62 | +`lcd.scrollDisplayRight()` |`lcd_scrollDisplayRight()` |
| 63 | +`lcd.printLeft()` |`lcd_printLeft()` |
| 64 | +`lcd.printRight()` |`lcd_printRight()` |
| 65 | +`lcd.leftToRight()` |`lcd_leftToRight()` |
| 66 | +`lcd.rightToLeft()` |`lcd_rightToLeft()` |
| 67 | +`lcd.shiftIncrement()` |`lcd_shiftIncrement()` |
| 68 | +`lcd.shiftDecrement()` |`lcd_shiftDecrement()` |
| 69 | +`lcd.noBacklight()` |`lcd_noBacklight()` |
| 70 | +`lcd.Backlight()` |`lcd_Backlight()` |
| 71 | +`result = lcd.getBacklight()` |`result = lcd_getBacklight()` |
| 72 | +`lcd.noAutoscroll()` |`lcd_noAutoscroll()` |
| 73 | +`lcd.autoscroll()` |`lcd_autoscroll()` |
| 74 | +`lcd.createChar(number, data[])` |`lcd_createChar(number, data[])` |
| 75 | +`lcd.setCursor(col,row)` |`lcd_setCursor(col,row)` |
| 76 | +`result = lcd.write(value)` |`result = lcd_write(value)` |
| 77 | +`lcd.command(value)` |`lcd_command(value)` |
| 78 | + |
| 79 | +The library supports the following alias definitions introduced by the |
| 80 | +original LiquidCrystal_I2C library. The use of these alias is depreciated |
| 81 | +and should be avoided: |
| 82 | + |
| 83 | +Arduino syntax |sduino syntax |
| 84 | +-------------------- |--------------------- |
| 85 | +`lcd_blink_on()` |`lcd_blink_on()` |
| 86 | +`lcd_blink_off()` |`lcd_blink_off()` |
| 87 | +`lcd_cursor_on()` |`lcd_cursor_on()` |
| 88 | +`lcd_cursor_off()` |`lcd_cursor_off()` |
| 89 | +`lcd_setBacklight(new_val)` |`lcd_setBacklight(new_val)` |
| 90 | +`lcd_load_custom_character(number, data[])`|`lcd_load_custom_character(number, data[])` |
| 91 | +`lcd_printstr(string)` |`lcd_printstr(string)` |
| 92 | + |
| 93 | + |
| 94 | + |
| 95 | + |
| 96 | +## Example |
| 97 | + |
| 98 | +Output some Text and count the time since the last reset. Notice the |
| 99 | +slightly different position of the opening parenthesis at the "class |
| 100 | +constructor" function LiquidCrystal_I2C compared to the C++ instatiation. |
| 101 | + |
| 102 | +```c |
| 103 | +#include <Arduino.h> |
| 104 | +#include <LiquidCrystal_I2C.h> |
| 105 | + |
| 106 | +// initialize the library with the I2C bus address |
| 107 | +// The instance name "lcd" is *within* the brackets |
| 108 | +LiquidCrystal_I2C (lcd,0x27,16,2); |
| 109 | + |
| 110 | +void setup() { |
| 111 | + lcd_begin(); |
| 112 | + lcd_print_s("hello, world!"); |
| 113 | +} |
| 114 | + |
| 115 | + |
| 116 | +void loop() { |
| 117 | + lcd_setCursor(0, 1); |
| 118 | + lcd_print_u(millis() / 1000); |
| 119 | +} |
| 120 | +``` |
| 121 | +
|
| 122 | +
|
| 123 | +Compare this to the original Arduino C++-Sytax: |
| 124 | +
|
| 125 | +```c |
| 126 | +#include <LiquidCrystal_I2C.h> |
| 127 | +
|
| 128 | +// initialize the library with the I2C bus address |
| 129 | +// The instance name "lcd" is *before* the brackets |
| 130 | +LiquidCrystal_I2C lcd(0x27,16,2); |
| 131 | +
|
| 132 | +void setup() { |
| 133 | + lcd.begin(); |
| 134 | + lcd.print("hello, world!"); |
| 135 | +} |
| 136 | +
|
| 137 | +void loop() { |
| 138 | + lcd.setCursor(0, 1); |
| 139 | + lcd.print(millis() / 1000); |
| 140 | +} |
| 141 | +``` |
| 142 | + |
| 143 | + |
| 144 | +As an extention to the original `LiquidCrystal_I2C` libray this Sduino port |
| 145 | +supports an initialisation similar to the syntax of the regular |
| 146 | +LiquidCrystal library: Defining only the electrical parameters at |
| 147 | +instantiation (I2C bus address) and giving the logical parameters (display |
| 148 | +size) with the `begin()` method: |
| 149 | + |
| 150 | +```c |
| 151 | +#include <Arduino.h> |
| 152 | +#include <LiquidCrystal_I2C.h> |
| 153 | + |
| 154 | +// initialize the library with the I2C bus address |
| 155 | +// The instance name "lcd" is *within* the brackets |
| 156 | +LiquidCrystal_I2C (lcd,0x27); |
| 157 | + |
| 158 | +void setup() { |
| 159 | + lcd_begin(16,2); |
| 160 | + lcd_print_s("hello, world!"); |
| 161 | +} |
| 162 | + |
| 163 | + |
| 164 | +void loop() { |
| 165 | + lcd_setCursor(0, 1); |
| 166 | + lcd_print_u(millis() / 1000); |
| 167 | +} |
| 168 | +``` |
| 169 | +
|
| 170 | +
|
| 171 | +
|
| 172 | +
|
| 173 | +## Possible improvements |
| 174 | +
|
| 175 | +This is not a to-do-list, just brainstorming and a collection of random |
| 176 | +thoughts. |
| 177 | +
|
| 178 | +
|
| 179 | +
|
| 180 | +## Further reading |
| 181 | +
|
| 182 | +[Detailed look at the PCF8574 I2C port |
| 183 | + expander](https://alselectro.wordpress.com/2016/05/12/serial-lcd-i2c-module-pcf8574/) |
| 184 | +
|
0 commit comments