# GB26875解码 **Repository Path**: JavaerLi/gb26875-decoding ## Basic Information - **Project Name**: GB26875解码 - **Description**: No description available - **Primary Language**: Unknown - **License**: WTFPL - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-22 - **Last Updated**: 2026-11-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # GB26875.3-2011 IoT Gateway 城市消防远程监控系统 **GB26875.3-2011** 协议物联网关。 将消防设备(用户信息传输装置)上传的**二进制 TCP 协议**自动解码为 **JSON**,并通过 **WebSocket** 推送给业务层,让业务开发人员无需关心底层二进制协议细节,直接消费结构化数据。 ## 特性 - **协议自动解码**:完整实现 GB26875.3-2011 协议帧的编码/解码,含启动符、流水号、版本、时间戳、源/目的地址、校验和等 - **策略模式扩展**:基于 `@IotStrategy` 注解 + 工厂模式,新增业务类型解析只需写一个实现类 - **心跳自动应答**:收到心跳包自动回复 ACK,无需业务层干预 - **实时 WebSocket 推送**:解码结果通过 WebSocket 实时推送给所有订阅方,支持 clientId 负载均衡避免重复消费 - **Spring Boot 集成**:一键启动,配置化端口 - **多平台支持**:基于 Netty,支持 Linux epoll 和 macOS/Windows NIO ## 技术栈 | 组件 | 版本 | 说明 | |------|------|------| | Java | 21 | JDK 版本 | | Spring Boot | 2.7.18 | 应用框架 | | Netty | 4.2.10.Final | TCP + WebSocket 网络框架 | | Jackson | 随 Spring Boot | JSON 序列化 | | Lombok | 随 Spring Boot | 简化代码 | ## 快速开始 ### 环境要求 - JDK 21+ - Maven 3.8+ ### 编译打包 ```bash mvn clean package -DskipTests ``` ### 启动服务 ```bash java -jar target/GB26875.3-2011.jar ``` 启动后将开启两个端口: | 服务 | 默认端口 | 说明 | |------|----------|------| | IoT TCP Server | 7799 | 消防设备接入端口,接收二进制协议数据 | | WebSocket Server | 8080 | 业务层订阅端口,路径 `/ws` | ### 配置文件 修改 `application.yml` 自定义端口: ```yaml server: iot: port: 7799 # TCP 接入端口 ws: port: 8080 # WebSocket 端口 logging: file: path: ./ spring: application: name: gb26875.3-2011 ``` ## 快速上手 三步走:**启动网关 → 配置设备 → 业务接收**,即可跑通整条链路。 ### 第一步:启动网关 按上方「快速开始」编译并启动网关服务,默认监听: - **TCP 7799** ← 消防设备连这里 - **WebSocket 8080/ws** ← 业务程序连这里 ### 第二步:配置用户信息传输装置(设备端) 用户信息传输装置(以下简称"用传")是消防系统的边缘设备,负责把火灾报警控制器的运行状态上传到远程监控中心。用传统过**主动 TCP 连接**的方式把数据推到网关,需要在设备侧配置以下参数: | 配置项 | 典型值 | 说明 | |--------|--------|------| | 传输方式 | TCP | 选择主动 TCP 连接模式 | | 监控中心 IP | 网关所在机器的 IP | 例如 `192.168.1.100` | | 监控中心端口 | `7799` | 网关 IoT TCP 端口 | | 设备地址编码(用户编码) | 6 字节 | 十六进制写入,**低字节在前**。例如地址为 `0x8F 0x1F 0x00 0x00 0x00 0x01`,按 `01 00 00 00 1F 8F` 顺序写入设备配置 | | 心跳间隔 | 30~60 秒 | 设备定时发心跳,网关自动回复 ACK | | 协议版本 | 2.3 | GB26875.3-2011 默认版本号 | > ⚠️ **关于地址编码**:不同品牌的用传配置方式不同——有的有 Web 管理界面,有的需要专用上位机软件,有的通过拨码开关。但无论哪种方式,最终写入设备的 6 字节地址会以**低字节在前**的顺序出现在协议帧中,网关解码后会自动转换成标准 MAC 格式(如 `8F:1F:00:00:00:01`)推给业务层。 配置好后重启用传,它会主动向网关发起 TCP 连接。网关启动日志中看到类似这样的输出即表示设备上线成功: ``` 收到客户端IP: /192.168.1.50:54321 启动解码器... 心跳包=========== ``` ### 第三步:业务程序接收数据 业务程序通过 WebSocket 订阅网关推来的 JSON。以下是几种主流语言的示例。 #### Java(Spring Boot) 在业务项目中引入 WebSocket 客户端(使用 Java 11 内置 API 或 OkHttp): ```java import okhttp3.*; public class FireMonitorClient { public static void main(String[] args) throws Exception { OkHttpClient client = new OkHttpClient(); Request request = new Request.Builder() .url("ws://127.0.0.1:8080/ws") .addHeader("clientId", "fire-business-system-01") .build(); WebSocket webSocket = client.newWebSocket(request, new WebSocketListener() { @Override public void onOpen(WebSocket ws, Response response) { System.out.println("已连接网关"); } @Override public void onMessage(WebSocket ws, String text) { // text 就是网关推送的 JSON 字符串 // 用 Jackson/Gson 反序列化为对象后处理 System.out.println("收到: " + text); // 示例:只关心 typeFlag=1(系统状态)的报警 // JsonNode node = objectMapper.readTree(text); // int typeFlag = node.path("dataUnit").path("dataType").asInt(); // if (typeFlag == 1) { ... } } @Override public void onFailure(WebSocket ws, Throwable t, Response response) { System.err.println("连接失败: " + t.getMessage()); } }); // 保持进程存活 Thread.currentThread().join(); } } ``` OkHttp 依赖: ```xml com.squareup.okhttp3 okhttp 4.12.0 ``` #### JavaScript(Node.js) ```javascript const WebSocket = require('ws'); const ws = new WebSocket('ws://127.0.0.1:8080/ws', { headers: { clientId: 'fire-business-system-01' } }); ws.on('open', () => { console.log('已连接网关'); }); ws.on('message', (data) => { const msg = JSON.parse(data); console.log('收到设备消息:', msg.src, msg.time); // 按业务类型分发处理 switch (msg.dataUnit?.dataType) { case 1: // 系统状态 case 2: // 部件状态 case 4: // 操作信息 handleAlarm(msg); break; default: console.log('其他类型:', msg.dataUnit?.dataType); } }); ws.on('error', (err) => { console.error('WebSocket 错误:', err.message); }); ``` ws 依赖:`npm install ws` #### 浏览器前端 ```javascript const ws = new WebSocket('ws://127.0.0.1:8080/ws?clientId=web-dashboard'); ws.onmessage = (event) => { const msg = JSON.parse(event.data); console.log('设备消息:', msg); // 实时渲染到页面 }; ws.onopen = () => console.log('已连接网关'); ws.onclose = () => console.log('连接断开'); ``` > 浏览器中 WebSocket API 不支持自定义 HTTP Header,所以 `clientId` 通过 URL query 参数传递,网关的 `WebSocketParameterHandler` 会从 Header 和 URL 两种方式读取。 #### Python ```python import asyncio import json import websockets async def main(): async with websockets.connect( 'ws://127.0.0.1:8080/ws', additional_headers={'clientId': 'fire-business-system-01'} ) as ws: print('已连接网关') async for message in ws: msg = json.loads(message) print(f"[{msg['src']}] {msg['time']} type={msg.get('dataUnit', {}).get('dataType')}") asyncio.run(main()) ``` websockets 依赖:`pip install websockets` ### 收到的 JSON 长什么样 以「上传建筑消防设施系统状态」(typeFlag=1)为例,网关推来的完整 JSON 如下: ```json { "flowId": 1, "versionMajor": 2, "versionMinor": 3, "time": "2026-11-18T10:30:00", "src": "8F:1F:00:00:00:01", "dest": "00:00:00:00:06:FF", "dataLen": 12, "cmd": 3, "dataUnit": { "dataType": 1, "dataLength": 2, "list": [ { "sysType": 1, "sysAddress": 1, "sysStatus": 2, "time": "2026-11-18T10:29:55" }, { "sysType": 1, "sysAddress": 2, "sysStatus": 1, "time": "2026-11-18T10:29:56" } ] } } ``` 各 typeFlag 对应的 list 元素字段结构不同,详见上方「应用数据单元解析」章节。 ### 收到消息后怎么区分业务类型 看 `dataUnit.dataType` 字段,对照 `IotTypeFlagEnum`: | dataType | 含义 | |----------|------| | 1 | 建筑消防设施系统状态 | | 2 | 建筑消防设施部件运行状态 | | 3 | 建筑消防设施部件模拟量值 | | 4 | 建筑消防设施操作信息 | | 21 | 用户信息传输装置运行状态 | | 24 | 用户传输装置操作信息 | | … | 更多见 `IotTypeFlagEnum` | ### 多实例部署注意事项 如果业务侧多开几个 WebSocket 客户端做高可用,**务必给每个客户端配相同的 `clientId`**。网关会对同一个 `clientId` 的连接做**随机负载均衡**,每条消息只推给其中一个客户端,避免重复入库。不配 `clientId` 的连接会收到全部广播消息。 ## 工作原理 ### 数据流向 ``` ┌──────────────┐ TCP 二进制帧 ┌─────────────────────────────────────────┐ WebSocket JSON ┌──────────────┐ │ 消防设备 │ ──────────────► │ IoT TCP Server (Netty Pipeline) │ ─────────────────► │ 业务应用 │ │ (用户信息 │ │ │ │ (前端/后端) │ │ 传输装置) │ ◄────────────── │ ACK 自动回复 │ ◄──────────────── │ │ └──────────────┘ └─────────────────────────────────────────┘ └──────────────┘ ``` ### Netty Pipeline IoT TCP Server 的 Channel 处理链: ``` LoggingHandler # 打印所有事件日志 │ IotDataEncodeHandler # OUTBOUND: ACK 响应编码为二进制帧 │ IotDataDecoderHandler # INBOUND: 二进制帧解码为 DTO(识别心跳包 / 数据包) │ IotHeartbeatHandler # 心跳包 → 直接回复 ACK,不传递;数据包 → 继续传递 │ IotUserTransmissionDeviceHandler # 业务数据包解析(策略模式)+ 回复 ACK │ IotUserSmartProtocolMessageHandler # 日志打印 + WebSocket 广播推送 ``` ### 协议帧结构 GB26875.3-2011 标准帧格式(最短 30 字节): | 字段 | 长度 | 说明 | |------|------|------| | 启动符 `@@` | 2 字节 | 固定值 `0x4040` | | 业务流水号 | 2 字节 | 低字节在前 | | 协议版本号 | 2 字节 | 主版本 + 次版本 | | 时间标签 | 6 字节 | 秒/分/时/日/月/年 | | 源地址 | 6 字节 | 低字节在前 | | 目的地址 | 6 字节 | 低字节在前 | | 应用数据单元长度 | 2 字节 | 低字节在前,≤ 1024 | | 命令字节 | 1 字节 | | | 应用数据单元 | N 字节 | 变长载荷 | | 校验和 | 1 字节 | 第3~27字节 + 应用数据的算术和(取低8位)| | 结束符 `##` | 2 字节 | 固定值 `0x2323` | 心跳包识别:数据长度 < 30 字节时自动判定为心跳包,服务端立即回复心跳响应。 ### 应用数据单元解析(策略模式) 应用数据单元的第一个字节是 **类型标志(typeFlag)**,决定后续数据结构。项目采用**注解 + 工厂**的策略模式进行动态路由: 1. 每个业务类型对应一个策略实现类,标注 `@IotStrategy(value = IotTypeFlagEnum.XXX)` 2. `DefaultFactory` 在 Spring 容器启动时扫描所有策略,以 typeFlag 为 key 注册 3. 收到数据包后,根据 typeFlag 自动分发到对应策略解析 继承体系: ``` IotApplicationDataDecodeStrategy (接口) │ BaseIotApplicationDataDecodeStrategy (模板基类,处理 infoObjectAmount + 组装 IotDataUnit) │ ├── IotFireProtectionFacilitySystemStatusDecodeStrategy (typeFlag=1) ├── IotFireProtectionFacilityPartStatusDecodeStrategy (typeFlag=2) ├── IotFireProtectionFacilityPartAnalogQuantityDecodeStrategy (typeFlag=3) ├── IotFireProtectionFacilityOperationalDecodeStrategy (typeFlag=4) ├── IotFireProtectionFacilityVersionDecodeStrategy (typeFlag=5) ├── IotFireProtectionFacilitySystemConfigurationDecodeStrategy (typeFlag=6) ├── IotFireProtectionFacilityPartConfigurationDecodeStrategy (typeFlag=7) ├── IotFireProtectionFacilityTimeDecodeStrategy (typeFlag=8) ├── IotUserOperationRunStatusDecodeStrategy (typeFlag=21) ├── IotUserOperationInfoDecodeStrategy (typeFlag=24) ├── IotFireProtectionSoftWareVersionDecodeStrategy (typeFlag=25) ├── IotUserOperationConfigurationDecodeStrategy (typeFlag=26) └── IotUserOperationSystemTimeDecodeStrategy (typeFlag=28) ``` ### WebSocket 输出格式 业务层通过 WebSocket 订阅 `/ws` 端点,即可收到实时 JSON 消息。示例: ```json { "flowId": 1, "versionMajor": 2, "versionMinor": 3, "time": "2026-11-18T10:30:00", "src": "8F:1F:00:00:00:01", "dest": "00:00:00:00:06:FF", "dataLen": 12, "cmd": 3, "dataUnit": { "dataType": 1, "dataLength": 2, "list": [ { "sysType": 1, "sysAddress": 1, "sysStatus": 2, "time": "2026-11-18T10:29:55" }, { "sysType": 1, "sysAddress": 2, "sysStatus": 1, "time": "2026-11-18T10:29:56" } ] } } ``` 字段说明: | 字段 | 类型 | 说明 | |------|------|------| | flowId | Integer | 业务流水号 | | versionMajor | Integer | 主协议版本号 | | versionMinor | Integer | 次协议版本号 | | time | LocalDateTime | 数据包携带的时间标签 | | src | String | 源设备地址(MAC 格式)| | dest | String | 目的地址(MAC 格式)| | dataLen | Integer | 应用数据单元长度 | | cmd | Integer | 命令字节 | | dataUnit.dataType | Integer | 业务类型标志(typeFlag)| | dataUnit.dataLength | Integer | 数据对象条数 | | dataUnit.list | Array | 具体业务数据列表(结构依 typeFlag 而定)| WebSocket 支持的控制消息: | 消息 | 响应 | 说明 | |------|------|------| | `ping` | `pong` | 心跳检测 | | `ls` | JSON | 查看当前在线客户端列表 | | `send:\nxxx` | — | 向所有连接广播测试消息 | ### clientId 负载均衡 WebSocket 客户端连接时可在 HTTP Header 中携带 `clientId` 字段。相同 `clientId` 的多个连接会**随机选择一个**推送消息,避免同一业务系统重复消费。不携带 `clientId` 的连接则接收全部广播消息。 ## 扩展新的业务类型 假设要新增 typeFlag=100 的业务类型: **第一步**:在 `IotTypeFlagEnum` 中新增枚举值: ```java IOT_NEW_TYPE(100, "上传新业务数据") ``` **第二步**:创建数据单元 POJO,实现 `IotDataUnitInfo` 接口: ```java @Data public class IotDataUnitInfo100 implements IotDataUnitInfo { private Integer field1; private String field2; } ``` **第三步**:创建策略实现类: ```java @IotStrategy(value = IotTypeFlagEnum.IOT_NEW_TYPE) @Component public class IotNewTypeDecodeStrategy extends BaseIotApplicationDataDecodeStrategy { @Override protected List applicationDataDecode(ByteBuffer buffer) { int count = getInfoObjectAmount(); List list = new ArrayList<>(count); for (int i = 0; i < count; i++) { IotDataUnitInfo100 info = new IotDataUnitInfo100(); info.setField1(Byte.toUnsignedInt(buffer.get())); // ... 按协议规范解析更多字段 list.add(info); } return list; } } ``` **完成!** 新策略会在 Spring 启动时自动注册到工厂,收到 typeFlag=100 的数据包时自动调用。 ## 项目结构 ``` src/main/java/org/gb26875/ ├── Application.java # Spring Boot 启动类 └── iot/ ├── annotation/ │ └── IotStrategy.java # 策略注解(标记业务类型与策略的映射) ├── enums/ │ └── IotTypeFlagEnum.java # 业务类型枚举(typeFlag 定义) ├── factory/ │ └── DefaultFactory.java # 策略工厂(启动时自动注册所有策略) ├── netty/ │ ├── IotServer.java # TCP 物联网关服务 │ ├── WebSocketServer.java # WebSocket 服务 │ ├── IotUserSmartIotProtocol.java # 协议帧模型(用于编码/回复) │ ├── IotUserSmartIotProtocolDTO.java # 协议帧 DTO(Builder 模式,用于解码中间态) │ └── handlers/ │ ├── IotServerInitializer.java # TCP Pipeline 初始化 │ ├── IotDataEncodeHandler.java # OUTBOUND 协议帧编码 │ ├── IotDataDecoderHandler.java # INBOUND 协议帧解码 │ ├── IotHeartbeatHandler.java # 心跳包自动应答 │ ├── IotGBT268753AgreementSupportHandler.java # 解码基类(ACK 组装 + 校验和计算 + 策略路由) │ ├── IotUserTransmissionDeviceHandler.java # 业务数据包处理 │ ├── IotUserSmartProtocolMessageHandler.java # 日志 + WebSocket 广播 │ ├── WebSocketServerInitializer.java # WebSocket Pipeline 初始化 │ ├── WebSocketParameterHandler.java # clientId 解析 + Ping/Pong │ └── WebSocketServerHandler.java # WebSocket 消息处理 ├── strategy/ │ ├── IotApplicationDataDecodeStrategy.java # 策略接口 │ ├── BaseIotApplicationDataDecodeStrategy.java # 模板方法基类 │ ├── impl/ # 13 个策略实现类 │ └── properties/ # 数据单元 POJO(IotDataUnitInfo1 ~ IotDataUnitInfo28) └── utils/ ├── BytesUtils.java # 字节/MAC地址/时间/编码转换 ├── DateUtils.java # 当前时间获取 ├── JsonUtils.java # JSON 序列化 ├── SpringUtil.java # Bean 获取 └── WebSocketUtils.java # WebSocket ChannelGroup 管理与广播 ``` ## 协议文档 `doc/` 目录下包含《城市消防远程监控系统协议_拓展版_V1.53-20230608.pdf》供参考。 ## 许可证 本项目基于 **Apache License 2.0** 开源。见 [LICENSE](./LICENSE) 文件。 ## 致谢 - 参考了 GB/T 26875.3-2011《城市消防远程监控系统 第3部分:报警传输网络通信协议》标准 - 使用 Netty 实现高性能网络通信框架