diff --git a/.gitignore b/.gitignore index 65225d8..496ee2c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1 @@ -.DS_Store -.vscode -build -sdkconfig -sdkconfig.old \ No newline at end of file +.DS_Store \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt index 9ab5c51..0b27796 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1 +1 @@ -idf_component_register(SRCS "main.c" INCLUDE_DIRS "include") \ No newline at end of file +idf_component_register(SRCS "zh_1602a.c" INCLUDE_DIRS "include" REQUIRES driver) \ No newline at end of file diff --git a/README.md b/README.md index 3df3e4d..f38b3d8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,73 @@ -# esp_component_template +# ESP32 ESP-IDF and ESP8266 RTOS SDK component for liquid crystal display module 1602A -esp_component_template \ No newline at end of file +## Tested on + +1. ESP8266 RTOS_SDK v3.4 +2. ESP32 ESP-IDF v5.4 + +## Note + +1. Automatic selection of 8 bit or 4 bit work mode. +2. Display off and cursor display are not supported. + +## Using + +In an existing project, run the following command to install the component: + +```text +cd ../your_project/components +git clone http://git.zh.com.ru/alexey.zholtikov/zh_1602a +``` + +In the application, add the component: + +```c +#include "zh_1602a.h" +``` + +## Example + +8 bit or 4 bit work mode: + +```c +#include "zh_1602a.h" + +void app_main(void) +{ + esp_log_level_set("zh_1602a", ESP_LOG_NONE); // For ESP8266 first enable "Component config -> Log output -> Enable log set level" via menuconfig. + zh_1602a_init_config_t init_config = { + .rs_gpio_number = GPIO_NUM_4, + .e_gpio_number = GPIO_NUM_2, + // .d0_gpio_number = GPIO_NUM_21, // Required for 8 bit work mode only. + // .d1_gpio_number = GPIO_NUM_13, // Required for 8 bit work mode only. + // .d2_gpio_number = GPIO_NUM_14, // Required for 8 bit work mode only. + // .d3_gpio_number = GPIO_NUM_15, // Required for 8 bit work mode only. + .d4_gpio_number = GPIO_NUM_16, + .d5_gpio_number = GPIO_NUM_17, + .d6_gpio_number = GPIO_NUM_18, + .d7_gpio_number = GPIO_NUM_19, + }; + zh_1602a_init(&init_config); + for (;;) + { + zh_1602a_set_cursor(0, 0); + zh_1602a_print_char("LCD 1602A"); + zh_1602a_set_cursor(1, 0); + zh_1602a_print_char("Hello World!"); + vTaskDelay(5000 / portTICK_PERIOD_MS); + zh_1602a_clear_row(0); + zh_1602a_print_char("Progress: "); + for (uint8_t i = 0; i <= 100; ++i) + { + zh_1602a_set_cursor(0, 10); + zh_1602a_print_int(i); + zh_1602a_print_char("%"); + zh_1602a_print_progress_bar(1, i); + vTaskDelay(100 / portTICK_PERIOD_MS); + } + vTaskDelay(5000 / portTICK_PERIOD_MS); + zh_1602a_lcd_clear(); + vTaskDelay(5000 / portTICK_PERIOD_MS); + } +} +``` diff --git a/ds/Liquid crystal display module 1602A.pdf b/ds/Liquid crystal display module 1602A.pdf new file mode 100644 index 0000000..7ccb73f Binary files /dev/null and b/ds/Liquid crystal display module 1602A.pdf differ diff --git a/include/main.h b/include/main.h deleted file mode 100644 index e69de29..0000000 diff --git a/include/zh_1602a.h b/include/zh_1602a.h new file mode 100644 index 0000000..1c61083 --- /dev/null +++ b/include/zh_1602a.h @@ -0,0 +1,103 @@ +#pragma once + +#include "esp_log.h" +#include "esp_err.h" +#include "freertos/FreeRTOS.h" +#include "freertos/task.h" +#include "driver/gpio.h" + +#ifdef __cplusplus +extern "C" +{ +#endif + + typedef struct // Structure for initial initialization of LCD 1602A. + { + uint8_t rs_gpio_number; // GPIO connected to RS of LCD 1602A. + uint8_t e_gpio_number; // GPIO connected to E of LCD 1602A. + uint8_t d0_gpio_number; // GPIO connected to D0 of LCD 1602A. @note Required for 8 bit work mode only. + uint8_t d1_gpio_number; // GPIO connected to D1 of LCD 1602A. @note Required for 8 bit work mode only. + uint8_t d2_gpio_number; // GPIO connected to D2 of LCD 1602A. @note Required for 8 bit work mode only. + uint8_t d3_gpio_number; // GPIO connected to D3 of LCD 1602A. @note Required for 8 bit work mode only. + uint8_t d4_gpio_number; // GPIO connected to D4 of LCD 1602A. + uint8_t d5_gpio_number; // GPIO connected to D5 of LCD 1602A. + uint8_t d6_gpio_number; // GPIO connected to D6 of LCD 1602A. + uint8_t d7_gpio_number; // GPIO connected to D7 of LCD 1602A. + } zh_1602a_init_config_t; + + /** + * @brief Initializes the LCD 1602A. + * + * @param[in] config Pointer to 1602A initialized configuration structure. Can point to a temporary variable. + * + * @return ESP_OK if success or an error code otherwise. + */ + esp_err_t zh_1602a_init(const zh_1602a_init_config_t *config); + + /** + * @brief Clears the LCD screen. + * + * @return ESP_OK if success or an error code otherwise. + */ + esp_err_t zh_1602a_lcd_clear(void); + + /** + * @brief Sets the cursor to a specific position on the LCD. + * + * @param[in] row The row number (0 or 1). + * @param[in] col The column number (0–15). + * + * @return ESP_OK if success or an error code otherwise. + */ + esp_err_t zh_1602a_set_cursor(uint8_t row, uint8_t col); + + /** + * @brief Prints a string to the LCD. + * + * @param[in] str Pointer to the string to be displayed. + * + * @return ESP_OK if success or an error code otherwise. + */ + esp_err_t zh_1602a_print_char(const char *str); + + /** + * @brief Prints an integer to the LCD. + * + * @param[in] num The integer to be displayed. + * + * @return ESP_OK if success or an error code otherwise.. + */ + esp_err_t zh_1602a_print_int(int num); + + /** + * @brief Prints a floating-point number to the LCD. + * + * @param[in] num The floating-point number to be displayed. + * @param[in] precision The number of decimal places to display. + * + * @return ESP_OK if success or an error code otherwise. + */ + esp_err_t zh_1602a_print_float(float num, uint8_t precision); + + /** + * @brief Displays a progress bar on a specific row of the LCD. + * + * @param[in] row The row number (0 or 1). + * @param[in] progress The progress percentage (0–100). + * + * @return ESP_OK if success or an error code otherwise. + */ + esp_err_t zh_1602a_print_progress_bar(uint8_t row, uint8_t progress); + + /** + * @brief Clears a specific row on the LCD. + * + * @param[in] row The row number (0 or 1). + * + * @return ESP_OK if success or an error code otherwise. + */ + esp_err_t zh_1602a_clear_row(uint8_t row); + +#ifdef __cplusplus +} +#endif \ No newline at end of file diff --git a/main.c b/main.c deleted file mode 100644 index e69de29..0000000 diff --git a/version.txt b/version.txt index e69de29..afaf360 100644 --- a/version.txt +++ b/version.txt @@ -0,0 +1 @@ +1.0.0 \ No newline at end of file diff --git a/zh_1602a.c b/zh_1602a.c new file mode 100644 index 0000000..46a80e2 --- /dev/null +++ b/zh_1602a.c @@ -0,0 +1,291 @@ +#include "zh_1602a.h" + +static const char *TAG = "zh_1602a"; + +#define ZH_1602A_LOGI(msg, ...) ESP_LOGI(TAG, msg, ##__VA_ARGS__) +#define ZH_1602A_LOGW(msg, ...) ESP_LOGW(TAG, msg, ##__VA_ARGS__) +#define ZH_1602A_LOGE(msg, ...) ESP_LOGE(TAG, msg, ##__VA_ARGS__) +#define ZH_1602A_LOGE_ERR(msg, err, ...) ESP_LOGE(TAG, "[%s:%d:%s] " msg, __FILE__, __LINE__, esp_err_to_name(err), ##__VA_ARGS__) + +#define ZH_1602A_CHECK(cond, err, msg, ...) \ + if (!(cond)) \ + { \ + ZH_1602A_LOGE_ERR(msg, err); \ + return err; \ + } + +#ifdef CONFIG_IDF_TARGET_ESP8266 +#define esp_delay_us(x) os_delay_us(x) +#else +#define esp_delay_us(x) esp_rom_delay_us(x) +#endif + +static esp_err_t _zh_1602a_gpio_init(const zh_1602a_init_config_t *config); +static void _zh_1602a_lcd_init(void); +static bool _zh_1602a_8bit_gpio_check(uint8_t rs, uint8_t e, uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3, uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7); +static bool _zh_1602a_4bit_gpio_check(uint8_t rs, uint8_t e, uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7); +static void _zh_1602a_send_command(uint8_t command); +static void _zh_1602a_send_data(uint8_t data); +static void _zh_1602a_pulse_enable(void); +static void _zh_1602a_send_8bit(uint8_t data); +static void _zh_1602a_send_4bit(uint8_t data); + +static uint8_t _rs_pin = 0; +static uint8_t _e_pin = 0; +static uint8_t _gpio_matrix[8] = {0}; +static bool _is_initialized = false; +static bool _is_8bit_work_mode = true; + +esp_err_t zh_1602a_init(const zh_1602a_init_config_t *config) +{ + ZH_1602A_LOGI("1602A initialization started."); + ZH_1602A_CHECK(config != NULL, ESP_ERR_INVALID_ARG, "1602A initialization failed. Invalid argument."); + ZH_1602A_CHECK(_is_initialized == false, ESP_ERR_INVALID_STATE, "1602A initialization failed. 1602A is already initialized."); + esp_err_t err = _zh_1602a_gpio_init(config); + ZH_1602A_CHECK(err == ESP_OK, ESP_FAIL, "1602A initialization failed. GPIO initialization failed."); + _zh_1602a_lcd_init(); + _is_initialized = true; + ZH_1602A_LOGI("CD74HC4067 initialization completed successfully in %d bit mode.", (_is_8bit_work_mode == true) ? 8 : 4); + return ESP_OK; +} + +esp_err_t zh_1602a_lcd_clear(void) +{ + ZH_1602A_LOGI("1602A display cleaning started."); + ZH_1602A_CHECK(_is_initialized == true, ESP_ERR_INVALID_STATE, "1602A display cleaning failed. 1602A not initialized."); + _zh_1602a_send_command(0x01); + esp_delay_us(1600); + ZH_1602A_LOGI("1602A display cleaning completed successfully."); + return ESP_OK; +} + +esp_err_t zh_1602a_set_cursor(uint8_t row, uint8_t col) +{ + ZH_1602A_LOGI("1602A set cursor started."); + ZH_1602A_CHECK(row < 2 && col < 16, ESP_ERR_INVALID_ARG, "1602A set cursor failed. Invalid argument."); + ZH_1602A_CHECK(_is_initialized == true, ESP_ERR_INVALID_STATE, "1602A set cursor failed. 1602A not initialized."); + uint8_t address = (row == 0) ? col : (0x40 + col); + _zh_1602a_send_command(0x80 | address); + ZH_1602A_LOGI("1602A set cursor completed successfully."); + return ESP_OK; +} + +esp_err_t zh_1602a_print_char(const char *str) +{ + ZH_1602A_LOGI("1602A print char started."); + ZH_1602A_CHECK(str != NULL, ESP_ERR_INVALID_ARG, "1602A print char failed. Invalid argument."); + ZH_1602A_CHECK(_is_initialized == true, ESP_ERR_INVALID_STATE, "1602A print char failed. 1602A not initialized."); + while (*str != 0) + { + _zh_1602a_send_data((uint8_t)*str++); + } + ZH_1602A_LOGI("1602A print char completed successfully."); + return ESP_OK; +} + +esp_err_t zh_1602a_print_int(int num) +{ + ZH_1602A_LOGI("1602A print int started."); + ZH_1602A_CHECK(_is_initialized == true, ESP_ERR_INVALID_STATE, "1602A print int failed. 1602A not initialized."); + char buffer[12]; + sprintf(buffer, "%d", num); + zh_1602a_print_char(buffer); + ZH_1602A_LOGI("1602A print int completed successfully."); + return ESP_OK; +} + +esp_err_t zh_1602a_print_float(float num, uint8_t precision) +{ + ZH_1602A_LOGI("1602A print float started."); + ZH_1602A_CHECK(_is_initialized == true, ESP_ERR_INVALID_STATE, "1602A print float failed. 1602A not initialized."); + char buffer[16]; + sprintf(buffer, "%.*f", precision, num); + zh_1602a_print_char(buffer); + ZH_1602A_LOGI("1602A print float completed successfully."); + return ESP_OK; +} + +esp_err_t zh_1602a_print_progress_bar(uint8_t row, uint8_t progress) +{ + ZH_1602A_LOGI("1602A print progress bar started."); + ZH_1602A_CHECK(row < 2 && progress <= 100, ESP_ERR_INVALID_ARG, "1602A print progress bar failed. Invalid argument."); + ZH_1602A_CHECK(_is_initialized == true, ESP_ERR_INVALID_STATE, "1602A print progress bar failed. 1602A not initialized."); + uint8_t blocks = (progress * 16) / 100; + zh_1602a_set_cursor(row, 0); + for (uint8_t i = 0; i < 16; ++i) + { + if (i < blocks) + { + zh_1602a_print_char("\xFF"); + } + else + { + zh_1602a_print_char(" "); + } + } + ZH_1602A_LOGI("1602A print progress bar completed successfully."); + return ESP_OK; +} + +esp_err_t zh_1602a_clear_row(uint8_t row) +{ + ZH_1602A_LOGI("1602A clear row started."); + ZH_1602A_CHECK(row < 2, ESP_ERR_INVALID_ARG, "1602A clear row failed. Invalid argument."); + ZH_1602A_CHECK(_is_initialized == true, ESP_ERR_INVALID_STATE, "1602A clear row failed. 1602A not initialized."); + zh_1602a_set_cursor(row, 0); + for (uint8_t i = 0; i < 16; ++i) + { + zh_1602a_print_char(" "); + } + zh_1602a_set_cursor(row, 0); + ZH_1602A_LOGI("1602A clear row completed successfully."); + return ESP_OK; +} + +static esp_err_t _zh_1602a_gpio_init(const zh_1602a_init_config_t *config) +{ + ZH_1602A_CHECK(config->rs_gpio_number < GPIO_NUM_MAX || config->e_gpio_number < GPIO_NUM_MAX || config->d0_gpio_number < GPIO_NUM_MAX || + config->d1_gpio_number < GPIO_NUM_MAX || config->d2_gpio_number < GPIO_NUM_MAX || config->d3_gpio_number < GPIO_NUM_MAX || + config->d4_gpio_number < GPIO_NUM_MAX || config->d5_gpio_number < GPIO_NUM_MAX || config->d6_gpio_number < GPIO_NUM_MAX || config->d7_gpio_number < GPIO_NUM_MAX, + ESP_ERR_INVALID_ARG, "Invalid GPIO number."); + bool gpio_check = _zh_1602a_8bit_gpio_check(config->rs_gpio_number, config->e_gpio_number, config->d0_gpio_number, config->d1_gpio_number, config->d2_gpio_number, + config->d3_gpio_number, config->d4_gpio_number, config->d5_gpio_number, config->d6_gpio_number, config->d7_gpio_number); + if (gpio_check == false) + { + gpio_check = _zh_1602a_4bit_gpio_check(config->rs_gpio_number, config->e_gpio_number, config->d4_gpio_number, config->d5_gpio_number, config->d6_gpio_number, config->d7_gpio_number); + ZH_1602A_CHECK(gpio_check == true, ESP_FAIL, "Invalid GPIO number."); + _is_8bit_work_mode = false; + } + gpio_config_t pin_config = { + .mode = GPIO_MODE_OUTPUT, + .pull_down_en = GPIO_PULLDOWN_ENABLE, + .pin_bit_mask = (1ULL << config->rs_gpio_number) | (1ULL << config->e_gpio_number) | (1ULL << config->d0_gpio_number) | (1ULL << config->d1_gpio_number) | + (1ULL << config->d2_gpio_number) | (1ULL << config->d3_gpio_number) | (1ULL << config->d4_gpio_number) | (1ULL << config->d5_gpio_number) | + (1ULL << config->d6_gpio_number) | (1ULL << config->d7_gpio_number), + }; + esp_err_t err = gpio_config(&pin_config); + ZH_1602A_CHECK(err == ESP_OK, err, "GPIO initialization failed.") + _rs_pin = config->rs_gpio_number; + _e_pin = config->e_gpio_number; + _gpio_matrix[0] = config->d0_gpio_number; + _gpio_matrix[1] = config->d1_gpio_number; + _gpio_matrix[2] = config->d2_gpio_number; + _gpio_matrix[3] = config->d3_gpio_number; + _gpio_matrix[4] = config->d4_gpio_number; + _gpio_matrix[5] = config->d5_gpio_number; + _gpio_matrix[6] = config->d6_gpio_number; + _gpio_matrix[7] = config->d7_gpio_number; + return ESP_OK; +} + +static void _zh_1602a_lcd_init(void) +{ + vTaskDelay(20 / portTICK_PERIOD_MS); + _zh_1602a_send_4bit(0x03); + vTaskDelay(10 / portTICK_PERIOD_MS); + _zh_1602a_send_4bit(0x03); + vTaskDelay(10 / portTICK_PERIOD_MS); + _zh_1602a_send_4bit(0x03); + esp_delay_us(150); + if (_is_8bit_work_mode == false) + { + _zh_1602a_send_4bit(0x02); + } + _zh_1602a_send_command((_is_8bit_work_mode == true) ? 0x38 : 0x28); + vTaskDelay(10 / portTICK_PERIOD_MS); + _zh_1602a_send_command((_is_8bit_work_mode == true) ? 0x38 : 0x28); + esp_delay_us(150); + _zh_1602a_send_command((_is_8bit_work_mode == true) ? 0x38 : 0x28); + _zh_1602a_send_command(0x0C); + _zh_1602a_send_command(0x01); + _zh_1602a_send_command(0x06); + vTaskDelay(10 / portTICK_PERIOD_MS); +} + +static bool _zh_1602a_8bit_gpio_check(uint8_t rs, uint8_t e, uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3, uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7) +{ + uint8_t matrix[] = {rs, e, d0, d1, d2, d3, d4, d5, d6, d7}; + for (uint8_t i = 0; i < sizeof(matrix); ++i) + { + for (uint8_t j = i + 1; j < sizeof(matrix); ++j) + { + if (matrix[i] == matrix[j]) + { + return false; + } + } + } + return true; +} + +static bool _zh_1602a_4bit_gpio_check(uint8_t rs, uint8_t e, uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7) +{ + uint8_t matrix[] = {rs, e, d4, d5, d6, d7}; + for (uint8_t i = 0; i < sizeof(matrix); ++i) + { + for (uint8_t j = i + 1; j < sizeof(matrix); ++j) + { + if (matrix[i] == matrix[j]) + { + return false; + } + } + } + return true; +} + +static void _zh_1602a_send_command(uint8_t command) +{ + gpio_set_level(_rs_pin, 0); + gpio_set_level(_e_pin, 0); + if (_is_8bit_work_mode == true) + { + _zh_1602a_send_8bit(command); + } + else + { + _zh_1602a_send_4bit(command >> 4); + _zh_1602a_send_4bit(command); + } +} + +static void _zh_1602a_send_data(uint8_t data) +{ + gpio_set_level(_rs_pin, 1); + gpio_set_level(_e_pin, 0); + if (_is_8bit_work_mode == true) + { + _zh_1602a_send_8bit(data); + } + else + { + _zh_1602a_send_4bit(data >> 4); + _zh_1602a_send_4bit(data); + } +} + +static void _zh_1602a_pulse_enable(void) +{ + gpio_set_level(_e_pin, 1); + esp_delay_us(1); + gpio_set_level(_e_pin, 0); + esp_delay_us(40); +} + +static void _zh_1602a_send_8bit(uint8_t data) +{ + for (uint8_t i = 0; i <= 7; ++i) + { + gpio_set_level(_gpio_matrix[i], (data >> i) & 0x01); + } + _zh_1602a_pulse_enable(); +} + +static void _zh_1602a_send_4bit(uint8_t data) +{ + for (uint8_t i = 0; i <= 3; ++i) + { + gpio_set_level(_gpio_matrix[i + 4], (data >> i) & 0x01); + } + _zh_1602a_pulse_enable(); +} \ No newline at end of file