协议格式详解#

NexuTrace 的协议解析只负责把普通字节流变成统一的“命令号 + 载荷”记录。连接方式可以是串口、USB、TCP、UDP；协议可以选择不解析、FireWater、JustFloat 或 NexuFrame。

协议总览#

协议

输入格式

适合场景

不解析

原始字节

只看日志、Hex、表格，不需要通道和公式。

FireWater

文本行，逗号分隔浮点数，可带 chN: 前缀

固件早期调试、快速画曲线、人眼可读日志。

JustFloat

float32 数组 + 固定尾标记，可选命令扩展尾

高速连续浮点数据、传感器曲线、控制量观察。

NexuFrame

同步字 + 命令号 + 长度 + 载荷 + SUM8

正式二进制协议、命令/响应、TCP 粘包拆包场景。

不解析模式#

禁用协议解析时，NexuTrace 不尝试把字节变成通道。你仍然可以使用：

  1. 文本视图。

  2. 表格视图。

  3. Hex 分析。

  4. 普通发送和文件发送。

  5. CAN 表和 CAN 发送。

适合场景：

  1. 只想看日志。

  2. 设备协议还没稳定。

  3. 正在定位连接、编码、波特率、端点或网络问题。

  4. 需要保存原始证据，暂时不关心字段值。

FireWater#

FireWater 是最轻量的文本浮点协议。每一行以 \n 结束，可以有 \r\n，解析时会去掉行尾 \r。

基本格式：

12.3,45.6,-7.8
ch10:100,200,300
channel2:1.25,2.5

解析规则：

规则

说明

行结束

以 \n 为一帧结束，兼容 \r\n。

空行

忽略。

image: 行

忽略，避免把图像类文本流误当浮点数据。

: 前缀

前缀末尾有数字且包含字母时，数字作为命令号，例如 ch10 得到 cmd=10。

数值

从前缀后开始解析 float，支持空格、Tab 和逗号分隔。

通道上限

最多按当前最大通道数解析，通常不超过 32 个。

发送规则：

  1. TX 帧的载荷按 float32 数组解释。

  2. cmd=0 时输出 v1,v2,v3\n。

  3. cmd!=0 时输出 ch{cmd}:v1,v2,v3\n。

  4. 数字使用紧凑格式输出，适合串口日志和文本协议。

FireWater 优点是固件实现简单，抓日志也能直接读；缺点是文本解析开销比二进制大，且字段类型固定偏向浮点。

JustFloat#

JustFloat 是紧凑浮点流。它把一组 float32 按原始字节发送，末尾加固定标记。

普通格式：

float32[0] float32[1] ... float32[n-1] 00 00 80 7F

扩展命令格式：

float32[] 00 00 80 7F  54 A5  cmd_lo cmd_hi  00 00 80 FF

解析规则：

规则

说明

主尾标记

00 00 80 7F 表示一组 float 数据结束。

扩展尾标记

主尾后若跟 54 A5 + cmd + 00 00 80 FF，则提取命令号。

数据长度

建议为 4 字节倍数，每 4 字节一个 float32。

字节序

常规 MCU/PC 小端 float32 最常用。

通道上限

float 数量不要超过最大通道数，通常 32 路以内。

发送规则：

  1. cmd=0 时发送 float32 载荷 + 00 00 80 7F。

  2. cmd!=0 时再追加扩展尾，保留命令号。

  3. 适合高速曲线，因为不用把数字转成文本。

JustFloat 适合“只想快速看多路浮点曲线”的场景。如果需要混合整数、状态位、变长载荷或严格命令/响应，建议用 NexuFrame。

NexuFrame#

NexuFrame 是正式二进制帧协议，适合命令式设备协议和可靠解析。

线格式：

54 A5  cmd_lo cmd_hi  len_lo len_hi  data...  sum8

字段说明：

字段

长度

说明

Sync

2 字节

同步字。常规小端字节为 54 A5，解析器也能识别交换顺序。

Cmd

2 字节

命令号，小端。用于区分状态帧、控制帧、配置帧等。

Len

2 字节

data 加 sum8 的总长度。

Data

N 字节

业务载荷，可包含整数、浮点、状态位和数组。

SUM8

1 字节

从 cmd、len 到 data 的所有字节累加后取低 8 位。

解析规则：

  1. 在字节流中搜索同步字。

  2. 读取命令号和长度。

  3. 长度超过上限时丢弃当前同步字并继续寻找。

  4. 数据不足时等待后续字节。

  5. 校验失败时丢弃当前同步字并继续寻找。

  6. 校验通过后输出命令号和载荷记录。

容量边界：

项目

说明

通道数

数据面板通常按最多 32 路通道组织。

Len 上限

1024 字节。它包含最后 1 字节 SUM8，因此业务 Data 建议不超过 1023 字节。

帧头长度

6 字节：Sync 2 + Cmd 2 + Len 2。

发送规则：

  1. TX 帧里填写命令号和业务载荷。

  2. NexuTrace 自动写入 54 A5、命令号、长度和 SUM8。

  3. Len 会按业务载荷长度 + 1 个 SUM8 生成。

示例：发送 cmd=0x0102，业务载荷 01 02 03：

54 A5 02 01 04 00 01 02 03 0B

其中 04 00 表示 3 字节 data + 1 字节 SUM8，0B 是 02+01+04+00+01+02+03 的低 8 位。

普通模式里的协议选择#

需求

建议

固件还在早期调试

先用不解析或 FireWater，方便人眼确认。

只看多路浮点曲线

用 JustFloat，开销低、结构简单。

需要命令号和多种字段类型

用 NexuFrame。

跑在 TCP 上

优先 NexuFrame，因为 TCP 会粘包和拆包。

跑在 UDP 上

可用任意协议，但重要数据建议带命令号、序号或校验。

跑在 HID 上

简单报告可不解析；正式业务建议 NexuFrame。

和数据面板的关系#

协议解析只负责得到 cmd 和 data。真正把 data 解释成电压、温度、转速、状态位的是数据面板：

  1. RX Frames 按 cmd 管理接收帧。

  2. RX Channels 按 cmd + offset + type 提取字段。

  3. TX Frames 按 cmd 生成发送帧。

  4. TX Channels 把控件或公式写入载荷。

  5. Formula 把原始值变成工程值。

  6. Plot Channels 决定哪些值进入波形。

所以排障时要分层看：原始字节是否正确，协议帧是否解析，通道偏移是否正确，公式是否符合单位换算。