esp-arduino-libs · Lzw655 · Dec 6, 2024 · Dec 5, 2024 · Dec 6, 2024
diff --git a/.codespellrc b/.codespellrc
@@ -1,2 +1 @@
 [codespell]
-skip = ./src/touch/base/esp_lcd_touch_xpt2046.c
diff --git a/.github/workflows/build_test.yml b/.github/workflows/build_test.yml
@@ -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

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # ChangeLog
 
+## v1.0.0 - 2024-12-06
+
+### Enhancements:
+
+* feat(repo): refactor with esp-lib-utils
+* feat(repo): support micropython
+
 ## v0.1.0 - 2024-11-05
 
 ### Enhancements:

diff --git a/README.md b/README.md
@@ -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();
 
@@ -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.
diff --git a/examples/TestFunctions/TestFunctions.ino b/examples/TestFunctions/TestFunctions.ino
diff --git a/examples/TestCH422G/TestCH422G.ino → examples/ch422g/ch422g.ino b/examples/TestCH422G/TestCH422G.ino → examples/ch422g/ch422g.ino
@@ -1,5 +1,5 @@
 /**
- * | Supported IO Expanders | CH422G |
+ * | Supported IO Expanders    | CH422G |
  * | ------------------------- | ------ |
  *
  * # CH422G Test Example
@@ -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();
 

diff --git a/examples/general/general.ino b/examples/general/general.ino
@@ -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);
+}
Original file line number	Diff line number	Diff line change
		@@ -1,2 +1 @@
		[codespell]
		skip = ./src/touch/base/esp_lcd_touch_xpt2046.c