Skip to content

codex.md

Latest commit

 

History

History
336 lines (248 loc) · 13.5 KB

codex.md

File metadata and controls

336 lines (248 loc) · 13.5 KB
Raw

BionicLobster-ROV 双板固件整理说明

本文档用于整理原始修改要求，并将其与仓库当前已经落地的实现统一起来。
后续如果文档描述与代码不一致，以当前工程代码为准。

1. 整体结论

由于单颗 STM32F103C8T6 引脚资源不足，项目已经拆分为双主控结构：

  • firmware：主板固件，负责机械臂、尾部舵机、深度传感器、编码器，以及遥控接收和板间指令转发。
  • firmware_quad：从板固件，负责头部推进、尾部 4 路推进、背部 4 路四旋翼电机，以及 JY901S IMU 数据接收与姿态保持。

设计原则如下：

  • 以 firmware 为主控制板。
  • 主要控制逻辑集中在 firmware。
  • firmware_quad 以执行推进和姿态稳定为主。
  • 原始草稿中若存在引脚冲突、接口命名错乱或逻辑重复，已按当前代码实现整理。

2. 双板职责划分

固件目录 角色 当前职责
firmware/ 主板 接收遥控帧、解析控制状态、控制机械臂与尾部舵机、读取 MS5837、读取 6 路 AS5600、通过 USART1 向从板转发控制帧
firmware_quad/ 从板 接收主板控制帧、驱动头部推进电机、驱动尾部 4 路推进电机、驱动背部 4 路四旋翼电机、通过 USART2 接收 JY901S IMU 数据、执行简单姿态保持混控

3. 板间通信与控制帧

3.1 控制帧格式

当前通信已经分成两层：

  • USART2 外部遥控输入仍然使用 7 字节离散按键帧。
  • USART1 主从板链路改为 10 字节控制量帧，主板负责把按键翻译成连续控制量后再下发给从板。

外部遥控帧格式如下：

字节下标 含义 备注
0 帧头 0xA5
1 key 基础运动控制
2 Left_Move 左臂动作字段
3 Right_Move 右臂动作字段
4 hand_OC 夹爪控制
5 Water_Control 保留字段，当前仅解析并透传
6 帧尾 0x7B

主从板控制量帧格式如下：

字节下标 含义 备注
0 帧头 0xA5
1 协议版本 当前为 0x01
2 序号 每帧自增
3 mode SAFE / STABILIZE
4 surge 前后控制量，范围 -100..100
5 yaw 偏航控制量，范围 -100..100
6 heave 升沉控制量，范围 -100..100
7 flags 预留标志位
8 校验 对 1..7 字节做异或校验
9 帧尾 0x7B

3.2 基础运动控制码

key 当前定义如下：

码值 动作
0x01 前进
0x02 后退
0x04 左移 / 左转语义复用
0x08 右移 / 右转语义复用
0x10 上升
0x20 下降

3.3 板间链路行为

  • 主板每 10 ms 调用一次 BoardLink_SendCommand()。
  • 主板会把旧 key 按键映射成 surge / yaw / heave 三轴控制量，支持组合输入。
  • 从板每次主循环调用 BoardLink_Tick()。
  • 从板超时阈值为 BOARD_LINK_TIMEOUT_TICKS = 25。
  • 按当前循环周期估算，若约 250 ms 未收到主板有效帧，从板会清空控制状态并执行 Start() 停机。

3.4 从板运行状态机

从板当前将运行状态明确分成 3 类：

  • SAFE：无运动指令，或者故障解除后等待重新进入安全态。
  • STABILIZE：收到合法控制量，且板间通信正常、IMU 在线。
  • FAULT：任一安全前提不满足，立即停机。

当前故障标志包括：

标志位 含义
0x01 主板链路丢失
0x02 IMU 离线但仍请求稳定控制
0x04 控制模式非法

恢复策略：

  • 故障出现时，从板立即进入 FAULT 并执行 Start()。
  • FAULT 不会在条件恢复后自动重新起转。
  • 只有当主板重新下发 SAFE 命令且故障条件已经消失时，状态机才会退出 FAULT。

3.5 从板周期调度

从板不再使用 while(1) + delay_ms(10) 的阻塞循环，而是改为 TIM4 提供 1 ms 时基的软调度器：

任务 周期 作用
control 10 ms (100 Hz) 递增链路/IMU 看门狗，并执行推进与飞控输出
supervisor 20 ms (50 Hz) 拉取最新板间命令、更新在线状态、刷新运行状态机
status 100 ms (10 Hz) 刷新状态快照，给后续遥测/调试输出预留挂点

这样处理后：

  • 主循环不再忙等阻塞。
  • 主循环在无待处理任务时执行 __WFI()，等待下一次定时器或串口中断唤醒。
  • 控制频率固定为 100 Hz。
  • 监督逻辑和状态快照被显式拆分，后续增加遥测输出时可以直接挂在 status 任务上。

3.6 从板状态遥测

从板会在 status 任务中以 10 Hz 生成状态遥测帧，经 USART1 发回主板；主板收到有效帧后会缓存最新状态，并原样从 USART2_TX 转发给外部上位机。

遥测帧格式如下：

字节下标 含义 备注
0 帧头 0x5A
1 协议版本 当前为 0x01
2 序号 每帧自增
3 run_state SAFE / STABILIZE / FAULT
4 fault_flags 当前故障标志位
5 board_link_online 主从链路在线状态
6 imu_online IMU 在线状态
7 control_mode 当前控制模式
8 surge 当前前后指令，范围 -100..100
9 yaw 当前偏航指令，范围 -100..100
10 heave 当前升沉指令，范围 -100..100
11 校验 对 1..10 字节做异或校验
12 帧尾 0xA7

4. 主板固件 firmware

4.1 执行器资源分配

PWM / 舵机输出

定时器通道 引脚 当前用途 代码接口
TIM1_CH1 PA8 左夹爪 180 度舵机 L_Claw()
TIM1_CH2 PA9 左肘 180 度舵机 L_Elbow()
TIM1_CH3 PA10 左上臂 360 度连续旋转舵机 L_Upper_360()
TIM1_CH4 PA11 左下臂 360 度连续旋转舵机 L_Lower_360()
TIM2_CH1 PA0 右夹爪 180 度舵机 R_Claw()
TIM2_CH2 PA1 右肘 180 度舵机 R_Elbow()
TIM2_CH3 PB10 右上臂 360 度连续旋转舵机 R_Upper_360()
TIM2_CH4 PB11 右下臂 360 度连续旋转舵机 R_Lower_360()
TIM3_CH1 PA6 尾部上舵机 Tail_Servo1()
TIM3_CH2 PA7 尾部下舵机 Tail_Servo2()

说明：

  • TIM2 使用 PartialRemap2，因此 CH3/CH4 实际输出到 PB10/PB11。
  • 当前主板共承担 10 路 PWM 输出，其中机械臂相关 8 路，尾部舵机 2 路。

4.2 串口与 I2C 分配

外设 引脚 当前用途
USART2_TX PA2 上位机 / 遥控数据发送
USART2_RX PA3 上位机 / 遥控数据接收
USART1_TX PB6 发往从板的板间串口
USART1_RX PB7 板间串口接收预留

软件 I2C

当前项目没有占用硬件 I2C，而是使用软件 I2C：

信号 引脚 用途
SCL PB4 MS5837 与 6 路 AS5600 共用时钟线
SDA0 PB3 默认软件 I2C 数据线，同时用于 MS5837 与第 1 路 AS5600
SDA1 PB12 第 2 路 AS5600
SDA2 PB13 第 3 路 AS5600
SDA3 PB14 第 4 路 AS5600
SDA4 PB15 第 5 路 AS5600
SDA5 PB5 第 6 路 AS5600

这种实现方式本质上是共享一根 SCL，为不同 AS5600 分配独立 SDA，从而避免地址冲突。

4.3 传感器接入

AS5600 分配

主板当前已经实现 6 路 AS5600 读取：

传感器编号 代码名 引脚总线 对应机构
0 left_arm_upper_360 PB4 + PB3 左上臂连续旋转关节
1 left_arm_lower_360 PB4 + PB12 左下臂连续旋转关节
2 right_arm_upper_360 PB4 + PB13 右上臂连续旋转关节
3 right_arm_lower_360 PB4 + PB14 右下臂连续旋转关节
4 tail_servo1 PB4 + PB15 尾部上舵机 Tail_Servo1()
5 tail_servo2 PB4 + PB5 尾部下舵机 Tail_Servo2()

MS5837

模块 接口 当前状态
MS5837 压力 / 水深传感器 软件 I2C，默认总线 PB4 + PB3 已初始化并可读取压力、温度、水深数据

4.4 主板控制逻辑

主板在 main.c 中执行以下流程：

  1. 初始化 GPIO、PWM、双串口、MS5837、全部 AS5600。
  2. 每个循环周期刷新 6 路 AS5600 状态。
  3. 根据控制帧判断是否执行基础运动或机械臂动作。
  4. 将当前控制帧通过 USART1 转发给从板。

当前代码中的几个重要事实：

  • key == 0x00 && hand_OC == 0x00 && Left_Move == 0x00 && Right_Move == 0x00 时，主板认为系统空闲，执行 Start()。
  • hand_OC 负责左 / 右夹爪打开动作。
  • Left_Move 和 Right_Move 负责左右机械臂展开动作。
  • Water_Control 当前仍会被主板解析并透传到从板，但主板主循环未对该字段执行本地动作。

5. 从板固件 firmware_quad

5.1 执行器资源分配

PWM / 电机输出

原始草稿中该部分存在明显冲突，例如将 PA8 重复分配给两个外设。根据当前代码，正确映射如下：

定时器通道 引脚 当前用途 代码接口
TIM3_CH4 PB1 头部推进电机 HeadMotor()
TIM1_CH1 PA8 背部左上四旋翼电机 Quad_LeftUpper()
TIM1_CH2 PA9 背部右上四旋翼电机 Quad_RightUpper()
TIM1_CH3 PA10 背部左下四旋翼电机 Quad_LeftLower()
TIM1_CH4 PA11 背部右下四旋翼电机 Quad_RightLower()
TIM2_CH1 PA0 尾部推进电机 1 Tail_Motor1()
TIM2_CH2 PA1 尾部推进电机 2 Tail_Motor2()
TIM2_CH3 PB10 尾部推进电机 3 Tail_Motor3()
TIM2_CH4 PB11 尾部推进电机 4 Tail_Motor4()

说明：

  • TIM2 同样使用 PartialRemap2。
  • PB1 才是当前头部推进电机的真实输出引脚，不是 PA8。
  • PB0 未在当前从板实现中使用。

5.2 串口分配

外设 引脚 当前用途
USART1_TX PB6 板间串口发送
USART1_RX PB7 板间串口接收主板控制帧
USART2_TX PA2 与 JY901S 的串口通信
USART2_RX PA3 接收 JY901S 数据

5.3 传感器接入

模块 接口 当前状态
JY901S IMU USART2 已实现 11 字节数据帧解析，可输出 roll / pitch / yaw 与三轴角速度，并带在线检测

当前从板会在接收 0x55 0x52 / 0x53 数据帧后更新陀螺与姿态缓存，飞控以此执行低算力闭环控制。

5.4 从板控制逻辑

从板的实际职责比原始草稿更清晰，当前逻辑如下：

  • 若板间链路离线，则清空状态并停机。
  • 若 key == 0x00，则执行 Start()。
  • 若收到有效控制帧，则只根据 key 执行推进 / 姿态动作。

对应行为：

key 从板行为
Front 4 个尾部推进电机沿 +X 方向推进
Back 4 个尾部推进电机沿 -X 方向推进
Left 头部推进电机执行目标偏航角速度，释放后保持当前航向
Right 头部推进电机执行目标偏航角速度，释放后保持当前航向
Up 背部四旋翼输出向上推力，同时维持姿态稳定
Down 背部四旋翼输出向下推力，同时维持姿态稳定

当前从板飞控的实现要点：

  • 固定 10 ms 主循环，适配 STM32F103C8T6，不引入重型滤波或矩阵运算。
  • roll / pitch 使用角度外环 + 角速度内环的轻量级闭环。
  • yaw 使用航向保持 + 角速度控制，驱动头部推进电机完成偏航。
  • 四旋翼电机始终通过混控分配姿态修正量，Front / Back 时尾推进与姿态稳定可同时工作。
  • 若 JY901S 数据超时，则自动退化到开环输出，避免闭环使用陈旧姿态数据。

6. 已整理后的结论

本次整理后，可以将原始要求概括为以下稳定结论：

  • 双板方案已经确定，并且已经在代码中落地。
  • firmware 是主控中心，firmware_quad 是推进与四旋翼执行板。
  • 主板负责机械臂、尾部舵机、编码器、水深传感器，以及指令分发。
  • 从板负责头部推进、尾部推进、背部四旋翼和 IMU 姿态修正。
  • 原始文档中最容易引起误解的从板引脚表已经修正，特别是头部推进电机应为 PB1。
  • 当前协议中 Water_Control 仍作为保留字节透传，但不再绑定本地执行机构。

7. 后续建议

如果后面继续迭代，建议优先做以下整理：

  1. 若后续需要扩展控制协议，优先明确 Water_Control 的后续用途，避免新增语义继续挤占现有字段。
  2. 为主板和从板分别补充正式的引脚图或原理图标注。
  3. 将 codex.md 保持为“设计约束与实现说明”，不要再混入临时聊天式修改要求。

8. 代码参考

本整理主要依据以下文件：

  • firmware/BSP/GPIO.c
  • firmware/BSP/timer.c
  • firmware/HARDWARE/Servo.c
  • firmware/HARDWARE/AS5600.c
  • firmware/HARDWARE/MS5837.c
  • firmware/SYSTEM/usart/usart.c
  • firmware/USER/main.c
  • firmware_quad/BSP/GPIO.c
  • firmware_quad/BSP/timer.c
  • firmware_quad/HARDWARE/Servo.c
  • firmware_quad/HARDWARE/JY901S.c
  • firmware_quad/SYSTEM/usart/usart.c
  • firmware_quad/USER/main.c