# 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 实现高性能网络通信框架