当前位置：首页 > news >正文

Splitflap串行通信协议详解：从文本模式到Protobuf二进制协议

news 2026/8/25 15:56:19

Splitflap串行通信协议详解：从文本模式到Protobuf二进制协议

【免费下载链接】splitflapDIY split-flap display项目地址: https://gitcode.com/gh_mirrors/sp/splitflap

Splitflap串行通信协议是DIY翻页显示器（split-flap display）控制系统的核心，它定义了微控制器与上位机之间的通信规范。本文将深入解析splitflap通信协议从简单的文本模式到高效的Protobuf二进制协议的演进历程，帮助您全面掌握splitflap显示器的通信机制。

📡 什么是Splitflap串行通信协议？

Splitflap串行通信协议是一套用于控制翻页显示器的通信规范，它允许上位机（如PC、树莓派或手机应用）通过串口向splitflap控制器发送指令，控制每个模块显示特定字符，并实时获取模块状态信息。协议支持两种模式：传统文本模式和现代Protobuf二进制模式。

📝 传统文本模式协议

传统文本模式协议设计简洁，基于ASCII字符进行通信，易于手动调试和快速原型开发。该协议实现位于firmware/esp32/splitflap/serial_legacy_json_protocol.cpp。

核心命令格式

字符显示命令：直接发送ASCII字符序列，以换行符结束
```
HELLO\n
```
这将控制模块依次显示"H"、"E"、"L"、"L"、"O"
特殊控制字符：
- @：重置所有模块
- #：无操作（用于心跳检测）
- %：切换传感器测试模式
- +：复制第一个字符到所有模块
- >/<：调整偏移量

状态响应格式

控制器以JSON格式返回状态信息：

{ "type": "status", "modules": [ { "state": "normal", "flap": "H", "count_missed_home": 0, "count_unexpected_home": 0 } ] }

文本模式的优缺点

优点：

简单直观，易于调试
无需特殊库，直接使用串口工具即可控制
响应格式为JSON，易于解析

缺点：

带宽利用率低
不支持高级功能（如批量配置）
错误处理能力有限

🔧 Protobuf二进制协议

为了克服文本模式的限制，splitflap项目引入了基于Google Protobuf的二进制协议，提供更高效、更强大的通信能力。协议定义位于proto/splitflap.proto。

协议架构设计

Protobuf协议采用双向通信架构，包含两个主要消息类型：

ToSplitflap：上位机→控制器的命令
FromSplitflap：控制器→上位机的状态反馈

核心消息类型详解

1. 状态查询与反馈

message SplitflapState { message ModuleState { enum State { NORMAL = 0; LOOK_FOR_HOME = 1; SENSOR_ERROR = 2; PANIC = 3; STATE_DISABLED = 4; } State state = 1; uint32 flap_index = 2; bool moving = 3; bool home_state = 4; } repeated ModuleState modules = 1; }

2. 控制命令

message SplitflapCommand { message ModuleCommand { enum Action { NO_OP = 0; GO_TO_FLAP = 1; RESET_AND_HOME = 2; INCREASE_OFFSET_TENTH = 90; INCREASE_OFFSET_HALF = 91; SET_OFFSET = 92; } Action action = 1; uint32 param = 2; } repeated ModuleCommand modules = 2; bool save_all_offsets = 3; }

3. 配置管理

message SplitflapConfig { message ModuleConfig { uint32 target_flap_index = 1; uint32 movement_nonce = 2; uint32 reset_nonce = 3; } repeated ModuleConfig modules = 1; }

通信流程与数据封装

Protobuf协议采用三层封装确保通信可靠性：

Protobuf编码层：使用nanopb库进行高效二进制编码
CRC32校验层：添加4字节CRC32校验码，确保数据完整性
COBS封装层：使用Consistent Overhead Byte Stuffing避免数据包冲突

具体实现位于firmware/esp32/splitflap/serial_proto_protocol.cpp，关键处理流程包括：

数据包接收与CRC校验
Protobuf解码与命令分发
状态监控与周期性报告
非重复性命令处理（基于nonce机制）

Protobuf协议的优势

高效性：

二进制编码，数据量减少60-80%
支持批量操作，减少通信次数
内置CRC校验，数据传输更可靠

扩展性：

支持模块化配置管理
提供详细的错误状态信息
可轻松添加新功能字段

可靠性：

非重复性命令处理（nonce机制）
自动重传与确认机制
实时状态监控与故障报告

🔄 协议切换与兼容性

Splitflap系统支持动态协议切换，确保向后兼容：

自动检测：控制器启动时发送初始化消息
协议切换：发送0x00字节切换到Protobuf模式
双模式运行：同时支持文本和二进制协议

协议切换代码示例

// 在serial_legacy_json_protocol.cpp中 if (b == 0) { // 收到0x00字节 if (protocol_change_callback_) { protocol_change_callback_(SERIAL_PROTOCOL_PROTO); } break; }

🛠️ 实际应用指南

1. 快速开始：文本模式

# 使用Python控制splitflap import serial ser = serial.Serial('/dev/ttyUSB0', 115200) ser.write(b'HELLO\n') # 显示"HELLO"

2. 高级应用：Protobuf模式

# 使用splitflap_proto库 from splitflap_proto import SplitflapProto proto = SplitflapProto('/dev/ttyUSB0') proto.send_command(['H', 'E', 'L', 'L', 'O']) state = proto.get_state() # 获取详细状态信息

3. 状态监控与故障处理

实时监控每个模块的state字段
检测count_missed_home和count_unexpected_home计数器
根据错误类型采取相应恢复策略

📊 性能对比分析

特性	文本模式	Protobuf模式
数据大小	较大（JSON文本）	较小（二进制）
带宽效率	低	高
功能支持	基础控制	高级配置
错误处理	有限	完善
开发复杂度	简单	中等
向后兼容	是	是