Merge pull request #10 from hasenradball/develop

Release v0.3.0

.github/workflows/compile_examples.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-        - uses: actions/checkout@v3
+        - uses: actions/checkout@v4
         - uses: arduino/compile-sketches@v1
           with:
             libraries: |

README.md

@@ -60,3 +60,7 @@ This library is licensed under MIT Licence.
 # Helpful Links
 [Wikipedia - a great description of HD44780 module](https://de.wikipedia.org/wiki/HD44780)
 
+[How to Initialize LCD correctly](https://web.alfredstate.edu/faculty/weimandn/lcd/lcd_initialization/lcd_initialization_index.html)
+
+[LCD Addressing](https://web.alfredstate.edu/faculty/weimandn/lcd/lcd_addressing/lcd_addressing_index.html)
+

examples/Custom_Chars/Custom_Chars.ino

@@ -61,8 +61,7 @@ uint8_t snow[8] =
     0b10000
 };
 
-void setup()
-{
+void setup() {
     lcd.begin();
     lcd.display();
     lcd.backlight();
@@ -79,6 +78,5 @@ void setup()
     lcd.write(3);
 }
 
-void loop()
-{
+void loop() {
 }

examples/write_character_codes/write_character_codes.ino

@@ -0,0 +1,40 @@
+/*
+*	write_character_codes.ino
+*
+*	Author: Frank Häfele
+*	Date:	03.05.2024
+*
+*	Object: print characters from code table
+*/
+
+#include <LCD-I2C.h>
+
+
+LCD_I2C lcd(0x27, 16, 2); // Default address of most PCF8574 modules, change according
+
+void setup() {
+  // If you are using more I2C devices using the Wire library use lcd.begin(false)
+  // this stop the library(LCD-I2C) from calling Wire.begin()
+  lcd.begin();
+  lcd.display();
+  lcd.backlight();
+}
+
+void loop() {
+  // write som character code from ROM code A00
+  lcd.setCursor(0, 1);
+  lcd.print("print characters");
+  lcd.setCursor(0, 0);
+  // writes a H
+  lcd.writeCharCode(0b01001000);
+  delay(1000);
+
+  // writes a degree sign
+  lcd.writeCharCode(0b11011111);
+  delay(1000);
+
+  // writes a question mark
+  lcd.writeCharCode(0b00111111);
+  delay(1000);
+
+}

keywords.txt

@@ -38,12 +38,26 @@ setCursor           KEYWORD2
 ##################################
 # Constants (LITERAL1)
 ##################################
-HD44780_CLEAR                   LITERAL1
-HD44780_CLEAR                   LITERAL1
-HD44780_HOME                    LITERAL1
-HD44780_ENTRY_MODE_SET          LITERAL1
-HD44780_DISPLAY_CONTROL         LITERAL1
-HD44780_CURSOR_OR_DISPLAY_SHIFT LITERAL1
-HD44780_FUNCTION_SET            LITERAL1
-HD44780_SET_CGRAM_ADDR          LITERAL1
-HD44780_SET_DDRRAM_ADDR         LITERAL1
+HD44780_CLEAR_DISPLAY               LITERAL1
+HD44780_CURSOR_HOME                 LITERAL1
+HD44780_ENTRY_MODE_SET              LITERAL1
+HD44780_ACCOMPANIES_DISPLAY_SHIFT	LITERAL1
+HD44780_ENTRY_SHIFTINCREMENT		LITERAL1
+HD44780_ENTRY_SHIFTDECREMENT		LITERAL1
+HD44780_DISPLAY_CONTROL				LITERAL1
+HD44780_BLINK_ON					LITERAL1
+HD44780_CURSOR_ON					LITERAL1
+HD44780_DISPLAY_ON					LITERAL1
+HD44780_CURSOR_OR_DISPLAY_SHIFT		LITERAL1
+HD44780_SHIFT_RIGHT					LITERAL1
+HD44780_DISPLAY_SHIFT				LITERAL1
+HD44780_CURSOR_MOVE					LITERAL1
+HD44780_FUNCTION_SET				LITERAL1 
+HD44780_5x10_DOTS					LITERAL1
+HD44780_5x8_DOTS					LITERAL1
+HD44780_2_LINE						LITERAL1
+HD44780_1_LINE						LITERAL1
+HD44780_8_BIT_MODE					LITERAL1
+HD44780_4_BIT_MODE					LITERAL1
+HD44780_SET_CGRAM_ADDR				LITERAL1
+HD44780_SET_DDRRAM_ADDR				LITERAL1

library.json

@@ -1,6 +1,6 @@
 {
     "name": "LCD-I2C",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "repository":
     {
         "type": "git",

library.properties

@@ -1,5 +1,5 @@
 name=LCD-I2C
-version=0.2.0
+version=0.3.0
 author=Frank Häfele <[email protected]>
 maintainer=Frank Häfele <[email protected]>
 sentence=C++ Library for Liquid Crystal Displays (LCD) with the Hitachi HD44780 display driver.

src/LCD-I2C.cpp

@@ -22,19 +22,19 @@ void LCD_I2C::begin(bool beginWire) {
  * 
  */
 void LCD_I2C::backlight() {
-    _output.Led = 1;
+    _output.led = 1;
     // Led pin is independent from LCD data and control lines.
-    I2C_Write(0b00000000 | _output.Led << 3);
+    I2C_Write(0b00000000 | _output.led << 3);
 }
 
 /**
  * @brief switch backlight off
  * 
  */
 void LCD_I2C::backlightOff() {
-    _output.Led = 0;
+    _output.led = 0;
     // Led pin is independent from LCD data and control lines.
-    I2C_Write(0b00000000 | _output.Led << 3); 
+    I2C_Write(0b00000000 | _output.led << 3); 
 }
 
 /**
@@ -74,7 +74,7 @@ void LCD_I2C::leftToRight() {
     _output.rs = 0;
     _output.rw = 0;
 
-    _entryState |= (1 << 1);
+    _entryState |= HD44780_ENTRY_SHIFTINCREMENT;
 
     LCD_Write(HD44780_ENTRY_MODE_SET | _entryState);
     delayMicroseconds(37);
@@ -91,7 +91,7 @@ void LCD_I2C::rightToLeft() {
     _output.rs = 0;
     _output.rw = 0;
 
-    _entryState &= ~(1 << 1);
+    _entryState &= ~HD44780_ENTRY_SHIFTINCREMENT;
 
     LCD_Write(HD44780_ENTRY_MODE_SET | _entryState);
     delayMicroseconds(37);
@@ -110,7 +110,7 @@ void LCD_I2C::autoscroll() {
     _output.rs = 0;
     _output.rw = 0;
 
-    _entryState |= 1;
+    _entryState |= HD44780_ACCOMPANIES_DISPLAY_SHIFT;
 
     LCD_Write(HD44780_ENTRY_MODE_SET | _entryState);
     delayMicroseconds(37);
@@ -126,7 +126,7 @@ void LCD_I2C::autoscrollOff() {
     _output.rs = 0;
     _output.rw = 0;
 
-    _entryState &= ~1;
+    _entryState &= ~HD44780_ACCOMPANIES_DISPLAY_SHIFT;
 
     LCD_Write(HD44780_ENTRY_MODE_SET | _entryState);
     delayMicroseconds(37);
@@ -142,7 +142,7 @@ void LCD_I2C::display() {
     _output.rs = 0;
     _output.rw = 0;
 
-    _displayState |= (1 << 2);
+    _displayState |= HD44780_DISPLAY_ON;
 
     LCD_Write(HD44780_DISPLAY_CONTROL | _displayState);
     delayMicroseconds(37);
@@ -157,7 +157,7 @@ void LCD_I2C::displayOff() {
     _output.rs = 0;
     _output.rw = 0;
 
-    _displayState &= ~(1 << 2);
+    _displayState &= ~HD44780_DISPLAY_ON;
 
     LCD_Write(HD44780_DISPLAY_CONTROL | _displayState);
     delayMicroseconds(37);
@@ -172,7 +172,7 @@ void LCD_I2C::cursor() {
     _output.rs = 0;
     _output.rw = 0;
 
-    _displayState |= (1 << 1);
+    _displayState |= HD44780_CURSOR_ON;
 
     LCD_Write(HD44780_DISPLAY_CONTROL | _displayState);
     delayMicroseconds(37);
@@ -187,7 +187,7 @@ void LCD_I2C::cursorOff() {
     _output.rs = 0;
     _output.rw = 0;
 
-    _displayState &= ~(1 << 1);
+    _displayState &= ~HD44780_CURSOR_ON;
 
     LCD_Write(HD44780_DISPLAY_CONTROL | _displayState);
     delayMicroseconds(37);
@@ -203,7 +203,7 @@ void LCD_I2C::blink() {
     _output.rs = 0;
     _output.rw = 0;
 
-    _displayState |= 1;
+    _displayState |= HD44780_BLINK_ON;
 
     LCD_Write(HD44780_DISPLAY_CONTROL | _displayState);
     delayMicroseconds(37);
@@ -218,7 +218,7 @@ void LCD_I2C::blinkOff() {
     _output.rs = 0;
     _output.rw = 0;
 
-    _displayState &= ~1;
+    _displayState &= ~HD44780_BLINK_ON;
 
     LCD_Write(HD44780_DISPLAY_CONTROL | _displayState);
     delayMicroseconds(37);
@@ -327,28 +327,43 @@ void LCD_I2C::InitializeLCD() {
     // wait more than 40 ms after Vcc = 2.7 V
     delay(50);
 
-    // first
+    // first - 0x30
     LCD_Write(0b00110000, true);
     delayMicroseconds(4200);
-    // second
+    // second - 0x30
     LCD_Write(0b00110000, true);
     delayMicroseconds(150);
-    // third
+    // third - 0x30
     LCD_Write(0b00110000, true);
     delayMicroseconds(37);
 
-    // Function Set - 4 bits mode
+    // Function Set - 4 bits mode write 0x20
     LCD_Write(0b00100000, true);
     delayMicroseconds(37);
-    // Function Set  - 4 bit Interface, 1 = 2 lines, 0 = 5x8 font
-    LCD_Write(0b00101000);
+
+    // Setup Display Function Set  - 4 bit Interface, 1 = 2 lines, 0 = 5x8 font
+    LCD_Write(HD44780_FUNCTION_SET | HD44780_4_BIT_MODE | HD44780_2_LINE | HD44780_5x8_DOTS);
     delayMicroseconds(37);
 
     displayOff();
     clear();
     leftToRight();
 }
 
+/**
+ * @brief write character code from corresponding code table
+ * 
+ * see HD44780.pdf => page 17
+ * 
+ * @param output 
+ */
+void LCD_I2C::writeCharCode(uint8_t code) {
+    _output.rs = 1;
+    LCD_Write(code);
+    delayMicroseconds(37);
+}
+
+
 /**
  * @brief I²C write function
  * 
@@ -369,25 +384,25 @@ void LCD_I2C::I2C_Write(uint8_t output) {
 void LCD_I2C::LCD_Write(uint8_t output, bool initialization) {
     _output.data = output;
 
-    _output.E = true;
+    _output.en = true;
     I2C_Write(_output.GetHighData());
     // High part of enable should be > 450 ns
     delayMicroseconds(1);
 
-    _output.E = false;
+    _output.en = false;
     I2C_Write(_output.GetHighData());
 
     // During initialization we only send half a byte
     if (!initialization) {
         // I think we need a delay between half byte writes, but no sure how long it needs to be.
         delayMicroseconds(37);
 
-        _output.E = true;
+        _output.en = true;
         I2C_Write(_output.GetLowData());
         // High part of enable should be > 450 ns
         delayMicroseconds(1); 
 
-        _output.E = false;
+        _output.en = false;
         I2C_Write(_output.GetLowData());
     }
 }

src/LCD-I2C.h

@@ -10,27 +10,32 @@
    while the other 4 bits are for the 8 bits of data which are send in parts using the enable output.
 */
 struct OutputState {
+    // Select register
+    // 0: instruction register
+    // 1: data register
     uint8_t rs = 0;
+    // select read or write
     uint8_t rw = 0;
-    uint8_t E = 0;
-    uint8_t Led = 0;
+    // Enable: starts data read or write
+    uint8_t en = 0;
+    // LED status
+    uint8_t led = 0;
     uint8_t data = 0;
 
     uint8_t GetLowData() {
         uint8_t buffer = rs;
         buffer |= rw << 1;
-        buffer |= E << 2;
-        buffer |= Led << 3;
+        buffer |= en << 2;
+        buffer |= led << 3;
         buffer |= (data & 0x0F) << 4;
-
         return buffer;
     }
 
     uint8_t GetHighData() {
         uint8_t buffer = rs;
         buffer |= rw << 1;
-        buffer |= E << 2;
-        buffer |= Led << 3;
+        buffer |= en << 2;
+        buffer |= led << 3;
         buffer |= (data & 0xF0);
         return buffer;
     }
@@ -61,6 +66,7 @@ class LCD_I2C : public Print {
         void scrollDisplayRight();
         void createChar(uint8_t memory_location, uint8_t charmap[]);
         void setCursor(uint8_t column, uint8_t row);
+        void writeCharCode(uint8_t code);
         // Method used by the Arduino class "Print" which is the one that provides the .print(string) method
         virtual size_t write(uint8_t character);