14 KiB
14 KiB
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） |
关键注意事项
src/mesh/generated/— 自动生成的 protobuf 绑定，禁止手动编辑。需修改.proto时，先向 meshtastic/protobufs 提 PR，再由bin/regen-protos.sh重新同步。protobufs/— Git 子模块，需git submodule update --init初始化。variants/— 每个硬件变体包含variant.h（引脚/外设定义）和platformio.ini片段（构建配置）。bin/run-tests.sh— 首选测试入口（内置 ASan/LSan + RED/AMBER/GREEN 判定）。trunk fmt— 提交前必须运行，CI 的trunk_check门禁会拒绝未格式化的代码。.github/copilot-instructions.md— AI Agent 的主指令文档，做任何非平凡修改前应先阅读。