Add Chinese and English README files

2026-05-07 18:43:31 +08:00
1 parent a35a6e8f37
commit f153fec301
@@ -0,0 +1,338 @@
+# sweekar-esp32-gyroscope
+[English](README.md) | [中文](README_CN.md)
+## Project Overview
+
+`sweekar-esp32-gyroscope` is a modular embedded project based on **ESP-IDF**.
+
+This repository is a trimmed-down version of the original `sweekar-esp32` project. It currently keeps only the **gyroscope-related functionality**, and is intended for independent development, feature isolation, verification, and testing.
+
+The project still preserves the modular structure of the original codebase, making it easy to continue extending board-level drivers, HAL modules, executor modules, and test code in the future.
+
+---
+
+## Directory Description
+
+### `main/02_physical/boards`
+Board-level related code.  
+This directory contains content strongly tied to specific hardware boards, such as board definitions, board initialization, IO expansion, and board configuration.
+
+### `main/04_hal`
+Hardware Abstraction Layer (HAL).  
+This directory contains basic modules related to board drivers, such as:
+
+- `audio_codec`
+- `base_board_hal`
+- `stepper_driver`
+
+### `main/05_executors`
+Executor / functional module layer.  
+In this trimmed-down project, the main retained module is:
+
+- `gyroscope`: gyroscope driver code
+
+### `main/tests`
+Test module directory.  
+This directory is used to write test cases to verify whether a module can be correctly included, compiled, linked, and executed.
+
+---
+
+## How to Run
+
+Make sure **ESP-IDF** has been installed correctly and the environment has been exported.
+
+### Normal build, flash, and monitor
+
+```bash
+idf.py build flash monitor
+```
+
+### When you need to auto-generate `module.cmake`
+
+If you add a new test directory, or want to re-trigger module scanning and generation, use:
+
+```bash
+idf.py fullclean build flash monitor
+```
+
+Notes:
+
+* For normal development: `idf.py build flash monitor`
+* After adding a new test directory and you want to auto-generate `module.cmake`: `idf.py fullclean build flash monitor`
+
+---
+
+## Example Output
+
+If the test code runs correctly, you should see output similar to:
+
+```text
+I (600) main_task: Calling app_main()
+load OK
+9
+I (604) main_task: Returned from app_main()
+```
+
+This means:
+
+* The `load_gyroscope` test module ran successfully
+* `Gyroscope` was instantiated successfully
+* The `add` test module also ran successfully and printed `9`
+
+---
+
+## How to Create a Test Case
+
+The workflow for creating a test case is simple:
+
+### 1. Create a new folder under `main/tests/`
+
+Each test feature should correspond to one directory.
+
+For example:
+
+```text
+main/tests/add/
+```
+
+or:
+
+```text
+main/tests/load_gyroscope/
+```
+
+---
+
+### 2. Write code inside the new folder
+
+Usually, you should create at least two files:
+
+* `xxx.h`
+* `xxx.cc`
+
+For example, the `add` test module:
+
+#### `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;
+}
+```
+
+Another example is the `load_gyroscope` test module:
+
+#### `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");
+}
+```
+
+This example is used to verify:
+
+* Whether `gyroscope.h` can be included correctly
+* Whether the `Gyroscope` class can be instantiated correctly
+* Whether the test module can participate in linking and execution correctly
+
+---
+
+### 3. Call the test case in `main/main.cc`
+
+After writing the test code, include the headers and call the test functions in `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));
+}
+```
+
+Then build and run:
+
+```bash
+idf.py build flash monitor
+```
+
+If this is the **first time you add a new test directory** and you want the project to auto-generate the corresponding `module.cmake`, use:
+
+```bash
+idf.py fullclean build flash monitor
+```
+
+---
+
+## Minimal Structure of a Test Module
+
+It is recommended that each test module contains at least the following 3 files:
+
+```text
+xxx/
+├── xxx.cc
+├── xxx.h
+└── module.cmake
+```
+
+Meaning:
+
+* `xxx.h`: declares the interface
+* `xxx.cc`: implements the test logic
+* `module.cmake`: registers this module into the build system
+
+---
+
+## Where `module.cmake` Comes From
+
+When you add a new test directory under `main/tests/`, the project can automatically generate a corresponding `module.cmake` for it.
+
+For example, if you first create:
+
+```text
+main/tests/load_gyroscope/
+├── load.cc
+└── load.h
+```
+
+Then run:
+
+```bash
+idf.py fullclean build flash monitor
+```
+
+After that, the directory will become:
+
+```text
+main/tests/load_gyroscope/
+├── load.cc
+├── load.h
+└── module.cmake
+```
+
+So the workflow is:
+
+1. Create a test directory
+2. Write the `.h` and `.cc` files
+3. Run `idf.py fullclean build flash monitor`
+4. `module.cmake` is generated automatically
+5. Call the test code in `main/main.cc`
+
+---
+
+## How Automatic CMake Registration Works
+
+This project does not manually hardcode every `.cc` file one by one in `main/CMakeLists.txt`. Instead, it automatically collects source files and include directories by scanning each module's `module.cmake`.
+
+### Step 1: Define the directories to scan
+
+In `main/CMakeLists.txt`:
+
+```cmake
+set(SUBSYSTEM_DIRS 
+    "04_hal"
+    "05_executors"
+    "05_service"
+    "06_behaviors"
+    "tests"
+)
+```
+
+---
+
+### Step 2: Scan `module.cmake` under each subdirectory
+
+```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()
+```
+
+That means the main project automatically looks for each module's own `module.cmake`.
+
+---
+
+### Step 3: Each module appends its own information
+
+Each module's `module.cmake` appends content to these global variables:
+
+* `MODULE_SRCS`
+* `MODULE_INCLUDE_DIRS`
+* `MODULE_REQUIRES`
+* `MODULE_PRIV_REQUIRES`
+
+For example, a test module may append:
+
+* `tests/add/add.cc`
+* `tests/add`
+
+---
+
+### Step 4: Everything is registered through `idf_component_register(...)`
+
+Finally, everything is registered together:
+
+```cmake
+idf_component_register(
+    SRCS
+        "main.cc"
+        ${MODULE_SRCS}
+    INCLUDE_DIRS
+        "."
+        ${MODULE_INCLUDE_DIRS}
+    REQUIRES
+        ${MODULE_REQUIRES}
+    PRIV_REQUIRES
+        ${MODULE_PRIV_REQUIRES}
+)
+```
+
+So in essence:
+
+**The main project automatically scans all modules' `module.cmake` files, each module declares the files it wants to participate in compilation, and finally everything is merged into `idf_component_register(...)`.**
+
+---
+
+## Summary
+
+The purpose of this repository is very clear:
+
+* It is a trimmed-down version of `sweekar-esp32`
+* It currently keeps mainly the `gyroscope`-related code
+* It supports quickly adding new test modules under `main/tests/`
+
+When adding a new test case, just follow this process:
+
+1. Create a new folder under `main/tests/`
+2. Write the `.h` and `.cc` files in that folder
+3. When the directory is added for the first time, run `idf.py fullclean build flash monitor` to auto-generate `module.cmake`
+4. Call the test code in `main/main.cc`
+5. For later normal development, run `idf.py build flash monitor`
+
+This allows you to quickly verify whether a module can compile and run correctly.