308 lines
14 KiB
Markdown
308 lines
14 KiB
Markdown
# 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 的主指令文档，做任何非平凡修改前应先阅读。
|