From 923dd6542f2fd85f713c62a8c697f25c195d0371 Mon Sep 17 00:00:00 2001 From: Alexey Zholtikov Date: Sun, 30 Aug 2026 17:26:12 +0300 Subject: [PATCH] doc: updated readme --- README.md | 105 +++++++++-- WIKI_EN.md | 500 ----------------------------------------------------- WIKI_RU.md | 500 ----------------------------------------------------- 3 files changed, 94 insertions(+), 1011 deletions(-) delete mode 100644 WIKI_EN.md delete mode 100644 WIKI_RU.md diff --git a/README.md b/README.md index b40ea9c..fb32212 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,5 @@ # ESP32 ESP-IDF component for PCF8574 8-bit I/O expander -## Wiki - -[EN](WIKI_EN.md) | [RU](WIKI_RU.md) - -## Tested on - -1. [ESP32 ESP-IDF v6.0.0](https://docs.espressif.com/projects/esp-idf/en/v6.0/esp32/index.html) - ## SAST Tools [PVS-Studio](https://pvs-studio.com/pvs-studio/?utm_source=website&utm_medium=github&utm_campaign=open_source) — static analyzer for C, C++, C#, and Java code. @@ -20,11 +12,21 @@ 4. Event-based architecture using esp_event framework. 5. Statistics tracking for debugging and monitoring. +## Note + +Enable the following settings in menuconfig: + +```text +GPIO_CTRL_FUNC_IN_IRAM +I2C_ISR_IRAM_SAFE +I2C_MASTER_ISR_HANDLER_IN_IRAM +``` + ## Using In an existing project, run the following command to install the components: -```text +```bash cd ../your_project/components git clone https://github.com/aZholtikov/zh_pcf8574 ``` @@ -35,6 +37,87 @@ In the application, add the component: #include "zh_pcf8574.h" ``` -## Examples +## Example -See Wiki [EN](WIKI_EN.md#usage-examples) | [RU](WIKI_RU.md#примеры-использования) +```c +#include "zh_pcf8574.h" + +#define I2C_PORT (I2C_NUM_MAX - 1) + +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); + +void print_gpio_status(const char *message, uint8_t reg) +{ + printf("%s", message); + for (uint8_t i = 0; i < 8; ++i) + { + printf("%c", (reg & 0x80) ? '1' : '0'); + reg <<= 1; + } + printf(".\n"); +} + +void app_main(void) +{ + esp_log_level_set("zh_pcf8574", ESP_LOG_ERROR); + esp_log_level_set("zh_vector", ESP_LOG_ERROR); + i2c_master_bus_config_t i2c_bus_config = { + .clk_source = I2C_CLK_SRC_DEFAULT, + .i2c_port = I2C_PORT, + .scl_io_num = GPIO_NUM_22, + .sda_io_num = GPIO_NUM_21, + .glitch_ignore_cnt = 7, + .flags.enable_internal_pullup = true, + }; + i2c_master_bus_handle_t i2c_bus_handle = NULL; + i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle); + esp_event_loop_create_default(); + esp_event_handler_instance_register(ZH_PCF8574, ESP_EVENT_ANY_ID, &zh_pcf8574_event_handler, NULL, NULL); + zh_pcf8574_init_config_t config = ZH_PCF8574_INIT_CONFIG_DEFAULT(); + config.i2c_handle = i2c_bus_handle; + config.i2c_address = 0x38; + config.p0_gpio_work_mode = ZH_PCF8574_GPIO_INPUT; + config.interrupt_gpio = GPIO_NUM_14; + zh_pcf8574_init(&config, &pcf8574_handle); + uint8_t reg = 0; + zh_pcf8574_read(&pcf8574_handle, ®); + print_gpio_status("GPIO status: ", reg); + printf("Set P7 to 1, P1 to 1 and P0 to 0.\n"); + zh_pcf8574_write(&pcf8574_handle, 0b10000010); + zh_pcf8574_read(&pcf8574_handle, ®); + print_gpio_status("GPIO status: ", reg); + printf("Sets P0 to 0.\n"); + zh_pcf8574_write_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P0, ZH_PCF8574_GPIO_LOW); + bool gpio = 0; + zh_pcf8574_read_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P0, &gpio); + printf("P0 status: %d.\n", gpio); + printf("Set P4 to 1.\n"); + zh_pcf8574_write_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P4, ZH_PCF8574_GPIO_HIGH); + zh_pcf8574_read_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P4, &gpio); + printf("P4 status: %d.\n", gpio); + zh_pcf8574_read(&pcf8574_handle, ®); + print_gpio_status("GPIO status: ", reg); + printf("Reset all GPIO.\n"); + zh_pcf8574_reset(&pcf8574_handle); + zh_pcf8574_read(&pcf8574_handle, ®); + print_gpio_status("GPIO status: ", reg); + for (;;) + { + const zh_pcf8574_stats_t *stats = zh_pcf8574_get_stats(); + printf("Number of i2c driver error: %ld.\n", stats->i2c_driver_error); + printf("Number of event post error: %ld.\n", stats->event_post_error); + printf("Number of vector error: %ld.\n", stats->vector_error); + printf("Number of queue overflow error: %ld.\n", stats->queue_overflow_error); + printf("Minimum free stack size: %ld.\n", stats->min_stack_size); + vTaskDelay(60000 / portTICK_PERIOD_MS); + } +} + +void zh_pcf8574_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data) +{ + zh_pcf8574_event_on_isr_t *event = event_data; + printf("Interrupt happened on device address 0x%02X on GPIO number %d at level %d at time %lld.\n", event->i2c_address, event->gpio_number, event->gpio_level, event->interrupt_time); +} +``` diff --git a/WIKI_EN.md b/WIKI_EN.md deleted file mode 100644 index b9ed6e8..0000000 --- a/WIKI_EN.md +++ /dev/null @@ -1,500 +0,0 @@ -# zh_pcf8574 - PCF8574(A) 8-bit I/O Expander Component for ESP-IDF - -## Table of Contents - -- [Overview](#overview) -- [Features](#features) -- [Installation](#installation) -- [API Reference](#api-reference) -- [Usage Examples](#usage-examples) -- [Technical Specifications](#technical-specifications) -- [Error Codes](#error-codes) -- [Contributing](#contributing) -- [License](#license) - ---- - -## Overview - -`zh_pcf8574` is an ESP-IDF component for 8-bit I/O expanders PCF8574 and PCF8574A. It provides a convenient API for working with GPIO expanders via I2C bus. The component supports up to 16 expanders on a single I2C bus and can generate interrupts when input GPIO states change. - -The component is designed specifically for ESP32 microcontrollers and uses ESP-IDF v5.0+ I2C driver API. - ---- - -## Features - -1. **Support for 16 Expanders**: Up to 16 PCF8574(A) on one I2C bus (addresses 0x20-0x27 and 0x38-0x3F) -2. **GPIO Modes**: Support for output and input modes for each of the 8 GPIO pins -3. **Interrupt Generation**: Support for interrupts from input GPIOs (negative edge) -4. **Error Statistics**: Built-in counters for I2C, event, vector, and queue overflow errors -5. **Thread-Safe**: Uses ESP-IDF I2C driver and FreeRTOS -6. **Minimal Overhead**: Low memory and CPU requirements -7. **Simple API**: Easy read/write for all GPIO and individual pins - ---- - -## Installation - -Navigate to your project's components directory: - -```bash -cd ../your_project/components -``` - -Clone the repository: - -```bash -git clone https://github.com/aZholtikov/zh_pcf8574 -``` - -In your application, include the header: - -```c -#include "zh_pcf8574.h" -``` - -The component will be automatically built with your project. - -### Required menuconfig Settings - -For correct operation, enable the following settings in menuconfig: - -```text -GPIO_CTRL_FUNC_IN_IRAM -I2C_ISR_IRAM_SAFE -I2C_MASTER_ISR_HANDLER_IN_IRAM -``` - ---- - -## API Reference - -### Macros - -```c -#define ZH_PCF8574_GPIO_OUTPUT false -#define ZH_PCF8574_GPIO_INPUT true -#define ZH_PCF8574_GPIO_LOW false -#define ZH_PCF8574_GPIO_HIGH true -``` - ---- - -### zh_pcf8574_init_config_t Structure - -```c -typedef struct -{ - i2c_master_bus_handle_t i2c_handle; // Unique I2C bus handle - uint32_t i2c_frequency; // I2C frequency of the expander (max 100000 Hz) - uint32_t stack_size; // Stack size for interrupt processing task - uint8_t task_priority; // Priority of interrupt processing task - uint8_t i2c_address; // I2C address of the expander (0x20-0x27 or 0x38-0x3F) - bool p0_gpio_work_mode; // GPIO P0 work mode (false - output, true - input) - bool p1_gpio_work_mode; // GPIO P1 work mode - bool p2_gpio_work_mode; // GPIO P2 work mode - bool p3_gpio_work_mode; // GPIO P3 work mode - bool p4_gpio_work_mode; // GPIO P4 work mode - bool p5_gpio_work_mode; // GPIO P5 work mode - bool p6_gpio_work_mode; // GPIO P6 work mode - bool p7_gpio_work_mode; // GPIO P7 work mode - gpio_num_t interrupt_gpio; // Interrupt GPIO (GPIO_NUM_MAX - disable) -} zh_pcf8574_init_config_t; -``` - -Use `ZH_PCF8574_INIT_CONFIG_DEFAULT()` macro to initialize with default values: - -- `i2c_frequency`: 100000 Hz -- `i2c_address`: 0xFF -- `p0_gpio_work_mode` ... `p7_gpio_work_mode`: `ZH_PCF8574_GPIO_OUTPUT` -- `interrupt_gpio`: `GPIO_NUM_MAX` - ---- - -### zh_pcf8574_handle_t Structure - -```c -typedef struct _zh_pcf8574_handle_t zh_pcf8574_handle_t; -``` - -Opaque handle for a PCF8574 device instance. The internal structure is minimal, storing only the I2C address — the full device state is maintained in an internal vector. - ---- - -### zh_pcf8574_stats_t Structure - -```c -typedef struct -{ - uint32_t i2c_driver_error; // Number of I2C driver errors - uint32_t event_post_error; // Number of event post errors - uint32_t vector_error; // Number of vector errors - uint32_t queue_overflow_error; // Number of queue overflow errors - uint32_t min_stack_size; // Minimum free stack of the task -} zh_pcf8574_stats_t; -``` - ---- - -### zh_pcf8574_event_on_isr_t Structure - -```c -typedef struct -{ - uint64_t interrupt_time; // Interrupt time (microseconds) - zh_pcf8574_gpio_num_t gpio_number; // GPIO number that caused the interrupt - uint8_t i2c_address; // I2C address of the expander - bool gpio_level; // GPIO level at interrupt time -} zh_pcf8574_event_on_isr_t; -``` - ---- - -### zh_pcf8574_init() - -Initializes the PCF8574 expander. - -**Parameters:** - -- `config` - Pointer to PCF8574 initialization configuration structure. Must not be NULL -- `handle` - Pointer to pointer to PCF8574 handle. Must be NULL - -**Returns:** - -- `ESP_OK` - Success -- `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_FAIL` - Configuration validation, I2C communication, or task creation error - ---- - -### zh_pcf8574_deinit() - -Deinitializes the PCF8574 expander. - -**Parameters:** - -- `handle` - Pointer to pointer to PCF8574 handle. Must not be NULL - -**Returns:** - -- `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 - ---- - -### zh_pcf8574_read() - -Reads the state of all GPIO pins of the expander. - -**Parameters:** - -- `handle` - Pointer to pointer to PCF8574 handle. Must not be NULL -- `reg` - Pointer to store GPIO status (bits 0-7). Must not be NULL - -**Returns:** - -- `ESP_OK` - Success -- `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 - ---- - -### zh_pcf8574_write() - -Sets the state of all output GPIO pins of the expander. - -**Parameters:** - -- `handle` - Pointer to pointer to PCF8574 handle. Must not be NULL -- `reg` - GPIO status (bits 0-7) - -**Returns:** - -- `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 - -**Note:** Only output GPIOs are affected. - ---- - -### zh_pcf8574_reset() - -Resets all GPIO pins of the expander to the initial state. - -**Parameters:** - -- `handle` - Pointer to pointer to PCF8574 handle. Must not be NULL - -**Returns:** - -- `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 - ---- - -### zh_pcf8574_read_gpio() - -Reads the state of one GPIO pin of the expander. - -**Parameters:** - -- `handle` - Pointer to pointer to PCF8574 handle. Must not be NULL -- `gpio` - GPIO number (ZH_PCF8574_GPIO_NUM_P0 ... ZH_PCF8574_GPIO_NUM_P7) -- `status` - Pointer to store GPIO status (true - HIGH, false - LOW). Must not be NULL - -**Returns:** - -- `ESP_OK` - Success -- `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). - ---- - -### zh_pcf8574_write_gpio() - -Sets the state of one output GPIO pin of the expander. - -**Parameters:** - -- `handle` - Pointer to pointer to PCF8574 handle. Must not be NULL -- `gpio` - GPIO number (ZH_PCF8574_GPIO_NUM_P0 ... ZH_PCF8574_GPIO_NUM_P7) -- `status` - GPIO status (true - HIGH, false - LOW) - -**Returns:** - -- `ESP_OK` - Success -- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL handle) -- `ESP_FAIL` - Invalid gpio, handle mismatch, or I2C communication error - -**Note:** Only output GPIOs are affected. - ---- - -### zh_pcf8574_get_stats() - -Gets error statistics since last reset. - -**Returns:** - -- Pointer to the statistics structure - ---- - -### zh_pcf8574_reset_stats() - -Resets error statistics counters. - ---- - -## Usage Examples - -### Basic Example: Single Expander - -```c -#include "zh_pcf8574.h" - -#define I2C_PORT (I2C_NUM_MAX - 1) - -zh_pcf8574_handle_t *pcf8574_handle = NULL; - -void print_gpio_status(const char *message, uint8_t reg) -{ - printf("%s", message); - for (uint8_t i = 0; i < 8; ++i) - { - printf("%c", (reg & 0x80) ? '1' : '0'); - reg <<= 1; - } - printf(".\n"); -} - -void app_main(void) -{ - esp_log_level_set("zh_pcf8574", ESP_LOG_ERROR); - esp_log_level_set("zh_vector", ESP_LOG_ERROR); - i2c_master_bus_config_t i2c_bus_config = { - .clk_source = I2C_CLK_SRC_DEFAULT, - .i2c_port = I2C_PORT, - .scl_io_num = GPIO_NUM_22, - .sda_io_num = GPIO_NUM_21, - .glitch_ignore_cnt = 7, - .flags.enable_internal_pullup = true, - }; - i2c_master_bus_handle_t i2c_bus_handle = NULL; - i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle); - zh_pcf8574_init_config_t config = ZH_PCF8574_INIT_CONFIG_DEFAULT(); - config.i2c_handle = i2c_bus_handle; - config.i2c_address = 0x38; - config.p0_gpio_work_mode = ZH_PCF8574_GPIO_INPUT; // P0 - input - zh_pcf8574_init(&config, &pcf8574_handle); - uint8_t reg = 0; - zh_pcf8574_read(&pcf8574_handle, ®); - print_gpio_status("GPIO status: ", reg); - printf("Set P7 to 1, P1 to 1 and P0 to 0.\n"); - zh_pcf8574_write(&pcf8574_handle, 0b10000010); - zh_pcf8574_read(&pcf8574_handle, ®); - print_gpio_status("GPIO status: ", reg); - printf("Set P0 to 0.\n"); - zh_pcf8574_write_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P0, ZH_PCF8574_GPIO_LOW); - bool gpio = 0; - zh_pcf8574_read_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P0, &gpio); - printf("P0 status: %d.\n", gpio); - printf("Set P1 to 0.\n"); - zh_pcf8574_write_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P1, ZH_PCF8574_GPIO_LOW); - zh_pcf8574_read_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P1, &gpio); - printf("P1 status: %d.\n", gpio); - zh_pcf8574_read(&pcf8574_handle, ®); - print_gpio_status("GPIO status: ", reg); - printf("Reset all GPIO.\n"); - zh_pcf8574_reset(&pcf8574_handle); - zh_pcf8574_read(&pcf8574_handle, ®); - print_gpio_status("GPIO status: ", reg); - const zh_pcf8574_stats_t *stats = zh_pcf8574_get_stats(); - printf("I2C errors: %ld.\n", stats->i2c_driver_error); -} -``` - ---- - -### Example with Interrupts - -```c -#include "zh_pcf8574.h" - -#define I2C_PORT (I2C_NUM_MAX - 1) - -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) -{ - zh_pcf8574_event_on_isr_t *event = event_data; - printf("Interrupt on device 0x%02X, GPIO %d, level %d, time %lld.\n", - event->i2c_address, event->gpio_number, event->gpio_level, event->interrupt_time); -} - -void app_main(void) -{ - esp_log_level_set("zh_pcf8574", ESP_LOG_ERROR); - esp_log_level_set("zh_vector", ESP_LOG_ERROR); - i2c_master_bus_config_t i2c_bus_config = { - .clk_source = I2C_CLK_SRC_DEFAULT, - .i2c_port = I2C_PORT, - .scl_io_num = GPIO_NUM_22, - .sda_io_num = GPIO_NUM_21, - .glitch_ignore_cnt = 7, - .flags.enable_internal_pullup = true, - }; - i2c_master_bus_handle_t i2c_bus_handle = NULL; - i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle); - esp_event_loop_create_default(); - esp_event_handler_instance_register(ZH_PCF8574, ESP_EVENT_ANY_ID, &zh_pcf8574_event_handler, NULL, NULL); - zh_pcf8574_init_config_t config = ZH_PCF8574_INIT_CONFIG_DEFAULT(); - config.i2c_handle = i2c_bus_handle; - config.i2c_address = 0x38; - config.p0_gpio_work_mode = ZH_PCF8574_GPIO_INPUT; // P0 - input for interrupts - config.interrupt_gpio = GPIO_NUM_14; // Connect INT to GPIO 14 - zh_pcf8574_init(&config, &pcf8574_handle); - for (;;) - { - const zh_pcf8574_stats_t *stats = zh_pcf8574_get_stats(); - printf("I2C errors: %ld.\n", stats->i2c_driver_error); - printf("Event errors: %ld.\n", stats->event_post_error); - printf("Interrupt queue: %ld.\n", stats->queue_overflow_error); - printf("Minimum free stack: %ld.\n", stats->min_stack_size); - vTaskDelay(60000 / portTICK_PERIOD_MS); - } -} -``` - ---- - -## Technical Specifications - -| Parameter | Value | -| ----------- | ------- | -| **Device Type** | 8-bit I2C GPIO expander | -| **Models** | PCF8574, PCF8574A | -| **Number of devices on bus** | Up to 16 (addresses 0x20-0x27, 0x38-0x3F) | -| **Number of GPIO** | 8 (P0-P7) | -| **I2C Address** | 0x20-0x27 (PCF8574), 0x38-0x3F (PCF8574A) | -| **I2C Frequency** | Up to 100 kHz | -| **GPIO Modes** | Input/Output (configurable per pin) | -| **Interrupts** | Yes (negative edge) | -| **ESP-IDF Version** | >= 5.0 | -| **Platform** | ESP32 series | -| **Language** | C (C99) | - ---- - -## Error Codes - -| Error Code | Description | -| ------------ | ------------- | -| `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` | Handle does not correspond to a registered device | -| `ESP_ERR_NO_MEM` | Insufficient memory | -| `ESP_FAIL` | General failure (I2C communication error, initialization error, etc.) | - ---- - -## Contributing - -Contributions are welcome! To contribute: - -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/AmazingFeature`) -3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) -4. Push to the branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request - -Please ensure your code follows the existing style and includes appropriate documentation. - ---- - -## License - -This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details. - -### Apache License, Version 2.0 - -Copyright (c) 2026 Alexey Zholtikov - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - ---- - -## Additional Notes - -- **I2C Pull-up Resistors**: Ensure pull-up resistors are connected to SDA and SCL lines (typically 4.7kΩ) -- **Input GPIOs**: All input GPIOs are internally pulled up to VCC (~100kΩ resistor) -- **Interrupts**: All INT outputs of expanders must be connected to one GPIO on ESP32 -- **I2C_ISR_IRAM_SAFE**: For correct operation, enable `I2C_ISR_IRAM_SAFE` and `I2C_MASTER_ISR_HANDLER_IN_IRAM` in menuconfig -- **GPIO_CTRL_FUNC_IN_IRAM**: For GPIO interrupts, enable `GPIO_CTRL_FUNC_IN_IRAM` in menuconfig - ---- - -"*Generated for zh_pcf8574 v3.0.0*" diff --git a/WIKI_RU.md b/WIKI_RU.md deleted file mode 100644 index 648dbc4..0000000 --- a/WIKI_RU.md +++ /dev/null @@ -1,500 +0,0 @@ -# zh_pcf8574 - Компонент 8-битного расширителя GPIO PCF8574(A) для ESP-IDF - -## Содержание - -- [Обзор](#обзор) -- [Возможности](#возможности) -- [Установка](#установка) -- [Справочник API](#справочник-api) -- [Примеры использования](#примеры-использования) -- [Технические характеристики](#технические-характеристики) -- [Коды ошибок](#коды-ошибок) -- [Вклад в проект](#вклад-в-проект) -- [Лицензия](#лицензия) - ---- - -## Обзор - -`zh_pcf8574` - это компонент ESP-IDF для 8-битных расширителей GPIO PCF8574 и PCF8574A. Он предоставляет удобный API для работы с расширителем GPIO через шину I2C. Компонент поддерживает до 16 расширителей на одной шине I2C и может генерировать прерывания при изменении состояния входных GPIO. - -Компонент разработан специально для микроконтроллеров ESP32 и использует API драйвера I2C ESP-IDF v5.0+. - ---- - -## Возможности - -1. **Поддержка 16 расширителей**: До 16 PCF8574(A) на одной шине I2C (адреса 0x20-0x27 и 0x38-0x3F) -2. **Режимы работы GPIO**: Поддержка выходных и входных режимов для каждого из 8 GPIO -3. **Генерация прерываний**: Поддержка прерываний от входных GPIO (отрицательный фронт) -4. **Статистика ошибок**: Встроенные счетчики ошибок I2C, событий, векторов и переполнения очереди -5. **Потокобезопасность**: Использует драйвер I2C ESP-IDF и FreeRTOS -6. **Минимальные накладные расходы**: Низкие требования к памяти и процессору -7. **Простой API**: Легкое чтение/запись состояния всех GPIO и отдельных пинов - ---- - -## Установка - -Перейдите в каталог компонентов вашего проекта: - -```bash -cd ../ваш_проект/components -``` - -Клонируйте репозиторий: - -```bash -git clone https://github.com/aZholtikov/zh_pcf8574 -``` - -В вашем приложении подключите заголовочный файл: - -```c -#include "zh_pcf8574.h" -``` - -Компонент будет автоматически собран вместе с вашим проектом. - -### Обязательные настройки в menuconfig - -Для корректной работы компонента включите следующие настройки в menuconfig: - -```text -GPIO_CTRL_FUNC_IN_IRAM -I2C_ISR_IRAM_SAFE -I2C_MASTER_ISR_HANDLER_IN_IRAM -``` - ---- - -## Справочник API - -### Макросы - -```c -#define ZH_PCF8574_GPIO_OUTPUT false -#define ZH_PCF8574_GPIO_INPUT true -#define ZH_PCF8574_GPIO_LOW false -#define ZH_PCF8574_GPIO_HIGH true -``` - ---- - -### Структура zh_pcf8574_init_config_t - -```c -typedef struct -{ - i2c_master_bus_handle_t i2c_handle; // Уникальный дескриптор шины I2C - uint32_t i2c_frequency; // Частота I2C расширителя (макс. 100000 Гц) - uint32_t stack_size; // Размер стека задачи обработки прерываний - uint8_t task_priority; // Приоритет задачи обработки прерываний - uint8_t i2c_address; // Адрес устройства расширителя I2C (0x20-0x27 или 0x38-0x3F) - bool p0_gpio_work_mode; // Режим работы GPIO P0 (false - output, true - input) - bool p1_gpio_work_mode; // Режим работы GPIO P1 - bool p2_gpio_work_mode; // Режим работы GPIO P2 - bool p3_gpio_work_mode; // Режим работы GPIO P3 - bool p4_gpio_work_mode; // Режим работы GPIO P4 - bool p5_gpio_work_mode; // Режим работы GPIO P5 - bool p6_gpio_work_mode; // Режим работы GPIO P6 - bool p7_gpio_work_mode; // Режим работы GPIO P7 - gpio_num_t interrupt_gpio; // GPIO для прерываний (GPIO_NUM_MAX - отключить) -} zh_pcf8574_init_config_t; -``` - -Используйте макрос `ZH_PCF8574_INIT_CONFIG_DEFAULT()` для инициализации значениями по умолчанию: - -- `i2c_frequency`: 100000 Гц -- `i2c_address`: 0xFF -- `p0_gpio_work_mode` ... `p7_gpio_work_mode`: `ZH_PCF8574_GPIO_OUTPUT` -- `interrupt_gpio`: `GPIO_NUM_MAX` - ---- - -### Структура zh_pcf8574_handle_t - -```c -typedef struct _zh_pcf8574_handle_t zh_pcf8574_handle_t; -``` - -Непрозрачный дескриптор экземпляра устройства PCF8574. Внутренняя структура минимальна — хранит только I2C-адрес; полное состояние устройства поддерживается во внутреннем векторе. - ---- - -### Структура zh_pcf8574_stats_t - -```c -typedef struct -{ - uint32_t i2c_driver_error; // Количество ошибок драйвера I2C - uint32_t event_post_error; // Количество ошибок отправки событий - uint32_t vector_error; // Количество ошибок вектора - uint32_t queue_overflow_error; // Количество переполнений очереди - uint32_t min_stack_size; // Минимальный свободный стек задачи -} zh_pcf8574_stats_t; -``` - ---- - -### Структура zh_pcf8574_event_on_isr_t - -```c -typedef struct -{ - uint64_t interrupt_time; // Время прерывания (мкс) - zh_pcf8574_gpio_num_t gpio_number; // Номер GPIO, вызвавшего прерывание - uint8_t i2c_address; // I2C адрес расширителя - bool gpio_level; // Уровень GPIO при прерывании -} zh_pcf8574_event_on_isr_t; -``` - ---- - -### zh_pcf8574_init() - -Инициализирует расширитель PCF8574. - -**Параметры:** - -- `config` - Указатель на структуру конфигурации инициализации PCF8574. Не должен быть NULL -- `handle` - Указатель на указатель на дескриптор PCF8574. Должен быть NULL - -**Возвращает:** - -- `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL config, handle или *handle) -- `ESP_ERR_INVALID_STATE` - Расширитель уже инициализирован -- `ESP_ERR_NO_MEM` - Недостаточно памяти -- `ESP_FAIL` - Ошибка валидации конфигурации, I2C-связи или создания задачи - ---- - -### zh_pcf8574_deinit() - -Деинициализирует расширитель PCF8574. - -**Параметры:** - -- `handle` - Указатель на указатель на дескриптор PCF8574. Не должен быть NULL - -**Возвращает:** - -- `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или *handle) -- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству -- `ESP_FAIL` - Ошибка удаления I2C или операций с вектором - ---- - -### zh_pcf8574_read() - -Считывает состояние всех GPIO расширителя. - -**Параметры:** - -- `handle` - Указатель на указатель на дескриптор PCF8574. Не должен быть NULL -- `reg` - Указатель для хранения состояния GPIO (биты 0-7). Не должен быть NULL - -**Возвращает:** - -- `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle, *handle или reg) -- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству -- `ESP_FAIL` - Ошибка I2C-связи или операций с вектором - ---- - -### zh_pcf8574_write() - -Устанавливает состояние всех выходных GPIO расширителя. - -**Параметры:** - -- `handle` - Указатель на указатель на дескриптор PCF8574. Не должен быть NULL -- `reg` - Состояние GPIO (биты 0-7) - -**Возвращает:** - -- `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или *handle) -- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству -- `ESP_FAIL` - Ошибка I2C-связи или операций с вектором - -**Примечание:** Только на выходные GPIO влияет. - ---- - -### zh_pcf8574_reset() - -Сбрасывает все GPIO расширителя в начальное состояние. - -**Параметры:** - -- `handle` - Указатель на указатель на дескриптор PCF8574. Не должен быть NULL - -**Возвращает:** - -- `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или *handle) -- `ESP_ERR_NOT_FOUND` - Handle не соответствует зарегистрированному устройству -- `ESP_FAIL` - Ошибка I2C-связи или операций с вектором - ---- - -### zh_pcf8574_read_gpio() - -Считывает состояние одного GPIO расширителя. - -**Параметры:** - -- `handle` - Указатель на указатель на дескриптор PCF8574. Не должен быть NULL -- `gpio` - Номер GPIO (ZH_PCF8574_GPIO_NUM_P0 ... ZH_PCF8574_GPIO_NUM_P7) -- `status` - Указатель для хранения состояния GPIO (true - HIGH, false - LOW). Не должен быть NULL - -**Возвращает:** - -- `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle или status) -- `ESP_FAIL` - Неверный номер gpio, handle не соответствует устройству или I2C-связь - -**Примечание:** Для входных GPIO всегда будет 1 (HIGH). - ---- - -### zh_pcf8574_write_gpio() - -Устанавливает состояние одного выходного GPIO расширителя. - -**Параметры:** - -- `handle` - Указатель на указатель на дескриптор PCF8574. Не должен быть NULL -- `gpio` - Номер GPIO (ZH_PCF8574_GPIO_NUM_P0 ... ZH_PCF8574_GPIO_NUM_P7) -- `status` - Состояние GPIO (true - HIGH, false - LOW) - -**Возвращает:** - -- `ESP_OK` - Успех -- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL handle) -- `ESP_FAIL` - Неверный номер gpio, handle не соответствует устройству или I2C-связь - -**Примечание:** Влияет только на выходные GPIO. - ---- - -### zh_pcf8574_get_stats() - -Получает статистику ошибок с момента последнего сброса. - -**Возвращает:** - -- Указатель на структуру статистики - ---- - -### zh_pcf8574_reset_stats() - -Сбрасывает счетчики статистики ошибок. - ---- - -## Примеры использования - -### Базовый пример: Один расширитель - -```c -#include "zh_pcf8574.h" - -#define I2C_PORT (I2C_NUM_MAX - 1) - -zh_pcf8574_handle_t *pcf8574_handle = NULL; - -void print_gpio_status(const char *message, uint8_t reg) -{ - printf("%s", message); - for (uint8_t i = 0; i < 8; ++i) - { - printf("%c", (reg & 0x80) ? '1' : '0'); - reg <<= 1; - } - printf(".\n"); -} - -void app_main(void) -{ - esp_log_level_set("zh_pcf8574", ESP_LOG_ERROR); - esp_log_level_set("zh_vector", ESP_LOG_ERROR); - i2c_master_bus_config_t i2c_bus_config = { - .clk_source = I2C_CLK_SRC_DEFAULT, - .i2c_port = I2C_PORT, - .scl_io_num = GPIO_NUM_22, - .sda_io_num = GPIO_NUM_21, - .glitch_ignore_cnt = 7, - .flags.enable_internal_pullup = true, - }; - i2c_master_bus_handle_t i2c_bus_handle = NULL; - i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle); - zh_pcf8574_init_config_t config = ZH_PCF8574_INIT_CONFIG_DEFAULT(); - config.i2c_handle = i2c_bus_handle; - config.i2c_address = 0x38; - config.p0_gpio_work_mode = ZH_PCF8574_GPIO_INPUT; // P0 - вход - zh_pcf8574_init(&config, &pcf8574_handle); - uint8_t reg = 0; - zh_pcf8574_read(&pcf8574_handle, ®); - print_gpio_status("Статус GPIO: ", reg); - printf("Установить P7 в 1, P1 в 1 и P0 в 0.\n"); - zh_pcf8574_write(&pcf8574_handle, 0b10000010); - zh_pcf8574_read(&pcf8574_handle, ®); - print_gpio_status("Статус GPIO: ", reg); - printf("Установить P0 в 0.\n"); - zh_pcf8574_write_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P0, ZH_PCF8574_GPIO_LOW); - bool gpio = 0; - zh_pcf8574_read_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P0, &gpio); - printf("Статус P0: %d.\n", gpio); - printf("Установить P1 в 0.\n"); - zh_pcf8574_write_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P1, ZH_PCF8574_GPIO_LOW); - zh_pcf8574_read_gpio(&pcf8574_handle, ZH_PCF8574_GPIO_NUM_P1, &gpio); - printf("Статус P1: %d.\n", gpio); - zh_pcf8574_read(&pcf8574_handle, ®); - print_gpio_status("Статус GPIO: ", reg); - printf("Сброс всех GPIO.\n"); - zh_pcf8574_reset(&pcf8574_handle); - zh_pcf8574_read(&pcf8574_handle, ®); - print_gpio_status("Статус GPIO: ", reg); - const zh_pcf8574_stats_t *stats = zh_pcf8574_get_stats(); - printf("Ошибки I2C: %ld.\n", stats->i2c_driver_error); -} -``` - ---- - -### Пример с прерываниями - -```c -#include "zh_pcf8574.h" - -#define I2C_PORT (I2C_NUM_MAX - 1) - -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) -{ - zh_pcf8574_event_on_isr_t *event = event_data; - printf("Прерывание на устройстве 0x%02X, GPIO %d, уровень %d, время %lld.\n", - event->i2c_address, event->gpio_number, event->gpio_level, event->interrupt_time); -} - -void app_main(void) -{ - esp_log_level_set("zh_pcf8574", ESP_LOG_ERROR); - esp_log_level_set("zh_vector", ESP_LOG_ERROR); - i2c_master_bus_config_t i2c_bus_config = { - .clk_source = I2C_CLK_SRC_DEFAULT, - .i2c_port = I2C_PORT, - .scl_io_num = GPIO_NUM_22, - .sda_io_num = GPIO_NUM_21, - .glitch_ignore_cnt = 7, - .flags.enable_internal_pullup = true, - }; - i2c_master_bus_handle_t i2c_bus_handle = NULL; - i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle); - esp_event_loop_create_default(); - esp_event_handler_instance_register(ZH_PCF8574, ESP_EVENT_ANY_ID, &zh_pcf8574_event_handler, NULL, NULL); - zh_pcf8574_init_config_t config = ZH_PCF8574_INIT_CONFIG_DEFAULT(); - config.i2c_handle = i2c_bus_handle; - config.i2c_address = 0x38; - config.p0_gpio_work_mode = ZH_PCF8574_GPIO_INPUT; // P0 - вход для прерываний - config.interrupt_gpio = GPIO_NUM_14; // Подключение INT к GPIO 14 - zh_pcf8574_init(&config, &pcf8574_handle); - for (;;) - { - const zh_pcf8574_stats_t *stats = zh_pcf8574_get_stats(); - printf("Ошибки I2C: %ld.\n", stats->i2c_driver_error); - printf("Ошибки событий: %ld.\n", stats->event_post_error); - printf("Очередь прерываний: %ld.\n", stats->queue_overflow_error); - printf("Минимальный свободный стек: %ld.\n", stats->min_stack_size); - vTaskDelay(60000 / portTICK_PERIOD_MS); - } -} -``` - ---- - -## Технические характеристики - -| Параметр | Значение | -| ---------- | ---------- | -| **Тип устройства** | 8-битный I2C GPIO расширитель | -| **Модели** | PCF8574, PCF8574A | -| **Количество устройств на шине** | До 16 (адреса 0x20-0x27, 0x38-0x3F) | -| **Количество GPIO** | 8 (P0-P7) | -| **Адрес I2C** | 0x20-0x27 (PCF8574), 0x38-0x3F (PCF8574A) | -| **Частота I2C** | До 100 кГц | -| **Режимы GPIO** | Вход/выход (настраиваемые для каждого пина) | -| **Прерывания** | Да (отрицательный фронт) | -| **Версия ESP-IDF** | >= 5.0 | -| **Платформа** | Семейство ESP32 | -| **Язык** | C (C99) | - ---- - -## Коды ошибок - -| Код ошибки | Описание | -| ------------ | ---------- | -| `ESP_OK` | Операция выполнена успешно | -| `ESP_ERR_INVALID_ARG` | Неверный аргумент (NULL указатель или неверная конфигурация) | -| `ESP_ERR_INVALID_STATE` | Устройство не инициализировано или уже инициализировано | -| `ESP_ERR_NOT_FOUND` | Handle не соответствует зарегистрированному устройству | -| `ESP_ERR_NO_MEM` | Недостаточно памяти | -| `ESP_FAIL` | Общая ошибка (ошибка связи I2C, инициализации и т.д.) | - ---- - -## Вклад в проект - -Вклад приветствуется! Чтобы внести свой вклад: - -1. Сделайте форк репозитория -2. Создайте ветку функции (`git checkout -b feature/AmazingFeature`) -3. Закоммитьте ваши изменения (`git commit -m 'Add some AmazingFeature'`) -4. Отправьте в ветку (`git push origin feature/AmazingFeature`) -5. Откройте Pull Request - -Пожалуйста, убедитесь, что ваш код следует существующему стилю и включает соответствующую документацию. - ---- - -## Лицензия - -Этот проект лицензирован по лицензии Apache, версия 2.0 - см. файл [LICENSE](LICENSE) для подробной информации. - -### Apache License, Version 2.0 - -Авторское право (c) 2026 Алексей Жолтиков - -Лицензировано по лицензии Apache License, Version 2.0 (далее — "Лицензия"); -вы не можете использовать этот файл, кроме случаев, предусмотренных Лицензией. -Копию Лицензии можно получить по адресу: - - http://www.apache.org/licenses/LICENSE-2.0 - -Если иное не требуется действующим законодательством или не согласовано в письменном виде, -программное обеспечение, распространяемое по Лицензии, распространяется на условиях "КАК ЕСТЬ", -БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, явных или подразумеваемых, включая, но не ограничиваясь, гарантии -ТОВАРНОГО СОСТОЯНИЯ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ. -Смотрите Лицензию для получения конкретных прав и ограничений. - ---- - -## Дополнительные заметки - -- **Подтягивающие резисторы I2C**: Убедитесь, что к линиям SDA и SCL подключены подтягивающие резисторы (обычно 4.7кОм) -- **Входные GPIO**: Все входные GPIO всегда подтянуты к питанию (внутренний подтягивающий резистор ~100кОм) -- **Прерывания**: Все выводы INT расширителей должны быть подключены к одному GPIO на ESP32 -- **I2C_ISR_IRAM_SAFE**: Для правильной работы включите `I2C_ISR_IRAM_SAFE` и `I2C_MASTER_ISR_HANDLER_IN_IRAM` в menuconfig -- **GPIO_CTRL_FUNC_IN_IRAM**: Для работы прерываний GPIO включите `GPIO_CTRL_FUNC_IN_IRAM` в menuconfig - ---- - -"*Сгенерировано для zh_pcf8574 v3.0.0*"