From a124922338ad1c53e2ad890e7bd7b7ec2af1616d Mon Sep 17 00:00:00 2001 From: Alexey Zholtikov Date: Sun, 16 Aug 2026 06:29:16 +0300 Subject: [PATCH] doc: updated comments --- WIKI_EN.md | 34 +++++++++++++++++------------- WIKI_RU.md | 36 +++++++++++++++++-------------- include/zh_pcf8574.h | 50 ++++++++++++++++++++++++++------------------ 3 files changed, 69 insertions(+), 51 deletions(-) diff --git a/WIKI_EN.md b/WIKI_EN.md index 0304aeb..b882d3d 100644 --- a/WIKI_EN.md +++ b/WIKI_EN.md @@ -163,10 +163,10 @@ Initializes the PCF8574 expander. **Returns:** - `ESP_OK` - Success -- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL config or handle) +- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL config, handle or *handle) - `ESP_ERR_INVALID_STATE` - Expander already initialized - `ESP_ERR_NO_MEM` - Insufficient memory -- `ESP_ERR_NOT_SUPPORTED` - I2C initialization error +- `ESP_FAIL` - Configuration validation, I2C communication, or task creation error --- @@ -182,6 +182,8 @@ Deinitializes the PCF8574 expander. - `ESP_OK` - Success - `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle or *handle) +- `ESP_ERR_NOT_FOUND` - Handle does not correspond to a registered device +- `ESP_FAIL` - I2C removal or vector operation error --- @@ -197,10 +199,9 @@ Reads the state of all GPIO pins of the expander. **Returns:** - `ESP_OK` - Success -- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle or reg) -- `ESP_ERR_INVALID_STATE` - Expander not initialized - -**Note:** For input GPIOs, the value will always be 1 (HIGH). +- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle, *handle or reg) +- `ESP_ERR_NOT_FOUND` - Handle does not correspond to a registered device +- `ESP_FAIL` - I2C communication or vector operation error --- @@ -216,8 +217,9 @@ Sets the state of all output GPIO pins of the expander. **Returns:** - `ESP_OK` - Success -- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle) -- `ESP_ERR_INVALID_STATE` - Expander not initialized +- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle or *handle) +- `ESP_ERR_NOT_FOUND` - Handle does not correspond to a registered device +- `ESP_FAIL` - I2C communication or vector operation error **Note:** Only output GPIOs are affected. @@ -235,6 +237,8 @@ Resets all GPIO pins of the expander to the initial state. - `ESP_OK` - Success - `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle or *handle) +- `ESP_ERR_NOT_FOUND` - Handle does not correspond to a registered device +- `ESP_FAIL` - I2C communication or vector operation error --- @@ -251,8 +255,8 @@ Reads the state of one GPIO pin of the expander. **Returns:** - `ESP_OK` - Success -- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle, gpio, status or gpio out of range) -- `ESP_ERR_INVALID_STATE` - Expander not initialized +- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle or status) +- `ESP_FAIL` - Invalid gpio, handle mismatch, or I2C communication error **Note:** For input GPIOs, the value will always be 1 (HIGH). @@ -271,8 +275,8 @@ Sets the state of one output GPIO pin of the expander. **Returns:** - `ESP_OK` - Success -- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle, gpio, status or gpio out of range) -- `ESP_ERR_INVALID_STATE` - Expander not initialized +- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle) +- `ESP_FAIL` - Invalid gpio, handle mismatch, or I2C communication error **Note:** Only output GPIOs are affected. @@ -303,7 +307,7 @@ Resets error statistics counters. #define I2C_PORT (I2C_NUM_MAX - 1) -zh_pcf8574_handle_t pcf8574_handle = {0}; +zh_pcf8574_handle_t *pcf8574_handle = NULL; void print_gpio_status(const char *message, uint8_t reg) { @@ -371,7 +375,7 @@ void app_main(void) #define I2C_PORT (I2C_NUM_MAX - 1) -zh_pcf8574_handle_t pcf8574_handle = {0}; +zh_pcf8574_handle_t *pcf8574_handle = NULL; void zh_pcf8574_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data) { @@ -441,7 +445,7 @@ void app_main(void) | `ESP_OK` | Operation successful | | `ESP_ERR_INVALID_ARG` | Invalid argument (NULL pointer or invalid configuration) | | `ESP_ERR_INVALID_STATE` | Device not initialized or already initialized | -| `ESP_ERR_NOT_FOUND` | Device not initialized | +| `ESP_ERR_NOT_FOUND` | Handle does not correspond to a registered device | | `ESP_ERR_NO_MEM` | Insufficient memory | | `ESP_FAIL` | General failure (I2C communication error, initialization error, etc.) | diff --git a/WIKI_RU.md b/WIKI_RU.md index cf65b99..4f419a0 100644 --- a/WIKI_RU.md +++ b/WIKI_RU.md @@ -163,10 +163,10 @@ typedef struct **Возвращает:** - `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL config или handle) +- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL config, handle или *handle) - `ESP_ERR_INVALID_STATE` - Расширитель уже инициализирован - `ESP_ERR_NO_MEM` - Недостаточно памяти -- `ESP_ERR_NOT_SUPPORTED` - Ошибка инициализации I2C +- `ESP_FAIL` - Ошибка валидации конфигурации, I2C-связи или создания задачи --- @@ -182,6 +182,8 @@ typedef struct - `ESP_OK` - Успех - `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или *handle) +- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству +- `ESP_FAIL` - Ошибка удаления I2C или операций с вектором --- @@ -197,10 +199,9 @@ typedef struct **Возвращает:** - `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или reg) -- `ESP_ERR_INVALID_STATE` - Расширитель не инициализирован - -**Примечание:** Для входных GPIO всегда будет 1 (HIGH). +- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle, *handle или reg) +- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству +- `ESP_FAIL` - Ошибка I2C-связи или операций с вектором --- @@ -216,10 +217,11 @@ typedef struct **Возвращает:** - `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle) -- `ESP_ERR_INVALID_STATE` - Расширитель не инициализирован +- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или *handle) +- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству +- `ESP_FAIL` - Ошибка I2C-связи или операций с вектором -**Примечание:** Влияет только на выходные GPIO. +**Примечание:** Только на выходные GPIO влияет. --- @@ -235,6 +237,8 @@ typedef struct - `ESP_OK` - Успех - `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или *handle) +- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству +- `ESP_FAIL` - Ошибка I2C-связи или операций с вектором --- @@ -251,8 +255,8 @@ typedef struct **Возвращает:** - `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle, gpio, status или выход gpio за пределы) -- `ESP_ERR_INVALID_STATE` - Расширитель не инициализирован +- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или status) +- `ESP_FAIL` - Неверный номер gpio, handle не соответствует устройству или I2C-связь **Примечание:** Для входных GPIO всегда будет 1 (HIGH). @@ -271,8 +275,8 @@ typedef struct **Возвращает:** - `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle, gpio, status или выход gpio за пределы) -- `ESP_ERR_INVALID_STATE` - Расширитель не инициализирован +- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle) +- `ESP_FAIL` - Неверный номер gpio, handle не соответствует устройству или I2C-связь **Примечание:** Влияет только на выходные GPIO. @@ -303,7 +307,7 @@ typedef struct #define I2C_PORT (I2C_NUM_MAX - 1) -zh_pcf8574_handle_t pcf8574_handle = {0}; +zh_pcf8574_handle_t *pcf8574_handle = NULL; void print_gpio_status(const char *message, uint8_t reg) { @@ -371,7 +375,7 @@ void app_main(void) #define I2C_PORT (I2C_NUM_MAX - 1) -zh_pcf8574_handle_t pcf8574_handle = {0}; +zh_pcf8574_handle_t *pcf8574_handle = NULL; void zh_pcf8574_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data) { @@ -441,7 +445,7 @@ void app_main(void) | `ESP_OK` | Операция выполнена успешно | | `ESP_ERR_INVALID_ARG` | Неверный аргумент (NULL указатель или неверная конфигурация) | | `ESP_ERR_INVALID_STATE` | Устройство не инициализировано или уже инициализировано | -| `ESP_ERR_NOT_FOUND` | Устройство не инициализировано | +| `ESP_ERR_NOT_FOUND` | Handle не соответствует зарегистрированному устройству | | `ESP_ERR_NO_MEM` | Недостаточно памяти | | `ESP_FAIL` | Общая ошибка (ошибка связи I2C, инициализации и т.д.) | diff --git a/include/zh_pcf8574.h b/include/zh_pcf8574.h index 0c09ee6..c611484 100755 --- a/include/zh_pcf8574.h +++ b/include/zh_pcf8574.h @@ -155,62 +155,72 @@ extern "C" * @param[out] handle Pointer to receive the device handle (must be NULL) * * @return ESP_OK on success - * @return ESP_ERR_INVALID_ARG if config parameter is NULL + * @return ESP_ERR_INVALID_ARG if config is NULL or handle points to non-NULL + * @return ESP_ERR_INVALID_STATE if device is already initialized * @return ESP_ERR_NO_MEM if memory allocation fails - * @return ESP_ERR_NOT_SUPPORTED if I2C initialization fails + * @return ESP_FAIL if configuration validation, I2C communication, or task creation fails */ esp_err_t zh_pcf8574_init(const zh_pcf8574_init_config_t *config, zh_pcf8574_handle_t **handle); /** * @brief Deinitialize PCF8574 device. * - * Deletes the internal task and releases all allocated resources. + * Releases I2C resources and the device handle. Deletes the internal + * task only when the last device instance is deinitialized. * - * @param[in,out] handle Pointer to the device handle (must not be NULL) + * @param[in] handle Pointer to the device handle (must not be NULL) * * @return ESP_OK on success - * @return ESP_ERR_INVALID_ARG if handle parameter is NULL + * @return ESP_ERR_INVALID_ARG if handle is NULL + * @return ESP_ERR_NOT_FOUND if handle does not correspond to a valid device instance + * @return ESP_FAIL if I2C removal or vector operations fail */ esp_err_t zh_pcf8574_deinit(zh_pcf8574_handle_t **handle); /** * @brief Read data from PCF8574 device. * - * Reads a byte from the PCF8574 input ports via I2C communication. + * Reads a byte from the PCF8574 input ports via I2C communication + * and updates the internal device state. * - * @param[in,out] handle Pointer to the device handle (must not be NULL) + * @param[in] handle Pointer to the device handle (must not be NULL) * @param[out] reg Pointer to receive the read value (must not be NULL) * * @return ESP_OK on success * @return ESP_ERR_INVALID_ARG if handle or reg is NULL - * @return ESP_ERR_INVALID_STATE if device is not initialized + * @return ESP_ERR_NOT_FOUND if handle does not correspond to a valid device instance + * @return ESP_FAIL if I2C communication or vector operations fail */ esp_err_t zh_pcf8574_read(zh_pcf8574_handle_t **handle, uint8_t *reg); /** * @brief Write data to PCF8574 device. * - * Writes a byte to the PCF8574 output ports via I2C communication. + * Writes a byte to the PCF8574 output ports via I2C communication + * and updates the internal device state. * - * @param[in,out] handle Pointer to the device handle (must not be NULL) + * @param[in] handle Pointer to the device handle (must not be NULL) * @param[in] reg Value to write to the output ports * * @return ESP_OK on success * @return ESP_ERR_INVALID_ARG if handle is NULL - * @return ESP_ERR_INVALID_STATE if device is not initialized + * @return ESP_ERR_NOT_FOUND if handle does not correspond to a valid device instance + * @return ESP_FAIL if I2C communication or vector operations fail */ esp_err_t zh_pcf8574_write(zh_pcf8574_handle_t **handle, uint8_t reg); /** * @brief Reset PCF8574 device. * - * Resets the device to its default state, clearing all outputs - * and reinitializing internal structures. + * Resets all outputs to their default input configuration + * and updates the internal device state. * - * @param[in,out] handle Pointer to the device handle (must not be NULL) + * @param[in] handle Pointer to the device handle (must not be NULL) * * @return ESP_OK on success * @return ESP_ERR_INVALID_ARG if handle is NULL + * @return ESP_ERR_NOT_FOUND if handle does not correspond to a valid device instance + * @return ESP_FAIL if I2C communication or vector operations fail */ esp_err_t zh_pcf8574_reset(zh_pcf8574_handle_t **handle); @@ -219,13 +229,13 @@ extern "C" * * Reads the current logical level of a specified GPIO pin. * - * @param[in,out] handle Pointer to the device handle (must not be NULL) + * @param[in] handle Pointer to the device handle (must not be NULL) * @param[in] gpio GPIO pin number to read * @param[out] status Pointer to receive the pin state (true = high, false = low) * * @return ESP_OK on success - * @return ESP_ERR_INVALID_ARG if handle, gpio, or status is NULL - * @return ESP_ERR_INVALID_ARG if gpio number exceeds ZH_PCF8574_GPIO_NUM_MAX + * @return ESP_ERR_INVALID_ARG if handle or status is NULL + * @return ESP_FAIL if gpio is invalid, handle is invalid, or I2C communication fails */ esp_err_t zh_pcf8574_read_gpio(zh_pcf8574_handle_t **handle, zh_pcf8574_gpio_num_t gpio, bool *status); @@ -234,13 +244,13 @@ extern "C" * * Sets the logical level of a specified GPIO pin configured as output. * - * @param[in,out] handle Pointer to the device handle (must not be NULL) + * @param[in] handle Pointer to the device handle (must not be NULL) * @param[in] gpio GPIO pin number to write * @param[in] status Logical level to set (true = high, false = low) * * @return ESP_OK on success - * @return ESP_ERR_INVALID_ARG if handle, gpio, or status is NULL - * @return ESP_ERR_INVALID_ARG if gpio number exceeds ZH_PCF8574_GPIO_NUM_MAX + * @return ESP_ERR_INVALID_ARG if handle is NULL + * @return ESP_FAIL if gpio is invalid, handle is invalid, or I2C communication fails */ esp_err_t zh_pcf8574_write_gpio(zh_pcf8574_handle_t **handle, zh_pcf8574_gpio_num_t gpio, bool status);