看到 openrig 这个名字，我第一反应不是什么高深框架，而是一个很具体的开源硬件项目应用场景：把一套半开放的设备框架跑起来，用低成本主控把传感器、显示、通信模块集成到一个可穿戴或桌面级的辅助终端上。这类项目现在其实不少，但 openrig 有意思的地方在于，它不追求把功能堆满，而是把“怎么搭、怎么接线、怎么调协议、怎么应急排障”这件事讲得比较透。这篇文章我就把这个项目从选型、接线、协议到固件架构和调试笔记完整拆一遍，给想动手复刻或者“借壳改造”的朋友做个参考。
1. 项目定位与整体方案拆解
1.1 需求解读：这个项目到底是做什么的
先聊项目名。rig 在硬件圈一般指“设备支架 / 框架 / 整套仪器平台”，open 则意味着这套东西的硬件接口、代码、通信协议都不是封闭的。从我拿到这个标题和相关资料来判断，openrig 的目标是把一块 ESP32 类主控、一块小尺寸 IPS 屏、若干传感器（温湿度、姿态、电压检测等）和一路串口/CAN 通信接口组合成一套开放式设备底座。它最典型的落地场景有三个：一是赛车或模拟驾驶场景的辅助仪表，读取车辆 OBD 数据后显示转速、水温、涡轮压力；二是桌面实验台的通用传感采集面板，把温度、湿度、光照这些信号统一显示并上报；三是可穿戴小终端，比如头盔或腕带上的状态指示模块。
这类项目的核心难点从来不是某一个模块“难驱动”，而是所有模块凑到一起之后，电源怎么分配、总线怎么分时复用、数据怎么对齐时间戳、掉电重启后怎么恢复配置。openrig 的定位就是把这层“胶水工作”标准化，让使用者可以跳过试错阶段。
1.2 设计思路：模块化与半开源的取舍
openrig 没有走全集成路线，而是选了“核心板 + 扩展接口”这种更稳妥的方案。核心板上固定了主控、电源、USB 转串口、烧录接口和一块 LED 状态灯；扩展区则用 2.54mm 排针引出 I2C、UART、SPI、ADC、GPIO，以及一路 CAN 收发器。这样做的好处有三点。
第一，降低入门门槛。新手只需要按排针丝印接外设，不用一开始就设计 PCB，面包板就能跑通。第二，故障隔离方便。哪一路外设出问题，拔掉对应排线就行，不用整体返工。第三，升级空间大。后期想加 4G 模块、GPS、LoRa，只需走扩展接口，核心板无需改动。
从实际经验看，半开源设计还有一个隐性优势：方案可以让用户自己选择“抄作业”还是“自由发挥”。对只是想复现的人来说，跟着默认的引脚定义接线即可；对有改造需求的人来说，全部引脚映射又在源码里开放，Fw 层重映射也预留了接口。这种取舍比我见过的一味堆料方案要成熟得多。
1.3 方案选型：为什么是 ESP32 而不是树莓派或 STM32
这是我被问得最多的问题。直接给结论：在这个项目场景下，ESP32 是最平衡的选型。
- 性价比：单片价格比 STM32F4 同等资源便宜，模块整体 BOM 可以压在百元以内；树莓派 Zero 虽然也能跑，但外设扩展还要转接 HAT，体积和功耗都受限制。
- 双核 + 无线：openrig 需要“采集一路、显示一路、对外通信一路”并行工作，ESP32 的双核正好可以把协议解析放在 Core 0，显示刷新放 Core 1，避免画面卡顿。
- 外设资源：I2C、SPI、UART、ADC、触摸、CAN（需外挂收发器）都齐备。
- 软件生态：Arduino、ESP-IDF、MicroPython 三套环境都能跑，社区例子多到可以“复制粘贴入门”。
树莓派不是不能用，但启动时间、功耗、供电复杂度会让这套小设备失去“即插即用”的便携优势；STM32 更适合对实时性要求极端的场景，但开发调试门槛明显高一些，不适合这种偏向实验和改装的开源框架。openrig 选择 ESP32，本质上是在低门槛和实用性能之间做了合理的折中。
2. 核心硬件接口与选型细节
2.1 主控核心：可选的 ESP32 系列区别
openrig 的主控区域兼容 ESP32-WROOM-32E、ESP32-S3-WROOM-1 和 ESP32-C3 三款模组。它们的区别需要讲清楚，否则有人买错模组会踩坑。
- ESP32-WROOM-32E：双核 Xtensa LX6，240MHz，经典款。优点是资料最多、例程最全、几乎每根引脚都能引出；缺点是功耗稍高，好货价格已经有上涨趋势。
- ESP32-S3-WROOM-1：双核 LX7，240MHz，自带向量指令加速和更多 GPIO，同时支持 USB 原生烧录。如果项目要跑屏幕刷新或者做简单边缘识别，S3 更合适。
- ESP32-C3：单核 RISC-V，160MHz，Wi-Fi 和 BLE 都有，但引脚少。openrig 默认 BOM 不推荐 C3 为主控，因为 I2C 和 UART 同时挂载后预留的调试口会紧张。只做纯显示、无太多外设时，C3 倒是可以压缩成本。
从实际开发角度看，我建议首次复刻的人直接用 ESP32-WROOM-32E 或开发板，跑通逻辑后觉得性能不够再升级 S3。它们的引脚定义在 openrig 源码的board_pins.h里有条件编译，改一个宏就切换，不用改接线。
2.2 传感与外设选型参考
openrig 默认推荐的外设都是“便宜、有库、资料多”的类型。下表是实测过比较稳的组合：
| 模块 | 型号/方案 | 接口 | 实测体验 |
|---|---|---|---|
| 温湿度 | SHT30 / SHT31 | I2C | 比 DHT11 稳定太多，精度 ±0.2°C，建议优先选 |
| 姿态 | MPU6050 / QMI8658 | I2C | MPU6050 旧但例程多，QMI8658 抗温飘更好 |
| 电压检测 | INA226 / 分压电阻 | I2C / ADC | INA226 可以直接测电流和功率，适合做功耗统计 |
| 显示 | 1.3 寸 ST7789 IPS | SPI | 240x240，性价比高；不建议用 OLED，刷新慢且易烧屏 |
| 定位 | ATGM336H / NEO-6M | UART | ATGM336H 冷启动更快，且价格便宜 |
| CAN 通信 | SN65HVD230 模块 | SPI/UART 转 CAN | 接入车载 OBD 或工业总线时要用 |
选择时我的原则是：凡是能用 I2C 解决的，绝不占 UART，因为串口资源在调试阶段非常宝贵；SPI 屏必须用专用 SPI 总线而不是 GPIO 模拟，否则刷新率掉一半以上。这里特别提醒：ST7789 这类屏的背光引脚默认是低电平点亮，如果你的模块和 openrig 的引脚定义不一致，需要把背光逻辑在驱动里反转，否则屏会一直暗着，误以为屏幕坏了。
2.3 接口映射与电气风险点
开放接口的排针丝印上，openrig 做了几种不同颜色的标注：红色是电源、黑色是 GND、黄色是主要外设、绿色是 SPI、蓝色是 UART。这是硬件设计者很贴心的做法，但接线时仍要注意三点。
第一，3.3V 与 5V 不要混插。ESP32 的 GPIO 耐压是 3.3V，很多 5V 传感器模块带有板载稳压，可以直接接 5V 供电，但它的信号线如果是推挽输出而没有电平转换，会烧 GPIO。我在调试 CAN 模块时就吃过这个亏。第二，I2C 上拉电阻。ESP32 内部有上拉但阻值偏弱，如果总线上挂超过三个设备，建议外部补焊两个 4.7k 电阻到 3.3V，否则通信偶发失败。第三，电源输入范围。标称输入是 USB 5V 或者锂电池 3.7-4.2V，但如果外部设备工作电流超过 800mA，最好把电源管理和主控分开供电，而不是让稳压器硬扛。
3. 软件架构与固件设计
3.1 分层设计：驱动、协议、应用三层分离
openrig 的固件虽然不算大，但它做了清晰的三层划分，这个思路很值得借鉴。
- 驱动层：每个传感器的初始化、数据读取、寄存器配置都封装成独立函数，不掺业务逻辑。比如
sht30_read_temperature()只负责 I2C 读取和 CRC 校验。 - 协议层：负责解析外部数据，例如 OBD 的 PID 请求应答、自定义串口帧协议、CAN 报文转译。这一层把“外部世界”和“内部显示”隔离开，换数据源时不必动 UI。
- 应用层：处理页面切换、报警触发、数据记录。这一层只依赖协议层定义的统一结构体，比如
sensor_data_t、vehicle_data_t，不直接碰寄存器。
老手可能觉得这有点过度设计，但实际用下来，这个分层极大地降低了调试成本。最典型的例子是：我后来把原来的 MPU6050 换成了 QMI8658，按这个结构只改了驱动层一个文件，协议层和应用层完全没动，半小时就完成了替换。
3.2 关键代码：多线程与数据流
openrig 的代码基于 Arduino 框架，但核心用到了 FreeRTOS 任务。下面是一个典型的任务分配示例：
void setup() { // 初始化各外设 init_display(); init_i2c_bus(); init_sensor_all(); // 核心数据采集任务，运行在 Core 0 xTaskCreatePinnedToCore( sensor_task, "sensor_task", 4096, NULL, 1, NULL, 0); // UI 刷新任务，运行在 Core 1 xTaskCreatePinnedToCore( ui_task, "ui_task", 8192, NULL, 1, NULL, 1); } void sensor_task(void *param) { while (1) { // 采集一次全量数据，存入共享结构体 read_all_sensors(&g_sensor_data); // 推送显示队列 notify_ui_event(EVENT_DATA_UPDATE); vTaskDelay(100); // 10Hz 刷新率 } } void ui_task(void *param) { while (1) { handle_ui_event(); vTaskDelay(16); // 约 60fps 的事件处理 } }注意我把数据采集放在了 Core 0，UI 事件处理放在了 Core 1。因为 ESP32 的 Wi-Fi 协议栈也运行在 Core 0，如果采集任务过重可能会影响无线吞吐，但显示刷新和无线没有直接冲突。这样安排之后，即使同时开着 Wi-Fi 传输日志，屏幕切换页面也不会卡。
3.3 数据协议：如何与上位机通信
openrig 与上位机的通信有两种方式：一是通过 USB 串口，二是通过 Wi-Fi 的 TCP WebSocket。最简单的自定义帧协议是“帧头 + 长度 + 类型 + 数据 + CRC”，例如：
0xAA 0x55 LEN TYPE DATA[LEN-2] CRC16其中 TYPE 分为0x01表示传感器数据、0x02表示车辆数据、0x03表示配置读写。我建议大家在代码里预留一个配置结构体，可以把屏幕亮度、页面顺序、传感器轮询间隔通过上位机下发，烧录后不再需要频繁接线。这个功能对开模和快速迭代非常有帮助。
有人问为什么不用现成的 JSON 或 MQTT？因为 openrig 的定位还包含 CAN 总线和串口链路，这些链路的带宽可能只有几十 KBps，JSON 带外开销太大，自定义二进制帧在这种环境下更为稳妥。若走 Wi-Fi，再在网络层包一层 MQTT 或 HTTP 并不冲突。
4. 实操组装与调试全流程
4.1 焊接到上电的完整步骤
我按下面步骤走，基本可以一次点亮：
- 先焊接主控模组、电源芯片、USB 座。焊接时注意 ESP32 模组的散热焊盘，温度 350°C 左右，别在一个引脚上停留超过三秒。
- 焊接 I2C、UART 排针。使用 2.54mm 单排针，可以先插在面包板上再焊，保证排针垂直。
- 连接 ST7789 屏幕。SPI 的四根线（SCLK、MOSI、CS、DC）分别接主控指定引脚，注意背光引脚单独控制。
- 连接传感器。先只接一路传感器，验证 I2C 地址扫描成功后再加第二路，避免一次性接线过多导致问题定位困难。
- 上电前用万用表蜂鸣档测量 3.3V 与 GND 是否有短路，这是必须步骤。如果电阻小于 2Ω，先不要上电，检查焊接。
- 接 USB 烧录。按住板载 BOOT 键再插 USB，可以看到串口枚举；用
esptool.py或 Arduino IDE 烧录引导程序。
第一次上电时，我习惯先烧一个最简单的 Blink 程序，确认主控和电源正常。如果连 LED 都不闪烁，优先检查 EN 复位引脚是否有 3.3V，以及晶振是否起振。
4.2 用 I2C 扫描快速确认外设
这是调试 I2C 设备时的基本功。在 Arduino 里跑一段 I2C 扫描程序，代码极短但能节省大量时间。
#include <Wire.h> void setup() { Serial.begin(115200); Wire.begin(21, 22); // SDA, SCL } void loop() { delay(500); for (byte addr = 1; addr < 127; addr++) { Wire.beginTransmission(addr); if (Wire.endTransmission() == 0) { Serial.printf("Found I2C device at 0x%02X\n", addr); } } }实测中，SHT30 通常出现在 0x44 或 0x45，MPU6050 是 0x68（或 0x69），INA226 可通过地址引脚设置。如果找不到设备，最可能的原因是上拉电阻缺失或地址引脚悬空。
4.3 显示与采集联调的常见问题
联调阶段出现“屏幕有显示但数据不动”的现象很常见。排查顺序是：先看传感器数据有没有更新串口打印，再看 UI 事件有没有触发，最后看显示队列有没有被填充。openrig 的 UI 事件采用了发布订阅模式，数据采集任务更新共享结构体后发事件，UI 任务收到事件才重绘对应区域，而不是全屏刷新。这避免了频繁刷新导致的撕裂感，也让漏电功耗降低了不少。
如果你发现某些区域刷新异常，可以把CONFIG_PARTIAL_REFRESH_ENABLE关掉，强制全屏刷新定位是绘制逻辑问题还是局部变量的问题。这里提醒一下：SPI 屏全屏刷新 240x240 大约要 60ms，如果 UI 任务里同时做了耗时操作，刷新率会肉眼可见地下降。优先保证 UI 任务只在事件驱动的回调里做绘制。
5. 常见问题与排查技巧实录
5.1 问题速查表
我把实际调试中遇到的高频问题整理成了表，方便大家按图索骥。
| 现象 | 可能原因 | 处理方案 |
|---|---|---|
| 上电后无任何反应 | 电源短路 / EN 引脚被拉低 / 晶振未起振 | 测 3.3V 和 GND 阻值，排查复位电路，检查晶振焊点 |
| 串口无输出 | 烧录了错误的波特率 / USB 驱动未装 | 用 115200 默认波特率，装 CP210x 或 CH340 驱动 |
| I2C 扫描不到传感器 | 地址错误 / 上拉不足 / SDA SCL 接反 | 确认设备地址和引脚，补焊 4.7k 上拉 |
| 屏幕花屏或白屏 | SPI 速率过高 / 初始化时序不对 / 背光未开 | 降低 SPI 频率到 20MHz 试，核对 reset 引脚时序 |
| 数据一直刷新但数值不变 | 传感器寄存器配置错误 / 未使能连续采集 | 读取设备 ID 寄存器验证通信，确认采集模式 |
| Wi-Fi 连接失败 | 天线区域被遮挡 / 电源纹波过大 | 使用外接天线版本模组，在电源输入加 100uF 电容 |
| CAN 收发无数据 | 终端电阻缺少 / 波特率不匹配 | 总线两端各接一个 120Ω 电阻，波特率设置为 500k 试 |
5.2 独家排查工具与习惯
除了万用表，我强烈建议在调试这类项目时配一个逻辑分析仪，不用贵的，十几块钱的 8 通道版本就够用。把 SDA、SCL、SPI 的 CLK 和 MOSI 一起挂上去，可以直观看到波形。大多数通信问题在波形面前无处遁形。比如一次 I2C 偶发超时，我抓了一个小时寄存器配置才发现是某引脚被复用成了 ADC，逻辑分析仪上能看到第七、第八个 SCL 时钟后 SDA 被拉低，问题立刻定位。
另一个好习惯是每个硬件改动后拍一张照，记录接线和跳线帽位置。听起来像老生常谈，但真到排查时，这比记忆可靠得多。尤其是改了电源跳线或者触发了某些保护后，回退到上一个正确状态是最快的修复路径。
5.3 电源纹波与静电问题
最后专门提一下电源。openrig 这类带屏幕和无线模块的设备，在电机或继电器启停瞬间容易出现电压跌落，表现就是屏幕闪一下或者 ESP32 自动重启。解决思路是：主控电源前加一个 100uF 钽电容（或两个 47uF 并联），屏幕供电再单独加一个 10uF；同时把 INA226 或分压采样的地线单独走，不要和传感器信号地共用一根长线。
静电问题在干燥季节尤其突出。首次使用 USB 插拔时，尽量先触碰金属外壳放静电，否则可能打坏 ESP32 的 USB 接口。如果长期在野外使用，至少在 USB 座和排针旁边预留 ESD 保护二极管的位置。
根据我个人经验，这类开源硬件项目最容易翻车的地方不是复杂的协议，反而是供电和地线。你花了两个小时写代码未必有这个半小时布线和检查电源有效。openrig 的框架帮你把接口标准化了，但供电扎实与否，永远是自己要守好的底线。
最后再分享一个小技巧：如果你打算长时间开机跑功耗测试，把屏幕亮度调到 50%，关掉 Wi-Fi 或用深度睡眠唤醒模式，整机电流可以从上百毫安降到十几毫安。这块的调优空间其实比换主控芯片还大，适合喜欢折腾的朋友继续深挖。
