Skip to content

Commit

Permalink
feat(repo): refactor with esp-lib-utils
Browse files Browse the repository at this point in the history
  • Loading branch information
Lzw655 committed Dec 6, 2024
1 parent bccbedd commit a227c60
Show file tree
Hide file tree
Showing 44 changed files with 1,969 additions and 1,239 deletions.
1 change: 0 additions & 1 deletion .codespellrc
Original file line number Diff line number Diff line change
@@ -1,2 +1 @@
[codespell]
skip = ./src/touch/base/esp_lcd_touch_xpt2046.c
2 changes: 1 addition & 1 deletion .github/workflows/build_test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ jobs:
container: espressif/idf:${{ matrix.idf_ver }}
steps:
- uses: actions/checkout@v3
- name: Build ESP_IOExpander Test Application
- name: Build Test Application
env:
IDF_TARGET: ${{ matrix.idf_target }}
working-directory: test_apps
Expand Down
124 changes: 90 additions & 34 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,62 +2,106 @@

**Latest Arduino Library Version**: [![GitHub Release](https://img.shields.io/github/v/release/esp-arduino-libs/ESP32_IO_Expander)](https://github.com/esp-arduino-libs/ESP32_IO_Expander/releases)

**Latest Espressif Component Version**: [![Espressif Release](https://components.espressif.com/components/espressif/ESP32_IO_Expander/badge.svg)](https://components.espressif.com/components/espressif/ESP32_IO_Expander)
**Latest Espressif Component Version**: [![Espressif Release](https://components.espressif.com/components/espressif/esp32_io_expander/badge.svg)](https://components.espressif.com/components/espressif/esp32_io_expander)

# ESP32_IO_Expander

ESP32_IO_Expander is a library designed for driving [IO expander chips](#supported-drivers) using ESP32 SoCs.
## Overview

`ESP32_IO_Expander` is a library designed for driving [IO expander chips](#supported-drivers) using ESP SoCs. It encapsulates various components from the [Espressif Components Registry](https://components.espressif.com/) and includes the following features:

* Supports various IO expander chips, such as TCA95xx, HT8574, and CH422G.
* Supports controlling individual IO pin with functions like `pinMode()`, `digitalWrite()`, and `digitalRead()`.
* Supports controlling multiple IO pins simultaneously with functions like `multiPinMode()`, `multiDigitalWrite()`, and `multiDigitalRead()`.
* Compatible with the `Arduino`, `ESP-IDF` and `MicroPython` for compilation.

## Table of Contents

- [ESP32\_IO\_Expander](#esp32_io_expander)
- [Overview](#overview)
- [Table of Contents](#table-of-contents)
- [Supported Drivers](#supported-drivers)
- [How to Use](#how-to-use)
- [ESP-IDF Framework](#esp-idf-framework)
- [Dependencies and Versions](#dependencies-and-versions)
- [Adding to Project](#adding-to-project)
- [Configuration Instructions](#configuration-instructions)
- [Arduino IDE](#arduino-ide)
- [Dependencies and Versions](#dependencies-and-versions-1)
- [Installing the Library](#installing-the-library)
- [Configuration Instructions](#configuration-instructions-1)
- [Examples](#examples)
- [Detailed Usage](#detailed-usage)
- [FAQ](#faq)
- [Where is the directory for Arduino libraries?](#where-is-the-directory-for-arduino-libraries)
- [How to Install ESP32\_IO\_Expander in Arduino IDE?](#how-to-install-esp32_io_expander-in-arduino-ide)

ESP32_IO_Expander encapsulates various components from the [Espressif Components Registry](https://components.espressif.com/). It is developed based on [arduino-esp32](https://github.com/espressif/arduino-esp32) or [esp-idf](https://github.com/espressif/esp-idf), and can be easily downloaded and integrated into the Arduino IDE.
## Supported Drivers

## Features
| **Driver** | **Version** |
| ---------------------------------------------------------------------------------------------------- | ----------- |
| [esp_io_expander](https://components.espressif.com/components/espressif/esp_io_expander) | 1.0.1 |
| [TCA95XX_8BIT](https://components.espressif.com/components/espressif/esp_io_expander_tca9554) | 1.0.1 |
| [TCA95XX_16BIT](https://components.espressif.com/components/espressif/esp_io_expander_tca95xx_16bit) | 1.0.0 |
| [HT8574](https://components.espressif.com/components/espressif/esp_io_expander_ht8574) | 1.0.0 |
| CH422G | x |

* Supports various IO expander chips.
* Supports controlling individual IO pin (using pinMode(), digitalRead(), and digitalWrite() functions).
* Supports controlling multiple IO pins simultaneously.
* Supports building on the Arduino IDE and the ESP-IDF framework.
## How to Use

## Supported Drivers
### ESP-IDF Framework

| **Driver** | **Version** |
| ------------------------------------------------------------------------------------------------------ | ----------- |
| [esp_io_expander](https://components.espressif.com/components/espressif/esp_io_expander) | 1.0.1 |
| [TCA95xx (8bit)](https://components.espressif.com/components/espressif/esp_io_expander_tca9554) | 1.0.1 |
| [TCA95xx (16bit)](https://components.espressif.com/components/espressif/esp_io_expander_tca95xx_16bit) | 1.0.0 |
| [HT8574](https://components.espressif.com/components/espressif/esp_io_expander_ht8574) | 1.0.0 |
| CH422G | x |
#### Dependencies and Versions

## Dependencies Version
| **Dependency** | **Version** |
| ------------------------------------------------------------------ | -------------------- |
| [esp-idf](https://github.com/espressif/esp-idf) | >= 5.1 |
| [esp-lib-utils](https://github.com/esp-arduino-libs/esp-lib-utils) | >= 0.1.0 && <= 0.2.0 |

### Arduino
#### Adding to Project

| **Name** | **Version** |
| ----------------------------------------------------------- | ----------- |
| [arduino-esp32](https://github.com/espressif/arduino-esp32) | >= v3.0.0 |
`ESP32_IO_Expander` has been uploaded to the [Espressif Component Registry](https://components.espressif.com/), and users can add it to their project using the `idf.py add-dependency` command, for example:

### ESP-IDF
```bash
idf.py add-dependency "espressif/ESP32_IO_Expander"
```

| **Name** | **Version** |
| ----------------------------------------------- | ----------- |
| [esp-idf](https://github.com/espressif/esp-idf) | >= v5.1 |
Alternatively, users can create or modify the *idf_component.yml* file in the project directory. For more details, please refer to the [Espressif Documentation - IDF Component Manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html).

## How to Use
#### Configuration Instructions

Since `ESP32_IO_Expander` depends on the `esp-lib-utils` library which implements the `logging`, `checking`, and `memory` functions, to configure it when using ESP-IDF, please refer to the [instructions](https://github.com/esp-arduino-libs/esp-lib-utils#configuration-instructions).

### Arduino IDE

#### Dependencies and Versions

| **Dependency** | **Version** |
| ------------------------------------------------------------------ | -------------------- |
| [arduino-esp32](https://github.com/espressif/arduino-esp32) | >= v3.0.0 |
| [esp-lib-utils](https://github.com/esp-arduino-libs/esp-lib-utils) | >= 0.1.0 && <= 0.2.0 |

For information on how to use the library in the Arduino IDE, please refer to the documentation for [Arduino IDE v1.x.x](https://docs.arduino.cc/software/ide-v1/tutorials/installing-libraries) or [Arduino IDE v2.x.x](https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-installing-a-library).
#### Installing the Library

For installation of the `ESP32_IO_Expander` library, refer to [How to Install ESP32_IO_Expander in Arduino IDE](#how-to-install-ESP32_IO_Expander-in-arduino-ide).

#### Configuration Instructions

Since `ESP32_IO_Expander` depends on the `esp-lib-utils` library which implements the `logging`, `checking`, and `memory` functions, to configure it when using Arduino, please refer to the [instructions](https://github.com/esp-arduino-libs/esp-lib-utils#configuration-instructions-1).

### Examples

* [Test Functions](examples/TestFunctions): Demonstrates how to use ESP32_IO_Expander and test all functions.
* [Test CH422G](examples/TestCH422G): Demonstrates how to use ESP32_IO_Expander with the CH422G chip.
* [General](examples/general): Demonstrates how to use `ESP32_IO_Expander` and test general functions.
* [CH422G](examples/ch422g): Demonstrates how to use `ESP32_IO_Expander` specifically with the CH422G chip.

### Detailed Usage

```cpp
#include <ESP_IOExpander_Library.h>
#include <esp_io_expander.hpp>

// Create and initialize an ESP_IOExpander object according to the chip type
ESP_IOExpander *expander = new ESP_IOExpander_TCA95xx_8bit(EXAMPLE_I2C_NUM_0, ESP_IO_EXPANDER_I2C_TCA9554_ADDRESS_000,
EXAMPLE_I2C_SCL_PIN, EXAMPLE_I2C_SDA_PIN);
// Create and initialize the IO expander chip, such as TCA95XX_8BIT
esp_expander::Base *expander = new esp_expander::TCA95XX_8BIT(
EXAMPLE_I2C_SCL_PIN, EXAMPLE_I2C_SDA_PIN, ESP_IO_EXPANDER_I2C_TCA9554_ADDRESS_000
);
expander->init();
expander->begin();

Expand All @@ -75,6 +119,18 @@ expander->multiDigitalWrite(IO_EXPANDER_PIN_NUM_0 | IO_EXPANDER_PIN_NUM_1, LOW);
expander->multiPinMode(IO_EXPANDER_PIN_NUM_0 | IO_EXPANDER_PIN_NUM_1, INPUT);
uint32_t level = expander->multiDigitalRead(IO_EXPANDER_PIN_NUM_2 | IO_EXPANDER_PIN_NUM_3);

// Release the ESP_IOExpander object
// Release the Base object
delete expander;
```
## FAQ
### Where is the directory for Arduino libraries?
Users can find and modify the directory path for Arduino libraries by selecting `File` > `Preferences` > `Settings` > `Sketchbook location` from the menu bar in the Arduino IDE.
### How to Install ESP32_IO_Expander in Arduino IDE?
- **If users want to install online**, navigate to `Sketch` > `Include Library` > `Manage Libraries...` in the Arduino IDE, then search for `ESP32_IO_Expander` and click the `Install` button to install it.
- **If users want to install manually**, download the required version of the `.zip` file from [ESP32_IO_Expander](https://github.com/esp-arduino-libs/ESP32_IO_Expander), then navigate to `Sketch` > `Include Library` > `Add .ZIP Library...` in the Arduino IDE, select the downloaded `.zip` file, and click `Open` to install it.
- Users can also refer to the guides on library installation in the [Arduino IDE v1.x.x](https://docs.arduino.cc/software/ide-v1/tutorials/installing-libraries) or [Arduino IDE v2.x.x](https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-installing-a-library) documentation.
88 changes: 0 additions & 88 deletions examples/TestFunctions/TestFunctions.ino

This file was deleted.

Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/**
* | Supported IO Expanders | CH422G |
* | Supported IO Expanders | CH422G |
* | ------------------------- | ------ |
*
* # CH422G Test Example
Expand Down Expand Up @@ -38,25 +38,23 @@
*/

#include <Arduino.h>
#include <ESP_IOExpander_Library.h>
#include <esp_io_expander.hpp>

#define EXAMPLE_I2C_NUM (0)
#define EXAMPLE_I2C_SDA_PIN (8)
#define EXAMPLE_I2C_SCL_PIN (9)
#define EXAMPLE_I2C_ADDR (ESP_IO_EXPANDER_I2C_CH422G_ADDRESS)

ESP_IOExpander_CH422G *expander = NULL;
esp_expander::CH422G *expander = NULL;

void setup() {
Serial.begin(115200);
delay(1000);
Serial.println("Test begin");

expander = new ESP_IOExpander_CH422G((i2c_port_t)EXAMPLE_I2C_NUM, EXAMPLE_I2C_ADDR, EXAMPLE_I2C_SCL_PIN, EXAMPLE_I2C_SDA_PIN);
expander = new esp_expander::CH422G(EXAMPLE_I2C_SCL_PIN, EXAMPLE_I2C_SDA_PIN, EXAMPLE_I2C_ADDR);
expander->init();
expander->begin();

/* For CH422G */
Serial.println("Set the OC pin to push-pull output mode.");
expander->enableOC_PushPull();

Expand Down
83 changes: 83 additions & 0 deletions examples/general/general.ino
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
#include <Arduino.h>
#include <esp_io_expander.hpp>

/* The following default configurations are for the board 'Espressif: ESP32_S3_LCD_EV_BOARD_V1_5, TCA9554' */
/**
* Choose one of the following chip names:
* - TCA95XX_8BIT
* - TCA95XX_16BIT
* - HT8574
* - CH422G
*/
#define EXAMPLE_CHIP_NAME TCA95XX_8BIT
#define EXAMPLE_I2C_SDA_PIN (47)
#define EXAMPLE_I2C_SCL_PIN (48)
#define EXAMPLE_I2C_ADDR (ESP_IO_EXPANDER_I2C_TCA9554_ADDRESS_000) // Change this value according to the
// hardware address

#define _EXAMPLE_CHIP_CLASS(name, ...) esp_expander::name(__VA_ARGS__)
#define EXAMPLE_CHIP_CLASS(name, ...) _EXAMPLE_CHIP_CLASS(name, ##__VA_ARGS__)

esp_expander::Base *expander = nullptr;

void setup()
{
Serial.begin(115200);
Serial.println("Test begin");

/**
* Taking `TCA95XX_8BIT` as an example, the following is the code after macro expansion:
* expander = new esp_expander::TCA95XX_8BIT((48), (47), (0x20))
*/
expander = new EXAMPLE_CHIP_CLASS(
EXAMPLE_CHIP_NAME, EXAMPLE_I2C_SCL_PIN, EXAMPLE_I2C_SDA_PIN, ESP_IO_EXPANDER_I2C_TCA9554_ADDRESS_000
);
expander->init();
expander->begin();

/* For CH422G */
// static_cast<esp_expander::CH422G *>(expander)->enableOC_OpenDrain();
// static_cast<esp_expander::CH422G *>(expander)->enableOC_PushPull();
// static_cast<esp_expander::CH422G *>(expander)->enableAllIO_Input();
// static_cast<esp_expander::CH422G *>(expander)->enableAllIO_Output();

Serial.println("Original status:");
expander->printStatus();

expander->pinMode(0, OUTPUT);
expander->pinMode(1, OUTPUT);
expander->multiPinMode(IO_EXPANDER_PIN_NUM_2 | IO_EXPANDER_PIN_NUM_3, OUTPUT);

Serial.println("Set pint 0-3 to output mode:");
expander->printStatus();

expander->digitalWrite(0, LOW);
expander->digitalWrite(1, LOW);
expander->multiDigitalWrite(IO_EXPANDER_PIN_NUM_2 | IO_EXPANDER_PIN_NUM_3, LOW);

Serial.println("Set pint 0-3 to low level:");
expander->printStatus();

expander->pinMode(0, INPUT);
expander->pinMode(1, INPUT);
expander->multiPinMode(IO_EXPANDER_PIN_NUM_2 | IO_EXPANDER_PIN_NUM_3, INPUT);

Serial.println("Set pint 0-3 to input mode:");
expander->printStatus();
}

int level[4] = {0, 0, 0, 0};
uint32_t level_temp;

void loop()
{
// Read pin 0-3 level
level[0] = expander->digitalRead(0);
level[1] = expander->digitalRead(1);
level_temp = expander->multiDigitalRead(IO_EXPANDER_PIN_NUM_2 | IO_EXPANDER_PIN_NUM_3);
level[2] = level_temp & IO_EXPANDER_PIN_NUM_2 ? HIGH : LOW;
level[3] = level_temp & IO_EXPANDER_PIN_NUM_3 ? HIGH : LOW;
Serial.printf("Pin level: %d, %d, %d, %d\n", level[0], level[1], level[2], level[3]);

delay(1000);
}
7 changes: 5 additions & 2 deletions idf_component.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
version: "0.1.0"
description: ESP32_IO_Expander is a library designed for driving IO expander chips using ESP32 SoCs
version: "1.0.0"
description: ESP32_IO_Expander is a library designed for driving IO expander chips using ESP SoCs
url: https://github.com/esp-arduino-libs/ESP32_IO_Expander
repository: https://github.com/esp-arduino-libs/ESP32_IO_Expander.git
issues: https://github.com/esp-arduino-libs/ESP32_IO_Expander/issues
dependencies:
idf: ">=5.1"
espressif/esp-lib-utils:
version: ">=0.1.0,<=0.2.0"
public: true
Loading

0 comments on commit a227c60

Please sign in to comment.