Add Waveshare AMOLED catalog and normalize board pack naming

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ concurrency:
 
 defaults:
   run:
-    working-directory: waveshare-boards
+    working-directory: waveshare_boards
 
 jobs:
   validate:
@@ -28,7 +28,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          path: waveshare-boards
+          path: waveshare_boards
           fetch-depth: 0
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
       - uses: actions/setup-python@v5
@@ -57,7 +57,7 @@ jobs:
             python ci/scripts/board_pack.py matrix --all
           fi
       - name: Validate component package without credentials
-        run: compote component pack --name waveshare-boards
+        run: compote component pack --name waveshare_boards
 
   build:
     name: ${{ matrix.board }} / ${{ matrix.idf }} / BMGR ${{ matrix.bmgr }}
@@ -70,20 +70,20 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          path: waveshare-boards
+          path: waveshare_boards
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
       - name: Generate and compile board definitions
         uses: espressif/esp-idf-ci-action@v1
         with:
           esp_idf_version: ${{ matrix.idf }}
           target: ${{ matrix.target }}
-          path: waveshare-boards/ci/test_app
+          path: waveshare_boards/ci/test_app
           command: |
             set -eu
             python -m pip install '${{ matrix.component_manager }}' '${{ matrix.bmgr_assist }}'
             python ../scripts/board_pack.py pin '${{ matrix.bmgr }}'
-            idf.py bmgr -l -c ../..
-            idf.py bmgr -b '${{ matrix.board }}' -c ../..
+            idf.py bmgr -l
+            idf.py bmgr -b '${{ matrix.board }}'
             idf.py build
 
   result:

.github/workflows/publish.yml

@@ -53,4 +53,4 @@ jobs:
           if [[ "$DRY_RUN" == true ]]; then
             options+=(--dry-run)
           fi
-          compote component upload --namespace waveshare --name waveshare-boards "${options[@]}"
+          compote component upload --namespace waveshare --name waveshare_boards "${options[@]}"

CONTRIBUTING.md

@@ -6,7 +6,10 @@ Submit board definitions, fixes, or documentation through a pull request.
 
 1. Keep each board's `board_info.yaml`, `board_peripherals.yaml`,
    `board_devices.yaml`, and optional setup source together. Names must be unique
-   and match the directory; nesting is limited to three levels.
+   and match the directory. Use `boards/<full_model>/`; keep the chip prefix
+   and add a hardware revision suffix only when separate definitions are needed.
+   Do not add another chip/category directory: local component discovery has a
+   lower effective depth limit. See [board organization](docs/BOARDS.md).
 2. Base hardware changes on the matching product revision's schematic or official
    hardware reference. Include the source link or permitted reference file and
    explain what was checked. Report hardware testing separately from compilation.

CONTRIBUTING_ZH.md

@@ -5,7 +5,9 @@
 通过 Pull Request 提交板卡定义、修复或文档。
 
 1. 将每块板卡的 `board_info.yaml`、`board_peripherals.yaml`、`board_devices.yaml`
-   及可选的初始化源码保存在同一目录。名称必须唯一并与目录名相同，最多嵌套三层。
+   及可选的初始化源码保存在 `boards/<完整型号>/`。名称必须唯一并与目录名相同，保留芯片前缀，
+   只有需要独立定义时才增加硬件版本后缀。不要再增加芯片或类别目录，避免超过本地组件的扫描深度。
+   详见[板卡组织方式](docs/BOARDS_ZH.md)。
 2. 硬件修改应基于对应产品版本的原理图或官方硬件资料。
    提供来源链接或允许公开的参考文件，说明核对内容，实机测试与编译结果分别报告。
 3. 板级适配代码留在本地，通用驱动通过托管依赖引入，说明版本约束及验证范围。

README.md

@@ -4,7 +4,7 @@
 
 <p><strong>Waveshare board definitions for ESP Board Manager</strong></p>
 
-<a href="https://github.com/waveshareteam/waveshare-boards/actions/workflows/ci.yml"><img src="https://github.com/waveshareteam/waveshare-boards/actions/workflows/ci.yml/badge.svg" alt="Build"></a>
+<a href="https://github.com/waveshareteam/waveshare_boards/actions/workflows/ci.yml"><img src="https://github.com/waveshareteam/waveshare_boards/actions/workflows/ci.yml/badge.svg" alt="Build"></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a>
 
 English | [简体中文](README_ZH.md)
@@ -30,12 +30,15 @@ such as `spi_sd` describe a bus; they do not imply a complete storage applicatio
 <!-- BEGIN SUPPORTED_BOARDS -->
 | Board | Chip | Device definitions | Peripheral definitions |
 | --- | --- | --- | --- |
-| [`esp32_s3_touch_lcd_7`](esp32_s3_touch_lcd_7/) | ESP32-S3 | `display_lcd`, `lcd_touch` | `i2c_master`, `uart_rs485`, `uart_external`, `adc_sensor`, `spi_sd` |
+| [`esp32_s3_touch_amoled_1_75c`](boards/esp32_s3_touch_amoled_1_75c/) | ESP32-S3 | `axp2101_power_manager`, `audio_dac`, `audio_adc`, `display_lcd`, `lcd_touch` | `i2c_master`, `i2s_audio_out`, `i2s_audio_in`, `gpio_pa_control`, `spi_display` |
+| [`esp32_s3_touch_amoled_1_8`](boards/esp32_s3_touch_amoled_1_8/) | ESP32-S3 | `gpio_expander`, `axp2101_power_manager`, `audio_dac`, `audio_adc`, `display_lcd`, `lcd_touch`, `fs_sdcard` | `i2c_master`, `i2s_audio_out`, `i2s_audio_in`, `gpio_pa_control`, `spi_display` |
+| [`esp32_s3_touch_amoled_2_16`](boards/esp32_s3_touch_amoled_2_16/) | ESP32-S3 | `axp2101_power_manager`, `audio_dac`, `audio_adc`, `display_lcd`, `lcd_touch`, `fs_sdcard` | `i2c_master`, `i2s_audio_out`, `i2s_audio_in`, `gpio_pa_control`, `spi_display` |
+| [`esp32_s3_touch_lcd_7`](boards/esp32_s3_touch_lcd_7/) | ESP32-S3 | `display_lcd`, `lcd_touch` | `i2c_master`, `uart_rs485`, `uart_external`, `adc_sensor`, `spi_sd` |
 <!-- END SUPPORTED_BOARDS -->
 
-Board configurations remain in their existing directories. CI validates and
-compiles them; electrical behavior and operation on physical hardware require
-separate testing.
+Definitions live under `boards/<full_model>/`. The three AMOLED profiles come
+from Espressif Brookesia; see [board revisions and migration notes](docs/BOARDS.md).
+CI validates generation and compilation; physical operation requires board testing.
 
 <a id="quick-start"></a>
 
@@ -46,8 +49,9 @@ into an **existing ESP-IDF application's** component directory:
 
 ```bash
 mkdir -p components
-git clone https://github.com/waveshareteam/waveshare-boards.git components/waveshare-boards
+git clone https://github.com/waveshareteam/waveshare_boards.git components/waveshare_boards
 python -m pip install esp-bmgr-assist==0.8.3
+idf.py set-target esp32s3
 idf.py bmgr -l
 idf.py bmgr -b esp32_s3_touch_lcd_7
 idf.py build
@@ -56,7 +60,11 @@ idf.py build
 Use the Component Manager version from the active IDF environment; the tested
 versions for each IDF line are listed in [the CI guide](docs/CI.md).
 
-Keep the local directory name `waveshare-boards`: ESP-IDF uses the directory name as
+`set-target` resolves the pack dependencies before discovery. In an already
+configured ESP32-S3 application, use `idf.py reconfigure` instead to preserve
+its configuration.
+
+Keep the local directory name `waveshare_boards`: ESP-IDF uses the directory name as
 the component name. The pack declares `espressif/esp_board_manager` as a public
 dependency. Applications can include `esp_board_manager.h` and initialize the
 selected board using `esp_board_manager_init()`.
@@ -65,23 +73,25 @@ After maintainers publish the component, install it from the registry instead
 of keeping the local clone:
 
 ```bash
-idf.py add-dependency "waveshare/waveshare-boards"
+idf.py add-dependency "waveshare/waveshare_boards"
+idf.py reconfigure
+idf.py bmgr -l
 ```
 
-The intended registry identity is `waveshare/waveshare-boards`; a repository version
+The intended registry identity is `waveshare/waveshare_boards`; a repository version
 or a passing packaging check does not by itself mean that version is published.
 
 ## 🗂️ Repository layout
 
 ```text
-esp32_s3_touch_lcd_7/    Board metadata, peripherals, devices, and setup code
+boards/<full_model>/   Board metadata, peripherals, devices, and setup code
 idf_component.yml      Component metadata and managed dependencies
 CMakeLists.txt         Board-pack component registration
 ci/test_app/           Board Manager integration compile test
 ci/scripts/            Discovery, change routing, and validation tests
 ci/versions.json       Exact ESP-IDF and Python tooling versions
 scripts/               Generated board catalog maintenance
-docs/                  CI and registry publication guides
+docs/                  Board revisions, CI, and registry publication guides
 .github/               Workflows and contribution templates
 ```
 
@@ -96,12 +106,14 @@ python ci/scripts/board_pack.py check
 python -m unittest discover -s ci/scripts -p 'test_*.py' -v
 ```
 
-Board directories may be nested up to three levels. Each directory name must
-match its unique `board` value. The generated catalog lists the actual device
-and peripheral names, including board removals and renames.
+Use one `boards/` container and keep the chip prefix in each model name. Do not
+add another chip/category directory: the layout must fit Board Manager scanning
+from an application's `components/` root. Each model directory must match its
+unique `board` value. The catalog is regenerated from the definitions.
 
 ## 📚 Documentation
 
+- [Board organization, hardware revisions, and migration](docs/BOARDS.md)
 - [CI coverage and local validation](docs/CI.md)
 - [Registry credentials and publication](docs/PUBLISHING.md)
 - [Contributing](CONTRIBUTING.md)
@@ -110,5 +122,5 @@ and peripheral names, including board removals and renames.
 
 ## 📄 License
 
-[Apache License 2.0](LICENSE). Preserve existing notices when contributing or
-reusing board definitions and third-party code.
+[Apache License 2.0](LICENSE), with imported files retaining their original
+SPDX notices, including CC0-1.0. See [source attribution](docs/BOARDS.md).

README_ZH.md

@@ -4,7 +4,7 @@
 
 <p><strong>适用于 ESP Board Manager 的微雪开发板定义组件包</strong></p>
 
-<a href="https://github.com/waveshareteam/waveshare-boards/actions/workflows/ci.yml"><img src="https://github.com/waveshareteam/waveshare-boards/actions/workflows/ci.yml/badge.svg" alt="Build"></a>
+<a href="https://github.com/waveshareteam/waveshare_boards/actions/workflows/ci.yml"><img src="https://github.com/waveshareteam/waveshare_boards/actions/workflows/ci.yml/badge.svg" alt="Build"></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a>
 
 [English](README.md) | 简体中文
@@ -29,10 +29,14 @@
 <!-- BEGIN SUPPORTED_BOARDS -->
 | 开发板 | 芯片 | 设备定义 | 外设定义 |
 | --- | --- | --- | --- |
-| [`esp32_s3_touch_lcd_7`](esp32_s3_touch_lcd_7/) | ESP32-S3 | `display_lcd`, `lcd_touch` | `i2c_master`, `uart_rs485`, `uart_external`, `adc_sensor`, `spi_sd` |
+| [`esp32_s3_touch_amoled_1_75c`](boards/esp32_s3_touch_amoled_1_75c/) | ESP32-S3 | `axp2101_power_manager`, `audio_dac`, `audio_adc`, `display_lcd`, `lcd_touch` | `i2c_master`, `i2s_audio_out`, `i2s_audio_in`, `gpio_pa_control`, `spi_display` |
+| [`esp32_s3_touch_amoled_1_8`](boards/esp32_s3_touch_amoled_1_8/) | ESP32-S3 | `gpio_expander`, `axp2101_power_manager`, `audio_dac`, `audio_adc`, `display_lcd`, `lcd_touch`, `fs_sdcard` | `i2c_master`, `i2s_audio_out`, `i2s_audio_in`, `gpio_pa_control`, `spi_display` |
+| [`esp32_s3_touch_amoled_2_16`](boards/esp32_s3_touch_amoled_2_16/) | ESP32-S3 | `axp2101_power_manager`, `audio_dac`, `audio_adc`, `display_lcd`, `lcd_touch`, `fs_sdcard` | `i2c_master`, `i2s_audio_out`, `i2s_audio_in`, `gpio_pa_control`, `spi_display` |
+| [`esp32_s3_touch_lcd_7`](boards/esp32_s3_touch_lcd_7/) | ESP32-S3 | `display_lcd`, `lcd_touch` | `i2c_master`, `uart_rs485`, `uart_external`, `adc_sensor`, `spi_sd` |
 <!-- END SUPPORTED_BOARDS -->
 
-板卡配置保留在现有目录。CI 校验并编译这些配置；电气行为和实机运行效果需要单独测试。
+板卡定义统一放在 `boards/<完整型号>/`。新增的三个 AMOLED 型号来自 Espressif Brookesia，
+详见[硬件版本与迁移说明](docs/BOARDS_ZH.md)。CI 校验生成与编译，实机运行效果需要单独测试。
 
 <a id="quick-start"></a>
 
@@ -42,39 +46,45 @@
 
 ```bash
 mkdir -p components
-git clone https://github.com/waveshareteam/waveshare-boards.git components/waveshare-boards
+git clone https://github.com/waveshareteam/waveshare_boards.git components/waveshare_boards
 python -m pip install esp-bmgr-assist==0.8.3
+idf.py set-target esp32s3
 idf.py bmgr -l
 idf.py bmgr -b esp32_s3_touch_lcd_7
 idf.py build
 ```
 
 使用当前 IDF 环境配套的 Component Manager；各 IDF 版本线测试过的版本见 [CI 指南](docs/CI_ZH.md)。
 
-本地目录名请使用 `waveshare-boards`，因为 ESP-IDF 使用目录名作为组件名。
+`set-target` 会先解析组件依赖，再进行板卡发现。已有配置的 ESP32-S3 应用可以改用
+`idf.py reconfigure`，保留原配置。
+
+本地目录名请使用 `waveshare_boards`，因为 ESP-IDF 使用目录名作为组件名。
 组件包已经公开依赖 `espressif/esp_board_manager`；应用可以包含
 `esp_board_manager.h`，并通过 `esp_board_manager_init()` 初始化所选板卡。
 
 维护者正式发布组件后，可以通过组件库安装，替代本地克隆：
 
 ```bash
-idf.py add-dependency "waveshare/waveshare-boards"
+idf.py add-dependency "waveshare/waveshare_boards"
+idf.py reconfigure
+idf.py bmgr -l
 ```
 
-计划使用的组件库名称为 `waveshare/waveshare-boards`。仓库里的版本号或打包检查通过，
+计划使用的组件库名称为 `waveshare/waveshare_boards`。仓库里的版本号或打包检查通过，
 不代表该版本已经在组件库发布。
 
 ## 🗂️ 仓库结构
 
 ```text
-esp32_s3_touch_lcd_7/    板卡信息、外设、设备与初始化代码
+boards/<完整型号>/      板卡信息、外设、设备与初始化代码
 idf_component.yml      组件元数据与托管依赖
 CMakeLists.txt         板卡包组件注册
 ci/test_app/           Board Manager 集成编译测试
 ci/scripts/            发现、变更路由与验证测试
 ci/versions.json       明确的 ESP-IDF 与 Python 工具版本
 scripts/               板卡目录生成维护
-docs/                  CI 与组件库发布指南
+docs/                  硬件版本、CI 与组件库发布指南
 .github/               工作流与贡献模板
 ```
 
@@ -88,11 +98,13 @@ python ci/scripts/board_pack.py check
 python -m unittest discover -s ci/scripts -p 'test_*.py' -v
 ```
 
-板卡目录最多可以嵌套三层。目录名必须与唯一的 `board` 字段一致。
-生成的目录表使用实际设备和外设名称，并同步处理板卡删除或重命名。
+使用一层 `boards/` 容器，型号名称保留芯片前缀，不再增加芯片或类别目录，
+确保从应用 `components/` 根目录扫描时仍在 Board Manager 深度限制内。
+型号目录名必须与唯一的 `board` 字段一致，目录表根据实际定义自动生成。
 
 ## 📚 文档
 
+- [板卡组织、硬件版本与迁移说明](docs/BOARDS_ZH.md)
 - [CI 覆盖范围与本地验证](docs/CI_ZH.md)
 - [组件库凭据与发布](docs/PUBLISHING_ZH.md)
 - [贡献指南](CONTRIBUTING_ZH.md)
@@ -101,4 +113,5 @@ python -m unittest discover -s ci/scripts -p 'test_*.py' -v
 
 ## 📄 许可证
 
-采用 [Apache License 2.0](LICENSE)。贡献或复用板卡定义与第三方代码时，请保留已有声明。
+采用 [Apache License 2.0](LICENSE)，导入文件保留原有 SPDX 声明，包括 CC0-1.0。
+详见[来源说明](docs/BOARDS_ZH.md)。

SUPPORT.md

@@ -3,7 +3,7 @@
 [简体中文](SUPPORT_ZH.md) · [Home](README.md)
 
 For board-definition, generation, or compilation problems, use the
-[repository issue form](https://github.com/waveshareteam/waveshare-boards/issues/new/choose).
+[repository issue form](https://github.com/waveshareteam/waveshare_boards/issues/new/choose).
 Include the board and revision, exact ESP-IDF and Board Manager versions,
 reproduction steps, and the first relevant error. Remove credentials and
 personal or device identifiers from logs.

SUPPORT_ZH.md

@@ -2,7 +2,7 @@
 
 [English](SUPPORT.md) · [首页](README_ZH.md)
 
-板卡定义、生成或编译问题请使用[仓库问题表单](https://github.com/waveshareteam/waveshare-boards/issues/new/choose)。
+板卡定义、生成或编译问题请使用[仓库问题表单](https://github.com/waveshareteam/waveshare_boards/issues/new/choose)。
 请提供板卡型号与版本、准确的 ESP-IDF 和 Board Manager 版本、复现步骤以及第一处相关错误。
 日志中请删除凭据和个人、设备标识。
 

boards/esp32_s3_touch_amoled_1_75c/axp2101_power_manager.h

@@ -0,0 +1,66 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif  /* __cplusplus */
+
+typedef enum {
+    POWER_MANAGER_BATTERY_POWER_SOURCE_UNKNOWN,
+    POWER_MANAGER_BATTERY_POWER_SOURCE_BATTERY,
+    POWER_MANAGER_BATTERY_POWER_SOURCE_EXTERNAL,
+} power_manager_battery_power_source_t;
+
+typedef enum {
+    POWER_MANAGER_BATTERY_CHARGE_STATE_UNKNOWN,
+    POWER_MANAGER_BATTERY_CHARGE_STATE_NOT_CHARGING,
+    POWER_MANAGER_BATTERY_CHARGE_STATE_CHARGING,
+    POWER_MANAGER_BATTERY_CHARGE_STATE_TRICKLE,
+    POWER_MANAGER_BATTERY_CHARGE_STATE_PRE_CHARGE,
+    POWER_MANAGER_BATTERY_CHARGE_STATE_CONSTANT_CURRENT,
+    POWER_MANAGER_BATTERY_CHARGE_STATE_CONSTANT_VOLTAGE,
+    POWER_MANAGER_BATTERY_CHARGE_STATE_FULL,
+    POWER_MANAGER_BATTERY_CHARGE_STATE_FAULT,
+} power_manager_battery_charge_state_t;
+
+typedef struct {
+    bool is_present;
+    power_manager_battery_power_source_t power_source;
+    power_manager_battery_charge_state_t charge_state;
+    bool has_voltage_mv;
+    uint32_t voltage_mv;
+    bool has_percentage;
+    uint8_t percentage;
+    bool has_vbus_voltage_mv;
+    uint32_t vbus_voltage_mv;
+    bool has_system_voltage_mv;
+    uint32_t system_voltage_mv;
+} power_manager_battery_state_t;
+
+typedef struct {
+    bool enabled;
+    uint32_t target_voltage_mv;
+    uint32_t charge_current_ma;
+    uint32_t precharge_current_ma;
+    uint32_t termination_current_ma;
+} power_manager_battery_charge_config_t;
+
+esp_err_t power_manager_get_battery_state(void *device_handle, power_manager_battery_state_t *state);
+
+esp_err_t power_manager_get_charge_config(void *device_handle, power_manager_battery_charge_config_t *config);
+
+esp_err_t power_manager_set_charge_config(void *device_handle, const power_manager_battery_charge_config_t *config);
+
+esp_err_t power_manager_set_charging_enabled(void *device_handle, bool enabled);
+
+#ifdef __cplusplus
+}
+#endif  /* __cplusplus */