diff --git a/docs/directory-structure.md b/docs/directory-structure.md new file mode 100644 index 000000000..82ed0a2a4 --- /dev/null +++ b/docs/directory-structure.md @@ -0,0 +1,307 @@ +# Meshtastic 固件项目目录结构 + +> 本文档描述 Meshtastic 固件仓库的完整目录层级及各文件夹用途。 + +## 顶层目录 + +``` +meshtastic_firmware/ +├── src/ # 固件核心 C++ 源码（见下详述） +├── variants/ # 200+ 硬件变体定义，按芯片平台分子目录 +│ ├── esp32/ # ESP32（原版） +│ ├── esp32c3/ # ESP32-C3 +│ ├── esp32c6/ # ESP32-C6 +│ ├── esp32p4/ # ESP32-P4 +│ ├── esp32s2/ # ESP32-S2 +│ ├── esp32s3/ # ESP32-S3 +│ ├── nrf52840/ # Nordic nRF52840 +│ ├── nrf54l15/ # Nordic nRF54L15 +│ ├── rp2040/ # Raspberry Pi RP2040 +│ ├── rp2350/ # Raspberry Pi RP2350 +│ ├── stm32/ # STM32WL +│ └── native/ # Linux/macOS Portduino 仿真 +├── boards/ # PlatformIO 自定义板级 JSON 定义（75+ 开发板） +├── test/ # 原生 C++ 单元测试（19 个测试套件） +│ ├── fixtures/ # 测试数据/固件 +│ └── support/ # 测试辅助代码 +├── bin/ # 构建/CI/发布脚本（run-tests.sh, regen-protos.sh, build-*.sh…） +├── protobufs/ # .proto 子模块（从 meshtastic/protobufs 拉取） +├── .github/ # GitHub 配置 +│ ├── workflows/ # CI/CD 流水线 +│ ├── prompts/ # Copilot 固件脚手架提示词 +│ ├── copilot-instructions.md # AI Agent 主指令文档（最重要） +│ ├── ISSUE_TEMPLATE/ # Issue 模板 +│ └── actions/ # 复用的 GitHub Actions +├── .trunk/ # Trunk 代码格式化/静态检查配置 +├── .claude/ # Claude Code 配置（PostToolUse hook 等） +├── .devcontainer/ # VS Code Dev Container 定义 +├── .clusterfuzzlite/ # ClusterFuzzLite 模糊测试配置 +├── .vscode/ # VS Code 工作区设置 +├── extra_scripts/ # PlatformIO 构建钩子脚本（按平台链接器/LTO 等） +├── scripts/ # 额外构建脚本（mbedtls 源码添加） +├── tools/ # 独立工具（lockdown 配置脚本） +├── monitor/ # 串口监控辅助脚本 +├── docs/ # 设计文档（路由、信标模块等） +├── branding/ # 品牌资源说明 +├── release/ # 发布产物输出目录（gitignore） +├── data/static/ # 打包进文件系统的静态资源 +├── meshtestic/ # 测试相关（当前为空） +├── managed_components/ # PlatformIO 自动管理的依赖组件 +├── zephyr/ # Zephyr RTOS 适配（实验性） +├── debian/ # Debian 打包文件 +├── .dummy/ # 占位/空组件 +├── platformio.ini # PlatformIO 主构建配置（所有环境定义） +├── Dockerfile # 主 Docker 构建 +├── Dockerfile.test # 测试用 Docker +├── docker-compose.yml # Docker Compose +├── .mcp.json # MCP 服务器注册（meshtastic-mcp，uvx 启动） +├── AGENTS.md # Agent 快速参考指令 +├── CLAUDE.md # Claude Code 指令镜像 +├── userPrefs.jsonc # 设备用户偏好配置（测试会话状态） +├── version.properties # 版本号定义 +├── partition-table*.csv # 各平台分区表 +├── sdkconfig.defaults # ESP-IDF 默认配置 +└── *.ld / *.hex / *.uf2 # 链接脚本、引导加载程序、softdevice +``` + +## `src/` 源码内部结构 + +### 顶层文件 + +| 文件 | 用途 | +| --- | --- | +| `main.cpp` / `main.h` | 固件入口 | +| `meshUtils.*` | 通用工具函数（clamp、UTF-8、字符串格式化等） | +| `Observer.*` | 观察者模式 / 事件总线 | +| `PowerFSM.*` | 电源状态机 | +| `Power.*` / `PowerMon.*` | 电源管理与监控 | +| `RedirectablePrint.*` | 可重定向日志输出 | +| `SerialConsole.*` | 串口控制台 | +| `sleep.*` | 睡眠管理 | +| `SafeFile.*` | 安全文件读写 | +| `FSCommon.*` | 文件系统通用操作 | +| `GpioLogic.*` | GPIO 逻辑 | +| `MessageStore.*` | 消息存储 | +| `SPILock.*` | SPI 总线锁 | +| `xmodem.*` | XModem 协议 | +| `airtime.*` | 发射占空比统计 | +| `memGet.*` | 内存查询 | +| `configuration.h` | 全局配置 | +| `DebugConfiguration.*` | 调试日志宏（LOG_DEBUG/INFO/WARN…） | +| `RF95Configuration.h` | RF95 射频配置 | + +### 子目录 + +``` +src/ +├── mesh/ # 核心网络层（最重要） +├── modules/ # 功能模块 +├── platform/ # 平台抽象层 +├── graphics/ # 显示与 UI +├── input/ # 输入设备 +├── gps/ # GPS 定位 +├── motion/ # 运动传感器 +├── mqtt/ # MQTT 网关 +├── nimble/ # NimBLE 蓝牙低功耗 +├── concurrency/ # 并发原语 +├── security/ # 安全功能 +├── serialization/ # 序列化 +├── detect/ # 硬件检测 +├── buzz/ # 蜂鸣器反馈 +├── watchdog/ # 看门狗定时器 +├── power/ # 电源管理 +└── memory/ # 内存审计工具 +``` + +--- + +### `src/mesh/` — 核心网络层 + +| 文件/目录 | 用途 | +| --- | --- | +| `generated/` | ⚠️ 自动生成的 protobuf 绑定（**禁止手动编辑**） | +| `api/` | 设备 API 抽象 | +| `eth/` / `http/` / `udp/` / `wifi/` / `raspihttp/` | 网络传输后端 | +| `NodeDB.*` | 节点数据库（对等节点表） | +| `NodeDBLegacyMigration.cpp` | 旧版节点数据库迁移 | +| `Router.*` | 路由基类 | +| `FloodingRouter.*` | 泛洪路由 | +| `ReliableRouter.*` | 可靠路由 | +| `NextHopRouter.*` | 下一跳路由 | +| `CryptoEngine.*` | 加密引擎（AES-CTR 信道加密 + X25519 PKI） | +| `aes-ccm.*` | AES-256-CCM（DM 加密） | +| `Channels.*` | 信道管理（PSK） | +| `RadioInterface.*` | 射频接口基类 | +| `RadioLibInterface.*` | RadioLib 统一接口 | +| `RadioLibRF95.*` | RF95 RadioLib 适配 | +| `RF95Interface.*` | RF95/SX1276 射频驱动 | +| `SX126xInterface.*` | SX1262/SX1268 射频驱动 | +| `SX128xInterface.*` | SX1280 射频驱动 | +| `LR11x0Interface.*` | LR1110/LR1120/LR1121 射频驱动 | +| `LR20x0Interface.*` | LR2021 射频驱动 | +| `LLCC68Interface.*` | LLCC68 射频驱动 | +| `STM32WLE5JCInterface.*` | STM32WLE5JC 射频驱动 | +| `LoRaFEMInterface.*` | LoRa 前端模块控制 | +| `PhoneAPI.*` | 手机通信协议 | +| `StreamAPI.*` | 串线通信协议 | +| `StreamFrameWriter.*` | 流帧写入器 | +| `MeshService.*` | Mesh 服务主循环 | +| `MeshModule.*` | 模块框架基类 | +| `ProtobufModule.*` | Protobuf 模块基类 | +| `SinglePortModule.h` | 单端口模块基类 | +| `MeshPacketQueue.*` | 数据包队列 | +| `PacketCache.*` | 数据包缓存 | +| `PacketHistory.*` | 数据包历史（去重） | +| `TransmitHistory.*` | 发射历史 | +| `PositionPrecision.*` | 位置精度控制 | +| `TypeConversions.*` | protobuf 类型转换 | +| `WarmNodeStore.*` | 暖存储（睡眠中保持节点缓存） | +| `Throttle.*` | 限流工具（替代 raw `millis()`，防溢出） | +| `HardwareRNG.*` | 硬件随机数生成 | +| `MeshTypes.h` / `MeshRadio.h` | 核心类型定义 | +| `mesh-pb-constants.*` | protobuf 常量 | +| `Default.*` | 默认值 | +| `MemoryPool.h` / `PointerQueue.h` / `TypedQueue.h` / `StaticPointerQueue.h` | 内存池与队列模板 | +| `InterfacesTemplates.cpp` | 接口模板 | + +--- + +### `src/modules/` — 功能模块 + +| 文件/目录 | 用途 | +| --- | --- | +| `AdminModule.*` | 远程管理 | +| `PositionModule.*` | 位置上报 | +| `TextMessageModule.*` | 文本消息 | +| `RoutingModule.*` | 路由 | +| `TraceRouteModule.*` | 路由追踪 | +| `NeighborInfoModule.*` | 邻居信息 | +| `NodeInfoModule.*` | 节点信息 | +| `StoreForwardModule.*` | 存储转发 | +| `ExternalNotificationModule.*` | 外部通知 | +| `CannedMessageModule.*` | 预设消息 | +| `AtakPluginModule.*` | ATAK 插件 | +| `RemoteHardwareModule.*` | 远程 GPIO 控制 | +| `RangeTestModule.*` | 距离测试 | +| `ReplyBotModule.*` | 自动回复机器人 | +| `ReplyModule.*` | 回复模块 | +| `KeyVerificationModule.*` | PKI 密钥验证 | +| `HopScalingModule.*` | 跳数缩放 | +| `TrafficManagementModule.*` | 流量管理 | +| `MeshBeaconModule.*` | Mesh 信标 | +| `WaypointModule.*` | 路径点 | +| `DetectionSensorModule.*` | 检测传感器 | +| `DropzoneModule.*` | 空投区 | +| `StatusLEDModule.*` | 状态 LED | +| `StatusMessageModule.*` | 状态消息 | +| `OnScreenKeyboardModule.*` | 屏幕键盘 | +| `PowerStressModule.*` | 电源压力测试 | +| `SystemCommandsModule.*` | 系统命令 | +| `SerialModule.*` | 串口模块 | +| `GenericThreadModule.*` | 通用线程模块 | +| `esp32/` | ESP32 专用模块 | +| `Telemetry/` | 遥测模块（见下） | +| `Modules.*` / `ModuleDev.h` | 模块注册与开发辅助 | + +#### `src/modules/Telemetry/` — 遥测 + +| 文件/目录 | 用途 | +| --- | --- | +| `BaseTelemetryModule.h` | 遥测模块基类 | +| `DeviceTelemetry.*` | 设备遥测（电池/电压/信道利用率等） | +| `EnvironmentTelemetry.*` | 环境遥测（温湿度/气压等） | +| `HealthTelemetry.*` | 健康遥测（心率等） | +| `PowerTelemetry.*` | 电源遥测 | +| `AirQualityTelemetry.*` | 空气质量遥测 | +| `HostMetrics.*` | 主机指标（Linux 原生） | +| `UnitConversions.*` | 单位转换 | +| `Sensor/` | 50+ I2C 传感器驱动 | + +--- + +### `src/platform/` — 平台抽象层 + +| 目录 | 用途 | +| --- | --- | +| `esp32/` | ESP32 专用（OTA、加密引擎、内存分配器、MCP23017 IO 扩展） | +| `nrf52/` | nRF52 专用（蓝牙 DFU、加密引擎、softdevice、hardfault 处理） | +| `nrf54l15/` | nRF54L15 专用 | +| `portduino/` | Linux/macOS 仿真（GPSD 串口、模拟电台、USB HAL、wasm） | +| `rp2xx0/` | RP2040/RP2350 | +| `stm32wl/` | STM32WL | +| `extra_variants/` | 额外变体支持 | + +--- + +### `src/graphics/` — 显示与 UI + +| 文件/目录 | 用途 | +| --- | --- | +| `Screen.*` / `ScreenGlobals.*` | 屏幕主控 | +| `draw/` | 绘图工具 | +| `fonts/` | 字体资源 | +| `img/` | 图像资源 | +| `emotes.*` / `EmoteRenderer.*` | 表情符号渲染 | +| `EInk*.*` | 电子墨水屏驱动（多种型号） | +| `TFT*.*` | TFT 彩屏驱动 | +| `tftSetup.cpp` / `TFTPalette.h` / `TFTColorRegions.*` | TFT 配置与调色板 | +| `VirtualKeyboard.*` | 虚拟键盘 | +| `SharedUIDisplay.*` | 共享 UI 显示 | +| `ScreenFonts.h` / `TimeFormatters.*` | 字体与时间格式化 | +| `images.h` / `PointStruct.h` | 图像与点结构定义 | +| `niche/` | 小众显示方案 | +| `NomadStarLED.h` | LED 灯阵 | +| `Panel_sdl.*` | SDL 面板（仿真） | +| `GxEPD2Multi.h` | GxEPD2 多屏支持 | + +--- + +### `src/input/` — 输入设备 + +支持多种输入方式（64 个文件）： + +| 类别 | 文件 | +| --- | --- | +| 用户按键 | `ButtonThread.*` | +| I2C 键盘 | `BBQ10Keyboard.*`、`cardKbI2cImpl.*`、`kbI2cBase.*`、`MPR121Keyboard.*`、`TCA8418Keyboard.*` | +| 板载键盘 | `CardputerKeyboard.*`、`TLoraPagerKeyboard.*`、`TDeckProKeyboard.*`、`HackadayCommunicatorKeyboard.*` | +| 旋钮编码器 | `RotaryEncoderInterruptBase.*`、`RotaryEncoderInterruptImpl1.*`、`SeesawRotary.*` | +| 五向开关 | `ExpressLRSFiveWay.*`、`UpDownInterruptBase.*` | +| 轨迹球 | `TrackballInterruptBase.*`、`TrackballInterruptImpl1.*` | +| 触摸屏 | `TouchScreenBase.*`、`TouchScreenImpl1.*` | +| Linux 输入 | `LinuxInput.*`、`LinuxInputImpl.*`、`LinuxJoystick.*` | +| 矩阵键盘 | `kbMatrixBase.*`、`kbMatrixImpl.*` | +| I2C 按钮 | `i2cButton.*` | +| 触觉反馈 | `HapticFeedback.*` | +| 串口键盘 | `SerialKeyboard.*`、`SerialKeyboardImpl.*` | +| 输入代理 | `InputBroker.*` | + +--- + +### 其他子目录 + +| 目录 | 用途 | +| --- | --- | +| `gps/` | GPS 定位（`GPS.*`、`RTC.*`、`GeoCoord.*`、`NMEAWPL.*`、`GPSUpdateScheduling.*`） | +| `motion/` | 运动传感器（加速度计/磁力计：BMA423、BMI270、BMM150、BMX160、ICM20948、ICM42607P、LIS3DH、LSM6DS3、MPU6050、QMA6100P、STK8XXX、MMC5983MA） | +| `mqtt/` | MQTT 网关（`MQTT.*`、`ServiceEnvelope.*`） | +| `nimble/` | NimBLE 蓝牙低功耗 | +| `concurrency/` | 并发原语（线程/锁/信号量，FreeRTOS + POSIX 双实现、`NotifiedWorkerThread`、`InterruptableDelay`） | +| `security/` | 安全功能（加密存储 `EncryptedStorage.*`、AP 保护 `APProtect.*`、锁定显示 `LockdownDisplay.*`、安全清零 `SecureZero.h`） | +| `serialization/` | 序列化（COBS 编码 `cobs.*`、MeshPacket 序列化 `MeshPacketSerializer.*`） | +| `detect/` | 硬件检测（I2C 扫描 `ScanI2C*`、e-ink 检测 `einkScan.h`、LoRa 射频类型检测 `LoRaRadioType.h`） | +| `buzz/` | 蜂鸣器反馈（`buzz.*`、`BuzzerFeedbackThread.*`） | +| `watchdog/` | 看门狗定时器 | +| `power/` | 电源管理（`PowerHAL.*`、`SGM41562.*` 充电器驱动） | +| `memory/` | 内存审计工具（`MemAudit.*`、`MemClass.h`） | + +--- + +## 关键注意事项 + +1. **`src/mesh/generated/`** — 自动生成的 protobuf 绑定，**禁止手动编辑**。需修改 `.proto` 时，先向 [meshtastic/protobufs](https://github.com/meshtastic/protobufs) 提 PR，再由 `bin/regen-protos.sh` 重新同步。 +2. **`protobufs/`** — Git 子模块，需 `git submodule update --init` 初始化。 +3. **`variants/`** — 每个硬件变体包含 `variant.h`（引脚/外设定义）和 `platformio.ini` 片段（构建配置）。 +4. **`bin/run-tests.sh`** — 首选测试入口（内置 ASan/LSan + RED/AMBER/GREEN 判定）。 +5. **`trunk fmt`** — 提交前必须运行，CI 的 `trunk_check` 门禁会拒绝未格式化的代码。 +6. **`.github/copilot-instructions.md`** — AI Agent 的主指令文档，做任何非平凡修改前应先阅读。