协议与数据面板#

协议面板负责把“收到一串字节”变成“这是哪个命令、哪个字段、当前值是多少”。数据面板负责把这些字段继续送到曲线、仪表、公式、控制输入和发送帧里。协议线格式的详细说明见协议格式详解。

建议的使用顺序是：先看原始数据，确认链路正常；再选择协议；然后建立帧和通道；最后再绑定波形或控件。

支持的解析方式#

协议	适合数据	你会得到什么
FireWater	文本、CSV、带通道前缀的日志，例如 `ch1:12.3`	快速把可读日志变成通道值，适合早期固件调试。
JustFloat	连续小端 float32 数据流	低成本查看多路浮点曲线，适合传感器、控制量和算法输出。
NexuFrame	带同步头、命令号、长度、载荷和校验的二进制帧	按命令号拆帧，再按偏移和类型提取字段，适合工程化设备协议。
CAN 载荷解析为 NexuFrame	设备把 NexuFrame 帧放在 CAN Data 中传输	USB-CAN 模式下只把 CAN 载荷送入 NexuFrame 解析，CAN ID 可作为原始帧命令键辅助区分。

USB-CAN 模式下，CAN 表仍然显示完整 CAN 报文；协议解析只关注 CAN Data。这样可以同时保留总线证据和上层业务值，避免把 ID、DLC 当成协议载荷误解析。

协议选择不是越复杂越好。Bring-up 阶段可以先用 FireWater 或 JustFloat 观察趋势，协议稳定后再切到 NexuFrame。

区域	用途
Raw Frame	查看最近解析到的原始帧，确认命令号、长度和载荷是否符合预期。
RX Frames	声明设备发来的帧，按命令号管理不同业务包。
TX Frames	声明要发给设备的帧，可手动发送或按周期自动发送。
RX Channels	从 RX 帧载荷里按偏移和类型提取值，例如电压、电流、温度、转速。
TX Channels	把用户输入、公式结果或固定值写入 TX 帧字段。
GX Variables	全局变量，适合做中间计算、状态保持或跨控件共享值。
Formula	用通道名写计算表达式，把原始值转换成工程值或控制量。
Plot Channels	选择哪些 RX/TX/GX 值进入波形，并配置颜色和显示名称。

通道从载荷中读取字段时，需要指定偏移和类型。常见类型包括：

如果固件使用定点数，例如 int16 表示 0.01 度，建议先建原始通道，再用公式生成工程值。

假设设备周期发送状态帧 cmd = 0x0101，载荷从偏移 0 开始依次放置 float32 转速和 float32 温度：

通道名	命令号	偏移	类型
`motor_rpm`	`0x0101`	`0`	`float`
`motor_temp`	`0x0101`	`4`	`float`

建立后先观察通道实时值。如果值跳变离谱，优先检查偏移、类型、大小端和设备实际协议版本。

假设要发送 cmd = 0x0201 的控制帧，载荷偏移 0 写入目标 PWM，偏移 2 写入使能位：

通道名	命令号	偏移	类型
`target_pwm`	`0x0201`	`0`	`int16`
`motor_enable`	`0x0201`	`2`	`uint8`

然后可以把 target_pwm 绑定到数值输入，把 motor_enable 绑定到开关。点击发送或开启 TX 帧自动发送时，NexuTrace 会按字段生成载荷。

公式适合把原始通道转换成更容易判断的值。表达式里可以使用通道名、常量和常见函数，例如 sin、cos、sqrt、abs、log、pow、min、max、PI、E。

示例：

motor_rad_s = motor_rpm * 0.10472
temp_alarm = motor_temp > 80
pwm_limit = min(max(user_pwm, 0), 100)

建议把“设备原始值”和“工程换算值”分开命名。原始值用于回查协议，工程值用于波形、仪表和控制判断。

GX 变量是数据面板里的全局工作变量。它不直接来自某一帧，也不一定直接发给设备，适合做中间状态。

用法	示例
工程换算	`power_w = bus_voltage * bus_current`
告警状态	`over_temp = motor_temp > 80`
用户目标值	输入框写入 `target_speed`，公式再限幅后写入 TX 通道。
跨控件共享	一个值同时驱动波形、仪表和发送帧。

GX 变量可以让面板更像一个小型测试台，而不是只显示设备发来的原始值。

TX Frames 适合把一条命令做成可复用模板。你可以把某些字段绑定到 TX Channels 或 GX Variables，再让输入框、滑块、开关或公式改变这些字段。

常见用法：

周期发送不要一开始就设到很低。先用较慢周期确认设备能正确响应，再逐步降低周期并观察发送计数、设备响应和 CPU 占用。

USB-CAN 模式下，数据面板 TX 帧可以配置 CAN 帧标志，常见为 EXT、RTR、FD、BRS。

如果只是普通串口、USB 或网络连接，这些 CAN 标志不会参与普通字节流发送。

数据面板配置保存为 JSON，默认放在 config/cfg_data。建议按设备和协议版本命名，例如：

motor_controller_v1.json
bms_canfd_500k_2m.json
bootloader_uart.json

当固件协议变更时，不要直接覆盖旧配置。保留旧文件能帮助你回归历史固件，也能在现场快速确认“是工具配置变了，还是设备协议变了”。