Directly pull in the i2c_lcd driver

2025-03-18 12:32:35 -05:00
parent 1343618729
commit beb7f0bfb9
3 changed files with 524 additions and 21 deletions
@@ -0,0 +1,357 @@
+/// \file i2c_lcd_pcf8574.c
+/// \brief Liquid Crystal display driver with PCF8574 adapter for esp-idf
+///
+/// \author Femi Olugbon, https://iamflinks.github.io
+/// \copyright Copyright (c) 2024 by Femi Olugbon
+///
+/// ChangeLog see: i2c_lcd_pcf8574.h
+
+#include <stdio.h>
+#include "i2c_lcd_pcf8574.h"
+#include "esp_log.h"
+#include "esp_check.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+
+#define TAG "I2C_LCD_PCF8574"
+
+#define I2C_MASTER_TIMEOUT_MS 1000
+
+
+// private functions
+static void lcd_send(i2c_lcd_pcf8574_handle_t* lcd, uint8_t value, bool is_data);
+static void lcd_write_nibble(i2c_lcd_pcf8574_handle_t* lcd, uint8_t half_byte, bool is_data, i2c_cmd_handle_t cmd);
+static void lcd_write_i2c(i2c_lcd_pcf8574_handle_t* lcd, uint8_t data, bool is_data, bool enable);
+
+void lcd_init(i2c_lcd_pcf8574_handle_t* lcd, uint8_t i2c_addr, i2c_port_t i2c_port) {
+    lcd->i2c_addr = i2c_addr;
+    lcd->i2c_port = i2c_port;
+    lcd->backlight = 0;
+    lcd->entrymode = 0x02; // Init the LCD with an internal reset
+    lcd->displaycontrol = 0x04;
+    lcd->rs_mask = 0x01;
+    lcd->rw_mask = 0x00;
+    lcd->enable_mask = 0x04;
+    lcd->data_mask[0] = 0x10;
+    lcd->data_mask[1] = 0x20;
+    lcd->data_mask[2] = 0x40;
+    lcd->data_mask[3] = 0x80;
+    lcd->backlight_mask = 0x08;
+}   // lcd_begin()
+
+void lcd_begin(i2c_lcd_pcf8574_handle_t* lcd, uint8_t cols, uint8_t rows) {
+
+    // Ensure the cols and rows stay within max limit
+    lcd->cols = (cols > 80) ? 80 : cols;
+    lcd->lines = (rows > 4) ? 4 : rows;
+
+    lcd->row_offsets[0] = 0x00;
+    lcd->row_offsets[1] = 0x40;
+    lcd->row_offsets[2] = 0x00 + cols;
+    lcd->row_offsets[3] = 0x40 + cols;
+
+    // Initialize the LCD
+    lcd_write_i2c(lcd, 0x00, false, false);
+    esp_rom_delay_us(50000);
+
+    // This follows after the reset mode
+    lcd->displaycontrol = 0x04;
+    lcd->entrymode = 0x02;
+
+    // The following are the reset sequence: Please see "Initialization instruction in the PCF8574 datasheet."
+    i2c_cmd_handle_t cmd = i2c_cmd_link_create();
+    i2c_master_start(cmd);
+    // We left-shift the device addres and add the read/write command
+    i2c_master_write_byte(cmd, (lcd->i2c_addr << 1) | I2C_MASTER_WRITE, true);
+    
+    lcd_write_nibble(lcd, 0x03, false, cmd);
+    i2c_master_stop(cmd);
+    i2c_master_cmd_begin(lcd->i2c_port, cmd, I2C_MASTER_TIMEOUT_MS / portTICK_PERIOD_MS);
+    i2c_cmd_link_delete(cmd);
+    esp_rom_delay_us(4500);
+
+    cmd = i2c_cmd_link_create();
+    i2c_master_start(cmd);
+    i2c_master_write_byte(cmd, (lcd->i2c_addr << 1) | I2C_MASTER_WRITE, true);
+    lcd_write_nibble(lcd, 0x03, false, cmd);
+    i2c_master_stop(cmd);
+    i2c_master_cmd_begin(lcd->i2c_port, cmd, I2C_MASTER_TIMEOUT_MS / portTICK_PERIOD_MS);
+    i2c_cmd_link_delete(cmd);
+    esp_rom_delay_us(200);
+
+    cmd = i2c_cmd_link_create();
+    i2c_master_start(cmd);
+    i2c_master_write_byte(cmd, (lcd->i2c_addr << 1) | I2C_MASTER_WRITE, true);
+    lcd_write_nibble(lcd, 0x03, false, cmd);
+    i2c_master_stop(cmd);
+    i2c_master_cmd_begin(lcd->i2c_port, cmd, I2C_MASTER_TIMEOUT_MS / portTICK_PERIOD_MS);
+    i2c_cmd_link_delete(cmd);
+    esp_rom_delay_us(200);
+
+    // Set the data interface to 4-bit interface (PCF8574 uses 4-bit interface)
+    cmd = i2c_cmd_link_create();
+    i2c_master_start(cmd);
+    i2c_master_write_byte(cmd, (lcd->i2c_addr << 1) | I2C_MASTER_WRITE, true);
+    lcd_write_nibble(lcd, 0x02, false, cmd);
+    i2c_master_stop(cmd);
+    i2c_master_cmd_begin(lcd->i2c_port, cmd, I2C_MASTER_TIMEOUT_MS / portTICK_PERIOD_MS);
+    i2c_cmd_link_delete(cmd);
+
+    // Instruction: function set = 0x20
+    lcd_send(lcd, 0x20 | (rows > 1 ? 0x08 : 0x00), false);
+
+    // Set the display parameters (turn on display, clear, and set left to right)
+    lcd_display(lcd);
+    lcd_clear(lcd);
+    lcd_left_to_right(lcd);
+}  // lcd_begin()
+
+// Clear the display content
+void lcd_clear(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Instruction: Clear display = 0x01
+    lcd_send(lcd, 0x01, false);
+    // Clearing the display takes a while: takes approx. 1.5ms
+    esp_rom_delay_us(1600);
+}  // lcd_clear()
+
+// Set the display to home
+void lcd_home(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Instruction: Return home = 0x02
+    lcd_send(lcd, 0x02, false);
+    // Same as clearing the display: takes approx. 1.5ms
+    esp_rom_delay_us(1600);
+}  // lcd_home()
+
+// Set the cursor to a new position.
+void lcd_set_cursor(i2c_lcd_pcf8574_handle_t* lcd, uint8_t col, uint8_t row) {
+    // Check the display boundaries
+    if (row >= lcd->lines) {
+        row = lcd->lines - 1;
+    }
+    if (col >= lcd->cols) {
+        col = lcd->cols - 1;
+    }
+    // Instruction: Set DDRAM address = 080
+    lcd_send(lcd, 0x80 | (lcd->row_offsets[row] + col), false);
+}  // lcd_set_cursor()
+
+// Turn off the display: fast operation
+void lcd_no_display(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Display Control: Display on/off control = 0x04
+    lcd->displaycontrol &= ~0x04;
+    // Instruction: Display mode: 0x08
+    lcd_send(lcd, 0x08 | lcd->displaycontrol, false);
+}  // lcd_no_display()
+
+// Turn on the display: fast operation
+void lcd_display(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Display Control: Display on/off control = 0x04
+    lcd->displaycontrol |= 0x04;
+    // Instruction: Display mode: 0x08
+    lcd_send(lcd, 0x08 | lcd->displaycontrol, false);
+}  // lcd_display()
+
+// Turn on the cursor
+void lcd_cursor(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Display Control: Cursor on/off control = 0x02
+    lcd->displaycontrol |= 0x02;
+    // Instruction: Display mode: 0x08
+    lcd_send(lcd, 0x08 | lcd->displaycontrol, false);
+}  // lcd_cursor()
+
+// Turn off the cursor
+void lcd_no_cursor(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Display Control: Cursor on/off control = 0x02
+    lcd->displaycontrol &= ~0x02;
+    // Instruction: Display mode: 0x08
+    lcd_send(lcd, 0x08 | lcd->displaycontrol, false);
+}  // lcd_no_cursor()
+
+// Turn on the blinking
+void lcd_blink(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Display Control: Blink on/off control = 0x01
+    lcd->displaycontrol |= 0x01;
+    // Instruction: Display mode: 0x08
+    lcd_send(lcd, 0x08 | lcd->displaycontrol, false);
+}  // lcd_blink()
+
+// Turn off the blinking
+void lcd_no_blink(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Display Control: Blink on/off control = 0x01
+    lcd->displaycontrol &= ~0x01;
+    // Instruction: Display mode: 0x08
+    lcd_send(lcd, 0x08 | lcd->displaycontrol, false);
+}  // lcd_no_blink()
+
+// This command will scroll the display left by one step without changing the RAM
+void lcd_scroll_display_left(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Instruction: Cursor or display shift - 0x10
+    // Instruction: Display mode: 0x08
+    // Control: Left shift control = 0x00
+    // 0x10 | 0x08 | 0x00 = 0x18
+    lcd_send(lcd, 0x18, false);
+}  // lcd_scroll_display_left()
+
+// This command will scroll the display right by one step without changing the RAM
+void lcd_scroll_display_right(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Instruction: Cursor or display shift - 0x10
+    // Instruction: Display mode: 0x08
+    // Control: Left shift control = 0x04
+    // 0x10 | 0x08 | 0x04 = 0x1C
+    lcd_send(lcd, 0x1C, false);
+}  // lcd_scroll_display_right()
+
+// Controlling the entry mode: This is for text that flows left to right
+void lcd_left_to_right(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Instruction: Entry mode set, set increment/decrement = 0x02
+    lcd->entrymode |= 0x02;
+    lcd_send(lcd, 0x04 | lcd->entrymode, false);
+}  // lcd_left_to_right()
+
+// Controlling the entry mode: This is for text that flows right to left
+void lcd_right_to_left(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Instruction: Entry mode set, clear increment/decrement = 0x02
+    lcd->entrymode &= ~0x02;
+    lcd_send(lcd, 0x04 | lcd->entrymode, false);
+}  // lcd_right_to_left()
+
+// This will justify the text to the right from the cursor
+void lcd_autoscroll(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Instruction: Entry mode set, set shift = 0x01
+    lcd->entrymode |= 0x01;
+    lcd_send(lcd, 0x04 | lcd->entrymode, false);
+}  // lcd_autoscroll()
+
+// This will justify the text to the left from the cursor
+void lcd_no_autoscroll(i2c_lcd_pcf8574_handle_t* lcd) {
+    // Instruction: Entry mode set, clear shift = 0x01
+    lcd->entrymode &= ~0x01;
+    lcd_send(lcd, 0x04 | lcd->entrymode, false);
+}  // lcd_no_autoscroll()
+
+// Setting the backlight: It can only be turn on or off.
+// Current backlight value is saved in the i2c_lcd_pcf8574_handle_t struct for further data transfers
+void lcd_set_backlight(i2c_lcd_pcf8574_handle_t* lcd, uint8_t brightness) {
+    // Place the backlight value in the lcd struct
+    lcd->backlight = brightness;
+    // Send no data
+    lcd_write_i2c(lcd, 0x00, true, false);
+}  // lcd_set_backlight()
+
+// Custom character creation: allows us to create up to 8 custom characters in the CGRAM locations
+void lcd_create_char(i2c_lcd_pcf8574_handle_t* lcd, uint8_t location, uint8_t charmap[]) {
+    location &= 0x7;  // Only 8 locations are available
+    // Set the CGRAM address
+    lcd_send(lcd, 0x40 | (location << 3), false);
+    for (int i = 0; i < 8; i++) {
+        lcd_write(lcd, charmap[i]);
+    }
+}  // lcd_create_char()
+
+// Write a byte to the LCD
+void lcd_write(i2c_lcd_pcf8574_handle_t* lcd, uint8_t value) {
+    lcd_send(lcd, value, true);
+}  // lcd_write()
+
+// Print characters to the LCD: cursor set or clear instruction must preceded this instruction, or it will write on the current text.
+void lcd_print(i2c_lcd_pcf8574_handle_t* lcd, const char* str) {
+    while (*str) {
+        lcd_write(lcd, *str++);
+    }
+}  // lcd_print()
+
+// Additional function to print numbers as formatted string
+void lcd_print_number(i2c_lcd_pcf8574_handle_t* lcd, uint8_t col, uint8_t row, uint8_t buf_len, const char *str, ...) {
+    //  Ensure the buffer length is greater than zero
+    if (buf_len == 0)
+    {
+        ESP_LOGE(TAG, "Buffer length must be greater than 0");
+    }
+
+    //  Create a buffer to hold the characters
+    char buffer[buf_len];
+
+    va_list args;
+    va_start(args, str);
+
+    int chars_written = vsniprintf(buffer, buf_len, str, args);
+
+    va_end(args);
+
+    if (chars_written < 0) {
+        ESP_LOGE(TAG, "Encoding error in vsnprintf");
+    }
+
+    if ((size_t)chars_written >= buf_len) {
+        ESP_LOGW(TAG, "Buffer overflow: %d characters needed, but only %d available", chars_written + 1, buf_len);
+    }
+
+    lcd_set_cursor(lcd, col, row);
+    lcd_print(lcd, buffer);
+    
+}  // lcd_print_number()
+
+
+// Private functions: derived from the esp32 i2c_master driver
+
+
+static void lcd_send(i2c_lcd_pcf8574_handle_t* lcd, uint8_t value, bool is_data) {
+    i2c_cmd_handle_t cmd = i2c_cmd_link_create();
+    i2c_master_start(cmd);
+    i2c_master_write_byte(cmd, (lcd->i2c_addr << 1) | I2C_MASTER_WRITE, true);
+    lcd_write_nibble(lcd, (value >> 4 & 0x0F), is_data, cmd);
+    lcd_write_nibble(lcd, (value & 0x0F), is_data, cmd);
+    i2c_master_stop(cmd);
+    esp_err_t ret = i2c_master_cmd_begin(lcd->i2c_port, cmd, I2C_MASTER_TIMEOUT_MS / portTICK_PERIOD_MS);
+    i2c_cmd_link_delete(cmd);
+    
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to send data to LCD: %s", esp_err_to_name(ret));
+    }
+}  // lcd_send()
+
+// Write a nibble / half byte with ACK
+static void lcd_write_nibble(i2c_lcd_pcf8574_handle_t* lcd, uint8_t half_byte, bool is_data, i2c_cmd_handle_t cmd) {
+
+    // Map the data to the given pin connections
+    uint8_t data = is_data ? lcd->rs_mask : 0;
+
+    // Don't use rw_mask here
+    if (lcd->backlight > 0) {
+        data |= lcd->backlight_mask;
+    }
+    // Allow arbitrary pin configuration
+    if (half_byte & 0x01) data |= lcd->data_mask[0];
+    if (half_byte & 0x02) data |= lcd->data_mask[1];
+    if (half_byte & 0x04) data |= lcd->data_mask[2];
+    if (half_byte & 0x08) data |= lcd->data_mask[3];
+
+    i2c_master_write_byte(cmd, data | lcd->enable_mask, true);
+    i2c_master_write_byte(cmd, data, true);
+}  // lcd_write_nibble()
+
+// Private function to change the PCF8574 pins to the given value.
+static void lcd_write_i2c(i2c_lcd_pcf8574_handle_t* lcd, uint8_t data, bool is_data, bool enable) {
+    if (is_data) {
+        data |= lcd->rs_mask;
+    }
+    if (enable) {
+        data |= lcd->enable_mask;
+    }
+    if (lcd->backlight > 0) {
+        data |= lcd->backlight_mask;
+    }
+
+    i2c_cmd_handle_t cmd = i2c_cmd_link_create();
+    i2c_master_start(cmd);
+    i2c_master_write_byte(cmd, (lcd->i2c_addr << 1) | I2C_MASTER_WRITE, true);
+    i2c_master_write_byte(cmd, data, true);
+    i2c_master_stop(cmd);
+    esp_err_t ret = i2c_master_cmd_begin(lcd->i2c_port, cmd, I2C_MASTER_TIMEOUT_MS / portTICK_PERIOD_MS);
+    i2c_cmd_link_delete(cmd);
+
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to write to LCD: %s", esp_err_to_name(ret));
+    }
+}  // lcd_write_i2c()
@@ -0,0 +1,112 @@
+/// \file i2c_lcd_pcf8574.h
+/// \brief Liquid Crystal display driver with PCF8574 adapter for esp-idf
+///
+/// \author Femi Olugbon, https://iamflinks.github.io
+/// \copyright Copyright (c) 2024 by Femi Olugbon
+///
+/// The library work is lincensed under a BSD style license.
+///
+/// \details
+/// This library can drive a LCD based on the Hitachi's HD44790 display chip that is wired through a PCF8574 I2C converter. It uses the esp-idf i2c_driver component for communication. The library was adapted from the LiquidCrystal_PCF8574 (Mathias Hertel) and LiquidCrystal_I2C Arduino libraries.
+///
+///
+/// ChangeLog:
+/// ===========
+/// * 07/22/2024 --> Created
+/// * 07/23/2024 --> Added number printing functionality
+///
+
+#pragma once
+
+#ifndef I2C_LCD_PCF8574_H
+#define I2C_LCD_PCF8574_H
+
+#include <stdint.h>
+#include <stdbool.h>
+#include "esp_err.h"
+#include "driver/i2c.h"
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define LCD_MAX_ROWS 4
+
+typedef struct
+{
+    uint8_t i2c_addr;
+    uint8_t backlight;
+    uint8_t cols;
+    uint8_t lines;
+    uint8_t entrymode;
+    uint8_t displaycontrol;
+    uint8_t row_offsets[LCD_MAX_ROWS];
+    uint8_t rs_mask;
+    uint8_t rw_mask;
+    uint8_t enable_mask;
+    uint8_t backlight_mask;
+    uint8_t data_mask[4];
+    i2c_port_t i2c_port;
+} i2c_lcd_pcf8574_handle_t;
+
+
+// Initialize the LCD
+void lcd_init(i2c_lcd_pcf8574_handle_t* lcd, uint8_t i2c_addr, i2c_port_t i2c_port);
+
+// Begin using the LCD
+void lcd_begin(i2c_lcd_pcf8574_handle_t* lcd, uint8_t cols, uint8_t rows);
+
+// Clear the LCD
+void lcd_clear(i2c_lcd_pcf8574_handle_t* lcd);
+
+// Move cursor to home position
+void lcd_home(i2c_lcd_pcf8574_handle_t* lcd);
+
+// Set cursor position
+void lcd_set_cursor(i2c_lcd_pcf8574_handle_t* lcd, uint8_t col, uint8_t row);
+
+// Turn the display on/off
+void lcd_no_display(i2c_lcd_pcf8574_handle_t* lcd);
+void lcd_display(i2c_lcd_pcf8574_handle_t* lcd);
+
+// Turn the cursor on/off
+void lcd_cursor(i2c_lcd_pcf8574_handle_t* lcd);
+void lcd_no_cursor(i2c_lcd_pcf8574_handle_t* lcd);
+
+// Turn blinking cursor on/off
+void lcd_blink(i2c_lcd_pcf8574_handle_t* lcd);
+void lcd_no_blink(i2c_lcd_pcf8574_handle_t* lcd);
+
+// Scroll the display
+void lcd_scroll_display_left(i2c_lcd_pcf8574_handle_t* lcd);
+void lcd_scroll_display_right(i2c_lcd_pcf8574_handle_t* lcd);
+
+// Set the direction for text that flows automatically
+void lcd_left_to_right(i2c_lcd_pcf8574_handle_t* lcd);
+void lcd_right_to_left(i2c_lcd_pcf8574_handle_t* lcd);
+
+// Turn on/off autoscroll
+void lcd_autoscroll(i2c_lcd_pcf8574_handle_t* lcd);
+void lcd_no_autoscroll(i2c_lcd_pcf8574_handle_t* lcd);
+
+// Set backlight brightness
+void lcd_set_backlight(i2c_lcd_pcf8574_handle_t* lcd, uint8_t brightness);
+
+// Create a custom character
+void lcd_create_char(i2c_lcd_pcf8574_handle_t* lcd, uint8_t location, uint8_t charmap[]);
+
+// Write a character to the LCD
+void lcd_write(i2c_lcd_pcf8574_handle_t* lcd, uint8_t value);
+
+// Print a string to the LCD
+void lcd_print(i2c_lcd_pcf8574_handle_t* lcd, const char* str);
+
+void lcd_print_number(i2c_lcd_pcf8574_handle_t* lcd, uint8_t col, uint8_t row, uint8_t buf_len, const char *str, ...);
+
+
+#ifdef __cplusplus
+}
+#endif // C++ extern
+
+#endif // I2C_LCD_PCF8574_H