协议与数据面板

数据路径

开启协议后，NexusTools 会把原始字节解析为统一的 cmd + payload 语义，再由数据面板按命令字、偏移和数据类型拆成可绑定的通道。

1

Device

串口、USB、网络或 CAN 输入原始字节。

2

Raw Views

文本、表格和 Hex 视图保留裸数据，便于回看。

3

Protocol

协议解析器输出统一的 cmd + payload。

4

DataPanel

RX/TX/GX 通道按模板和公式刷新。

5

Binding

Plot、仪表、控件和 3D 使用 UID 绑定通道。

协议页示例：解析器把不同传输格式归一到数据帧。

数据面板：Raw Frame、RX/TX Frames、Channels、GX、Formula 与 Plot Channels 集中配置。

绑定面板：控件通过通道 UID 关联，不依赖容易变化的显示名称。

协议对照

协议	传输形态	cmd_value 来源	适合场景
FireWater	CSV 文本行 + 换行。	前缀规则，无合法前缀时为 0。	快速联调、文本可读、串口日志兼容。
JustFloat	小端 float[] + 帧尾，可选扩展段。	扩展段或默认 0。	高频浮点数据、波形观察。
NexusPro	sync + cmd + packet_len + data[] + CRC。	帧头直接给出。	严谨二进制协议、工程化设备通信。

解析细节

协议	源码规则	使用提示
FireWater	按 \n 分行，自动去掉 \r；忽略 image: 行；: 前缀中包含字母且末尾带数字时提取为 cmd，否则 cmd 为 0。	适合 CSV 浮点流和日志混发。需要命令字时可用 ch12:1.0,2.0 这类前缀。
JustFloat	载荷为小端 float[]，普通帧尾为 00 00 80 7F；扩展帧尾为 00 00 80 FF，可携带 54 A5 + cmd 扩展段。	适合持续波形数据。解析器限制浮点通道数不超过协议最大通道数。
NexusPro	同步字为 54 A5，解析器也会处理字节交换场景；字段为 cmd、packet_len、data 和 SUM8 校验。	适合严谨二进制帧。packet_len 超过 1024 字节会被拒绝。

协议规范

三种协议在端口侧完成分帧后，都会转换为统一解析帧：cmd_value + payload。数据面板不关心原始协议来自文本、浮点尾帧还是二进制帧，只按 cmd、offset 和 type 从 payload 中取数。

FireWater

文本 CSV 行协议。换行结束一帧，数值按 float 解析，适合快速联调和可读日志。

JustFloat

小端 float32 数组 + 固定尾字节。吞吐比文本高，适合波形和多通道浮点流。

NexusPro

同步字、命令字、长度和 SUM8 校验。边界明确，适合工程设备协议。

FireWater

FireWater 是文本行协议，兼容常见 CSV 浮点输出习惯。每一帧必须以 \n、\r\n 或 \n\r 结束；长时间不换行时，解析器无法确认帧边界，接收缓冲会持续等待。

<prefix>:v0,v1,v2,...,vN\n

前缀和冒号可以省略，换行不可省略。逗号分隔的每个数值按 float 解析，进入统一载荷时会转换为小端 float 字节。整行以 image: 开头时会被保留用途忽略。

cmd_value 由第一个冒号前的前缀推导：

行首	规则	cmd_value
1.0,2.0,3.0	无冒号	0
samples:1.0,2.0	有字母但末尾无数字	0
plot01:1.0,2.0	前缀含字母，取末尾连续数字	1
ch10:1.0,2.0	前缀含字母，末尾数字为 10	10

发送侧规则与接收侧保持一致：cmd_value == 0 时发送纯 CSV + 换行；cmd_value != 0 时行首自动加 ch{cmd}:，例如 cmd=10 会发送 ch10:1.0,2.0\n。

JustFloat

JustFloat 是小端 float32 数组加帧尾的二进制协议。经典帧只包含浮点载荷和 4 字节尾：

float   data[N];                         // little-endian IEEE754 float32
uint8_t tail[4] = {0x00, 0x00, 0x80, 0x7F};

无扩展段时 cmd_value = 0，payload 为尾字节之前的全部 float 字节。尾四字节对应 float +inf，理论上存在被普通数据误命中的可能；如果设备需要强边界、长度和校验，应优先使用 NexusPro。

带命令字时，在经典尾之后追加 8 字节扩展段：

字段	长度	说明
sync	2	小端 0xA554，线上常见字节为 54 A5。
cmd_value	2	小端 uint16_t。
ext_tail	4	00 00 80 FF，用于区别经典尾。

发送侧在 cmd_value == 0 时只输出 payload + 00 00 80 7F；在 cmd_value != 0 时继续追加 54 A5 + cmd 小端 + 00 00 80 FF。

NexusPro

NexusPro 是推荐的工程化二进制帧。帧头固定 6 字节，packet_len 包含末尾 1 字节 SUM8，真正业务载荷长度为 packet_len - 1。

#pragma pack(4)
typedef struct {
    uint16_t sync;          // 0xA554, little-endian bytes: 54 A5
    uint16_t cmd_value;     // application command
    uint16_t packet_len;    // payload bytes + 1 byte SUM8
    uint8_t  data[];        // payload + SUM8
} NexusProFrame;
#pragma pack()

常量	值	说明
NEXUSPRO_SYNC	0xA554	小端字段值，线上通常为 54 A5。
NEXUSPRO_SYNC_SWAP	0x54A5	解析器会识别交换字节序的 sync。
NEXUSPRO_HEADER_SIZE	6	sync、cmd、packet_len 三个 16 位字段。
NEXUSPRO_DATA_MAX_LEN	1024	data[] 最大长度，包含末尾 SUM8。

SUM8 校验计算范围为 cmd_value 两字节、packet_len 两字节，以及 data[0 .. packet_len - 2]。所有字节按无符号累加，取低 8 位，写入 data[packet_len - 1]。

uint8_t sum = 0;
sum += cmd_low;
sum += cmd_high;
sum += len_low;
sum += len_high;
for (int i = 0; i < packet_len - 1; ++i) {
    sum += payload[i];
}
frame.data[packet_len - 1] = sum;

接收端会在字节流中搜索 sync，读取 cmd_value 与 packet_len，拒绝超过 1024 字节的帧，并在 SUM8 通过后把 payload 交给数据面板。校验失败时解析器会移动搜索窗口继续找下一帧。

数据面板区块

区块	用途	关键操作
Raw Frame	展示最近收到的各 cmd 原始帧。	核对协议解析是否正确。
RX Frames	配置关心的接收帧模板。	填写 cmd，观察 len / data 刷新。
TX Frames	配置要下发的帧模板。	设置 cmd、len、Auto 和 us 周期。
RX Channels	按 cmd + offset + type 拆出接收数值。	选择 uint / int / float 类型，确认 value。
TX Channels	供控件和公式写入，再组帧发送。	绑定发送控件或自动发送帧。
GX	通用中间变量。	承接公式结果或跨控件共享值。
Plot Channels	配置波形曲线名称、颜色与数据源。	选择 RX / TX / GX 作为曲线源。
Formula	对 TX / GX 做表达式求值。	使用 sin、cos、sqrt、pow、PI、RX_00 等表达式。

数据面板操作细节

顶部工具栏从左到右通常包含协议选择、配置文件选择、新建配置和另存为。协议选择对应内部编号 1=FireWater、2=JustFloat、3=NexusPro；在 CAN 模式下，界面会隐藏普通协议选择，改为显示“CAN 数据作为 NexusPro 解析”的开关。

配置文件下拉框会扫描工作目录中的 *.json。选择文件后，RX/TX 帧模板、通道映射、GX、公式和波形通道都会替换为文件内容；字段修改后会自动标记配置变更，并写回当前 JSON。

RX Frames 的核心作用是声明“关心哪些 cmd”。收到匹配命令字的帧时，该行 len 和 data 会刷新，便于确认设备是否正在上报目标帧。TX Frames 用于声明要下发的帧，len 是有效载荷长度，不包含 NexusPro 的 CRC；编辑长度后，软件会自动扩缩帧缓冲。

RX Channels 按 cmd + offset + type 从接收载荷读取数值。TX Channels 是反向路径：控件、数值输入或公式写入 TX 通道后，软件把值回填到对应 TX 帧缓冲，再按当前协议组帧发送。GX 是中间变量，不直接对应某个收发帧，适合放公式结果或跨控件共享状态。

Plot Channels 每行是一条曲线：色块用于打开颜色选择器，源下拉框选择 RX_xx、TX_xx、GX_xx 或未绑定。新曲线按 8 色循环分配默认颜色，源码中的绘图缓冲最多支持 64 个通道。

通道映射

RX 通道用于把接收帧载荷拆成数值，TX 通道用于把控件或公式写入的数据重新放回发送帧，GX 通道用于中间变量。

常见映射字段包括：

• cmd：该通道对应的帧命令字。

• offset：在 data[] 中的字节偏移，0 起始。

• type：数据类型，例如 uint8、int16、uint32、float。

• value：当前解析值或写入值。

数据类型与公式

源码中的数据面板类型覆盖 uint8、int8、uint16、int16、uint32、int32 和 float。通道显示名使用 RX_00、TX_00、GX_00 这类稳定命名，内部绑定使用 UID，改名或调整排序时不容易丢失关联。

公式编辑器会识别通道名、函数、数字、运算符和常量。常用函数包括 sin、cos、tan、asin、acos、atan、sqrt、abs、log、log10、exp、pow、min、max，常量包括 PI 和 E。

Raw Frame 区域会展示最近解析帧的 cmd 与数据摘要；源码中单次十六进制摘要最多显示 64 字节，适合快速核对帧头、长度和校验。

自动发送

在 TX Frames 中勾选 Auto 后，软件会按设定的 us 周期组帧发送。当前资料记录的自动发送最小间隔为 175μs，实际精度仍会受到系统调度和设备链路影响。