电赛元器件硬件字典

使用顺序

先按类别找到模块，看实物/参考图确认自己手上是不是同一类接口。
再看电路/接线图确认电源边界、信号方向、是否需要驱动器或收发器。
最后打开 Markdown 卡片，把具体主控脚落到接线总表里。

当前必须补拍

MG310 GMR 编码器电机：单件参考图来源：ebuy7/淘宝商品图；你手上电机的 6P 线序仍以实物插头和线色为准
MG513X / MG513XL 霍尔编码器直流减速电机：实物图来源：轮趣科技 MG513X/MG513XL 官方产品页；霍尔/GMR 版本外观和 6P 插头可能不同，接线前以你手上插头线序为准
灰度巡迹模块：装配参考图来自本地 25E 三轮底盘资料；灰度模块单件排针丝印仍建议实拍替换
激光驱动板：实物图待替换：建议拍驱动板丝印、激光头正负极
张大头/ZDT 闭环步进驱动：实物图来自张大头 Emm42_V5.0 手册渲染；你手上驱动器端子、拨码/地址仍建议实拍确认

主控选择

主控选择矩阵

先决定谁负责实时安全闭环，再决定视觉、姿态、显示和执行器怎么分工。比赛现场优先选接口余量大、调试路径稳、踩坑少的组合。

主控 / 角色	串口数量与用法	PWM / 定时器	ADC	CAN / 高速接口	调试方式	适合题型	最容易踩坑
STM32F103C8T6 Blue Pill轻量主控 / 备份板	USART1/2/3；常用 1 路视觉 + 1 路调试	定时器够用，适合 TB6612/AT8236、舵机、激光 EN	10 路左右 12-bit ADC，够灰度/电压采样	有 bxCAN 引脚，但必须外接 CAN 收发器	SWD：PA13/PA14；常见 STLink/DAPLink	小型云台、单机控制、备用主控、低风险练习	PA13/PA14 别占；PA11/PA12 不能直接接 CANH/CANL；5V 模块输出要查电平
立创天猛星 MSPM0G3507电赛实时控制主控	UART0/1/2/3；适合视觉、串口屏、IMU、调试分开	TIMA/TIMG 资源丰富，优先做电机 PWM/编码器捕获	12-bit ADC + VREF/DAC，适合模拟采样和闭环调参	有 CAN_TX/RX，仍需外部 CAN 收发器	SWD + RST；必要时 ROM UART BSL	差速底盘、传感器融合、PWM 控制、2026 控制题主线	SWD/RST/BSL 保留；PA18/BSL 状态别误触发；电机/步进/激光不要吃板载 3V3
立创天空星 STM32F407高性能主控 / 多外设板	多 USART/UART；适合多模块并行通信	高级/通用定时器多，适合多轴 PWM、编码器、舵机	多通道 12-bit ADC，适合高速采样和多路模拟量	CAN 资源更充裕；总线仍要收发器和终端电阻	SWD/JTAG；PA13/PA14 优先保留	复杂底盘、多串口视觉协同、SDIO 记录、多执行器系统	P1/P2 序号先查 Pinout；TF/LCD/音频/按键/LED 会占脚；同一 TIM 通道要成组规划
MaixCAM Pro / K230视觉协处理器	UART 输出识别结果给 MCU，USB/串口用于调试	不建议承担电机实时闭环；只做视觉侧 IO 辅助	不作为比赛实时模拟采样主线	通常不直接做 CAN 主控；通过 MCU 转总线更稳	USB、串口日志、脚本/模型调试	识别色块、二维码、靶标、赛道/目标点，再把 valid/dx/dy 发给主控	不要让视觉板直接管危险执行器；协议先只传少量字段；供电、电平和帧率要留余量

默认组合：天猛星 M0 或天空星 F407 管实时控制和安全状态机，MaixCAM 只发识别结果；F103 适合轻量任务、备份板或独立子系统。

题型搭配

典型题型主控搭配表

从题型反推硬件分工：先定主控，再定视觉、姿态、执行器和显示。每一行都是首版能开工的组合，后续再按实际题目删减。

题型 / 优先级	推荐主控	视觉 / 识别	姿态 / 传感	执行器 / 驱动	调试 / 显示	第一轮必须先测
视觉导航与定点小车2026 控制题主线	天猛星 M0；多串口/记录需求高时上天空星 F407	MaixCAM Pro/K230 输出 valid、dx、dy、目标 ID	BNO085/JY61P 做航向；灰度阵列做近场补线	AT8236/TB6612 + MG310/MG513X 编码器电机；必要时加蜂鸣/灯光提示	OLED 显示模式、误差、速度；串口日志留给调参	先跑视觉 UART 帧，再空载轮速闭环，最后验证急停和丢目标停车
巡迹 / 灰度底盘最稳基础题	天猛星 M0 优先；F103 可做轻量版	通常不用视觉；复杂路口可加 MaixCAM 辅助识别标志	灰度巡迹模块 + 编码器；BNO085/JY61P 辅助抗漂移	AT8236/TB6612 + MG310/MG513X；PWM 和编码器捕获尽量成组规划	OLED 显示黑白阈值、线位、置信度、速度	先定黑白阈值和线位方向，再开低速直线，最后测角点和丢线恢复
云台打靶 / 激光瞄准视觉 + 执行器耦合	天空星 F407 做复杂版；F103 可做轻量双轴版	MaixCAM Pro/K230 识别靶心、色块或二维码	BNO085/JY61P 可做机体姿态补偿；限位开关必须保留	张大头/ZDT 闭环步进或舵机云台 + 激光驱动板	OLED/串口屏显示靶点偏差、云台状态、锁定状态	先禁用激光只动云台，再低功率点亮；每个轴必须先验证 STOP 和限位
电磁搬运 / 钢球 PPR 送料兼容扩展题	天猛星 M0 管实时闸门；机构复杂或多传感时用 F407	MaixCAM 可识别目标区、钢球位置或投放标志	称重/霍尔/光电/限位优先；IMU 只做车体姿态辅助	电磁铁 MOS 驱动、舵机闸门、送料电机或小车底盘	OLED/数码管显示目标数量、已投放、故障状态	先测电磁铁续流、温升和电源跌落，再测单球释放，最后上车闭环
多车通信 / 协同控制发挥题常见	天空星 F407 做主车；天猛星 M0 做从车或执行节点	主车可挂 MaixCAM；从车只接收目标或相对位姿	每车保留编码器和 IMU；关键状态要本地闭环	每车独立 AT8236/TB6612 + MG310/MG513X，或 ZDT 执行器	OLED 显示车号、链路、任务阶段；无线/CAN 留心跳	先双车心跳和超时停车，再发目标点，最后测通信丢包和重连
姿态稳定 / 平衡 / 平台控制高频闭环训练	天猛星 M0 优先实时控制；复杂多轴可上 F407	一般不用视觉；需要定位时才加 MaixCAM	BNO085 快速出姿态；ICM42688/MPU6050 适合练裸传感器融合	AT8236/TB6612 电机、舵机或闭环步进，按负载选驱动	OLED 显示角度、角速度、PWM、故障；串口输出曲线	先静态 IMU 零偏，再小 PWM 方向测试，最后限制角度和占空比闭环

先别急着一次性全接：每个题型都按“通信帧 -> 单模块 smoke -> 执行器空载 -> 安全停机 -> 上车闭环”的顺序推进。

STM32F103C8T6 Blue Pill 主控板

常见 F103 最小系统板，可做云台/执行/轻量底盘主控；模块库里按接口复用，不绑定具体题目。

主控已有公开实物图

核心定位轻量控制板、备用主控、云台/小执行器子系统

代码链路CubeMX/CubeIDE 或 Keil 生成外设初始化，业务代码放在 main 循环、定时器回调和串口接收回调里

下载调试SWD 使用 PA13/PA14，保留 NRST 更利于现场救程序

电气边界GPIO 为 3.3V 逻辑，电机、激光、步进不能从板载 3V3 取电

开发链路 / 适用题型

阶段	要做什么	可见证据
空工程	先跑 safe-idle，确认启动文件、时钟、SWD 和主循环。	能下载、复位后 LED/串口心跳正常。
外设 smoke	分别跑 UART 回环、I2C 扫描、PWM 空载、GPIO 输入。	串口有字节、I2C 有地址、PWM 占空比可测。
模块接入	一次只接一个外设，把 Init/Tick/GetSnapshot 分层。	每个模块有最小日志和失败码。
题目集成	把视觉/姿态/执行器接到 App 状态机，不在中断里跑业务。	STOP、超时和默认安全状态能单独验证。

轻量云台
串口/I2C 外设验证
备用主控
单执行器小系统
低风险练习板

落地代码链路

层级	入口 / 文件 / 命令	验收证据
safe-idle 构建	python online-build/tools/build_firmware.py --target stm32f103c8-safe-idle	生成 firmware.elf/hex/bin、firmware.map 和 build-manifest.json，只证明启动链路。
下载调试入口	PA13=SWDIO、PA14=SWCLK，NRST 建议接出；不要把 SWD 脚复用给普通外设。	调试器能 attach、复位后 heartbeat/LED/串口心跳正常。
外设接入模板	App_Init -> UartProbe/I2cScan/PwmSmoke -> App_Tick 状态机	UART 字节计数、I2C 地址、PWM 占空比和 STOP 路径都有单独日志。

例程字典

例程 / 模板	位置 / 目标	什么时候用
safe-idle 在线编译模板	stm32f103c8-safe-idle	只验证工具链、启动文件、链接脚本和空闲主循环，不驱动外设
串口模块模板	USART1/USART2 + 环形缓冲	接 MaixCAM/JY61P/ZDT TTL 时，先只收帧和打印状态
I2C 调试模板	I2C1 + 地址扫描	OLED/MPU6050 上车前先扫 0x3C/0x68，确认上拉和线序
PWM/GPIO 执行模板	TIM PWM + GPIO	TB6612、激光 EN/PWM、舵机先空载低占空比验证

代码怎么调用

F103 先用生成工具把 GPIO/UART/I2C/TIM 初始化好，再在用户代码区写业务调用；不要在中断里做阻塞打印或长计算。

在 CubeMX/Keil 中开启 SWD，避免把 PA13/PA14 改成普通 GPIO。
为每个外设先写最小 smoke 函数，例如 UartProbe、I2cScan、MotorLowSpeedTest。
主循环只调状态机；串口接收只入缓冲；定时器中断只做计数/置标志。

int main(void) {
  HAL_Init();
  SystemClock_Config();
  MX_GPIO_Init();
  MX_USART1_UART_Init();
  MX_I2C1_Init();
  MX_TIM3_Init();
  App_Init();
  while (1) { App_Tick(); }
}

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
PA13/PA14	DAPLink/STLink SWDIO/SWCLK	下载调试固定保留；现场故障靠它恢复
PA9 -> 外设 RX；PA10 <- 外设 TX	视觉/JY61P/ZDT TTL	UART 必须 TX/RX 交叉，GND 共地
PB6/PB7	OLED/MPU6050 SCL/SDA	I2C1 常用脚；确认模块是否已有上拉
TIMx_CHx	TB6612 PWMA/PWMB 或舵机 PWM	PWM 尽量用同一组定时器，便于统一频率
5V/3V3/GND	小信号模块供电参考	大电流执行器另供电，但必须共地

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
电源域	5V、3V3、GND、稳压器和 USB 供电路径	先确认外设只吃逻辑电源，电机/激光/步进另供电并共地。	把板载 3V3 当执行器电源会掉压复位，5V 模块输出直进 IO 也可能超压。
下载恢复	PA13/PA14 SWDIO/SWCLK、NRST、BOOT0	SWD 和 NRST 保留到排针，BOOT0 默认不误拉高。	占用 PA13/PA14 后现场无法下载；BOOT 配错会表现为烧录后不启动。
通信边界	PA9/PA10 USART、PA11/PA12 USB/CAN 复用	UART 按 TX/RX 交叉；CAN 必须外接收发器后才到 CANH/CANL。	把 PA11/PA12 当 CANH/CANL 直连会完全不通，甚至损坏总线侧器件。

原理图证据 / 上电清单

本页已有 Blue Pill 原理图 PDF 来源和本地接口速查 SVG；接线前先看电源、晶振、BOOT、SWD、USB/CAN 复用。
PA11/PA12 是 MCU USB/CAN 相关引脚，不等于 CANH/CANL；接 CAN 必须经过收发器。
不同 Blue Pill 克隆板 5V、3V3、BOOT0、PC13 LED 细节可能不同，以板上丝印和实物测试为准。

资料入口

stm32-base.org / STM32F103C8T6-Blue-Pill.html图片、资料或原理图来源
stm32-base.org / STM32F103C8T6_Blue_Pill-2.jpg图片、资料或原理图来源
stm32-base.org / original-schematic-STM32F103C8T6-Blue_Pill.pdf图片、资料或原理图来源

SWD 能连接
空工程能下载运行
串口回环能收到
I2C 扫描能找到地址
PWM 空载输出正确

故障定位表

现象	常见原因	下一步证据
SWD 连不上	PA13/PA14 被复用、NRST 未接、BOOT/供电异常	断开外设，保留 SWD/NRST，先只下载空工程。
串口无输出	TX/RX 未交叉、波特率不一致、GPIO 复用未开	用 USB-TTL 做回环，再只发固定 heartbeat。
I2C 找不到 OLED/MPU6050	SCL/SDA 接反、无上拉、地址 0x3C/0x3D/0x68/0x69 不一致	先跑地址扫描，降低速率并缩短线。

STM32F103C8T6 Blue Pill 主控板实物图 — 实物 / 参考图

电路 / 接线 / 补充图

模块脚	连接对象	说明
PA9/PA10	USART1 TX/RX	视觉/JY61P/调试串口
PA2/PA3	USART2 TX/RX	底盘通信/调试
PB6/PB7	I2C1 SCL/SDA	OLED/MPU6050
PA11/PA12	USB 或 CAN	CAN 需收发器
PB0/PB1	GPIO/PWM	激光 EN/PWM 或普通输出
PA13/PA14	SWDIO/SWCLK	下载调试，别随便占
5V/3V3/GND	模块供电/共地	不带电机/激光/步进

接线禁忌 / 调试重点

F103 IO 是 3.3V 逻辑
PA13/PA14 留给 SWD
CANH/CANL 不能直连 PA11/PA12
电机/激光/步进独立供电
按题目决定它是主控还是辅助板

打开 Markdown 卡片

立创天猛星 MSPM0G3507 M0 主控板

TI MSPM0G3507 主控板，适合底盘控制、传感器采集、PWM/定时器练习和低功耗 M0 题目。按模块接口复用，不绑定某一道题。

主控已有官方/开源项目实物图、板载资源图和 MCU 引脚图

核心定位电赛实时控制主控，适合差速底盘、PWM/编码器、传感器融合和安全状态机

代码链路TI MSPM0 SDK + SysConfig + driverlib，生成外设初始化后写 App 层状态机

下载调试SWD/RST 优先；必要时 ROM UART BSL，但要先确认 PA18/BSL 和 TX/RX

推荐架构M0 管实时闭环和急停，MaixCAM/F407/F103 只发送上层目标或辅助信息

开发链路 / 适用题型

阶段	要做什么	可见证据
工具链	用 TI MSPM0 SDK、SysConfig、GNU Arm/Makefile 跑 safe-idle。	本地或在线编译产物 fresh，SWD 可 attach。
板级 ABI	固定 BoardApp_Init/BoardApp_Poll 和 runtime 字段，不手改 SysConfig 生成文件。	loop_counter、boot_cookie、APP_READY 可读。
外设分层	JY61P、TB6612、OLED、线阵都走 Init/Poll/Snapshot/Command。	UART 帧计数、PWM/编码器、OLED ACK、line_raw_bits 都有运行态证据。
安全闭环	电机/激光/步进先经过 DISARM/ARM/RUNNING/FAULT 状态机。	STOP 和 DISARM 后 duty/command 归零。

2026 视觉导航定点小车
差速底盘
传感器融合
PWM/编码器闭环
实时安全控制

落地代码链路

层级	入口 / 文件 / 命令	验收证据
safe-idle 构建	python online-build/tools/build_firmware.py --target mspm0g3507-safe-idle	生成 fresh 产物；先证明 GNU Arm、链接脚本和启动文件可用。
车载主循环	BoardApp_Init -> BoardApp_Poll，外设走 Init/Poll/Snapshot/Command	boot_cookie、loop_counter、APP_READY、模块 runtime 字段可读。
SWD 调试 ABI	g_board_app_runtime / g_board_app_swd_control / g_board_app_line_snapshot	每次重编后从最新 ELF 解析符号，不复用旧地址。
UART BSL 救援	9600 8N1：connection_pack -> 0xBB -> GET_ID -> password/erase/download	不能只发 0xBB；每一步记录响应字节和超时。

例程字典

例程 / 模板	位置 / 目标	什么时候用
safe-idle 在线编译模板	mspm0g3507-safe-idle	验证 MSPM0 工具链、链接和空闲主循环
2026 天猛星车载最小上板工程骨架	本地 MSPM03507各模块例程代码/80_integrated_app	已整理 JY61P、线阵、TB6612、OLED 和安全 DISARMED 默认状态
MSPM0 UART BSL 恢复流程	Connection frame -> 0xBB -> GET_ID	救砖/串口下载时用，不能只发单字节 0xBB
AT8236 + MG513X 速度闭环移植	https://github.com/ZhiKong0/nuedc-component-examples/tree/main/motor/at8236-mg513x	移植电机驱动、编码器测速和速度 PI

代码怎么调用

M0 代码建议分三层：SysConfig/driverlib 初始化、board_app 驱动封装、App 状态机。执行器必须受 DISARM/STOP 统一安全门控制。

先在 SysConfig 里固定 UART/I2C/PWM/编码器/ADC 引脚，导出后不要手改生成文件。
每个外设写 Init、Poll/Tick、GetSnapshot 或 Command 函数，主循环只调 App_Tick。
电机和激光类输出必须先经过 arm/disarm 状态，调试时默认 DISARMED。

int main(void) {
  SYSCFG_DL_init();
  BoardApp_Init();
  while (1) {
    BoardApp_Tick();
  }
}

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
SWDIO/SWCLK/RST	DAPLink	下载、读内存、运行态证明都依赖它
PA18/BSL	BSL 模式控制	进入 ROM BSL 前必须明确电平状态，避免误触发
UART0 PA0/PA1	JY61P 或调试串口	已有车载骨架使用 UART0 作为 JY61P 入口
TIMG/TIMA PWM	TB6612/AT8236 控制输入	电机 PWM 优先用连续定时器资源
I2C0 PA31/PA28	SSD1306 OLED	已在车载骨架中作为显示调试路径
GPIO/ADC	灰度线阵 OUT0..OUTn	先做阈值/方向表，再接入闭环

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
板载资源	官方 pinout、板载资源图、排针丝印	先冻结 UART/I2C/PWM/编码器/SWD 的占脚表，再接外设。	只看芯片 GPIO 名会忽略板载占脚，导致 OLED、线阵、JY61P 互相抢脚。
下载与救援	SWDIO/SWCLK/RST、PA18/BSL、UART BSL TX/RX	SWD 优先保留；需要 BSL 时按 PA18 和完整 connection frame 流程。	BSL 只发 0xBB 或 TX/RX 接反会表现为无响应，盲目擦写会放大故障。
执行器隔离	5V、3V3、GND、VM/VIN 外部供电接口	电机、激光、步进电源独立，主控只给逻辑信号且全部共地。	执行器电流走主控板会引起复位、ADC 漂移和通信丢帧。

原理图证据 / 上电清单

本页已有天猛星板载资源图、MSPM0G3507 pinout 和开源硬件工程入口；查引脚时先用官方 pinout，再看板上接口丝印。
CAN_TX/RX 不是 CANH/CANL，必须加 CAN 收发器。
电机、步进、激光另供电，和主控共地；不要把板载 3V3 当执行器电源。

资料入口

天猛星 MSPM0G3507 官方教程先看板载资源、供电、下载和外设分布
天猛星资料下载中心原理图、资料包和例程入口
天猛星开源硬件工程查看 PCB、BOM、封装和原理图工程
item.szlcsc.com / 44440454.html图片、资料或原理图来源

SDK 能编译
SWD 能 attach
空工程能烧录
UART 有心跳
每个执行器默认 DISARMED

故障定位表

现象	常见原因	下一步证据
编译或烧录失败	SDK/工具链缺失、SysConfig 输出不匹配、pyOCD 目标或探针错误	先跑 safe-idle，记录命令、产物时间和 pyOCD list 结果。
BSL 无响应	没有先发完整 Connection 帧、PA18/BSL 状态不对、TX/RX 接反	按 connection_pack -> 0xBB -> GET_ID 顺序复测。
外设代码跑了但车不动	安全状态仍 DISARMED、输出编译开关关闭、VM/STBY/GND 问题	读 safety/motor_cmd/motor_duty，再决定改代码还是查硬件。

电路 / 接线 / 补充图

LCKFB TMX MSPM0G3507 TianMengXing board resources

LCKFB TMX MSPM0G3507 TianMengXing MSPM0G3507 pinout

例程 / 资料链接

天猛星 MSPM0G3507 官方教程先看板载资源、供电、下载和外设分布
天猛星资料下载中心原理图、资料包和例程入口
天猛星开源硬件工程查看 PCB、BOM、封装和原理图工程

模块脚	连接对象	说明
3V3/5V/GND	供电/共地	大电流另供电
SWDIO/SWCLK/RST	DAPLink/SWD	下载调试保留
BSL/PA18	ROM BSL	进串口下载模式
UART0-3 TX/RX	视觉/屏/调试	TX/RX 交叉接
I2C0-1 SCL/SDA	OLED/IMU	查上拉和地址
SPI0-1	Flash/高速外设	PICO/POCI 别接反
TIMG/TIMA	PWM/捕获	电机优先连续通道
ADC/VREF/DAC	模拟量	远离电机噪声
CAN_TX/RX	CAN 收发器	不可直连总线

接线禁忌 / 调试重点

IO 按 3.3V 逻辑处理
下载口和 RST 不要随便复用
UART BSL 前确认 TX/RX 和 PA18 状态
电机/步进/激光不要从板上 3V3 取电
同一接口外设多时先做引脚冲突表

打开 Markdown 卡片

立创天空星 STM32F407 主控板

STM32F407VxT6 高性能主控板，适合视觉协同、运动控制、SDIO/高速采样和多串口多定时器题目。引脚序号按官方 Pinout 图查。

主控已有官方引脚序号图、原理图总览和晶振原理图

核心定位高性能多外设主控，适合多串口视觉协同、复杂云台、多执行器和记录任务

代码链路STM32CubeMX/CubeIDE 或 Keil，先用官方 Pinout 锁定 P1/P2，再生成 HAL/LL 初始化

下载调试SWD/JTAG 保留；高速外设和板载资源会占脚，改线前先查原理图

典型角色主车/复杂外设汇聚板；实时危险执行仍要写 STOP 和超时保护

开发链路 / 适用题型

阶段	要做什么	可见证据
Pinout 冻结	先按官方 P1/P2 和板载资源表锁定 UART/I2C/SPI/TIM。	接口分配表写清楚，SWD/JTAG 未占用。
外设 smoke	逐个验证多 UART、SPI/I2C IMU、PWM/编码器、SDIO/日志。	每个接口有独立最小例程和日志。
并发通信	串口接收用 DMA/中断 + ring buffer，App 层统一调度。	丢帧/超时不会阻塞主循环。
复杂题集成	把视觉、云台、电机和记录分到状态机，不让驱动层直接决策。	每个执行器都有 STOP、限位和超时路径。

复杂底盘
多串口视觉协同
云台打靶
SDIO 记录
多执行器系统

落地代码链路

层级	入口 / 文件 / 命令	验收证据
safe-idle 构建	python online-build/tools/build_firmware.py --target stm32f407ve-safe-idle	生成 F407 safe-idle 产物，确认 M4 工具链和链接脚本。
Pinout 冻结	先查官方 P1/P2 交互式 Pinout，再生成 CubeMX/CubeIDE 工程。	每个 UART/I2C/SPI/TIM 都有唯一占用记录，SWD/JTAG 保留。
并发接收	USART DMA/IT -> ring buffer -> App_Tick 解析	记录 rx_bytes、last_frame、checksum_error，不让阻塞接收卡住主循环。
执行器安全	Motor/Laser/Stepper 只接受 App 层语义命令	STOP、限位、超时和 FAULT 均能单独触发。

例程字典

例程 / 模板	位置 / 目标	什么时候用
safe-idle 在线编译模板	stm32f407ve-safe-idle	验证 F407 工具链、启动文件和空闲工程
多 UART 外设模板	USART + DMA/IT	接 MaixCAM、串口屏、JY61P、ZDT TTL 时先分配优先级
SPI/I2C IMU 模板	https://github.com/ZhiKong0/nuedc-component-examples/tree/main/imu/icm42688-hardware	参考 ICM42688 驱动、OLED、编码器和步进代码组织
云台/激光控制模板	本地 ZDT/F103 云台资料可移植	先禁激光，只测云台 STOP、限位和低速点动

代码怎么调用

F407 适合把通信、记录和多外设集中起来，但代码上必须分层：驱动层不做业务决策，App 层统一处理状态和安全。

先按官方 Pinout 选 P1/P2 引脚，检查 TF/LCD/音频/按键/LED 是否占用。
串口接收优先 DMA/中断 + ring buffer，避免阻塞主循环。
PWM/编码器通道尽量按 TIM 成组规划，方便同步和频率统一。

void App_Tick(void) {
  Vision_Poll();
  Imu_Poll();
  MotorSafety_Update();
  Actuator_Update();
}

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
P1/P2 80P	所有外设排针	必须先查官方交互式 Pinout，不能只看 GPIO 名
PA13/PA14/NRST	SWD 调试器	保留下载和现场恢复能力
USARTx TX/RX	MaixCAM/JY61P/ZDT/串口屏	多串口要先分配优先级和波特率
I2C/SPI	OLED/IMU/Flash	短线、共地、确认上拉或 CS 电平
TIMx CHx	PWM/编码器/舵机	多轴控制要避免通道冲突

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
P1/P2 排针	官方 80P 引脚编号图和原理图总览	每个 USART/I2C/SPI/TIM 通道先写入接口分配表。	F407 外设多但复用也多，未冻结 pinout 会让后期连线反复返工。
调试口	PA13/PA14、NRST、JTAG/SWD 相关跳线	比赛现场保留 SWD/JTAG 下载恢复能力。	把调试口当普通 IO 后，卡死时只能拆线或进 Bootloader 救。
总线接口	CAN/RS485/USB/SDIO 外围电路和 3.3V 逻辑域	总线侧确认是否有收发器、终端电阻和外部接口保护。	MCU TX/RX 直连差分总线、5V 信号直入 IO 都会造成通信失败或硬件风险。

原理图证据 / 上电清单

本页已有官方 Pinout、原理图总览和晶振原理图；接线前先查板载外设占脚。
F407 IO 仍按 3.3V 逻辑处理；5V 模块输出接入前必须查电平兼容。
CAN/RS485 都需要外部收发器或板载接口确认，不能把 MCU 引脚直接接总线。

资料入口

天空星 STM32F407 官方教程先看板卡介绍、板载资源和外设入口
天空星官方原理图说明查电源、时钟、下载、板载外设占脚
天空星官方交互式 Pinout按 P1/P2 序号查具体 GPIO 和复用功能
天空星开源硬件工程查看 PCB、BOM、封装和原理图工程

Pinout 表已确认
SWD 能连接
串口分配表已写
板载占脚已排除
STOP/超时保护已验证

故障定位表

现象	常见原因	下一步证据
某个外设初始化后另一个外设失效	P1/P2 引脚复用或 TIM/USART 通道冲突	回到 Pinout 表，按外设组重新分配。
高速通信丢帧	阻塞接收、优先级不当、DMA 缓冲过小	改为 ring buffer，先只记录计数和 last_frame。
CAN/RS485 不通	把 MCU TX/RX 当成总线线直接接，缺收发器或终端	确认收发器、电源、终端电阻和总线侧线序。

电路 / 接线 / 补充图

LCKFB TKX STM32F407 SkyStar pin number map

LCKFB TKX STM32F407 SkyStar schematic overview

LCKFB TKX STM32F407 SkyStar crystal schematic

例程 / 资料链接

天空星 STM32F407 官方教程先看板卡介绍、板载资源和外设入口
天空星官方原理图说明查电源、时钟、下载、板载外设占脚
天空星官方交互式 Pinout按 P1/P2 序号查具体 GPIO 和复用功能
天空星开源硬件工程查看 PCB、BOM、封装和原理图工程

模块脚	连接对象	说明
P1/P2 80P	外接模块	先查 Pinout 序号
5V/3V3/GND	供电/共地	大电流另供电
PA13/PA14	SWD	下载调试保留
USART1-3	视觉/屏/调试	先分配优先级
PB6/PB7 I2C1	OLED/IMU	查板载占脚
PA5/PB5 SPI1	IMU/Flash	按 Pinout 接线
TIMx CHx	PWM/编码器	优先同一 TIM
SDIO/TF	TF 卡	启用后占 GPIO
CAN/RS485	收发器	外部转差分

接线禁忌 / 调试重点

先看 Pinout 序号再插线
板载 TF/LCD/音频/按键/LED 会占脚
F407 IO 仍按 3.3V 逻辑处理
SWD 口必须留出来便于现场救程序
所有模块上车前先做引脚冲突表

打开 Markdown 卡片

TB6612FNG 双路直流电机驱动

用于驱动两路直流电机；主控只给 PWM/GPIO，电机电流走 VM。

外设已有常用红板模块正反面引脚图

用途两路有刷直流电机 H 桥驱动；主控只给 PWM/GPIO，电机电流走 VM

调用方式PWM 控速度，AIN/BIN 控方向，STBY 作为总使能

接线风险VM 和 VCC 分开；编码器线不接 TB6612；电机上电前架空车轮

落地代码链路

层级	入口 / 文件 / 命令	验收证据
驱动 API	Tb6612_Init -> Tb6612_SetChannel(MOTOR_A/B, -1000..1000) -> Tb6612_Stop	setSpeed 内部统一方向脚、PWM、刹车/滑行策略。
天猛星接线约定	PWMA=PA12、PWMB=PA13；方向脚 PB17/PB19/PA16/PB24；STBY 按板子实际拉高或由 GPIO 控制。	读 motor_cmd、motor_drive、motor_duty、safety_state 后再判断代码/硬件。
低速 smoke	ARM -> 40..90 permille -> 800..1200 ms -> STOP -> DISARM	轮子架空，STOP 后 command/duty 归零，编码器 delta 与电机方向一致。

代码怎么调用

把每路电机封装成 setSpeed(-1000..1000)，函数内部决定方向脚和 PWM 占空比；所有输出受 motorEnable/stop 统一控制。

初始化 PWMA/PWMB 为同频 PWM，AIN1/AIN2/BIN1/BIN2/STBY 为推挽输出。
启动前 STBY 拉低、PWM=0；确认方向脚后再 STBY 拉高。
速度为正反向时互斥方向脚；速度为 0 时 PWM=0 并按刹车/滑行策略处理。

void Motor_Set(int left, int right) {
  Tb6612_SetChannel(MOTOR_A, left);
  Tb6612_SetChannel(MOTOR_B, right);
}

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
VM	电机电源正极	承载电机电流，按电机电压选择
VCC	主控 3V3/5V 逻辑电源	只供芯片逻辑，不等于电机电源
GND	主控地、电池地	控制信号必须共地
PWMA/PWMB	主控 PWM 输出	调速
AIN1/AIN2/BIN1/BIN2	主控 GPIO	决定两路电机方向
AO1/AO2/BO1/BO2	左右电机两根电机线	只接电机绕组，不接编码器

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
双电源	VM、VCC、GND、板上滤波电容	VM 接电机电源，VCC 接逻辑电源，两路地必须相连。	VM/VCC 混接会导致电机不转、主控复位，严重时损坏驱动板。
使能脚	STBY、PWMA/PWMB、AIN/BIN 到芯片脚	STBY 默认安全态，PWM 和方向脚上电先归零。	STBY 悬空或方向脚未初始化会出现上电乱转。
输出端	AO1/AO2、BO1/BO2 与电机端子	输出端只接电机绕组，编码器 A/B 不接 TB6612。	把编码器线接到 H 桥输出会烧传感器或主控输入。

原理图证据 / 上电清单

本页包含 Pololu 最小接线图和原理图，可用来确认 VM/VCC/GND/STBY 关系。
红板模块丝印可能不同，先用万用表和丝印确认 VM、VCC、GND。

资料入口

www.pololu.com / 713图片、资料或原理图来源
a.pololu-files.com / 0J4621.1200.jpg图片、资料或原理图来源
a.pololu-files.com / 0J12386.1200.png图片、资料或原理图来源
a.pololu-files.com / 0J4624.1200.png图片、资料或原理图来源

不接电机测 PWM
STBY 默认低
单路空载低速
方向反了记录软件符号
再接编码器闭环

故障定位表

现象	常见原因	下一步证据
PWM 有波形但电机不转	VM 未供电、STBY 未拉高、GND 未共地或电机线未接到 AO/BO	轮子架空，先测 VM/VCC/GND/STBY，再单路 40-90 permille。
上电就乱转	方向脚/PWM 未默认归零，安全门未生效	上电 STBY 低、PWM=0，DISARMED 后再允许输出。
闭环越调越炸	电机方向、编码器方向、左右轮映射不一致	先修符号和左右映射，不要先调 PID。

电路 / 接线 / 补充图

模块脚	连接对象	说明
VM	电机电源正	与 VCC 分开
VCC	主控逻辑电源	3V3/5V 逻辑
GND	系统地	必须共地
PWMA/PWMB	主控 PWM	调速
AIN1/AIN2	主控 GPIO	A 路方向
BIN1/BIN2	主控 GPIO	B 路方向
STBY	GPIO/上拉	低电平待机
AO1/AO2	左电机	电机绕组
BO1/BO2	右电机	电机绕组

接线禁忌 / 调试重点

VM 和 VCC 不要混
电机启动前先架空车轮
方向反了先改 AIN/BIN 或软件符号
VM 旁加电解和 0.1uF
编码器不接 TB6612

打开 Markdown 卡片

MG310 GMR 编码器电机

电机两线进驱动器，编码器四线进主控；最容易接错。

外设已有单件参考图，6P 线序仍需实物确认

用途带 A/B 相编码器的直流减速电机，电机线进驱动器，编码器线进主控

调用方式驱动器负责给电机供电；主控用定时器编码器模式、GPIO 中断或定时采样读取 A/B 相

接线风险6P 线序必须按实物确认，不能把电机线接到主控 IO

落地代码链路

层级	入口 / 文件 / 命令	验收证据
编码器读取	Encoder_ReadCount -> Encoder_Tick -> speed_count = now - last	只接 VCC/GND/A/B 手转轮，count 和 raw A/B 都变化。
方向符号	先定义车体前进时每侧 encoder delta 的正方向。	目标正速度时，左/右轮测得速度也为正；不一致先改 sign。
驱动分离	M+/M- 只接 H 桥输出；A/B/VCC/GND 只进主控编码器接口。	电机转动和编码器计数可以独立 smoke。

代码怎么调用

先写 Encoder_GetCount/Encoder_GetDelta，再用定时任务计算速度；闭环前只手转轮子验证计数方向。

A/B 相接主控成对输入，开启上拉或按模块输出类型配置。
固定周期读取 count 差分得到速度，方向由 A/B 相位或 count 正负决定。
把方向符号和电机 M+/M- 软件符号统一，再进入速度闭环。

void Encoder_Tick(void) {
  int32_t now = Encoder_ReadCount();
  motor.speed_count = now - motor.last_count;
  motor.last_count = now;
}

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
1 电机+	TB6612/AT8236 输出一端	电机绕组，不接主控
6 电机-	TB6612/AT8236 输出另一端	反接只改变电机物理方向
2 编码器 GND	系统 GND	编码器信号参考地
5 编码器 VCC	3V3/5V	按实物版本确认输出电平
3/4 A/B 相	主控编码器输入	测速和方向反馈

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
6P 方向	插头缺口、线色、卖家 6P 线序图	先画出你手上插头从 1 到 6 的实际顺序。	套用别的电机线序最容易把电机线接到 MCU IO。
编码器侧	ENC VCC、ENC GND、A 相、B 相	只接编码器时手转轮子，raw A/B 和 count 都变化。	A/B 反接不会烧，但会让速度闭环符号反掉。
电机侧	M+、M- 与 H 桥 AO/BO 输出	电机两线只进驱动器输出，不直接进主控。	主控 GPIO 直驱电机必然过流，且会把噪声打进逻辑地。

原理图证据 / 上电清单

本页已有 MG310 6P 线序图和装配参考图；真正接线前仍要对照你手上插头方向。
A/B 相反接不会烧，但闭环方向会错；电机线接错到 IO 才危险。

资料入口

www.ebuy7.com / wheel-fun-technology-mg310-dc-gear-motor-with-ab-phase-500-line-high-precision-gmr-encoder-mg370.html图片、资料或原理图来源

只接编码器供电
手转轮看计数
记录正方向
接驱动器空载低速
最后开速度环

故障定位表

现象	常见原因	下一步证据
手转轮计数不变	编码器 VCC/GND/A/B 线序错、输入无上拉或引脚配置错	只接编码器，读 raw A/B，再接驱动器。
计数方向反	A/B 相顺序与软件坐标不一致	交换 A/B 或改 encoder sign，记录正方向。
电机转但速度为零	电机线接对但编码器线没进主控	分开验证 M+/M- 和 A/B，不把电机线接 IO。

电路 / 接线 / 补充图

模块脚	连接对象	说明
1 电机+	TB6612 AO/BO	电机绕组
2 编码器GND	系统 GND	编码器地
3 B 相	主控编码器输入	速度方向反馈
4 A 相	主控编码器输入	速度方向反馈
5 编码器VCC	3V3/5V	按实物确认
6 电机-	TB6612 AO/BO	电机绕组

接线禁忌 / 调试重点

电机线和编码器线不要混
A/B 相符号反会让闭环发疯
5V 编码器进 3V3 主控要确认电平
先手转轮看计数
再接 VM 测电机

打开 Markdown 卡片

MG513X / MG513XL 霍尔编码器直流减速电机

12V 1:28 金属减速电机；电机绕组进驱动器，A/B 编码器反馈进主控，适合小车底盘和中等负载闭环。

外设已有官方产品图和编码器参数图，6P 线序仍需实物确认

用途12V 直流减速电机 + 霍尔/GMR 编码器，适合小车底盘速度闭环

调用方式电机 M+/M- 接 H 桥；编码器 A/B 接主控计数；速度 PI 在主控里跑

接线风险不同版本 6P 插头线序可能不同，先看卖家/实物线序图

落地代码链路

层级	入口 / 文件 / 命令	验收证据
编码器驱动	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/motor/at8236-mg513x/firmware/common/mg513x_encoder.c	先移植 count/delta/方向符号，再进入速度闭环。
速度环	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/motor/at8236-mg513x/firmware/common/motor_speed_pi.c	单轮限幅 200-300 permille，目标正速度时 measured speed 也为正。
接线证据	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/motor/at8236-mg513x/docs/wiring.md	6P 插头方向、线色和 A/B 相顺序必须按实物记录，不套 MG310 旧线序。

代码怎么调用

推荐直接参考 AT8236 + MG513X 例程，把驱动器输出、编码器计数、速度 PI 三件事拆开。

移植 at8236_motor.c/h 或等价 H 桥驱动，只负责输出方向和 PWM。
移植 mg513x_encoder.c/h 或用定时器编码器模式读取 A/B 相。
固定周期调用 motor_speed_pi.c，把目标速度换成 PWM 输出。

Motor_SetTarget(left_target, right_target);
Encoder_UpdateDelta();
MotorSpeedPi_Tick();
At8236_ApplyPwm();

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
M+ / M-	AT8236/TB6612 电机输出	承载电机电流
ENC VCC	3V3/5V	按编码器版本供电
ENC GND	系统 GND	必须与主控/驱动共地
A/B 相	主控 TIM 编码器输入	速度和方向反馈

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
版本线序	MG513X/MG513XL 参数图、6P 接线示意、实物线色	按实物记录 M+/M-、ENC VCC/GND、A/B 相。	霍尔/GMR 版本线序不同，照抄旧 MG310 线序会让反馈和电机错位。
反馈入口	A/B 相到主控定时器/捕获输入	左右轮分别手转，确认 delta 属于对应车轮。	左右编码器通道接反会出现一边动、另一边计数的假象。
功率路径	驱动板输出端、电源端和电机堵转电流	单轮低占空比空载验证后再闭环。	方向符号未统一时直接加 PI，会表现为越调越冲和发热。

原理图证据 / 上电清单

本页已有 MG513X 6P 接线示意、产品参数表和编码器参数图；它们用于确认版本差异。
闭环发散时优先查方向符号：M+/M-、A/B 相、左右轮坐标三者必须统一。

资料入口

AT8236 + MG513X 速度闭环例程目录公共 C 驱动、编码器测速、速度 PI、host smoke test 和移植说明
MG513X 编码器 smoke test 清单先手转看计数，再空载低速，再闭环
wheeltec.net / html图片、资料或原理图来源
wheeltec.net / 1763712101.jpg图片、资料或原理图来源

手转计数方向
单轮空载
左右轮符号
低速 PI
堵转/过流保护

故障定位表

现象	常见原因	下一步证据
低速抖动或闭环发散	M+/M-、A/B 相、左右轮坐标三者符号不一致	先单轮空载，比较命令方向和 encoder delta。
一个轮子动另一个计数变	左右编码器通道映射接反	手转左/右轮分别读 raw AB 和 count。
堵转或发热	负载过大、PWM 太高、保护缺失	限幅低速，加入 STOP/过流/超时保护。

MG513X / MG513XL 霍尔编码器直流减速电机实物图 — 实物 / 参考图

电路 / 接线 / 补充图

例程 / 资料链接

AT8236 + MG513X 速度闭环例程目录公共 C 驱动、编码器测速、速度 PI、host smoke test 和移植说明
MG513X 编码器 smoke test 清单先手转看计数，再空载低速，再闭环

模块脚	连接对象	说明
M+ / Motor+	AT8236/TB6612 输出	电机绕组，不接主控 IO
M- / Motor-	AT8236/TB6612 输出	电机绕组，方向可软件取反
ENC VCC	3V3/5V	官方编码器供电 3.3-5V，按版本确认
ENC GND	系统 GND	必须与主控和驱动器共地
A 相	主控 TIM/捕获输入	速度/方向计数
B 相	主控 TIM/捕获输入	与 A 相成对，反了会方向相反
6P 物理顺序	实物插头/卖家线序图	不要直接套 MG310 线序

接线禁忌 / 调试重点

先只接编码器手转看 A/B 计数
再接驱动器空载低速转
M+/M- 与 A/B 任一反向都要统一到软件符号
堵转电流较大，驱动器和电池要留余量
6P 顺序必须按实物确认

打开 Markdown 卡片

AT8236 双路编码器直流电机驱动

比普通 TB6612 板更适合带霍尔编码器的小车底盘；标准版把电机输出和编码器端口都集中到驱动板上。

外设已有官方标准版实物图、接口说明图和接线示例

用途双路直流电机驱动，适合带编码器底盘；标准版把电机和编码器接口集中到板上

调用方式和普通 H 桥一样写方向/PWM；编码器反馈仍进主控计数

接线风险标准版和 Lite 版排针不同，5V/3V3 是输入还是输出要看丝印

落地代码链路

层级	入口 / 文件 / 命令	验收证据
H 桥驱动文件	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/motor/at8236-mg513x/firmware/common/at8236_motor.c	只负责控制 IN1/IN2/PWM，不把编码器逻辑塞进驱动输出层。
编码器/PI 配套	https://github.com/ZhiKong0/nuedc-component-examples/tree/main/motor/at8236-mg513x	at8236_motor、mg513x_encoder、motor_speed_pi 三层分开移植。
上车前 smoke	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/motor/at8236-mg513x/docs/debug_checklist.md	按编码器、驱动、闭环顺序验证；任何异常先 STOP/DISARM。

代码怎么调用

把 AT8236 当成双路 H 桥：控制输入由主控输出，编码器 A/B 由主控读取，驱动板不替你做闭环。

先按 wiring.md 区分标准版/Lite 版接口。
AIN/BIN 或 PWM/DIR 接主控输出，E1/E2 编码器线接主控输入。
单路低速 smoke 通过后再双路同向、反向、差速测试。

At8236_SetMotor(LEFT, pwm_left);
At8236_SetMotor(RIGHT, pwm_right);
left_delta = Encoder_LeftDelta();
right_delta = Encoder_RightDelta();

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
VIN/VM	电机电源	不要从主控板取电
GND	主控地/电池地	控制和编码器反馈必须共地
AIN1/AIN2/BIN1/BIN2	主控 GPIO/PWM	控制双路方向和速度
E1A/E1B/E2A/E2B	主控编码器输入	反馈仍由主控读取
AO/BO 或电机端口	左右电机绕组	承载电机电流

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
版本识别	标准版接口说明、Lite 版引脚图、板上丝印	先确认自己手上是哪一版，再决定 5V/3V3、控制排针和编码器端子。	标准版和 Lite 版混用线表会导致供电或控制脚接错。
电机电源	VIN/VM、GND、电机输出 AO/BO	驱动板吃独立电机电源，主控只接控制信号并共地。	GND 不共地时 PWM 看似有波形但驱动无效。
编码器通道	E1A/E1B、E2A/E2B 到主控输入	驱动板可能只是汇线，编码器仍要进主控计数。	只把电机接到驱动板而没把编码器接回主控，闭环速度会一直为 0。

原理图证据 / 上电清单

本页已有标准版接口说明、接线示例和 Lite 版引脚图；接线时先确认自己是哪一版。
如果板上提供 5V 输出，不要反向把主控 5V 强灌进去，先查丝印/手册。

资料入口

AT8236 + MG513X 电机例程目录双路驱动、编码器反馈、速度 PI 和 STM32F103/MSPM0 移植提示
AT8236 接线说明标准版、Lite 版、MG513X 电机线和编码器线怎么分
category.yahboom.net / dual-md-module图片、资料或原理图来源
www.yahboom.com / Dual-MD-Module图片、资料或原理图来源

版本确认
VM/GND 确认
单路空载
编码器计数
速度闭环

故障定位表

现象	常见原因	下一步证据
标准版和 Lite 版线接不上	接口版本不同，5V/编码器/控制排针定义不同	先按丝印和手册确认版本，再照接线表改线。
驱动板有电但主控控制无效	GND 未共地、控制模式脚不对、PWM/DIR 接反	只测单路输入脚和输出端，暂不接闭环。
编码器反馈异常	驱动板只过线不解码，编码器仍要接主控	确认 E1A/E1B/E2A/E2B 进主控计数脚。

电路 / 接线 / 补充图

例程 / 资料链接

AT8236 + MG513X 电机例程目录双路驱动、编码器反馈、速度 PI 和 STM32F103/MSPM0 移植提示
AT8236 接线说明标准版、Lite 版、MG513X 电机线和编码器线怎么分

模块脚	连接对象	说明
VIN/VM 5-12V	电机电源正	不要从主控板取电
GND	系统地	主控、驱动、电池必须共地
5V / 3V3	逻辑参考/小负载	多为板上输出，避免反灌
AIN1/AIN2	主控 GPIO/PWM	电机 A 方向/调速信号
BIN1/BIN2	主控 GPIO/PWM	电机 B 方向/调速信号
E1A/E1B / E2A/E2B	主控编码器输入	电机 A/B 霍尔反馈
AO1/AO2 / BO1/BO2	电机 A/B 绕组	PH2.0 端口或排针输出
ADC / Vout	主控 ADC / 级联可选	采 VM 电压；级联前先算电流

接线禁忌 / 调试重点

标准版和 Lite 版引脚表不同
先确认 5V/3V3 是输出还是输入
单路空载调通后再双路闭环
编码器反馈仍进主控计数
峰值电流、散热和电池内阻要留余量

打开 Markdown 卡片

MaixCAM Pro / K230 / OpenMV 视觉模块

视觉模块自己识别目标，只把 valid/dx/dy 发给主控。

外设已有实物图和完整 IO 引脚图

用途视觉协处理器，负责识别目标并把少量结果发给实时主控

调用方式MaixPy/OpenMV 风格脚本识别目标，UART 输出 valid/dx/dy/id

接线风险不要让视觉板直接控制危险执行器；主控必须有丢帧停车策略

落地代码链路

层级	入口 / 文件 / 命令	验收证据
视觉脚本	MaixPy/OpenMV：检测目标 -> 输出 V,valid,dx,dy,confidence,seq\n	USB 串口先能连续看到固定格式帧，遮挡目标时 valid=0。
主控接收	UART RX ring buffer -> 按换行解析 -> Vision_Snapshot(valid, dx, dy, age_ms)	记录 vision_rx_bytes、last_seq、bad_frame、age_ms，不让解析阻塞主循环。
丢帧保护	age_ms > 100~200 或 valid=0 时目标失效，底盘/云台进入降级或 STOP	拔掉 TX 或盖住镜头后，控制输出在超时内归零。

代码怎么调用

视觉侧只输出结构化小帧，主控侧解析后进入状态机；先不要传大图片或复杂 JSON。

视觉脚本计算目标是否有效、中心偏差 dx/dy、目标编号 id。
UART 每 20-50ms 发一帧简短文本或二进制帧。
主控超过 100-300ms 没收到有效帧就降级或停车。

# MaixCAM side
uart.write(f"V,{valid},{dx},{dy},{target_id}\n")

// MCU side
if (VisionFrame_Parse(line, &vision)) App_SetVision(vision);

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
VBUS/VSYS	USB/5V 供电	视觉峰值电流较大，供电要稳
GND	主控 GND	UART 必须共地
A16/UART0_TX	主控 RX	发送识别结果
A17/UART0_RX	主控 TX	接收阈值/模式配置，可选
USB	电脑调试	现场调曝光、阈值、模型和日志

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
UART0	A16/UART0_TX、A17/UART0_RX 与官方 IO 图	A16 接主控 RX，A17 接主控 TX；只单向上报时可先不接 RX。	TX/RX 未交叉或选错 UART 组，会表现为主控收不到视觉结果。
供电	VBUS、VSYS、3V3、GND	视觉板用稳定 5V/USB 供电，UART 与主控共地。	K230 峰值电流不足会重启，主控侧只看到断续乱码或丢帧。
扩展 IO	A15/A27 I2C5、A18/A19、A28/A29、SPI4	只把必要信号接到主控，IO 按 3.3V 逻辑处理。	把视觉板当 5V IO 或让它直接控制危险执行器，会绕过主控安全状态机。

原理图证据 / 上电清单

本页已有 MaixCAM Pro 完整 IO 图；A16/A17、A15/A27 等编号以官方 IO 图为准。
视觉板 IO 多为 3.3V 逻辑，和 5V 主控/模块相接前查电平。

资料入口

wiki.sipeed.com / maixcam_pro.html图片、资料或原理图来源
wiki.sipeed.com / maixcam_pro.png图片、资料或原理图来源
wiki.sipeed.com / maixcam_pro_io.png图片、资料或原理图来源
raw.githubusercontent.com / maixcam_pro_io.png图片、资料或原理图来源

USB 调试正常
脚本能跑
UART 文本可读
主控丢帧保护
现场曝光参数可调

故障定位表

现象	常见原因	下一步证据
主控收不到视觉结果	TX/RX 未交叉、波特率不一致、视觉脚本未发帧	先用 USB 调试脚本，再发固定 V,1,0,0 帧。
识别结果偶发跳变	曝光、阈值、帧率或现场光不稳定	输出 valid/confidence，主控加连续帧确认和超时降级。
视觉板供电重启	USB/5V 峰值电流不足或地线压降	独立稳压供电，UART 与主控共地。

MaixCAM Pro / K230 / OpenMV 视觉模块卡片 — 一页卡片

MaixCAM Pro / K230 / OpenMV 视觉模块实物图 — 实物 / 参考图

电路 / 接线 / 补充图

模块脚	连接对象	说明
VBUS	USB/5V	4~5.5V 输入边界
VSYS	系统电源	VBUS 或 VBAT 供电域
3V3	小负载/电平参考	不要给大电流模块供电
GND	系统 GND	必须共地
A16/UART0_TX	主控 RX	发送识别结果
A17/UART0_RX	主控 TX	接收配置命令
A15/I2C5_SCL	I2C SCL	扩展 I2C
A27/I2C5_SDA	I2C SDA	扩展 I2C
A18/A19	UART1/JTAG	调试或扩展串口
A28/A29	UART2/JTAG	调试或扩展串口
A22/A23/A25/A24	SPI4	SCK/MISO/MOSI/CS
USB	电脑/调试	阈值和日志

接线禁忌 / 调试重点

TX/RX 交叉接
先用 115200
协议先只传 valid/dx/dy
现场要能调曝光/阈值
视觉供电要留余量

打开 Markdown 卡片

JY61P UART 姿态模块

串口输出角度/角速度，比 MPU6050 更适合快速调通。

外设已有公开实物图

用途快速获得姿态角/角速度的 UART 模块，适合先把车跑起来

调用方式串口收 WIT 帧，调用 wit_c_sdk 更新寄存器，再读取 Roll/Pitch/Yaw

接线风险TX 接主控 RX；只读姿态时 RX 可先不接；坐标系方向要贴标签

落地代码链路

层级	入口 / 文件 / 命令	验收证据
SDK 文件	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/imu/jy61p-sdk/wit_c_sdk.c	UART 收到的每个字节都喂给 WitSerialDataIn。
寄存器定义	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/imu/jy61p-sdk/REG.h	按 Roll/Pitch/Yaw 寄存器换算 raw / 32768 * 180。
运行态证明	uart_rx_bytes、jy61p_sync_bytes、jy61p_last_frame_id、jy61p_bad_checksums、jy61p_yaw_cdeg	先证明 0x55/0x51/0x52/0x53 帧稳定，再把 yaw 接进控制。

代码怎么调用

移植 REG.h、wit_c_sdk.c/h，把 UART 收到的每个字节喂给 WitSerialDataIn，再从回调或寄存器读角度。

初始化 UART 波特率，常见先试 9600 或 115200。
串口中断/DMA 收字节后调用 WitSerialDataIn(byte)。
收到角度寄存器更新后换算 Roll/Pitch/Yaw，注意单位和坐标系。

void Uart_RxByte(uint8_t b) {
  WitSerialDataIn(b);
}
yaw_deg = sReg[Yaw] / 32768.0f * 180.0f;

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
VCC	3V3/5V	按模块规格和丝印供电
GND	主控 GND	必须共地
TX	主控 RX	模块输出姿态帧
RX	主控 TX	需要配置输出内容/校准时再接

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
四线接口	VCC、GND、TX、RX 接线参考图	TX 到主控 RX，RX 到主控 TX；只读姿态可先接 VCC/GND/TX。	TX/RX 接反时 UART 有配置但没有任何有效 0x55 帧。
电源电平	模块规格、VCC 范围、串口电平	确认模块和主控 UART 电平兼容，必须共地。	电平不兼容会造成乱码、帧校验错或 IO 风险。
安装方向	模块坐标箭头、车体前进方向、固定螺丝位	把 yaw/pitch/roll 和车体坐标贴标签，代码里统一符号。	安装方向未定义时，即使通信正确，控制方向也会反。

原理图证据 / 上电清单

本页已有立创接线参考图和 UART 接线 SVG；接线图重点是 TX/RX 交叉和共地。
JY61P 输出角度不等于车体控制坐标，安装方向要固定并在代码里统一符号。

资料入口

JY61P WIT C SDK 驱动目录REG.h + wit_c_sdk.c/h，适合先移植串口帧解析
JY61P 完整 STM32H7 模板工程包含 UART、TIM、HAL 工程结构，适合看完整初始化
wiki.lckfb.com / jy61p-measurement-sensor.html图片、资料或原理图来源

串口有帧
帧头正确
静置 yaw 漂移可接受
转动方向正确
异常丢帧不阻塞控制

故障定位表

现象	常见原因	下一步证据
UART 字节计数为 0	供电、GND、TX/RX、pinmux、波特率或中断错误	先用 USB-TTL 看模块是否输出，再接主控 RX。
有字节但没有 0x55 帧	波特率/输出模式不匹配，或模块不是 WIT 协议	检查 0x55 0x51/0x52/0x53 和 checksum。
yaw 方向不对或漂移	安装方向和车体坐标未统一，或没有静置校准	贴方向标签，记录符号，静置测漂移。

电路 / 接线 / 补充图

例程 / 资料链接

JY61P WIT C SDK 驱动目录REG.h + wit_c_sdk.c/h，适合先移植串口帧解析
JY61P 完整 STM32H7 模板工程包含 UART、TIM、HAL 工程结构，适合看完整初始化

模块脚	连接对象	说明
VCC	3V3/5V	按模块规格
GND	系统 GND	必须共地
TX	主控 RX	姿态数据输出
RX	主控 TX	可选配置

接线禁忌 / 调试重点

只读姿态通常只接 TX
波特率先试 9600/115200
坐标系方向贴标签
运动补偿前先静态校准
和 MPU6050 不要重复上车

打开 Markdown 卡片

MPU6050 I2C 姿态模块

I2C 加速度/陀螺仪模块，需要滤波和姿态解算。

外设已有实物图、Pinout、原理图

用途裸 6 轴 IMU，适合练 I2C、滤波和姿态解算

调用方式I2C 写 PWR_MGMT_1 唤醒，再连续读加速度/陀螺仪寄存器

接线风险SCL/SDA 需要上拉；AD0 决定 0x68/0x69 地址

落地代码链路

层级	入口 / 文件 / 命令	验收证据
驱动入口	https://github.com/ZhiKong0/nuedc-component-examples/tree/main/imu/mpu6050-driver	先跑 WHO_AM_I=0x68，再读 accel/gyro raw，最后才上 DMP 或互补滤波。
I2C 适配	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/imu/mpu6050-syscfg/mpu6050-oled-software-i2c.syscfg	I2C scan 能看到 0x68/0x69；SCL/SDA 低速短线稳定 ACK。
姿态读取	MPU6050_Init -> CalibrateBias -> ReadAccelGyro -> Imu_Update	静止时 gyro bias 小、accel 约 1g，控制环里只读 snapshot 不阻塞。

代码怎么调用

先做 I2C 扫描确认地址，再写初始化，最后定时读取原始量并做零偏/滤波。

扫描 0x68/0x69，确认 VCC/GND/SCL/SDA。
写 0x6B=0x00 唤醒，配置量程和滤波。
周期读取 0x3B 起始的 14 字节，换算 ax/ay/az/gx/gy/gz。

i2c_write(MPU_ADDR, 0x6B, 0x00);
i2c_read(MPU_ADDR, 0x3B, buf, 14);
ax = (int16_t)((buf[0] << 8) | buf[1]);

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
VCC	3V3 优先	模块虽可能带稳压，但 3.3V 逻辑更稳
GND	系统 GND	I2C 参考地
SCL/SDA	主控 I2C	时钟和双向数据
AD0	GND/VCC	选择地址 0x68/0x69
INT	主控中断脚	数据就绪可选

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
I2C 总线	SCL、SDA、上拉电阻、线长	SCL/SDA 不反接，同总线 OLED 地址不冲突。	上拉不足或线太长会导致偶发 NACK、WHO_AM_I 失败和控制卡顿。
地址脚	AD0 到 GND/VCC 的连接	AD0=GND 通常 0x68，AD0=VCC 通常 0x69。	地址假设错会让扫描不到或和另一个 IMU 冲突。
电源与中断	VCC、GND、INT、模块稳压/电平转换	优先 3V3 逻辑，INT 可选接中断脚并做去抖/标志位。	电机噪声进地线会让姿态噪声变大，INT 悬空触发会造成误读。

原理图证据 / 上电清单

本页已有 MPU6050 Pinout、原理图和 Arduino 接线参考；先看地址、上拉和电源域。
如果同一 I2C 上还有 OLED，先确认地址不冲突，再降低线长和速率。

资料入口

MPU6050 MSPM0/CCS 驱动目录含 mpu6050.c/h、DMP、I2C 适配，适合移植到底盘板
MPU6050 OLED 软件 I2C SysConfigMSPM0 I2C 引脚和外设配置参考
components101.com / mpu6050-module图片、资料或原理图来源
components101.com / MPU6050-Pinout.png图片、资料或原理图来源

I2C 扫描
WHO_AM_I 正确
静态零偏
姿态方向
控制环非阻塞读取

故障定位表

现象	常见原因	下一步证据
I2C 扫不到 0x68/0x69	SCL/SDA 接反、AD0 状态不明、上拉不足	先扫地址，短线低速，确认 AD0 到 GND/VCC。
WHO_AM_I 不对	地址错、器件不是 MPU6050、总线被其他模块拉住	单独接模块并读 0x75。
姿态噪声大	零偏未校准、线束长、电机噪声进地线	静态零偏，远离电机线，控制环非阻塞读取。

电路 / 接线 / 补充图

例程 / 资料链接

MPU6050 MSPM0/CCS 驱动目录含 mpu6050.c/h、DMP、I2C 适配，适合移植到底盘板
MPU6050 OLED 软件 I2C SysConfigMSPM0 I2C 引脚和外设配置参考

模块脚	连接对象	说明
VCC	3V3	优先 3V3
GND	系统 GND	必须共地
SCL	主控 I2C SCL	时钟
SDA	主控 I2C SDA	数据双向
INT	主控中断脚	可选
AD0	GND/VCC	地址 0x68/0x69

接线禁忌 / 调试重点

SCL/SDA 需要上拉
线太长会不稳
地址冲突先查 AD0
只想快读角度优先 JY61P
I2C 先低速调通

打开 Markdown 卡片

BNO085 / BNO08X 九轴融合姿态模块

自带传感器融合，能直接输出姿态；比裸 MPU6050 更省调参时间。

外设已有官方接线图和 Pinout

用途自带融合的姿态模块，适合少调参拿稳定姿态

调用方式I2C/SPI 用库读取 report；UART-RVC 模式可直接解析姿态帧

接线风险PS0/PS1 决定接口模式，必须和例程一致

落地代码链路

层级	入口 / 文件 / 命令	验收证据
UART-RVC 驱动	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/imu/bno08x-uart-rvc/bno08x_uart_rvc.c	能稳定解析 yaw/pitch/roll、accel 和 frame counter，校验错误计数不增长。
模式固定	按 PS0/PS1 选择 UART-RVC 或 I2C，固件与接线只保留一种模式	上电后读取模式与例程一致；不要一边接 I2C 一边跑 UART 例程。
应用快照	Bno08x_Poll -> Bno08x_GetSnapshot(yaw, pitch, roll, age_ms)	age_ms 过大时控制层不再使用旧姿态；静置 yaw 漂移可记录。

代码怎么调用

比赛快调优先 UART-RVC：串口收固定帧，解析 yaw/pitch/roll；需要完整 report 再上 I2C/SPI 库。

按 PS0/PS1 选择 UART-RVC 或 I2C 模式。
UART 模式先确认波特率和帧头，再解析欧拉角。
I2C 模式先跑官方/Adafruit 示例，再移植到主控。

if (Bno08xRvc_ParseByte(byte, &pose)) {
  app.yaw = pose.yaw_deg;
  app.pitch = pose.pitch_deg;
}

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
VIN/GND	3V3/5V 与系统地	按模块板载稳压范围
SCL/SDA	主控 I2C	完整 report 模式
TX/RX	主控 UART	UART-RVC 快速姿态帧
PS0/PS1	固定电平	选择接口协议
RST/INT	GPIO/中断	复位和数据就绪可选

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
接口模式	PS0、PS1、I2C/SPI/UART 引脚说明	PS0/PS1 的电平和例程接口一致。	模式脚错时，代码完全正常也不会有任何有效帧或 ACK。
电源	VIN、3Vo、GND、RST	VIN 按模块规格供电，3Vo 只作小负载参考，RST 不悬空误复位。	把 3Vo 当外设电源或供电不足，会造成姿态输出断续。
数据口	TX/RX 或 SCL/SDA 到主控	UART-RVC 先 TX/RX 交叉；I2C 模式确认上拉和地址。	接口线同时接多种模式会互相拉扯，表现为偶发错误帧。

原理图证据 / 上电清单

本页已有 Adafruit Pinout 图；不同 BNO08x 模块 PS0/PS1 丝印和默认上拉可能不同。
UART-RVC 适合先跑通，完整融合参数和高频 report 再考虑 I2C/SPI。

资料入口

BNO08X UART-RVC 驱动目录适合 BNO085/BNO08X 走 UART-RVC，先拿稳定姿态帧
bno08x_uart_rvc.c串口帧解析入口，移植时先看这里
learn.adafruit.com / adafruit-9-dof-orientation-imu-fusion-breakout-bno085图片、资料或原理图来源
cdn-learn.adafruit.com / sensors_image.png图片、资料或原理图来源

模式脚确认
串口/I2C 有数据
静置稳定
转动方向正确
丢帧有保护

故障定位表

现象	常见原因	下一步证据
接口模式不对	PS0/PS1 电平和例程不一致	先固定 UART-RVC 或 I2C 模式，不混用例程。
有数据但角度跳	report 类型/坐标系解析错或丢帧	打印 frame id、时间戳和 yaw/pitch/roll。
I2C 不稳定	上拉、线长、电源或地址冲突	先 UART-RVC 跑通，再回到 I2C 完整 report。

电路 / 接线 / 补充图

例程 / 资料链接

BNO08X UART-RVC 驱动目录适合 BNO085/BNO08X 走 UART-RVC，先拿稳定姿态帧
bno08x_uart_rvc.c串口帧解析入口，移植时先看这里

模块脚	连接对象	说明
VIN	3V3/5V	按模块板载稳压范围
3Vo	电平参考/小负载	不要带大负载
GND	系统 GND	必须共地
SCL/SDA	主控 I2C	默认最容易调通
TX/RX	主控 UART	UART-RVC 姿态帧
PS0/PS1	模式选择	决定 I2C/UART/SPI 等接口
RST	GPIO/上拉	可选复位
INT	主控中断	可选数据就绪

接线禁忌 / 调试重点

想少写融合算法优先 BNO085
PS0/PS1 先按例程模式接
UART-RVC 先看波特率和帧头
I2C 线短并确认上拉
上车前先静置看 yaw 漂移

打开 Markdown 卡片

ICM42688 / ICM-42688-P 六轴 IMU

高性能三轴陀螺仪 + 三轴加速度计；输出原始量，需要你自己滤波/融合。

外设已有开源模块 Pinout 图

用途高性能 6 轴 IMU，适合高速采样和自写滤波

调用方式I2C/SPI 读写寄存器，配置量程/ODR/FIFO 后读原始加速度和角速度

接线风险它没有磁力计，yaw 需要融合/约束，不能指望长期绝对航向

落地代码链路

层级	入口 / 文件 / 命令	验收证据
驱动文件	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/imu/icm42688-hardware/icm42688_driver.c	先读 WHO_AM_I，再确认 accel/gyro 原始值随姿态变化。
初始化序列	soft reset -> 选择 SPI/I2C -> 配 ODR/FSR/滤波 -> 启动 accel/gyro	记录 whoami、odr_hz、sample_dt_us、fifo_count 或 data_ready。
控制接入	Imu_Poll 非阻塞采样 -> ImuSnapshot(raw, dps, g, dt)	控制周期不因 IMU 读数阻塞；yaw 不当绝对航向单独使用。

代码怎么调用

先用 I2C 低速验证 WHO_AM_I 和原始数据，再切 SPI/FIFO 提高采样率。

读 WHO_AM_I 验证通信。
配置陀螺/加速度量程、ODR、滤波。
周期读取原始量，做零偏标定，再进入姿态/速度估计。

ICM42688_Init(&imu, bus);
ICM42688_ReadRaw(&imu, &raw);
ImuFilter_Update(&filter, raw.gyro, raw.accel);

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
VCC/GND	3V3 与系统地	高性能 IMU 优先 3.3V 短线
SCL/SCLK	I2C SCL 或 SPI SCK	接口二选一
SDA/SDI	I2C SDA 或 SPI MOSI	写寄存器/数据线
SA0/SDO	地址选择或 SPI MISO	读数据/选地址
CS/INT	GPIO/中断	SPI 片选和数据就绪

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
接口选择	CS、SA0/SDO、SCL/SCLK、SDA/SDI	SPI 模式 CS 由 GPIO 控；I2C 模式 CS 通常拉高并用 SA0 定地址。	CS/SA0 接法和代码模式不一致时，WHO_AM_I 会读不到。
电源地	VCC、GND、模块旁路电容	使用 3.3V，IMU 地线尽量远离电机大电流回路。	地噪声会直接放大 gyro 噪声，采样看起来像机械抖动。
中断/FIFO	INT/INT1、FIFO 相关配置	高频采样优先用 data-ready 或 FIFO，主循环只消费快照。	阻塞式轮询会拖慢控制环，造成速度/姿态闭环抖动。

原理图证据 / 上电清单

本页 Pinout 来源于开源 ICM-42688-P 模块；其他模块需重新确认 CS、INT、SA0 丝印。
高速采样时线束、地线和电机噪声会明显影响数据。

资料入口

ICM42688 驱动目录含 icm42688_driver.c/h，适合看寄存器初始化和读数
icm42688_driver.c具体 SPI/I2C 读写封装和初始化流程
github.com / ICM-42688-P-Module图片、资料或原理图来源
github.com / pinout.png图片、资料或原理图来源

WHO_AM_I
静态零偏
采样周期稳定
方向轴定义
控制环非阻塞

故障定位表

现象	常见原因	下一步证据
WHO_AM_I 读不到	CS/SA0/SDO/SCL/SDA/SPI 模式接错	先 I2C 低速或 SPI 单设备验证 ID。
采样周期乱	主循环阻塞、FIFO/ODR 配置不一致	记录采样时间戳，先不进控制环。
yaw 长期漂移	它没有磁力计，陀螺积分必然漂	使用约束/视觉/线位辅助，不把 yaw 当绝对航向。

ICM42688 / ICM-42688-P 六轴 IMU 实物图 — 实物 / 参考图

电路 / 接线 / 补充图

例程 / 资料链接

ICM42688 驱动目录含 icm42688_driver.c/h，适合看寄存器初始化和读数
icm42688_driver.c具体 SPI/I2C 读写封装和初始化流程

模块脚	连接对象	说明
VCC	3V3	优先 3.3V 逻辑
GND	系统 GND	必须共地
SCL/SCLK	I2C SCL 或 SPI SCK	接口二选一
SDA/SDI	I2C SDA 或 SPI MOSI	写入数据
SA0/SDO	地址选择或 SPI MISO	I2C 地址/SPI 读出
CS	GPIO/SPI CS	I2C 模式通常拉高
INT/INT1	主控中断	数据就绪可选

接线禁忌 / 调试重点

它没有磁力计，yaw 会随时间漂
高速采样优先 SPI
I2C 调通后再上频率
陀螺零偏必须静态校准
比赛控制环里不要阻塞读 IMU

打开 Markdown 卡片

0.96 OLED / SSD1306 显示模块

调试显示模块，用于显示状态、阈值、速度、误差。

外设已有实物图

用途现场调试显示：模式、阈值、速度、误差、故障码

调用方式I2C 写 SSD1306 命令和显存 buffer，主循环低频刷新

接线风险显示刷新不要阻塞控制环，I2C 地址常见 0x3C/0x3D

落地代码链路

层级	入口 / 文件 / 命令	验收证据
显示驱动文件	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/imu/icm42688-hardware/OLED/OLED.c	底层只管 I2C/SPI 写命令和显存，业务层只更新字段。
初始化入口	I2C scan -> OLED_Init -> clear/test pattern -> low-rate OLED_Update	oled_ack_ok、oled_i2c_addr、render_counter 可读；0x3C/0x3D 先扫出来。
现场字段	mode、speed、line_error、yaw、fault_code、armed/running	不全屏高频刷新，控制环周期不因显示明显变慢。

代码怎么调用

初始化 SSD1306 后维护一块显存，业务层只改文本/数值，统一低频刷新。

I2C 扫描确认 0x3C/0x3D。
发送初始化命令序列，清屏。
周期刷新关键状态，刷新频率低于控制环。

OLED_Init();
OLED_Printf(0, 0, "mode:%d", app.mode);
OLED_Printf(0, 2, "spd:%d", speed);
OLED_Update();

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
VCC/GND	3V3/5V 与系统地	看模块丝印
SCL/SDA	主控 I2C	四线 I2C OLED 常用连接
RST/DC/CS	GPIO/SPI	SPI 屏才需要

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
接口版本	4P I2C 或 7P SPI 排针丝印	先按排针数量确认接口，不把 SPI 屏当 I2C 屏初始化。	接口版本错时屏幕全黑/全白，但代码日志可能看起来正常。
I2C 地址	SCL、SDA、地址焊盘、上拉	扫描 0x3C/0x3D 后再写初始化序列。	和 MPU6050 共线时，上拉、线长和阻塞刷新都会影响 IMU。
刷新节奏	VCC、GND、I2C 波形和刷新函数调用点	低频局部刷新，控制环里只更新关键字段。	全屏高频阻塞刷新会让电机控制周期变慢。

原理图证据 / 上电清单

本页已有 SSD1306 实物参考；具体 I2C/SPI 版本以排针数量和丝印为准。
I2C OLED 和 MPU6050 共总线时注意地址、上拉和刷新频率。

资料入口

components101.com / oled-display-ssd1306图片、资料或原理图来源
www.waveshare.com / 0.96inch_OLED_Module图片、资料或原理图来源

I2C 地址
初始化亮屏
不阻塞控制
显示故障码
比赛前固定字段

故障定位表

现象	常见原因	下一步证据
白屏/黑屏	地址 0x3C/0x3D、SCL/SDA、上拉或初始化序列错误	先 I2C 扫描，再画全屏测试图案。
控制变慢	每圈全屏刷新或 I2C 阻塞	低频刷新、脏行更新，只显示关键字段。
同总线 IMU 也失效	I2C 地址/上拉/线长冲突	单独接 OLED，再与 MPU6050 合总线。

电路 / 接线 / 补充图

模块脚	连接对象	说明
VCC	3V3/5V	看模块丝印
GND	系统 GND	必须共地
SCL	主控 I2C SCL	时钟
SDA	主控 I2C SDA	数据
DC/RST	主控 GPIO	SPI 屏才需要

接线禁忌 / 调试重点

I2C 地址常见 0x3C/0x3D
别占关键 PWM/UART 脚
显示刷新不要阻塞控制环
调试时非常有用
上电无显示先扫 I2C 地址

打开 Markdown 卡片

灰度巡迹模块

5/7/8/12 路输入，用于黑线、边界、角点和丢线判断。

外设有装配参考，单件待实拍

用途巡线、边界、角点、丢线检测

调用方式数字模块读 GPIO；模拟模块读 ADC；多路传感器转换成 line position 和 confidence

接线风险5V 供电时输出电平可能也是 5V，接 3.3V 主控前确认

落地代码链路

层级	入口 / 文件 / 命令	验收证据
采样驱动文件	https://github.com/ZhiKong0/nuedc-component-examples/blob/main/imu/icm42688-hardware/grayscale_sensor.c	先输出 raw_bits/active_bits，不直接喂 PID。
74HC4051 读取	S0/S1/S2 选通 -> 等待 settle -> 采 Z -> 打包 Y0..Y7	逐个遮挡传感器，通道顺序和极性都能复现。
控制入口	Line_ReadRaw -> Line_CalcPosition -> line_seen/line_error/confidence	丢线时进入搜索/减速/停车，不让 PID 继续盲打。

代码怎么调用

先把每路黑白值读出来，再计算加权线位；不要一上来直接套 PID。

读取 OUT0..OUTn，记录白底/黑线阈值。
把多路值转换成 line_pos、line_seen、confidence。
丢线时进入搜索/减速/停车状态，不让 PID 乱打方向。

Line_ReadRaw(raw);
Line_CalcPosition(raw, &line);
if (!line.seen) Chassis_RequestSlowSearch();

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
VCC/GND	3V3/5V 与系统地	按模块规格，输出电平要匹配主控
OUT0..OUTn	主控 GPIO/ADC	数字或模拟巡线输入
EN/LED 可选	GPIO 或固定电平	有些模块可关红外灯

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
输出电平	VCC、GND、OUT0..OUTn、模块比较器输出	5V 供电时先确认 OUT 是否为 5V，3.3V 主控必要时分压/限流。	5V OUT 直入 3.3V IO 会带来可靠性和损坏风险。
4051 复用	S0/S1/S2、Z、Y0..Y7 接口示意	选择脚顺序和传感器物理顺序逐个遮挡验证。	通道顺序错时，线位计算方向会反，PID 会把车带离黑线。
机械标定	模块高度、前伸量、遮光结构、线束固定	固定机械位置后再标定白底/黑线阈值。	先调代码后改安装高度，会让所有阈值和控制参数失效。

原理图证据 / 上电清单

本页已有 8 路接口示意；实际 5/7/12 路模块按同样思路扩展。
模块高度、角度、遮光和线材固定会比代码更影响阈值。

白底值
黑线值
左右方向
丢线策略
固定安装高度

故障定位表

现象	常见原因	下一步证据
所有通道恒 0 或恒 1	VCC/GND、输出极性、阈值电位器或使能脚问题	先读 raw_bits，不要直接套 PID。
通道顺序乱	排线方向或 74HC4051 Y0..Y7/S0..S2 顺序错	逐个遮挡传感器，记录通道映射。
线位抖动	安装高度、光照、遮光和线束固定不稳定	固定机械高度，再标定白底/黑线阈值。

电路 / 接线 / 补充图

模块脚	连接对象	说明
VCC	3V3/5V	按模块规格
GND	系统 GND	必须共地
OUT_L2	GPIO/ADC	左外
OUT_L1	GPIO/ADC	左内
OUT_M0	GPIO/ADC	中间
OUT_R1	GPIO/ADC	右内
OUT_R2	GPIO/ADC	右外

接线禁忌 / 调试重点

数字模块接 GPIO，模拟模块接 ADC
先做黑白阈值校准
角点要连续帧确认
模块供 5V 时确认输出电平
线束固定好再调阈值

打开 Markdown 卡片

激光驱动板

主控只输出 PWM/EN，激光功率由驱动板承担。

外设单件待实拍，已有原理图

用途主控用 EN/PWM 控制激光，驱动板承担限流/开关功率

调用方式GPIO 控亮灭，PWM 控功率；必须有 arm/disable 安全门

接线风险GPIO 不能直接给激光头供电；不要照射人眼或反光面

落地代码链路

层级	入口 / 文件 / 命令	验收证据
安全 API	Laser_Init -> Laser_Off(default) -> Laser_SetDutyPermille(0..1000) -> Laser_Off	上电、复位、程序异常路径都默认关激光。
动作门控	DISARMED 禁止输出；ARM 后只允许短脉冲；STOP/FAULT 立即关断	按停止键、超时或通信丢失时，PWM/EN 在一个控制周期内归零。
低功率验证	低占空比短脉冲 -> 测 VIN/GND/温升 -> 再和云台动作联动	先不用闭环打靶，只验证亮灭、极性、限流和热稳定。

代码怎么调用

激光输出必须独立封装，默认关闭；只有目标锁定、用户允许、安全状态满足时才允许短时点亮。

初始化 PWM/EN 后立即 Laser_Off。
调试先用低占空比短脉冲，不连续长亮。
和云台联动时先验证云台 STOP/限位，再允许激光输出。

Laser_Init();
Laser_Off();
if (app.armed && target.locked) Laser_SetDuty(120);

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
VIN/5V	独立电源	按驱动板丝印和激光功率选择
GND	主控地/电源地	PWM/EN 需要共地
PWM/EN	主控 GPIO/PWM	控制亮灭/功率
LASER+/LASER-	激光头正负极	极性不可接反

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
功率路径	VIN/5V、GND、LASER+、LASER-	激光头正负极只接驱动输出，驱动板按额定电源独立供电。	GPIO 直供激光或极性反接都会损坏器件。
控制脚	PWM/EN、下拉/上拉、驱动输入级	EN/PWM 默认关闭，MCU 初始化前也不误亮。	控制脚悬空会造成上电误亮，比赛现场非常危险。
限流与热	驱动板限流元件、散热铜皮、参考原理图	不清楚限流方式时只做低占空比短脉冲。	长时间高占空比会发热、掉压或烧激光头。

原理图证据 / 上电清单

本页已有激光驱动板原理简图和激光舵机控制参考图；正式接线仍要补实拍丝印。
限流方式未知时，不要长时间高占空比点亮。

默认关闭
低占空比短亮
极性确认
云台 STOP
安全提示

故障定位表

现象	常见原因	下一步证据
激光不亮	VIN/GND、EN/PWM 极性、激光头正负或驱动限流问题	低占空比短脉冲，先不接云台闭环。
上电误亮	EN 引脚悬空或默认态未关	GPIO 初始化前用硬件下拉/上拉，软件第一句 Laser_Off。
供电掉压或发热	驱动方式/限流/电源容量不匹配	限时点亮，测电源电压和温升。

电路 / 接线 / 补充图

模块脚	连接对象	说明
VIN/5V	独立电源	按丝印
GND	系统 GND	必须共地
PWM/EN	主控 GPIO/PWM	亮灭/调光
LASER+	激光正极	注意极性
LASER-	激光负极	注意极性

接线禁忌 / 调试重点

GPIO 不能直接给激光供电
只允许一个主控直接控制激光
先低占空比短时点亮
不照人眼和反光面
先确认限流方式

打开 Markdown 卡片

张大头/ZDT 闭环步进驱动

云台 yaw/pitch 常用执行器，TTL 或 CAN 按驱动器版本二选一。

外设已有手册实物参考，端子建议实拍

用途闭环步进云台/机构执行器，可走 TTL 或 CAN 协议

调用方式主控按驱动器协议发位置/速度/停止命令；每个轴地址必须唯一

接线风险TTL 和 CAN 不能混接；MCU CAN_TX/RX 不能直接接 CANH/CANL

落地代码链路

层级	入口 / 文件 / 命令	验收证据
TTL 协议层	Zdt_SendStop -> Zdt_QueryStatus -> Zdt_MoveRelative(addr, speed, acc, pulse)	先能查询状态和执行 STOP，再允许低速点动。
CAN 协议层	MCU CAN_TX/RX -> CAN 收发器 -> CANH/CANL；协议帧按驱动器手册组包	示波器/USB-CAN 能看到帧，地址和波特率匹配后驱动器应答。
云台安全	Laser disabled -> Stepper home/limit/STOP -> low-speed move -> enable aim logic	未验证限位、STOP 和超时前，激光保持关闭。

代码怎么调用

先封装 sendFrame 和 Stop，再做 MoveRel/MoveAbs；任何运动前先验证停止命令确实有效。

TTL 模式：主控 TX/RX 交叉接驱动器 RX/TX，GND 共地。
CAN 模式：主控 CAN_TX/RX 先接收发器，再接 CANH/CANL，并按总线加终端电阻。
先单轴低速点动，再做双轴联动；每条命令都要有超时和 STOP 回退。

Zdt_Init(&yaw, addr_yaw);
Zdt_Stop(&yaw);
Zdt_MoveRelative(&yaw, speed, steps);

逐针接线表

引脚 / 信号	接到哪里	为什么这样接
V+/Gnd	10-29V 驱动电源	按驱动器规格供电
A+/A-/B+/B-	步进电机相线	两相线不能随意混
TX/RX/GND	主控 UART	TTL 协议通信
CANH/CANL	CAN 收发器总线侧	CAN 模式，主控必须先经过收发器
Addr/拨码	驱动器地址设置	多轴地址不能冲突

原理图焦点表

看图位置	重点标注	必须确认	错了会怎样
电源与相线	V+/GND、A+/A-/B+/B-、电源额定范围	电机相线接到驱动器，电源容量满足加减速峰值。	相线错或电源不足会丢步、报警、发热，不能靠调代码解决。
TTL/CAN 二选一	TX/RX、CANH/CANL、CAN 收发器、模式/地址拨码	TTL 必须共地；CAN 必须经收发器和终端，不把 MCU CAN_TX/RX 直连 CANH/CANL。	混接 TTL 和 CAN 会导致完全无响应，甚至拉坏总线。
安全端子	EN、STOP、限位输入、报警输出	先验证 STOP/限位/超时，再做位置闭环和云台联动。	运动后停不住比运动不起来更危险，尤其是带激光云台。

原理图证据 / 上电清单

本页已有 ZDT/Emm 驱动板接口说明图和 TTL/CAN 接口示意；先按自己驱动器版本确认端子。
云台打靶必须先禁激光测步进 STOP 和限位。

地址唯一
单轴 STOP
低速点动
位置回读/状态
双轴联动前禁激光

故障定位表

现象	常见原因	下一步证据
驱动器不响应命令	TTL/CAN 模式错、地址错、波特率/协议帧错	先单轴 Stop/状态查询，再 MoveRel。
CAN 模式完全不通	MCU CAN_TX/RX 直连 CANH/CANL，缺收发器或终端	加收发器，确认 CANH/CANL 和终端电阻。
运动后停不住	STOP 命令没验证、超时回退缺失	先禁激光，只测 STOP、限位和低速点动。

电路 / 接线 / 补充图

模块脚	连接对象	说明
V+/Gnd	10-29V 电源	按驱动器规格
A+/A-/B+/B-	步进电机	电机相线
TX/RX	主控 UART	TTL/Emm 协议
CANH/CANL	CAN 总线	需收发器
EN/STOP	命令/控制	按协议实现
GND	系统 GND	串口 TTL 必须共地

接线禁忌 / 调试重点

TTL 和 CAN 不要混接
MCU CAN 不能直连 CANH/CANL
每个轴地址不能冲突
先单轴低速点动
必须先验证 STOP 命令

打开 Markdown 卡片