aZholtikov/zh_160x_i2c
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: updated commits

Browse Source
This commit is contained in:
aZholtikov committed 2026-10-10 09:22:34 +03:00
1 parent 04ce9746b1
commit 9696b8a0fe
3 files changed
+70 -59
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
-2
View File
@@ -15,8 +15,6 @@ Enable the following settings in menuconfig:
```text ```text
CONFIG_FREERTOS_HZ=1000 CONFIG_FREERTOS_HZ=1000
CONFIG_I2C_ISR_IRAM_SAFE
CONFIG_I2C_MASTER_ISR_HANDLER_IN_IRAM
``` ```
## Using ## Using
include/zh_160x_i2c.h
+49 -40
View File
@@ -13,6 +13,10 @@
* - Text, integer, and floating-point number printing * - Text, integer, and floating-point number printing
* - Custom progress bar rendering * - Custom progress bar rendering
* - Cursor visibility and blink control * - Cursor visibility and blink control
*
* @note All display operations require an initialized handle obtained through zh_160x_init().
* @note The text position counter of the HD44780 controller is shared by all rows,
* so row addresses are remapped internally.
*/ */
#pragma once #pragma once
@@ -37,9 +41,9 @@ extern "C"
*/ */
typedef enum typedef enum
{ {
ZH_LCD_16X2 = 0, /*!< LCD size 16x2 */ ZH_LCD_16X2, /*!< LCD size 16x2 */
ZH_LCD_16X4, /*!< LCD size 16x4 */ ZH_LCD_16X4, /*!< LCD size 16x4 */
ZH_LCD_NUM_MAX ZH_LCD_NUM_MAX /*!< Number of supported LCD sizes */
} zh_160x_i2c_lcd_size_t; } zh_160x_i2c_lcd_size_t;
/** /**
@@ -49,13 +53,13 @@ extern "C"
* sequence to the LCD controller via the PCF8574 I2C expander. * sequence to the LCD controller via the PCF8574 I2C expander.
* Configures 4-bit mode and sets default display parameters. * Configures 4-bit mode and sets default display parameters.
* *
* @param[in] expander Pointer to the PCF8574 expander handle (must not be NULL) * @param[in] expander Pointer to the PCF8574 expander handle pointer (must not be NULL and must point to a non-NULL handle)
* @param[out] handle Output pointer for the newly allocated LCD handle (must be NULL) * @param[out] handle Pointer to the output LCD handle pointer (must not be NULL and must point to a NULL pointer)
* @param[in] size LCD size (ZH_LCD_16X2 or ZH_LCD_16X4) * @param[in] size LCD size configuration (must be < ZH_LCD_NUM_MAX)
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_ERR_INVALID_ARG if any parameter is NULL or size is invalid * @return ESP_ERR_INVALID_ARG if any parameter pointer is NULL or size is invalid
* @return ESP_ERR_INVALID_STATE if the handle is already initialized * @return ESP_ERR_INVALID_STATE if the output pointer already holds an initialized handle
* @return ESP_ERR_NO_MEM if memory allocation fails * @return ESP_ERR_NO_MEM if memory allocation fails
* @return ESP_FAIL if LCD initialization sequence fails * @return ESP_FAIL if LCD initialization sequence fails
*/ */
@@ -70,7 +74,7 @@ extern "C"
* @param[in,out] handle Pointer to the LCD handle (must not be NULL) * @param[in,out] handle Pointer to the LCD handle (must not be NULL)
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_ERR_INVALID_ARG if handle is NULL * @return ESP_ERR_INVALID_ARG if handle pointer is NULL or points to a NULL handle
*/ */
esp_err_t zh_160x_deinit(zh_160x_i2c_handle_t **handle); esp_err_t zh_160x_deinit(zh_160x_i2c_handle_t **handle);
@@ -80,10 +84,10 @@ extern "C"
* Sends the LCD clear command (0x01) to erase all displayed text * Sends the LCD clear command (0x01) to erase all displayed text
* and reset the cursor to the upper-left corner (row 0, column 0). * and reset the cursor to the upper-left corner (row 0, column 0).
* *
* @param[in] handle Pointer to the LCD handle (must not be NULL) * @param[in] handle Pointer to the LCD handle pointer (must not be NULL and must point to a non-NULL handle)
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_ERR_INVALID_ARG if handle is NULL * @return ESP_ERR_INVALID_ARG if handle pointer is NULL or points to a NULL handle
* @return ESP_FAIL if sending the command fails * @return ESP_FAIL if sending the command fails
*/ */
esp_err_t zh_160x_lcd_clear(zh_160x_i2c_handle_t **handle); esp_err_t zh_160x_lcd_clear(zh_160x_i2c_handle_t **handle);
@@ -95,12 +99,12 @@ extern "C"
* For 16x2 displays: rows 0–1, columns 0–15. * For 16x2 displays: rows 0–1, columns 0–15.
* For 16x4 displays: rows 0–3, columns 0–15. * For 16x4 displays: rows 0–3, columns 0–15.
* *
* @param[in] handle Pointer to the LCD handle (must not be NULL) * @param[in] handle Pointer to the LCD handle pointer (must not be NULL and must point to a non-NULL handle)
* @param[in] row Row number (0 to 1 for 16x2, 0 to 3 for 16x4) * @param[in] row Row number (must be < 2 for 16x2 and < 4 for 16x4)
* @param[in] col Column number (0–15) * @param[in] col Column number (must be < 16)
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_ERR_INVALID_ARG if handle is NULL or coordinates are out of range * @return ESP_ERR_INVALID_ARG if any parameter pointer is NULL or coordinates are out of range
* @return ESP_FAIL if sending the command fails * @return ESP_FAIL if sending the command fails
* *
* @note Row address mapping: row 0 = 0x00, row 1 = 0x40, * @note Row address mapping: row 0 = 0x00, row 1 = 0x40,
@@ -114,11 +118,11 @@ extern "C"
* Transmits each character of the null-terminated string to the LCD * Transmits each character of the null-terminated string to the LCD
* in 4-bit mode. The cursor advances automatically after each character. * in 4-bit mode. The cursor advances automatically after each character.
* *
* @param[in] handle Pointer to the LCD handle (must not be NULL) * @param[in] handle Pointer to the LCD handle pointer (must not be NULL and must point to a non-NULL handle)
* @param[in] str Null-terminated string to display (must not be NULL) * @param[in] str Null-terminated string to display (must not be NULL)
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_ERR_INVALID_ARG if handle or str is NULL * @return ESP_ERR_INVALID_ARG if any parameter is NULL or handle points to a NULL handle
* @return ESP_FAIL if any character transmission fails * @return ESP_FAIL if any character transmission fails
*/ */
esp_err_t zh_160x_print_char(zh_160x_i2c_handle_t **handle, const char *str); esp_err_t zh_160x_print_char(zh_160x_i2c_handle_t **handle, const char *str);
@@ -127,13 +131,14 @@ extern "C"
* @brief Prints an integer to the LCD at the current cursor position. * @brief Prints an integer to the LCD at the current cursor position.
* *
* Converts the integer to a decimal string and displays it. * Converts the integer to a decimal string and displays it.
* Supports negative numbers (maximum 11 digits plus sign). * Supports the full range of signed 32-bit values
* (maximum 10 digits plus an optional sign).
* *
* @param[in] handle Pointer to the LCD handle (must not be NULL) * @param[in] handle Pointer to the LCD handle pointer (must not be NULL and must point to a non-NULL handle)
* @param[in] num Integer value to display * @param[in] num Integer value to display
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_ERR_INVALID_ARG if handle is NULL * @return ESP_ERR_INVALID_ARG if handle pointer is NULL or points to a NULL handle
* @return ESP_FAIL if string conversion or printing fails * @return ESP_FAIL if string conversion or printing fails
*/ */
esp_err_t zh_160x_print_int(zh_160x_i2c_handle_t **handle, int num); esp_err_t zh_160x_print_int(zh_160x_i2c_handle_t **handle, int num);
@@ -141,15 +146,16 @@ extern "C"
/** /**
* @brief Prints a floating-point number to the LCD at the current cursor position. * @brief Prints a floating-point number to the LCD at the current cursor position.
* *
* Converts the floating-point value to a string with the specified * Converts the floating-point value to a decimal string with the
* decimal precision and displays it. * specified number of decimal places and displays it. The converted
* text must fit into an internal 16-character buffer.
* *
* @param[in] handle Pointer to the LCD handle (must not be NULL) * @param[in] handle Pointer to the LCD handle pointer (must not be NULL and must point to a non-NULL handle)
* @param[in] num Floating-point value to display * @param[in] num Floating-point value to display
* @param[in] precision Number of decimal places (0–6 recommended) * @param[in] precision Number of decimal places passed to snprintf (0–6 recommended)
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_ERR_INVALID_ARG if handle is NULL * @return ESP_ERR_INVALID_ARG if handle pointer is NULL or points to a NULL handle
* @return ESP_FAIL if string conversion or printing fails * @return ESP_FAIL if string conversion or printing fails
*/ */
esp_err_t zh_160x_print_float(zh_160x_i2c_handle_t **handle, float num, uint8_t precision); esp_err_t zh_160x_print_float(zh_160x_i2c_handle_t **handle, float num, uint8_t precision);
@@ -157,16 +163,19 @@ extern "C"
/** /**
* @brief Displays a progress bar on a specific row of the LCD. * @brief Displays a progress bar on a specific row of the LCD.
* *
* Renders a 16-block progress bar using custom character (0xFF). * Renders a 16-block progress bar where filled blocks represent the
* Filled blocks represent the progress percentage, empty blocks show remaining. * progress percentage and empty blocks show the remainder. Filled
* blocks are printed as byte 0xFF, which displays as a solid block
* only when DDRAM location 0xFF is configured as a custom character
* (CGRAM pattern 7 on HD44780 controllers).
* Leaves the cursor at the end of the row.
* *
* @param[in] handle Pointer to the LCD handle (must not be NULL) * @param[in] handle Pointer to the LCD handle pointer (must not be NULL and must point to a non-NULL handle)
* @param[in] row Row number (0 to 1 for 16x2, 0 to 3 for 16x4) * @param[in] row Row number (must be < 2 for 16x2 and < 4 for 16x4)
* @param[in] progress Progress percentage (0–100) * @param[in] progress Progress percentage (must be <= 100)
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_ERR_INVALID_ARG if handle is NULL, row is out of range, * @return ESP_ERR_INVALID_ARG if any parameter pointer is NULL, row is out of range, or progress exceeds 100
* or progress exceeds 100
* @return ESP_FAIL if cursor positioning or character printing fails * @return ESP_FAIL if cursor positioning or character printing fails
*/ */
esp_err_t zh_160x_print_progress_bar(zh_160x_i2c_handle_t **handle, uint8_t row, uint8_t progress); esp_err_t zh_160x_print_progress_bar(zh_160x_i2c_handle_t **handle, uint8_t row, uint8_t progress);
@@ -178,11 +187,11 @@ extern "C"
* all 16 positions with spaces to erase existing content. * all 16 positions with spaces to erase existing content.
* Leaves the cursor at the start of the cleared row. * Leaves the cursor at the start of the cleared row.
* *
* @param[in] handle Pointer to the LCD handle (must not be NULL) * @param[in] handle Pointer to the LCD handle pointer (must not be NULL and must point to a non-NULL handle)
* @param[in] row Row number (0 to 1 for 16x2, 0 to 3 for 16x4) * @param[in] row Row number (must be < 2 for 16x2 and < 4 for 16x4)
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_ERR_INVALID_ARG if handle is NULL or row is out of range * @return ESP_ERR_INVALID_ARG if any parameter pointer is NULL or row is out of range
* @return ESP_FAIL if cursor positioning or character printing fails * @return ESP_FAIL if cursor positioning or character printing fails
*/ */
esp_err_t zh_160x_clear_row(zh_160x_i2c_handle_t **handle, uint8_t row); esp_err_t zh_160x_clear_row(zh_160x_i2c_handle_t **handle, uint8_t row);
@@ -193,11 +202,11 @@ extern "C"
* Turns on the cursor and optionally enables blinking. * Turns on the cursor and optionally enables blinking.
* Command 0x0F enables cursor with blink, 0x0E enables cursor only. * Command 0x0F enables cursor with blink, 0x0E enables cursor only.
* *
* @param[in] handle Pointer to the LCD handle (must not be NULL) * @param[in] handle Pointer to the LCD handle pointer (must not be NULL and must point to a non-NULL handle)
* @param[in] blink If true, enables blinking cursor; if false, solid cursor * @param[in] blink Enable cursor blink mode
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_ERR_INVALID_ARG if handle is NULL * @return ESP_ERR_INVALID_ARG if handle pointer is NULL or points to a NULL handle
* @return ESP_FAIL if sending the command fails * @return ESP_FAIL if sending the command fails
*/ */
esp_err_t zh_160x_on_cursor(zh_160x_i2c_handle_t **handle, bool blink); esp_err_t zh_160x_on_cursor(zh_160x_i2c_handle_t **handle, bool blink);
@@ -207,10 +216,10 @@ extern "C"
* *
* Sends command 0x0C to turn off both cursor and cursor blink. * Sends command 0x0C to turn off both cursor and cursor blink.
* *
* @param[in] handle Pointer to the LCD handle (must not be NULL) * @param[in] handle Pointer to the LCD handle pointer (must not be NULL and must point to a non-NULL handle)
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_ERR_INVALID_ARG if handle is NULL * @return ESP_ERR_INVALID_ARG if handle pointer is NULL or points to a NULL handle
* @return ESP_FAIL if sending the command fails * @return ESP_FAIL if sending the command fails
*/ */
esp_err_t zh_160x_off_cursor(zh_160x_i2c_handle_t **handle); esp_err_t zh_160x_off_cursor(zh_160x_i2c_handle_t **handle);
zh_160x_i2c.c
+21 -17
View File
@@ -18,6 +18,9 @@ static const char *TAG = "zh_160x_i2c";
* *
* Internal handle containing the PCF8574 expander pointer and * Internal handle containing the PCF8574 expander pointer and
* the configured LCD size for row address calculations. * the configured LCD size for row address calculations.
*
* @warning The expander handle is owned by the caller and must remain valid
* until the LCD handle is deinitialized.
*/ */
struct _zh_160x_i2c_handle_t struct _zh_160x_i2c_handle_t
{ {
@@ -25,6 +28,8 @@ struct _zh_160x_i2c_handle_t
zh_160x_i2c_lcd_size_t zh_160x_i2c_lcd_size; /*!< Configured LCD size (16x2 or 16x4) */ zh_160x_i2c_lcd_size_t zh_160x_i2c_lcd_size; /*!< Configured LCD size (16x2 or 16x4) */
}; };
static const uint8_t _lcd_row_addresses[] = {0x00, 0x40, 0x10, 0x50};
/** /**
* @brief Initialize the LCD 160x display. * @brief Initialize the LCD 160x display.
* *
@@ -35,49 +40,53 @@ struct _zh_160x_i2c_handle_t
* @param handle Pointer to the 160x I2C handle * @param handle Pointer to the 160x I2C handle
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_FAIL if error * @return ESP_FAIL if any expander write or pulse operation fails
*/ */
static esp_err_t _zh_160x_lcd_init(zh_160x_i2c_handle_t *handle); static esp_err_t _zh_160x_lcd_init(zh_160x_i2c_handle_t *handle);
/** /**
* @brief Send a command to the LCD. * @brief Send a command to the LCD.
* *
* Transmits a command byte to the LCD in 4-bit mode. * Transmits a command byte to the LCD in 4-bit mode. The high and low
* RS pin is set to low (0x08) to indicate command mode. * nibbles are sent sequentially on data lines D4-D7 (PCF8574 pins P4-P7),
* each followed by an enable pulse. Bit mask 0x08 keeps pin P3 high;
* RS (pin P0) and E (pin P2) are held low between pulses.
* *
* @param handle Pointer to the 160x I2C handle * @param handle Pointer to the 160x I2C handle
* @param command Command byte to send * @param command Command byte to send
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_FAIL if error * @return ESP_FAIL if any expander write or pulse operation fails
*/ */
static esp_err_t _zh_160x_send_command(zh_160x_i2c_handle_t *handle, uint8_t command); static esp_err_t _zh_160x_send_command(zh_160x_i2c_handle_t *handle, uint8_t command);
/** /**
* @brief Send data to the LCD. * @brief Send data to the LCD.
* *
* Transmits a data byte to the LCD in 4-bit mode. * Transmits a data byte to the LCD in 4-bit mode. The high and low
* RS pin is set to high (0x09) to indicate data mode. * nibbles are sent sequentially on data lines D4-D7 (PCF8574 pins P4-P7),
* each followed by an enable pulse. Bit mask 0x09 sets RS (pin P0) high
* for data mode and keeps pin P3 high; E (pin P2) is held low between pulses.
* *
* @param handle Pointer to the 160x I2C handle * @param handle Pointer to the 160x I2C handle
* @param data Data byte to send * @param data Data byte to send
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_FAIL if error * @return ESP_FAIL if any expander write or pulse operation fails
*/ */
static esp_err_t _zh_160x_send_data(zh_160x_i2c_handle_t *handle, uint8_t data); static esp_err_t _zh_160x_send_data(zh_160x_i2c_handle_t *handle, uint8_t data);
/** /**
* @brief Generate an Enable pulse for the LCD. * @brief Generate an enable pulse for the LCD.
* *
* Toggles the E pin (GPIO2 on PCF8574) to latch data into the LCD. * Toggles the enable line (PCF8574 pin P2) to latch data into the LCD.
* Sets E high, delays 1ms, then sets E low with another 1ms delay. * Sets the line high, delays 1ms, then sets it low with another 1ms delay.
* This pulse signals the LCD to process the data on the D4-D7 pins. * This pulse signals the LCD to process the data on the D4-D7 pins.
* *
* @param handle Pointer to the 160x I2C handle * @param handle Pointer to the 160x I2C handle
* *
* @return ESP_OK on success * @return ESP_OK on success
* @return ESP_FAIL if error * @return ESP_FAIL if any GPIO write operation fails
*/ */
static esp_err_t _zh_160x_pulse(zh_160x_i2c_handle_t *handle); static esp_err_t _zh_160x_pulse(zh_160x_i2c_handle_t *handle);
@@ -118,10 +127,7 @@ esp_err_t zh_160x_set_cursor(zh_160x_i2c_handle_t **handle, uint8_t row, uint8_t
{ {
ZH_LOGI("160X set cursor started."); ZH_LOGI("160X set cursor started.");
ZH_ERROR_CHECK(handle != NULL && *handle != NULL && row < (((*handle)->zh_160x_i2c_lcd_size == ZH_LCD_16X2) ? 2 : 4) && col < 16, ESP_ERR_INVALID_ARG, NULL, "160X set cursor failed. Invalid argument."); ZH_ERROR_CHECK(handle != NULL && *handle != NULL && row < (((*handle)->zh_160x_i2c_lcd_size == ZH_LCD_16X2) ? 2 : 4) && col < 16, ESP_ERR_INVALID_ARG, NULL, "160X set cursor failed. Invalid argument.");
// clang-format off ZH_ERROR_CHECK(_zh_160x_send_command(*handle, 0x80 | (_lcd_row_addresses[row] + col)) == ESP_OK, ESP_FAIL, NULL, "160X set cursor failed. PCF8574 error.");
ZH_ERROR_CHECK(_zh_160x_send_command(*handle, 0x80 | ((row == 0) ? col : (row == 1) ? (0x40 + col) : (row == 2) ? (0x10 + col) : (0x50 + col))) == ESP_OK,
ESP_FAIL, NULL, "160X set cursor failed. PCF8574 error.");
// clang-format on
ZH_LOGI("160X set cursor completed successfully."); ZH_LOGI("160X set cursor completed successfully.");
return ESP_OK; return ESP_OK;
} }
@@ -225,8 +231,6 @@ static esp_err_t _zh_160x_lcd_init(zh_160x_i2c_handle_t *handle)
ZH_ERROR_CHECK(zh_pcf8574_write(&handle->zh_pcf8574_handle, 0x20) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error."); ZH_ERROR_CHECK(zh_pcf8574_write(&handle->zh_pcf8574_handle, 0x20) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error.");
ZH_ERROR_CHECK(_zh_160x_pulse(handle) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error."); ZH_ERROR_CHECK(_zh_160x_pulse(handle) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error.");
ZH_ERROR_CHECK(_zh_160x_send_command(handle, 0x28) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error."); ZH_ERROR_CHECK(_zh_160x_send_command(handle, 0x28) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error.");
ZH_ERROR_CHECK(_zh_160x_send_command(handle, 0x28) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error.");
ZH_ERROR_CHECK(_zh_160x_send_command(handle, 0x28) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error.");
ZH_ERROR_CHECK(_zh_160x_send_command(handle, 0x0C) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error."); ZH_ERROR_CHECK(_zh_160x_send_command(handle, 0x0C) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error.");
ZH_ERROR_CHECK(_zh_160x_send_command(handle, 0x01) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error."); ZH_ERROR_CHECK(_zh_160x_send_command(handle, 0x01) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error.");
ZH_ERROR_CHECK(_zh_160x_send_command(handle, 0x06) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error."); ZH_ERROR_CHECK(_zh_160x_send_command(handle, 0x06) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error.");