# protocol-tutorials

**Repository Path**: deeprado/protocol-tutorials

## Basic Information

- **Project Name**: protocol-tutorials
- **Description**: protocol-tutorials
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Protocol Tutorials

工业物联网协议接入教程与统一连接器集合。提供 **21 种工业协议** 的统一抽象层，通过 `ProtocolConnector` 接口屏蔽底层协议差异，支持 Modbus、OPC-UA、MQTT、EtherNet/IP、S7、IEC104、DNP3、CAN 等主流协议。

## 项目结构

```
protocol-tutorials/
├── protocol-common/         核心抽象层（统一接口、注册中心、22个适配器）
├── protocol-modbus/         Modbus TCP/RTU 标准教程
├── protocol-opcua/          OPC-UA 客户端教程
├── protocol-opcua-spring/   OPC-UA + Spring Boot 集成
├── protocol-mqtt/           MQTT 发布/订阅教程
├── protocol-can/            CAN 虚拟网关（CanFrame 10字节帧格式）
├── protocol-mbus/           M-Bus 仪表通信教程
├── protocol-heat/           热力仪表协议（IEC104/CJ-T188/CDT/DL-T645）
├── protocol-plc/            PLC 协议（S7/MC/FINS/HostLink/FP7）
└── protocal-coap/           CoAP 受限应用协议教程
```

## 快速开始（统一连接器）

核心模块 `protocol-common` 提供 **协议名称+版本** 维度的统一对接能力：

```java
// 1. 启动注册
ProtocolBoot.init();

// 2. 构造设备配置
DeviceConfig config = new DeviceConfig()
    .setProtocol(ProtocolType.MODBUS_TCP)
    .setHost("192.168.1.100")
    .setPort(502)
    .setSlaveId(1);

// 3. 创建并连接
ProtocolConnector conn = ProtocolRegistry.create(config);
conn.connect();

// 4. 读写点位
PointKey temp = new PointKey("温度", "0", DataType.FLOAT).setFunction(0);
DataValue val = conn.read(temp);          // 保持寄存器，offset=0
conn.write(temp, 25.5f);                  // 写入

// 5. 关闭
conn.close();
```

## 已支持协议（21 种）

| 类别 | 协议 | 标识 | 传输层 | 连接器 | 依赖库 |
|---|---|---|---|---|---|
| **Modbus** | Modbus TCP | `Modbus/TCP` | TCP | `ModbusTcpConnector` | digitalpetri |
| | Modbus RTU | `Modbus/RTU` | 串口 | `ModbusRtuConnector` | jSerialComm |
| | Modbus RTU-over-TCP | `Modbus/RTU-over-TCP` | TCP | `ModbusRtuOverTcpConnector` | jSerialComm |
| | Modbus UDP | `Modbus/UDP` | UDP | `ModbusUdpConnector` | 纯Java |
| **物联网** | MQTT 3.1.1 | `MQTT/3.1.1` | TCP | `MqttConnector` | Paho v3 |
| | MQTT 5.0 | `MQTT/5.0` | TCP | `Mqtt5Connector` | Paho v5 |
| | CoAP | `CoAP/RFC7252` | UDP | `CoapConnector` | Californium |
| **自动化** | OPC-UA | `OPC-UA/1.0` | TCP | `OpcUaConnector` | Milo 0.6.10 |
| | EtherNet/IP | `EtherNet/IP/1.0` | TCP | `EtherNetIpConnector` | enip |
| | CAN 2.0 | `CAN/2.0` | TCP | `CanTcpConnector` | 纯Java (CanFrame) |
| **工业PLC** | Siemens S7 | `S7/S7comm` | TCP | `S7Connector` | iot-communication |
| | 三菱 MC | `PLC/MC` | TCP | `PlcMcConnector` | iot-communication |
| | Omron FINS | `PLC/FINS` | UDP | `FinsConnector` | 纯Java |
| | Omron HostLink | `PLC/HostLink` | 串口 | `HostLinkConnector` | jSerialComm |
| | Panasonic FP7 | `PLC/FP7` | 串口 | `Fp7Connector` | jSerialComm |
| **电力** | IEC 60870-5-104 | `IEC104/60870-5-104` | TCP | `Iec104Connector` | j60870 |
| | DNP3 | `DNP3/3.0` | TCP | `Dnp3Connector` | stepfunc + joou |
| **仪表** | DL/T645-2007 | `DL/T645/2007` | 串口 | `Dlt645Connector` | jSerialComm |
| | M-Bus | `M-Bus/3.0` | 串口 | `MBusConnector` | jSerialComm |
| | CJ/T188-2004 | `CJ/T188/2004` | 串口 | `Cjt188Connector` | jSerialComm |
| | CDT-II | `CDT/II` | 串口 | `CdtConnector` | jSerialComm |

## 核心接口

### ProtocolConnector

```java
public interface ProtocolConnector {
    void connect() throws Exception;
    void close();
    boolean isConnected();
    DataValue read(PointKey point) throws Exception;
    DataValue[] read(PointKey[] points) throws Exception;
    boolean write(PointKey point, Object value) throws Exception;
    DeviceConfig getConfig();
}
```

### 关键模型

| 类 | 说明 |
|---|---|
| `ProtocolType` | 协议枚举，`name + "/" + version` 唯一标识（如 `Modbus/TCP`） |
| `DeviceConfig` | 设备配置：host/port、串口参数、从站地址、认证信息、扩展参数 |
| `PointKey` | 点位定义：`protocolAddress`（协议地址）、`dataType`、`function`（功能码/区域） |
| `DataValue` | 采集结果：`value` + `dataType` + `quality` + `timestamp`，提供 `good()`/`bad()` 工厂方法 |
| `DataType` | 数据类型：BOOL/BYTE/UINT16/INT16/UINT32/INT32/FLOAT/DOUBLE/STRING/BYTES/RAW |

### PointKey.function 约定

`function` 字段语义由各适配器自行解释，常见约定：

- **Modbus**: 0=保持寄存器(FC03), 1=输入寄存器(FC04), 2=线圈(FC01), 3=离散输入(FC02)
- **S7**: 0=DB区, 1=M区, 2=I区, 3=Q区
- **DL/T645**: 功能码 (0x11读数据, 0x14写数据)
- **其他协议**: 可用于区分读写区或数据类型

## 体系架构

```
┌─────────────────────────────────────────┐
│           业务层 / 上层应用               │
├─────────────────────────────────────────┤
│         ProtocolRegistry（注册中心）       │
├─────────────────────────────────────────┤
│         ProtocolBoot（初始化引导）         │
├──────────┬──────────────┬───┬───────────┤
│ ModbusTcp│ MqttConnector│...│Fp7Connector│
│ Connector│              │   │            │
├──────────┴──────────────┴───┴───────────┤
│         AbstractConnector（公共基类）       │
│  - connect/read/write/isConnected/close  │
│  - scale(raw, decimal) 数值换算           │
├──────────┬───────────────────────────────┤
│  串口通道  │ SerialChannel (jSerialComm)  │
│  Modbus解 │ ModbusFrameUtil/ValueUtil    │
│  DL/T645解│ Dlt645FrameUtil               │
└──────────┴───────────────────────────────┘
```

## 新增协议适配器

所有适配器遵循 `AbstractConnector` 模板，实现步骤：

1. 在 `ProtocolType` 枚举添加新条目
2. 创建 `public class XxxConnector extends AbstractConnector`
3. 实现 `connect()` / `read(PointKey)` / `write(PointKey, Object)` / `isConnected()` / `close()`
4. 在 `ProtocolBoot.init()` 注册 `ProtocolRegistry.register(ProtocolType.XXX, XxxConnector::new)`
5. 如需外部库，在 `protocol-common/pom.xml` 添加依赖

## 构建与运行

```bash
# 编译核心模块（离线模式）
mvn -o -pl protocol-common compile

# 编译全量模块
mvn -o compile

# 运行演示
mvn -o -pl protocol-common exec:java -Dexec.mainClass="com.deep.protocol.ProtocolRegistryDemo"
```

**环境要求**: JDK 17+, Maven 3.9+

## 模块说明

| 模块 | 说明 |
|---|---|
| `protocol-common` | **核心层**：统一连接器接口、22个适配器、协议注册中心、数据模型、工具类 |
| `protocol-modbus` | Modbus TCP/RTU 标准教程与抓包示例 |
| `protocol-opcua` | OPC-UA 客户端、Keystore 配置、订阅示例 |
| `protocol-opcua-spring` | OPC-UA 与 Spring Boot/Actuator 集成 |
| `protocol-mqtt` | MQTT 发布订阅、QoS 演示、遗嘱消息 |
| `protocol-can` | 虚拟 CAN 网关 (TCP 127.0.0.1:8888)、CanFrame 编解码 |
| `protocol-mbus` | M-Bus 电表通信、帧解析 |
| `protocol-heat` | 热力行业：IEC104/CJ-T188/CDT/DL-T645 客户端演示 |
| `protocol-plc` | 工业 PLC：S7 连接器示例与调试工具 |
| `protocal-coap` | CoAP RFC7252 客户端/服务器交互 |

## 内置模拟器

每个协议适配器均有对应的模拟器/服务器，可直接启动进行联调测试，无需真实硬件设备。

### 纯 Java 模拟器（`protocol-common/simulator/`）

| 模拟器类 | 对应适配器 | 默认端口 | 传输 | 启动命令 |
|---|---|---|---|---|
| `ModbusTcpSimulator` | `ModbusTcpConnector` | 502 | TCP | `java ...simulator.ModbusTcpSimulator` |
| `ModbusUdpSimulator` | `ModbusUdpConnector` | 502 | UDP | `java ...simulator.ModbusUdpSimulator` |
| `FinsSimulator` | `FinsConnector` | 9600 | UDP | `java ...simulator.FinsSimulator` |
| `HostLinkSimulator` | `HostLinkConnector` | 9600 | TCP | `java ...simulator.HostLinkSimulator` |
| `Fp7Simulator` | `Fp7Connector` | 9600 | TCP | `java ...simulator.Fp7Simulator` |
| `S7RawSimulator` | `S7Connector` | 102 | TCP | `java ...simulator.S7RawSimulator` |
| `McRawSimulator` | `PlcMcConnector` | 5000 | TCP | `java ...simulator.McRawSimulator` |
| `EtherNetIpSimulator` | `EtherNetIpConnector` | 44818 | TCP | `java ...simulator.EtherNetIpSimulator` |
| `Dnp3TcpSimulator` | `Dnp3Connector` | 20000 | TCP | `java ...simulator.Dnp3TcpSimulator` |

### 统一启动器

```bash
# 启动指定模拟器
java com.deep.protocol.simulator.SimulatorLauncher modbus-tcp 502

# 列出所有模拟器
java com.deep.protocol.simulator.SimulatorLauncher list

# 一键启动所有纯Java模拟器
java com.deep.protocol.simulator.SimulatorLauncher all
```

### 各模块已有服务端/模拟器

| 协议 | 服务端类 | 模块 | 端口 | 说明 |
|---|---|---|---|---|
| **CAN** | `VirtualCanServer` | protocol-can | 8888 | TCP 虚拟 CAN 网关，周期性广播温压阀数据 |
| **CAN** | `CarCanGatewayServer` | protocol-can | 8888 | 整车 CAN 网关（引擎/轮胎/灯光/空调） |
| **MQTT 3.1.1** | `NettyMqttServer` | protocol-mqtt | 1883 | 自建 MQTT Broker（CONNECT/SUBSCRIBE/PUBLISH/PING） |
| **OPC-UA** | `OpcUaSimulatorServer` | protocol-opcua | 12680 | 模拟温度/压力/状态/运行/编码标签 |
| **OPC-UA** | `OpcUaServerDemo` | protocol-opcua | 4840 | 带 Subscription 的 OPC-UA 演示服务 |
| **IEC104** | `Iec104ServerDemo` | protocol-heat | 2404 | 周期性发送遥测遥信（IOA 1~7） |
| **CoAP** | `CoapSensorServer` | protocal-coap | 5683 | 温湿度/电池传感器服务 |
| **CoAP** | `CoapAllSensorServer` | protocal-coap | 5683 | 22 传感器综合模拟（CON/NON） |
| **DL/T645** | `DLT645MeterSim` | protocol-heat | COM2 | 电表模拟（总电量/电压/电流应答） |
| **CJ/T188** | `CJT188Simulator` | protocol-heat | COM5 | 热力表模拟（供回温/流量/热量） |
| **CDT** | `CdtSimulator` | protocol-heat | COM5 | 电力远动模拟（电压/电流/功率） |
| **M-Bus** | `MBusSlaveSimulator2` | protocol-mbus | COM2 | M-Bus 从站（水表数据） |

### 调试示例

以 Modbus TCP 为例，同时启动模拟器和连接器进行联调：

```bash
# 终端1：启动Modbus TCP模拟从站
java com.deep.protocol.simulator.SimulatorLauncher modbus-tcp

# 终端2：运行连接器Demo
java com.deep.protocol.ModbusTcpDemo
```

连接器端读取保持寄存器 offset=0 获得模拟值 0（10*0），offset=1 获得 10（10*1），写入后同步更新。