差异缓冲远程控制传输协议规范 - 深圳市酷唱科技有限公司

本协议为工业级远程控制专用的轻量级差异同步规范，采用双缓冲 + 分段差异 + 位掩码机制，实现本地与远端设备之间高效、低带宽的数据同步。协议与平台、语言无关，可在 C、JavaScript、Python、Java 等任意环境实现。

仅传输变化数据：降低通信带宽占用
固定分段、整段发送：保证解析可靠性
统一报文格式：唯一传输通道，便于工业场景使用
支持定时合并发送：减少频繁交互带来的延迟与抖动
支持多种业务：本地显示同步、远程控制、状态同步、大文件/列表传输

本地与远端均维护两组最大 1024 字节缓冲：

A 缓冲（当前状态缓冲）

本地设备自身产生的变化、控制指令、状态更新，全部写入 A 缓冲
A 缓冲代表本机当前最新、真实、有效的状态
当 A 缓冲与 B 缓冲对比出现差异时，表示有新数据需要发送给对方

B 缓冲（对方/同步基准缓冲）

从对方收到的数据，直接写入 B 缓冲
B 缓冲代表远端设备最新同步过来的状态
接收完成后，将 B 与 A 进行差异对比
若存在差异，用于本地显示刷新、消息通知、模块联动等业务处理

多线程安全要求：A 缓冲、B 缓冲均为共享资源，本地修改线程与网络接收线程不可同时写入，必须使用互斥锁或统一单线程处理。

数据区域按固定大小分为 8 段，段内任意 1 字节变化，整段发送。

段 0（bit0）：8 字节，偏移 0
段 1（bit1）：8 字节，偏移 8
段 2（bit2）：16 字节，偏移 16
段 3（bit3）：32 字节，偏移 32
段 4（bit4）：64 字节，偏移 64
段 5（bit5）：128 字节，偏移 128
段 6（bit6）：256 字节，偏移 256
段 7（bit7）：512 字节，偏移 512

总长度最大为 1024 字节。

所有发送统一使用唯一格式：1 字节位掩码 + 变化段数据（按段顺序拼接）

第 0 字节：位掩码
- bit0～bit7 分别对应 8 个段
- 位为 1：该段有变化，需要传输
- 位为 0：无变化，不发送
数据区：仅包含掩码为 1 的段数据

本机状态更新 → 写入 A 缓冲
定时对比 A 缓冲 ↔ B 缓冲
逐段比较，标记变化段
构建 1 字节位掩码
按掩码拼接变化段数据，形成报文
发送给对方
发送完成后可将 A 同步至 B

接收报文 → 解析位掩码
按掩码将数据写入 B 缓冲
对比 B 缓冲 ↔ A 缓冲，提取差异
差异用于：显示刷新、状态更新、业务消息推送
可根据策略将 B 同步至 A
所有缓冲写入保证线程安全

变化频繁、高频字段放在前面：小段优先放在前两段（各 8 字节），改动仅传极小数据。
同类型、同时变化的字段放在同一段：避免一次改动触发多段发送。
极少变化、大容量字段放在最后段：配置、扩展信息等放在后面大段。

不直接传输内存结构体
二进制报文 → Base64/HEX 编码 → JSON / 表单传输
接收端解码回二进制 → 按协议解析
可搭配 MD5、CRC 做校验

9.1 二进制转文本编码接口

提供以下标准化编码函数，用于二进制数据与文本格式的转换：

// 将二进制缓冲编码为HEX（十六进制）文本字符串

// 参数说明：

// bytes - 输出的HEX文本缓冲区

// SIZEOF - 输出缓冲区总大小（需≥2*length+1）

// inDat - 输入的二进制数据缓冲

// length - 输入二进制数据的长度

// 返回值：成功返回编码后文本长度，失败返回-1

int TxtHexEnc(char* bytes, int SIZEOF, uint8_t* inDat, int length);

// 将二进制缓冲编码为BASE64文本字符串

// 参数说明：

// bytes - 输出的BASE64文本缓冲区

// SIZEOF - 输出缓冲区总大小（需≥4*((length+2)/3)+1）

// inDat - 输入的二进制数据缓冲

// length - 输入二进制数据的长度

// 返回值：成功返回编码后文本长度，失败返回-1

int TxtBase64Enc(char* bytes, int SIZEOF, uint8_t* inDat, int length);

int DiffBkTxContrast(out, save, current, size)：对比差异，生成差异报文并更新基准。
int DiffBkTxOutAll(out, save, current, size)：全量发送，掩码 = 0xFF。
int DiffBkTxAppoint(out, buf, size, flag)：按掩码提取指定段数据。
int DiffBkTxMakeCrcs(crcOut, buf, size)：生成每段 CRC16 及整体校验。
uint8_t DiffBkTxFromCrcs(remoteCrc, localCrc, size)：对比 CRC 得到变化段位掩码。
void DiffBkTxInput(buf, size, inData, len)：按报文更新目标缓冲。

A、B 缓冲为共享资源
同一时间只允许一个写操作
使用互斥锁 / 单线程队列保证安全
禁止并发写导致数据错乱

8 段固定偏移与长度
1 字节位掩码打包 / 解包
整段比较、整段复制
缓冲线程安全
可选：标准 CRC16/CRC32

一、帧结构总规则

文件传输帧头固定长度：16 字节
对齐方式：1 字节紧凑对齐
多字节字段：小端序（Little-Endian）
帧总长度支持：32 / 64 / 128 / 256 / 512 字节
文件传输数据区长度 = 帧总长度 - 16 字节

二、文件传输帧头结构体定义（C 语言）

#pragma pack(push, 1)

typedef struct {

    uint16_t Crc16;                                         // 本帧CRC16校验值

    uint16_t SegNo : 3;                                     // 段编号，仅3~7有效

    uint16_t Dir : 1;                                       // 传输方向标识

    uint16_t Type : 5;                                      // 帧功能类型

    uint16_t RevType : 5;                                   // 反向应答类型

    uint16_t RetryCnt : 2;                                  // 重传计数

    uint16_t Reserved;                                      // 16位保留字段

    uint32_t FileOffset : 24;                               // 文件偏移

    uint32_t FileLength : 24;                               // 文件总长度

    uint32_t FileCrc32;                                     // 文件CRC32校验值

} DIFF_BK_TX_FILE_HEAD;                                     // 文件传输帧头结构体

#pragma pack(pop)

三、文件传输帧头字段详细说明

字段名	位宽/长度	说明
Crc16	16bit	本帧 CRC16 校验值，校验范围为该字段后所有字节至帧末尾
SegNo	3bit	段编号，仅 3~7 有效（对应 32/64/128/256/512 字节帧）
Dir	1bit	文件传输方向标识，0=A→B，1=B→A
Type	5bit	帧功能类型，用于区分文件读请求/文件数据帧/差分同步帧等
RevType	5bit	反向应答类型，与 Type 配对
RetryCnt	2bit	重传计数，0~3 循环递增
Reserved	16bit	保留字段，用于协议扩展
FileOffset	24bit	当前帧数据在文件中的起始字节偏移
FileLength	24bit	文件总长度（字节）
FileCrc32	32bit	整块传输文件的总 CRC32 校验值

一、说明

帧功能类型：0x01 读取文件名列表
示例数据：300 字节文件名列表
传输方式：使用 128 字节帧（SegNo=5）分包传输

二、分包示例

文件总长度（FileLength）：300 字节
每帧文件传输数据区长度：128 - 16 = 112 字节
分包数量：3 包

包 0：FileOffset=0，数据长度 = 112
包 1：FileOffset=112，数据长度 = 112
包 2：FileOffset=224，数据长度 = 76（结束包）

三、文件传输流程

发送端按 FileLength 拆分数据包，填充文件传输帧头各字段；
每帧携带 16 字节文件传输帧头 + 对应数据段；
（可选）通过 TxtHexEnc/TxtBase64Enc 将二进制帧数据编码为文本格式；
接收端解码回二进制，解析帧头的 FileOffset 和 FileLength；
全部接收完成后，校验 FileCrc32 确保文件完整；
服务器识别文件传输帧头特征，缓存完整文件供其他设备复用。

一、普通差异包转发规则

服务器只透明转发；
多设备连接时，广播给所有在线设备；
不解析、不存储、不修改内容。

二、文件传输包缓存规则

识别特征：包含 16 字节标准文件传输帧头（DIFF_BK_TX_FILE_HEAD）；SegNo=3~7；存在 Type、FileCrc32、FileOffset、FileLength 字段。
服务器自动缓存：接收完整文件后，本地持久化保存；索引 key：Type + FileCrc32 + FileLength。
缓存命中直接应答：其他设备请求相同文件时，服务器拦截指令，直接从本地缓存分包回复。

三、设计意义

服务器无需理解业务，仅通过 16 字节文件传输帧头即可识别缓存对象；
一次文件上传，多设备共享，避免重复传输；
普通控制指令正常转发，文件传输指令本地缓存应答，协议分层清晰。

1. 协议核心是双缓冲差异传输，仅发送变化数据，兼顾轻量与高效；

2. 补充了 TxtHexEnc/TxtBase64Enc 标准化编码函数，适配 HTTP / 文本传输场景；

3. 16 字节固定文件传输帧头（DIFF_BK_TX_FILE_HEAD）字段类型统一、长度合规，支持最大 16MB 文件传输；

4. 服务器基于 Type+FileCrc32+FileLength 做文件缓存，多设备复用缓存数据，大幅降低带宽消耗。