├── examples ├── HelloWorld │ └── HelloWorld.ino ├── BlinkingCursor │ └── BlinkingCursor.ino ├── SerialDisplay │ └── SerialDisplay.ino └── CustomChars │ └── CustomChars.ino ├── README.md ├── keywords.txt ├── LiquidCrystal_I2C.h └── LiquidCrystal_I2C.cpp /examples/HelloWorld/HelloWorld.ino: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | // Set the LCD address to 0x27 for a 16 chars and 2 line display 5 | LiquidCrystal_I2C lcd(0x27, 16, 2); 6 | 7 | void setup() 8 | { 9 | // initialize the LCD 10 | lcd.begin(); 11 | 12 | // Turn on the blacklight and print a message. 13 | lcd.backlight(); 14 | lcd.print("Hello, world!"); 15 | } 16 | 17 | void loop() 18 | { 19 | // Do nothing here... 20 | } 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Installation # 2 | Create a new folder called "LiquidCrystal_I2C" under the folder named "libraries" in your Arduino sketchbook folder. 3 | Create the folder "libraries" in case it does not exist yet. Place all the files in the "LiquidCrystal_I2C" folder. 4 | 5 | # Usage # 6 | To use the library in your own sketch, select it from *Sketch > Import Library*. 7 | 8 | ------------------------------------------------------------------------------------------------------------------- 9 | This library is based on work done by DFROBOT (www.dfrobot.com). -------------------------------------------------------------------------------- /examples/BlinkingCursor/BlinkingCursor.ino: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | // Set the LCD address to 0x27 for a 16 chars and 2 line display 5 | LiquidCrystal_I2C lcd(0x27, 16, 2); 6 | 7 | void setup() 8 | { 9 | // initialize the LCD 10 | lcd.begin(); 11 | } 12 | 13 | void loop() 14 | { 15 | bool blinking = true; 16 | lcd.cursor(); 17 | 18 | while (1) { 19 | if (blinking) { 20 | lcd.clear(); 21 | lcd.print("No cursor blink"); 22 | lcd.noBlink(); 23 | blinking = false; 24 | } else { 25 | lcd.clear(); 26 | lcd.print("Cursor blink"); 27 | lcd.blink(); 28 | blinking = true; 29 | } 30 | delay(4000); 31 | } 32 | } 33 | -------------------------------------------------------------------------------- /examples/SerialDisplay/SerialDisplay.ino: -------------------------------------------------------------------------------- 1 | /** 2 | * Displays text sent over the serial port (e.g. from the Serial Monitor) on 3 | * an attached LCD. 4 | */ 5 | #include 6 | #include 7 | 8 | // Set the LCD address to 0x27 for a 16 chars and 2 line display 9 | LiquidCrystal_I2C lcd(0x27, 16, 2); 10 | 11 | void setup() 12 | { 13 | lcd.begin(); 14 | lcd.backlight(); 15 | 16 | // Initialize the serial port at a speed of 9600 baud 17 | Serial.begin(9600); 18 | } 19 | 20 | void loop() 21 | { 22 | // If characters arrived over the serial port... 23 | if (Serial.available()) { 24 | // Wait a bit for the entire message to arrive 25 | delay(100); 26 | // Clear the screen 27 | lcd.clear(); 28 | 29 | // Write all characters received with the serial port to the LCD. 30 | while (Serial.available() > 0) { 31 | lcd.write(Serial.read()); 32 | } 33 | } 34 | } 35 | -------------------------------------------------------------------------------- /keywords.txt: -------------------------------------------------------------------------------- 1 | ########################################### 2 | # Syntax Coloring Map For LiquidCrystal_I2C 3 | ########################################### 4 | 5 | ########################################### 6 | # Datatypes (KEYWORD1) 7 | ########################################### 8 | 9 | LiquidCrystal_I2C KEYWORD1 10 | 11 | ########################################### 12 | # Methods and Functions (KEYWORD2) 13 | ########################################### 14 | init KEYWORD2 15 | begin KEYWORD2 16 | clear KEYWORD2 17 | home KEYWORD2 18 | noDisplay KEYWORD2 19 | display KEYWORD2 20 | noBlink KEYWORD2 21 | blink KEYWORD2 22 | noCursor KEYWORD2 23 | cursor KEYWORD2 24 | scrollDisplayLeft KEYWORD2 25 | scrollDisplayRight KEYWORD2 26 | leftToRight KEYWORD2 27 | rightToLeft KEYWORD2 28 | shiftIncrement KEYWORD2 29 | shiftDecrement KEYWORD2 30 | noBacklight KEYWORD2 31 | backlight KEYWORD2 32 | autoscroll KEYWORD2 33 | noAutoscroll KEYWORD2 34 | createChar KEYWORD2 35 | setCursor KEYWORD2 36 | print KEYWORD2 37 | blink_on KEYWORD2 38 | blink_off KEYWORD2 39 | cursor_on KEYWORD2 40 | cursor_off KEYWORD2 41 | setBacklight KEYWORD2 42 | load_custom_character KEYWORD2 43 | printstr KEYWORD2 44 | ########################################### 45 | # Constants (LITERAL1) 46 | ########################################### 47 | -------------------------------------------------------------------------------- /examples/CustomChars/CustomChars.ino: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | uint8_t bell[8] = {0x4, 0xe, 0xe, 0xe, 0x1f, 0x0, 0x4}; 5 | uint8_t note[8] = {0x2, 0x3, 0x2, 0xe, 0x1e, 0xc, 0x0}; 6 | uint8_t clock[8] = {0x0, 0xe, 0x15, 0x17, 0x11, 0xe, 0x0}; 7 | uint8_t heart[8] = {0x0, 0xa, 0x1f, 0x1f, 0xe, 0x4, 0x0}; 8 | uint8_t duck[8] = {0x0, 0xc, 0x1d, 0xf, 0xf, 0x6, 0x0}; 9 | uint8_t check[8] = {0x0, 0x1 ,0x3, 0x16, 0x1c, 0x8, 0x0}; 10 | uint8_t cross[8] = {0x0, 0x1b, 0xe, 0x4, 0xe, 0x1b, 0x0}; 11 | uint8_t retarrow[8] = { 0x1, 0x1, 0x5, 0x9, 0x1f, 0x8, 0x4}; 12 | 13 | // Set the LCD address to 0x27 for a 16 chars and 2 line display 14 | LiquidCrystal_I2C lcd(0x27, 16, 2); 15 | 16 | void setup() 17 | { 18 | lcd.begin(); 19 | lcd.backlight(); 20 | 21 | lcd.createChar(0, bell); 22 | lcd.createChar(1, note); 23 | lcd.createChar(2, clock); 24 | lcd.createChar(3, heart); 25 | lcd.createChar(4, duck); 26 | lcd.createChar(5, check); 27 | lcd.createChar(6, cross); 28 | lcd.createChar(7, retarrow); 29 | lcd.home(); 30 | 31 | lcd.print("Hello world..."); 32 | lcd.setCursor(0, 1); 33 | lcd.print(" i "); 34 | lcd.write(3); 35 | lcd.print(" arduinos!"); 36 | delay(5000); 37 | displayKeyCodes(); 38 | } 39 | 40 | // display all keycodes 41 | void displayKeyCodes(void) { 42 | uint8_t i = 0; 43 | 44 | while (1) { 45 | lcd.clear(); 46 | lcd.print("Codes 0x"); 47 | lcd.print(i, HEX); 48 | lcd.print("-0x"); 49 | lcd.print(i + 16, HEX); 50 | lcd.setCursor(0, 1); 51 | 52 | for (int j = 0; j < 16; j++) { 53 | lcd.write(i + j); 54 | } 55 | i += 16; 56 | 57 | delay(4000); 58 | } 59 | } 60 | 61 | void loop() 62 | { 63 | // Do nothing here... 64 | } 65 | 66 | -------------------------------------------------------------------------------- /LiquidCrystal_I2C.h: -------------------------------------------------------------------------------- 1 | #ifndef FDB_LIQUID_CRYSTAL_I2C_H 2 | #define FDB_LIQUID_CRYSTAL_I2C_H 3 | 4 | #include 5 | #include 6 | 7 | // commands 8 | #define LCD_CLEARDISPLAY 0x01 9 | #define LCD_RETURNHOME 0x02 10 | #define LCD_ENTRYMODESET 0x04 11 | #define LCD_DISPLAYCONTROL 0x08 12 | #define LCD_CURSORSHIFT 0x10 13 | #define LCD_FUNCTIONSET 0x20 14 | #define LCD_SETCGRAMADDR 0x40 15 | #define LCD_SETDDRAMADDR 0x80 16 | 17 | // flags for display entry mode 18 | #define LCD_ENTRYRIGHT 0x00 19 | #define LCD_ENTRYLEFT 0x02 20 | #define LCD_ENTRYSHIFTINCREMENT 0x01 21 | #define LCD_ENTRYSHIFTDECREMENT 0x00 22 | 23 | // flags for display on/off control 24 | #define LCD_DISPLAYON 0x04 25 | #define LCD_DISPLAYOFF 0x00 26 | #define LCD_CURSORON 0x02 27 | #define LCD_CURSOROFF 0x00 28 | #define LCD_BLINKON 0x01 29 | #define LCD_BLINKOFF 0x00 30 | 31 | // flags for display/cursor shift 32 | #define LCD_DISPLAYMOVE 0x08 33 | #define LCD_CURSORMOVE 0x00 34 | #define LCD_MOVERIGHT 0x04 35 | #define LCD_MOVELEFT 0x00 36 | 37 | // flags for function set 38 | #define LCD_8BITMODE 0x10 39 | #define LCD_4BITMODE 0x00 40 | #define LCD_2LINE 0x08 41 | #define LCD_1LINE 0x00 42 | #define LCD_5x10DOTS 0x04 43 | #define LCD_5x8DOTS 0x00 44 | 45 | // flags for backlight control 46 | #define LCD_BACKLIGHT 0x08 47 | #define LCD_NOBACKLIGHT 0x00 48 | 49 | #define En B00000100 // Enable bit 50 | #define Rw B00000010 // Read/Write bit 51 | #define Rs B00000001 // Register select bit 52 | 53 | /** 54 | * This is the driver for the Liquid Crystal LCD displays that use the I2C bus. 55 | * 56 | * After creating an instance of this class, first call begin() before anything else. 57 | * The backlight is on by default, since that is the most likely operating mode in 58 | * most cases. 59 | */ 60 | class LiquidCrystal_I2C : public Print { 61 | public: 62 | /** 63 | * Constructor 64 | * 65 | * @param lcd_addr I2C slave address of the LCD display. Most likely printed on the 66 | * LCD circuit board, or look in the supplied LCD documentation. 67 | * @param lcd_cols Number of columns your LCD display has. 68 | * @param lcd_rows Number of rows your LCD display has. 69 | * @param charsize The size in dots that the display has, use LCD_5x10DOTS or LCD_5x8DOTS. 70 | */ 71 | LiquidCrystal_I2C(uint8_t lcd_addr, uint8_t lcd_cols, uint8_t lcd_rows, uint8_t charsize = LCD_5x8DOTS); 72 | 73 | /** 74 | * Set the LCD display in the correct begin state, must be called before anything else is done. 75 | */ 76 | void begin(); 77 | 78 | /** 79 | * Remove all the characters currently shown. Next print/write operation will start 80 | * from the first position on LCD display. 81 | */ 82 | void clear(); 83 | 84 | /** 85 | * Next print/write operation will will start from the first position on the LCD display. 86 | */ 87 | void home(); 88 | 89 | /** 90 | * Do not show any characters on the LCD display. Backlight state will remain unchanged. 91 | * Also all characters written on the display will return, when the display in enabled again. 92 | */ 93 | void noDisplay(); 94 | 95 | /** 96 | * Show the characters on the LCD display, this is the normal behaviour. This method should 97 | * only be used after noDisplay() has been used. 98 | */ 99 | void display(); 100 | 101 | /** 102 | * Do not blink the cursor indicator. 103 | */ 104 | void noBlink(); 105 | 106 | /** 107 | * Start blinking the cursor indicator. 108 | */ 109 | void blink(); 110 | 111 | /** 112 | * Do not show a cursor indicator. 113 | */ 114 | void noCursor(); 115 | 116 | /** 117 | * Show a cursor indicator, cursor can blink on not blink. Use the 118 | * methods blink() and noBlink() for changing cursor blink. 119 | */ 120 | void cursor(); 121 | 122 | void scrollDisplayLeft(); 123 | void scrollDisplayRight(); 124 | void printLeft(); 125 | void printRight(); 126 | void leftToRight(); 127 | void rightToLeft(); 128 | void shiftIncrement(); 129 | void shiftDecrement(); 130 | void noBacklight(); 131 | void backlight(); 132 | bool getBacklight(); 133 | void autoscroll(); 134 | void noAutoscroll(); 135 | void createChar(uint8_t, uint8_t[]); 136 | void setCursor(uint8_t, uint8_t); 137 | virtual size_t write(uint8_t); 138 | void command(uint8_t); 139 | 140 | inline void blink_on() { blink(); } 141 | inline void blink_off() { noBlink(); } 142 | inline void cursor_on() { cursor(); } 143 | inline void cursor_off() { noCursor(); } 144 | 145 | // Compatibility API function aliases 146 | void setBacklight(uint8_t new_val); // alias for backlight() and nobacklight() 147 | void load_custom_character(uint8_t char_num, uint8_t *rows); // alias for createChar() 148 | void printstr(const char[]); 149 | 150 | private: 151 | void send(uint8_t, uint8_t); 152 | void write4bits(uint8_t); 153 | void expanderWrite(uint8_t); 154 | void pulseEnable(uint8_t); 155 | uint8_t _addr; 156 | uint8_t _displayfunction; 157 | uint8_t _displaycontrol; 158 | uint8_t _displaymode; 159 | uint8_t _cols; 160 | uint8_t _rows; 161 | uint8_t _charsize; 162 | uint8_t _backlightval; 163 | }; 164 | 165 | #endif // FDB_LIQUID_CRYSTAL_I2C_H 166 | -------------------------------------------------------------------------------- /LiquidCrystal_I2C.cpp: -------------------------------------------------------------------------------- 1 | #include "LiquidCrystal_I2C.h" 2 | #include 3 | #include 4 | #include 5 | 6 | // When the display powers up, it is configured as follows: 7 | // 8 | // 1. Display clear 9 | // 2. Function set: 10 | // DL = 1; 8-bit interface data 11 | // N = 0; 1-line display 12 | // F = 0; 5x8 dot character font 13 | // 3. Display on/off control: 14 | // D = 0; Display off 15 | // C = 0; Cursor off 16 | // B = 0; Blinking off 17 | // 4. Entry mode set: 18 | // I/D = 1; Increment by 1 19 | // S = 0; No shift 20 | // 21 | // Note, however, that resetting the Arduino doesn't reset the LCD, so we 22 | // can't assume that its in that state when a sketch starts (and the 23 | // LiquidCrystal constructor is called). 24 | 25 | LiquidCrystal_I2C::LiquidCrystal_I2C(uint8_t lcd_addr, uint8_t lcd_cols, uint8_t lcd_rows, uint8_t charsize) 26 | { 27 | _addr = lcd_addr; 28 | _cols = lcd_cols; 29 | _rows = lcd_rows; 30 | _charsize = charsize; 31 | _backlightval = LCD_BACKLIGHT; 32 | } 33 | 34 | void LiquidCrystal_I2C::begin() { 35 | Wire.begin(); 36 | _displayfunction = LCD_4BITMODE | LCD_1LINE | LCD_5x8DOTS; 37 | 38 | if (_rows > 1) { 39 | _displayfunction |= LCD_2LINE; 40 | } 41 | 42 | // for some 1 line displays you can select a 10 pixel high font 43 | if ((_charsize != 0) && (_rows == 1)) { 44 | _displayfunction |= LCD_5x10DOTS; 45 | } 46 | 47 | // SEE PAGE 45/46 FOR INITIALIZATION SPECIFICATION! 48 | // according to datasheet, we need at least 40ms after power rises above 2.7V 49 | // before sending commands. Arduino can turn on way befer 4.5V so we'll wait 50 50 | delay(50); 51 | 52 | // Now we pull both RS and R/W low to begin commands 53 | expanderWrite(_backlightval); // reset expanderand turn backlight off (Bit 8 =1) 54 | delay(1000); 55 | 56 | //put the LCD into 4 bit mode 57 | // this is according to the hitachi HD44780 datasheet 58 | // figure 24, pg 46 59 | 60 | // we start in 8bit mode, try to set 4 bit mode 61 | write4bits(0x03 << 4); 62 | delayMicroseconds(4500); // wait min 4.1ms 63 | 64 | // second try 65 | write4bits(0x03 << 4); 66 | delayMicroseconds(4500); // wait min 4.1ms 67 | 68 | // third go! 69 | write4bits(0x03 << 4); 70 | delayMicroseconds(150); 71 | 72 | // finally, set to 4-bit interface 73 | write4bits(0x02 << 4); 74 | 75 | // set # lines, font size, etc. 76 | command(LCD_FUNCTIONSET | _displayfunction); 77 | 78 | // turn the display on with no cursor or blinking default 79 | _displaycontrol = LCD_DISPLAYON | LCD_CURSOROFF | LCD_BLINKOFF; 80 | display(); 81 | 82 | // clear it off 83 | clear(); 84 | 85 | // Initialize to default text direction (for roman languages) 86 | _displaymode = LCD_ENTRYLEFT | LCD_ENTRYSHIFTDECREMENT; 87 | 88 | // set the entry mode 89 | command(LCD_ENTRYMODESET | _displaymode); 90 | 91 | home(); 92 | } 93 | 94 | /********** high level commands, for the user! */ 95 | void LiquidCrystal_I2C::clear(){ 96 | command(LCD_CLEARDISPLAY);// clear display, set cursor position to zero 97 | delayMicroseconds(2000); // this command takes a long time! 98 | } 99 | 100 | void LiquidCrystal_I2C::home(){ 101 | command(LCD_RETURNHOME); // set cursor position to zero 102 | delayMicroseconds(2000); // this command takes a long time! 103 | } 104 | 105 | void LiquidCrystal_I2C::setCursor(uint8_t col, uint8_t row){ 106 | int row_offsets[] = { 0x00, 0x40, 0x14, 0x54 }; 107 | if (row > _rows) { 108 | row = _rows-1; // we count rows starting w/0 109 | } 110 | command(LCD_SETDDRAMADDR | (col + row_offsets[row])); 111 | } 112 | 113 | // Turn the display on/off (quickly) 114 | void LiquidCrystal_I2C::noDisplay() { 115 | _displaycontrol &= ~LCD_DISPLAYON; 116 | command(LCD_DISPLAYCONTROL | _displaycontrol); 117 | } 118 | void LiquidCrystal_I2C::display() { 119 | _displaycontrol |= LCD_DISPLAYON; 120 | command(LCD_DISPLAYCONTROL | _displaycontrol); 121 | } 122 | 123 | // Turns the underline cursor on/off 124 | void LiquidCrystal_I2C::noCursor() { 125 | _displaycontrol &= ~LCD_CURSORON; 126 | command(LCD_DISPLAYCONTROL | _displaycontrol); 127 | } 128 | void LiquidCrystal_I2C::cursor() { 129 | _displaycontrol |= LCD_CURSORON; 130 | command(LCD_DISPLAYCONTROL | _displaycontrol); 131 | } 132 | 133 | // Turn on and off the blinking cursor 134 | void LiquidCrystal_I2C::noBlink() { 135 | _displaycontrol &= ~LCD_BLINKON; 136 | command(LCD_DISPLAYCONTROL | _displaycontrol); 137 | } 138 | void LiquidCrystal_I2C::blink() { 139 | _displaycontrol |= LCD_BLINKON; 140 | command(LCD_DISPLAYCONTROL | _displaycontrol); 141 | } 142 | 143 | // These commands scroll the display without changing the RAM 144 | void LiquidCrystal_I2C::scrollDisplayLeft(void) { 145 | command(LCD_CURSORSHIFT | LCD_DISPLAYMOVE | LCD_MOVELEFT); 146 | } 147 | void LiquidCrystal_I2C::scrollDisplayRight(void) { 148 | command(LCD_CURSORSHIFT | LCD_DISPLAYMOVE | LCD_MOVERIGHT); 149 | } 150 | 151 | // This is for text that flows Left to Right 152 | void LiquidCrystal_I2C::leftToRight(void) { 153 | _displaymode |= LCD_ENTRYLEFT; 154 | command(LCD_ENTRYMODESET | _displaymode); 155 | } 156 | 157 | // This is for text that flows Right to Left 158 | void LiquidCrystal_I2C::rightToLeft(void) { 159 | _displaymode &= ~LCD_ENTRYLEFT; 160 | command(LCD_ENTRYMODESET | _displaymode); 161 | } 162 | 163 | // This will 'right justify' text from the cursor 164 | void LiquidCrystal_I2C::autoscroll(void) { 165 | _displaymode |= LCD_ENTRYSHIFTINCREMENT; 166 | command(LCD_ENTRYMODESET | _displaymode); 167 | } 168 | 169 | // This will 'left justify' text from the cursor 170 | void LiquidCrystal_I2C::noAutoscroll(void) { 171 | _displaymode &= ~LCD_ENTRYSHIFTINCREMENT; 172 | command(LCD_ENTRYMODESET | _displaymode); 173 | } 174 | 175 | // Allows us to fill the first 8 CGRAM locations 176 | // with custom characters 177 | void LiquidCrystal_I2C::createChar(uint8_t location, uint8_t charmap[]) { 178 | location &= 0x7; // we only have 8 locations 0-7 179 | command(LCD_SETCGRAMADDR | (location << 3)); 180 | for (int i=0; i<8; i++) { 181 | write(charmap[i]); 182 | } 183 | } 184 | 185 | // Turn the (optional) backlight off/on 186 | void LiquidCrystal_I2C::noBacklight(void) { 187 | _backlightval=LCD_NOBACKLIGHT; 188 | expanderWrite(0); 189 | } 190 | 191 | void LiquidCrystal_I2C::backlight(void) { 192 | _backlightval=LCD_BACKLIGHT; 193 | expanderWrite(0); 194 | } 195 | bool LiquidCrystal_I2C::getBacklight() { 196 | return _backlightval == LCD_BACKLIGHT; 197 | } 198 | 199 | 200 | /*********** mid level commands, for sending data/cmds */ 201 | 202 | inline void LiquidCrystal_I2C::command(uint8_t value) { 203 | send(value, 0); 204 | } 205 | 206 | inline size_t LiquidCrystal_I2C::write(uint8_t value) { 207 | send(value, Rs); 208 | return 1; 209 | } 210 | 211 | 212 | /************ low level data pushing commands **********/ 213 | 214 | // write either command or data 215 | void LiquidCrystal_I2C::send(uint8_t value, uint8_t mode) { 216 | uint8_t highnib=value&0xf0; 217 | uint8_t lownib=(value<<4)&0xf0; 218 | write4bits((highnib)|mode); 219 | write4bits((lownib)|mode); 220 | } 221 | 222 | void LiquidCrystal_I2C::write4bits(uint8_t value) { 223 | expanderWrite(value); 224 | pulseEnable(value); 225 | } 226 | 227 | void LiquidCrystal_I2C::expanderWrite(uint8_t _data){ 228 | Wire.beginTransmission(_addr); 229 | Wire.write((int)(_data) | _backlightval); 230 | Wire.endTransmission(); 231 | } 232 | 233 | void LiquidCrystal_I2C::pulseEnable(uint8_t _data){ 234 | expanderWrite(_data | En); // En high 235 | delayMicroseconds(1); // enable pulse must be >450ns 236 | 237 | expanderWrite(_data & ~En); // En low 238 | delayMicroseconds(50); // commands need > 37us to settle 239 | } 240 | 241 | void LiquidCrystal_I2C::load_custom_character(uint8_t char_num, uint8_t *rows){ 242 | createChar(char_num, rows); 243 | } 244 | 245 | void LiquidCrystal_I2C::setBacklight(uint8_t new_val){ 246 | if (new_val) { 247 | backlight(); // turn backlight on 248 | } else { 249 | noBacklight(); // turn backlight off 250 | } 251 | } 252 | 253 | void LiquidCrystal_I2C::printstr(const char c[]){ 254 | //This function is not identical to the function used for "real" I2C displays 255 | //it's here so the user sketch doesn't have to be changed 256 | print(c); 257 | } 258 | --------------------------------------------------------------------------------