﻿水上火箭地面站 v1.36.1 通信及文件格式（以本轮桌面源码为准）
• 本文说明电脑端实际格式，不代表已验证现用飞控固件。
• 原始模式不解析 PWM/磁力计；扩展模式追加 0x02 的磁力计及 0xF0 的四路 PWM。

水上火箭地面站 ANO 帧与 TEE V4 格式
====================================

一、当前桌面解析器支持的旧版 ANO 帧
------------------------------------
帧结构：
AA AA FUNC LEN DATA... SUM

SUM 为从第一个 AA 到 DATA 最后一个字节的无符号累加和，只保留低 8 位。
多字节整数均为大端序（高字节在前）。

1. 0x01 姿态/高度
LEN = 12
int16 roll ×100
int16 pitch ×100
int16 yaw ×100
int32 altitude_cm
uint8 flight_mode
uint8 armed

2. 0x02 传感器
LEN = 12（基础）或 18（追加磁力计）
int16 raw_acc_x, raw_acc_y, raw_acc_z
int16 raw_gyro_x, raw_gyro_y, raw_gyro_z
int16 raw_mag_x, raw_mag_y, raw_mag_z

当前桌面解析器采用以下标度（实际固件需确认一致）：
acceleration_m_s2 = raw_acc / 16384 × 9.81
angular_rate_deg_s = raw_gyro / 131

3. 0x03 SBUS / 接收机通道
LEN = 20
int16 CH1～CH10，依次为 THR、YAW、ROLL、PITCH、AUX1～AUX6。
通道值按大端序解析，常见中值为 1500。

地面站仍可按 ROLL=CH3、PITCH=CH4、YAW=CH2 换算并保存期望角（THR 不作为姿态期望角）：
target_deg = clamp((channel - 1500) × 45 / 500, -45, +45)

飞行模式不由电脑端 SBUS 接收状态直接判定。数据分析检查 CSV 的 target_roll、
target_pitch、target_yaw：任一方向变化范围达到 3°，出现不少于 0.5° 的明显变化，
并持续至少 0.5 秒或变化后仍有 1 秒数据时判定为“制导模式”；否则判定为“自稳模式”。

4. 0x33 差分位置
LEN 至少为 6
int16 x_cm
int16 y_cm
int16 z_cm

只有收到有效 0x33 差分位置，或新版差分 GPS 帧后，软件才增加飞行路径点。
没有差分定位数据时，飞行路径保持为空，导出操作不会产生空路径文件。

二、12 路用户自定义数据
-----------------------
分别使用功能字 0xF1～0xFC，每帧表示一路数据。原有前 6 路仍固定使用
0xF1～0xF6，帧编号、数据格式和缩放比例均不变；新增 6 路顺序使用
0xF7、0xF8、0xF9、0xFA、0xFB、0xFC。

推荐且地面站已实现的旧版格式：
AA AA Fn 04 VALUE SUM

Fn：F1～FC 中对应通道的功能字。
VALUE：有符号 int32，大端序，实际值乘以 1000 后发送。
地面站显示值 = VALUE / 1000.0。

示例：User Data 1 = 12.345
VALUE = 12345 = 00 00 30 39
不含校验的帧为：
AA AA F1 04 00 00 30 39
最后追加上述字节的低 8 位累加和。

新版 0xAB 的 F1～FC 支持至少 4 字节小端 float 单通道；F1～FA 在载荷至少 36 字节时优先作为姿态 float32[3]、角速度 float32[3]、力矩 float32[3] 的复合帧，不作为单用户通道。
用户数据名称和启用状态在“程序设置”中调整。

三、新版 0xAB 双校验帧
----------------------
继续兼容已有格式：
AB SOURCE DEST FUNC LEN_L LEN_H DATA... SC AC

SC：从帧头到数据末尾的累加和。
AC：累加过程中每一步 SC 的再次累加和。
数值按小端序解析；以下偏移从 DATA 的第 0 字节开始：
• 0x01 / 至少 12 字节：偏移 6/8/10 的 int16 角速度，当前直接按 deg/s 读入。
• 0x03 / 至少 6 字节：int16 姿态 roll/pitch/yaw，除以 100 得度；载荷至少 8 字节且首字节为 1 时从偏移 1 开始读取三轴。
• 0x05 / 至少 4 字节：int32 高度厘米，除以 100 得米。
• 0x07 / 至少 6 字节：int16[3] 速度，除以 100 得 m/s。
• 0x21 / 至少 8 字节：偏移 0/2/6 的 int16 三轴力矩，当前直接读入，实际单位须与固件确认。
• 0x30 / 至少 22 字节：偏移 2/6 的 int32 经度/纬度除以 1e7；偏移 10 的 int32 高度除以 100；偏移 14/16/18 的 int16 三轴速度除以 100。
• F1～FC / 至少 4 字节：小端 float 用户通道；F1～FA / 至少 36 字节优先按上述复合帧读取。
• 未列出的功能字不要假定有有效测量；协议是否兼容以字段、单位与实际固件核对为准。
• 扩展模式的 AA AA F0 / 8 字节为 uint16 四路 PWM，大端，顺序 PE9、PE11、PD12、PD13，单位 us。

四、TEE / CSV V4 列
-------------------
time,roll,pitch,yaw,target_roll,target_pitch,target_yaw,rate_roll,rate_pitch,rate_yaw,accel_x,accel_y,accel_z,torque_roll,torque_pitch,torque_yaw,position_x_m,position_y_m,position_z_m,altitude,vx,vy,vz,latitude,longitude,pwm_pe9_us,pwm_pe11_us,pwm_pd12_us,pwm_pd13_us,mag_x,mag_y,mag_z,user1,user2,user3,user4,user5,user6,user7,user8,user9,user10,user11,user12,sbus_active,sbus1,sbus2,sbus3,sbus4,sbus5,sbus6,sbus7,sbus8,sbus9,sbus10,frame_id,updated_mask

即使波形页面只显示一种物理量，TEE 仍保存所有上述通道。
frame_id 保存产生该采样的功能字；updated_mask 保存该帧真正更新的字段。波形绘图据此只为本帧更新的物理量增加一个点，避免其他类型帧重复绘制旧角速度而形成阶跃。旧文件没有这两列时仍按完整采样兼容读取。

五、串口参数
------------
默认 9600 baud，8 数据位、无校验、1 停止位（8N1）。
如板端修改波特率，请在“串口通讯”中同步修改。

六、文本命令与回传
• 默认 9600 baud、8N1；双方必须一致。文本以 CRLF（十六进制 0D 0A）结束，无 BOM。
• GET\r\n：读取全部参数；每项返回 PARAM 名称=值\r\n，结束返回 PARAMS END\r\n。
• SET Kp_att_pitch=120.000\r\n：设置单项；整型示例 SET PWM_CENTER_PE9_US=1730\r\n。
• 当前选中项及 S+Enter 均逐条 SET，至少间隔 500 ms；浮点用英文小数点，整型不带小数点。
• SETALL Kp_att_pitch=120.000,Kd_att_pitch=0.000\r\n：仅为兼容旧接口的格式；当前界面不发送 SETALL，也不因 ERR 自动拆分重发。
• PARAM Kp_att_pitch=120.000\r\n 为读回值；ERR SET / ERR SETALL / ERR COMMAND 表示错误。OK SETALL 仅表示旧接口完成，不能替代逐项读回及安全验证。
• 参数名须与板端表一致，可新增；默认包含 Kp/Kd_att_pitch/roll、姿态死区、四路 PWM 中心与幅度。桌面本地表不保证板端支持所有项。
• 发送成功仅表示电脑端写出；Flash 持久化、原子事务、板端安全限幅须由真实固件定义。当前没有事务编号或持久化确认协议。

七、身份、校准及偏航
• 多板身份示例：WRGS:HELLO PROTO=1.0 BOARD=WR-F407 CAPS=0x000F SERIAL=000001\r\n。
• PROTO：协议版本；BOARD：型号；CAPS：能力位；SERIAL：实体标识。0x000F 为示意：参数、校准、PWM、磁力计；应按实际能力填写。
• 单板无需该握手；多板身份信息不阻断普通遥测。
• ZEROCAL\r\n：零偏校准；回传 WRGS:CALIB_STARTED、WRGS:CALIB_STEP,操作提示、WRGS:CALIB_DONE 或 WRGS:CALIB_FAILED,原因，每行 CRLF。
• YAWZERO\r\n：大写偏航归中；板端回执格式需依现用固件核对，不编造成功状态。
• WRGS:CONNECTED\r\n 可用于连接提示。

八、自定义文字与外部通讯
• 自定义发送仅直接 COM：UTF-8、无 BOM、单行最多 256 字符、追加 CRLF；板端需自行定义处理规则。
• 常规 GET/SET/校准命令可走直接 COM、外部软件标准输入/输出或受支持窗口桥接；每次发送遵守连接代次与状态检查。
• 外部软件标准输入用 CRLF，标准输出 PARAM 与 WRGS: 行用于解析。普通 GUI 不保证可桥接，HC-PC 等窗口适配需实际验证。

九、对应 C 代码与集成边界
• 同目录 wrgs_board_example.c 是通用 UART 行解析示例，与程序“导出示例代码”使用同一份来源。
• 覆盖有界接收缓冲、GET、SET、兼容 SETALL、身份；拒绝非法数值、未知名称、越界、重复项及过长行，SETALL 先完整校验再写入。
• 示例只有演示变量，需绑定实际飞控变量/UART，加入控制循环并发保护、板端限幅和真实校准状态机。校准/偏航默认 ERR UNSUPPORTED，避免假成功。
• 这是供集成的参考文件，不是现用固件；本轮未修改、编译或验证实机飞控。实际板端须取得现用固件、协议及设备后核对。
• updated_mask 仅标记本帧更新字段，不是帧序号、丢帧率、延迟或时间同步。
