From 9696b8a0fefaf55bfd0c37eb06bdd98a4a433b0d Mon Sep 17 00:00:00 2001 From: Alexey Zholtikov Date: Sat, 10 Oct 2026 09:22:34 +0300 Subject: [PATCH] doc: updated commits --- README.md | 2 - include/zh_160x_i2c.h | 89 ++++++++++++++++++++++++------------------- zh_160x_i2c.c | 38 +++++++++--------- 3 files changed, 70 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index a7a47f0..a981c2d 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,6 @@ Enable the following settings in menuconfig: ```text CONFIG_FREERTOS_HZ=1000 -CONFIG_I2C_ISR_IRAM_SAFE -CONFIG_I2C_MASTER_ISR_HANDLER_IN_IRAM ``` ## Using diff --git a/include/zh_160x_i2c.h b/include/zh_160x_i2c.h index 7ff9e5b..052fd1c 100644 --- a/include/zh_160x_i2c.h +++ b/include/zh_160x_i2c.h @@ -13,6 +13,10 @@ * - Text, integer, and floating-point number printing * - Custom progress bar rendering * - 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 @@ -37,9 +41,9 @@ extern "C" */ typedef enum { - ZH_LCD_16X2 = 0, /*!< LCD size 16x2 */ - ZH_LCD_16X4, /*!< LCD size 16x4 */ - ZH_LCD_NUM_MAX + ZH_LCD_16X2, /*!< LCD size 16x2 */ + ZH_LCD_16X4, /*!< LCD size 16x4 */ + ZH_LCD_NUM_MAX /*!< Number of supported LCD sizes */ } zh_160x_i2c_lcd_size_t; /** @@ -49,13 +53,13 @@ extern "C" * sequence to the LCD controller via the PCF8574 I2C expander. * Configures 4-bit mode and sets default display parameters. * - * @param[in] expander Pointer to the PCF8574 expander handle (must not be NULL) - * @param[out] handle Output pointer for the newly allocated LCD handle (must be NULL) - * @param[in] size LCD size (ZH_LCD_16X2 or ZH_LCD_16X4) + * @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 Pointer to the output LCD handle pointer (must not be NULL and must point to a NULL pointer) + * @param[in] size LCD size configuration (must be < ZH_LCD_NUM_MAX) * * @return ESP_OK on success - * @return ESP_ERR_INVALID_ARG if any parameter is NULL or size is invalid - * @return ESP_ERR_INVALID_STATE if the handle is already initialized + * @return ESP_ERR_INVALID_ARG if any parameter pointer is NULL or size is invalid + * @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_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) * * @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); @@ -80,10 +84,10 @@ extern "C" * Sends the LCD clear command (0x01) to erase all displayed text * 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_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 */ 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 16x4 displays: rows 0–3, columns 0–15. * - * @param[in] handle Pointer to the LCD handle (must not be NULL) - * @param[in] row Row number (0 to 1 for 16x2, 0 to 3 for 16x4) - * @param[in] col Column number (0–15) + * @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 (must be < 2 for 16x2 and < 4 for 16x4) + * @param[in] col Column number (must be < 16) * * @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 * * @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 * 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) * * @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 */ 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. * * 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 * * @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 */ 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. * - * Converts the floating-point value to a string with the specified - * decimal precision and displays it. + * Converts the floating-point value to a decimal string with the + * 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] 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_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 */ 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. * - * Renders a 16-block progress bar using custom character (0xFF). - * Filled blocks represent the progress percentage, empty blocks show remaining. + * Renders a 16-block progress bar where filled blocks represent the + * 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] row Row number (0 to 1 for 16x2, 0 to 3 for 16x4) - * @param[in] progress Progress percentage (0–100) + * @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 (must be < 2 for 16x2 and < 4 for 16x4) + * @param[in] progress Progress percentage (must be <= 100) * * @return ESP_OK on success - * @return ESP_ERR_INVALID_ARG if handle is NULL, row is out of range, - * or progress exceeds 100 + * @return ESP_ERR_INVALID_ARG if any parameter pointer is NULL, row is out of range, or progress exceeds 100 * @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); @@ -178,11 +187,11 @@ extern "C" * all 16 positions with spaces to erase existing content. * Leaves the cursor at the start of the cleared row. * - * @param[in] handle Pointer to the LCD handle (must not be NULL) - * @param[in] row Row number (0 to 1 for 16x2, 0 to 3 for 16x4) + * @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 (must be < 2 for 16x2 and < 4 for 16x4) * * @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 */ 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. * Command 0x0F enables cursor with blink, 0x0E enables cursor only. * - * @param[in] handle Pointer to the LCD handle (must not be NULL) - * @param[in] blink If true, enables blinking cursor; if false, solid cursor + * @param[in] handle Pointer to the LCD handle pointer (must not be NULL and must point to a non-NULL handle) + * @param[in] blink Enable cursor blink mode * * @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 */ 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. * - * @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_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 */ esp_err_t zh_160x_off_cursor(zh_160x_i2c_handle_t **handle); diff --git a/zh_160x_i2c.c b/zh_160x_i2c.c index 9ce6b37..c3b5be7 100644 --- a/zh_160x_i2c.c +++ b/zh_160x_i2c.c @@ -18,6 +18,9 @@ static const char *TAG = "zh_160x_i2c"; * * Internal handle containing the PCF8574 expander pointer and * 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 { @@ -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) */ }; +static const uint8_t _lcd_row_addresses[] = {0x00, 0x40, 0x10, 0x50}; + /** * @brief Initialize the LCD 160x display. * @@ -35,49 +40,53 @@ struct _zh_160x_i2c_handle_t * @param handle Pointer to the 160x I2C handle * * @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); /** * @brief Send a command to the LCD. * - * Transmits a command byte to the LCD in 4-bit mode. - * RS pin is set to low (0x08) to indicate command mode. + * Transmits a command byte to the LCD in 4-bit mode. The high and low + * 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 command Command byte to send * * @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); /** * @brief Send data to the LCD. * - * Transmits a data byte to the LCD in 4-bit mode. - * RS pin is set to high (0x09) to indicate data mode. + * Transmits a data byte to the LCD in 4-bit mode. The high and low + * 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 data Data byte to send * * @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); /** - * @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. - * Sets E high, delays 1ms, then sets E low with another 1ms delay. + * Toggles the enable line (PCF8574 pin P2) to latch data into the LCD. + * 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. * * @param handle Pointer to the 160x I2C handle * * @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); @@ -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_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 | ((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_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_LOGI("160X set cursor completed successfully."); 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_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, 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, 0x06) == ESP_OK, ESP_FAIL, NULL, "PCF8574 error.");