Add Chinese and English README files

2026-05-07 18:43:31 +08:00
1 parent a35a6e8f37
commit f153fec301
@@ -0,0 +1,340 @@
+# sweekar-esp32-gyroscope
+[English](README.md) | [中文](README_CN.md)
+## 项目简介
+
+`sweekar-esp32-gyroscope` 是一个基于 **ESP-IDF** 的模块化嵌入式工程。
+
+这个仓库是从原始 `sweekar-esp32` 工程中精简出来的版本，当前主要保留了 **gyroscope（陀螺仪）相关功能**，用于独立开发、裁剪验证和测试。
+
+工程仍然保留了原项目的模块化结构，方便后续继续扩展板级驱动、HAL 模块、执行器模块和测试代码。
+
+---
+
+## 目录说明
+
+### `main/02_physical/boards`
+板级相关代码。  
+这里放和具体板子强相关的内容，例如板卡定义、板级初始化、IO 扩展、板级配置。
+
+### `main/04_hal`
+硬件抽象层（HAL）。  
+这里放和板子驱动有关的基础模块，例如：
+
+- `audio_codec`
+- `base_board_hal`
+- `stepper_driver`
+
+### `main/05_executors`
+执行器 / 功能模块层。  
+当前这个精简工程里，主要保留：
+
+- `gyroscope`：陀螺仪驱动代码
+
+### `main/tests`
+测试模块目录。  
+这里用于编写测试用例，验证某个模块能否正常包含、编译、链接和运行。
+
+---
+
+## 怎么运行
+
+先确保已经正确安装并导出 **ESP-IDF** 环境。
+
+### 正常编译、烧录、查看日志
+
+```bash
+idf.py build flash monitor
+```
+
+### 当需要自动生成 `module.cmake` 时
+
+如果你新增了测试目录，或者希望重新触发模块扫描与生成，使用：
+
+```bash
+idf.py fullclean build flash monitor
+```
+
+说明：
+
+* 平时正常开发：`idf.py build flash monitor`
+* 新增测试目录后想自动生成 `module.cmake`：`idf.py fullclean build flash monitor`
+
+---
+
+## 运行结果示例
+
+如果测试代码运行正常，可以看到类似输出：
+
+```text
+I (600) main_task: Calling app_main()
+load OK
+9
+I (604) main_task: Returned from app_main()
+```
+
+这说明：
+
+* `load_gyroscope` 测试模块运行成功
+* `Gyroscope` 可以正常实例化
+* `add` 测试模块也正常运行，输出结果为 `9`
+
+---
+
+## 怎么创建测试用例
+
+创建测试用例的流程很简单：
+
+### 1. 先在 `main/tests/` 下新建一个文件夹
+
+一个测试功能对应一个目录。
+
+例如新建：
+
+```text
+main/tests/add/
+```
+
+或者：
+
+```text
+main/tests/load_gyroscope/
+```
+
+---
+
+### 2. 在新建的文件夹里写代码
+
+通常至少写两个文件：
+
+* `xxx.h`
+* `xxx.cc`
+
+例如 `add` 测试模块：
+
+#### `main/tests/add/add.h`
+
+```cpp
+int add(int a, int b);
+```
+
+#### `main/tests/add/add.cc`
+
+```cpp
+#include "add.h"
+
+int add(int a, int b) {
+    return a + b;
+}
+```
+
+再例如 `load_gyroscope` 测试模块：
+
+#### `main/tests/load_gyroscope/load.h`
+
+```cpp
+void load();
+```
+
+#### `main/tests/load_gyroscope/load.cc`
+
+```cpp
+#include "load.h"
+#include <cstdio>
+#include <gyroscope.h>
+
+void load() {
+    Gyroscope g;
+    printf("load OK\n");
+}
+```
+
+这个例子用于验证：
+
+* `gyroscope.h` 能否正常包含
+* `Gyroscope` 类能否正常实例化
+* 测试模块能否正确参与链接和运行
+
+---
+
+### 3. 在 `main/main.cc` 里调用测试用例
+
+测试代码写好后，在 `main/main.cc` 中包含头文件并调用。
+
+#### `main/main.cc`
+
+```cpp
+#include "add.h"
+#include "load.h"
+#include <cstdio>
+
+extern "C" void app_main() {
+    load();
+    printf("%d\n", add(5, 4));
+}
+```
+
+然后编译运行：
+
+```bash
+idf.py build flash monitor
+```
+
+如果你是**第一次新增测试目录**，想让工程自动生成对应的 `module.cmake`，使用：
+
+```bash
+idf.py fullclean build flash monitor
+```
+
+---
+
+## 测试模块的最小结构
+
+推荐每个测试模块至少包含下面 3 个文件：
+
+```text
+xxx/
+├── xxx.cc
+├── xxx.h
+└── module.cmake
+```
+
+含义如下：
+
+* `xxx.h`：声明接口
+* `xxx.cc`：实现测试逻辑
+* `module.cmake`：把这个模块注册进构建系统
+
+---
+
+## `module.cmake` 怎么来
+
+当你在 `main/tests/` 下新增一个测试目录时，工程可以自动为它生成 `module.cmake`。
+
+例如你先新建：
+
+```text
+main/tests/load_gyroscope/
+├── load.cc
+└── load.h
+```
+
+执行：
+
+```bash
+idf.py fullclean build flash monitor
+```
+
+之后目录会变成：
+
+```text
+main/tests/load_gyroscope/
+├── load.cc
+├── load.h
+└── module.cmake
+```
+
+所以流程就是：
+
+1. 先建测试目录
+2. 再写 `.h` 和 `.cc`
+3. 执行 `idf.py fullclean build flash monitor`
+4. 自动生成 `module.cmake`
+5. 在 `main/main.cc` 中调用测试代码
+
+---
+
+## 自动添加代码文件到 CMake 的原理
+
+这个工程不是手工在 `main/CMakeLists.txt` 里一条条写死所有 `.cc` 文件，而是通过扫描各模块目录下的 `module.cmake` 自动收集源码和头文件目录。
+
+### 第一步：定义要扫描的目录
+
+在 `main/CMakeLists.txt` 中定义：
+
+```cmake
+set(SUBSYSTEM_DIRS 
+    "04_hal"
+    "05_executors"
+    "05_service"
+    "06_behaviors"
+    "tests"
+)
+```
+
+---
+
+### 第二步：扫描每个子目录下的 `module.cmake`
+
+```cmake
+foreach(dir ${SUBSYSTEM_DIRS})
+    file(GLOB MODULE_FILES "${CMAKE_CURRENT_LIST_DIR}/${dir}/*/module.cmake")
+    foreach(mod_file ${MODULE_FILES})
+        include(${mod_file})
+    endforeach()
+endforeach()
+```
+
+也就是说，主工程会自动去找各个模块自己的 `module.cmake`。
+
+---
+
+### 第三步：每个模块把自己的信息追加进去
+
+每个模块自己的 `module.cmake` 会把内容追加到这些全局变量里：
+
+* `MODULE_SRCS`
+* `MODULE_INCLUDE_DIRS`
+* `MODULE_REQUIRES`
+* `MODULE_PRIV_REQUIRES`
+
+例如测试模块会把：
+
+* `tests/add/add.cc`
+* `tests/add`
+
+加进去。
+
+---
+
+### 第四步：统一交给 `idf_component_register(...)`
+
+最后统一注册：
+
+```cmake
+idf_component_register(
+    SRCS
+        "main.cc"
+        ${MODULE_SRCS}
+    INCLUDE_DIRS
+        "."
+        ${MODULE_INCLUDE_DIRS}
+    REQUIRES
+        ${MODULE_REQUIRES}
+    PRIV_REQUIRES
+        ${MODULE_PRIV_REQUIRES}
+)
+```
+
+所以本质上就是：
+
+**主工程自动扫描所有模块的 `module.cmake`，每个模块自己声明要参与编译的文件，最后统一汇总到 `idf_component_register(...)`。**
+
+---
+
+## 总结
+
+这个仓库的定位是：
+
+* `sweekar-esp32` 的精简版
+* 当前主要保留 `gyroscope` 相关代码
+* 支持在 `main/tests/` 下快速新增测试模块
+
+新增测试用例时，按下面流程做即可：
+
+1. 在 `main/tests/` 下新建一个文件夹
+2. 在新文件夹里写 `.h` 和 `.cc`
+3. 首次新增目录时执行 `idf.py fullclean build flash monitor` 自动生成 `module.cmake`
+4. 在 `main/main.cc` 中调用测试代码
+5. 后续正常开发执行 `idf.py build flash monitor`
+
+这样就可以快速验证模块是否正常编译和运行。