296 lines
7.5 KiB
Markdown
296 lines
7.5 KiB
Markdown
# UPC Resent - 自动化控制设备指令转发系统
|
||
|
||
基于配置驱动的代码生成系统，支持 TCP 和 UDP 协议，监听端口接收外部指令，转换为 Modbus TCP/UDP 协议发送到控制设备（继电器/PLC等）。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
upc_resent/
|
||
├── config/
|
||
│ └── devices.json # 设备配置文件（唯一需要修改的文件）
|
||
├── templates/ # 代码模板目录
|
||
│ ├── listener_tcp.py.tpl # TCP监听服务模板
|
||
│ ├── listener_udp.py.tpl # UDP监听服务模板
|
||
│ ├── crond_tcp.py.tpl # TCP保活检查模板
|
||
│ ├── crond_udp.py.tpl # UDP保活检查模板
|
||
│ ├── sender_tcp.py.tpl # TCP发送模块模板
|
||
│ └── sender_udp.py.tpl # UDP发送模块模板
|
||
├── scripts/
|
||
│ └── generate.py # 代码生成器
|
||
├── bin/ # 生成的监听服务文件（自动生成）
|
||
│ ├── sender_tcp.py # TCP发送模块
|
||
│ ├── sender_udp.py # UDP发送模块
|
||
│ └── {device_id}.py # 各设备监听服务
|
||
├── crond/ # 生成的保活检查文件（自动生成）
|
||
├── log/ # 日志目录
|
||
├── start.sh # 启动脚本（自动生成）
|
||
├── crontab.txt # 定时任务配置（自动生成）
|
||
└── cutlog.sh # 日志清理脚本
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 配置设备
|
||
|
||
编辑 `config/devices.json`：
|
||
|
||
```json
|
||
{
|
||
"global": {
|
||
"tms_server_ip": "192.168.8.9",
|
||
"python_path": "/usr/bin/python3",
|
||
"base_dir": "/opt/upc_resent"
|
||
},
|
||
"devices": [
|
||
{
|
||
"id": "dev1",
|
||
"name": "设备1-TCP",
|
||
"protocol": "tcp", // 协议类型: tcp 或 udp
|
||
"upc_ip": "192.168.8.73",
|
||
"upc_port": 502,
|
||
"listen_port": 10079,
|
||
"enabled": true
|
||
},
|
||
{
|
||
"id": "dev2",
|
||
"name": "设备2-UDP",
|
||
"protocol": "udp", // 使用UDP协议
|
||
"upc_ip": "192.168.8.200",
|
||
"upc_port": 502,
|
||
"listen_port": 10080,
|
||
"enabled": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 生成代码
|
||
|
||
```bash
|
||
# 检查配置是否正确
|
||
python3 scripts/generate.py --check
|
||
|
||
# 生成代码
|
||
python3 scripts/generate.py
|
||
```
|
||
|
||
### 3. 部署与启动
|
||
|
||
```bash
|
||
# 启动所有服务
|
||
./start.sh
|
||
|
||
# 配置定时任务（保活）
|
||
crontab crontab.txt
|
||
```
|
||
|
||
## 配置文件详解
|
||
|
||
### `config/devices.json`
|
||
|
||
#### 全局配置 (global)
|
||
|
||
| 参数 | 说明 | 示例 |
|
||
|-----|------|-----|
|
||
| `tms_server_ip` | 本机监听IP，接收外部指令 | `"192.168.8.9"` |
|
||
| `python_path` | Python3 解释器路径 | `"/usr/bin/python3"` |
|
||
| `base_dir` | 项目部署路径 | `"/opt/upc_resent"` |
|
||
|
||
#### 设备配置 (devices)
|
||
|
||
| 参数 | 说明 | 示例 |
|
||
|-----|------|-----|
|
||
| `id` | 设备唯一标识（用于文件名） | `"dev1"` |
|
||
| `name` | 设备名称（用于日志显示） | `"设备1-TCP"` |
|
||
| `protocol` | 协议类型：`tcp` 或 `udp` | `"tcp"` / `"udp"` |
|
||
| `upc_ip` | 控制设备的IP地址 | `"192.168.8.73"` |
|
||
| `upc_port` | 控制设备的端口（Modbus默认502） | `502` |
|
||
| `listen_port` | 本机监听端口（每个设备需不同） | `10079` |
|
||
| `enabled` | 是否启用该设备 | `true` / `false` |
|
||
|
||
#### 指令定义 (commands)
|
||
|
||
```json
|
||
{
|
||
"commands": {
|
||
"open1": "000100000008010F006400010001",
|
||
"close1": "000100000008010F006400010000",
|
||
"openall4": "000100000008010F00640004000F",
|
||
"closeall4": "000100000008010F006400040000"
|
||
}
|
||
}
|
||
```
|
||
|
||
格式：指令名 -> 16进制字符串
|
||
|
||
#### 指令映射 (mappings)
|
||
|
||
```json
|
||
{
|
||
"mappings": {
|
||
"open": "openall4",
|
||
"close": "closeall4",
|
||
"guanggao-guan": "closeall4"
|
||
}
|
||
}
|
||
```
|
||
|
||
## TCP vs UDP 差异
|
||
|
||
| 特性 | TCP | UDP |
|
||
|-----|-----|-----|
|
||
| 连接方式 | 面向连接 | 无连接 |
|
||
| 可靠性 | 可靠传输 | 尽力传输 |
|
||
| 响应 | 有确认响应 | 可选响应（可能超时） |
|
||
| 适用场景 | 可靠性要求高 | 实时性要求高 |
|
||
| 保活检查 | 端口连通性检查 | 进程状态检查 |
|
||
|
||
## 如何适配自己的设备
|
||
|
||
### 场景1：添加 TCP 设备
|
||
|
||
```json
|
||
{
|
||
"devices": [
|
||
{
|
||
"id": "dev_tcp",
|
||
"name": "TCP设备",
|
||
"protocol": "tcp",
|
||
"upc_ip": "192.168.1.100",
|
||
"upc_port": 502,
|
||
"listen_port": 10081,
|
||
"enabled": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 场景2：添加 UDP 设备
|
||
|
||
```json
|
||
{
|
||
"devices": [
|
||
{
|
||
"id": "dev_udp",
|
||
"name": "UDP设备",
|
||
"protocol": "udp",
|
||
"upc_ip": "192.168.1.200",
|
||
"upc_port": 502,
|
||
"listen_port": 10082,
|
||
"enabled": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 场景3：添加新的控制指令
|
||
|
||
```json
|
||
{
|
||
"commands": {
|
||
"open9": "000100000008010F006C00010001",
|
||
"close9": "000100000008010F006C00010000"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 场景4：禁用某个设备
|
||
|
||
```json
|
||
{
|
||
"devices": [
|
||
{
|
||
"id": "dev2",
|
||
"enabled": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 测试指令发送
|
||
|
||
### TCP 设备测试
|
||
|
||
```bash
|
||
# 向TCP设备发送开灯指令
|
||
echo "open1" | nc 192.168.8.9 10079
|
||
|
||
# 向TCP设备发送全关指令
|
||
echo "close" | nc 192.168.8.9 10079
|
||
```
|
||
|
||
### UDP 设备测试
|
||
|
||
```bash
|
||
# 向UDP设备发送开灯指令
|
||
echo "open1" | nc -u 192.168.8.9 10080
|
||
|
||
# 向UDP设备发送全关指令
|
||
echo "close" | nc -u 192.168.8.9 10080
|
||
|
||
# 使用 socat 测试 UDP
|
||
echo "open1" | socat - UDP:192.168.8.9:10080
|
||
```
|
||
|
||
## 支持的指令列表
|
||
|
||
| 外部指令 | 内部指令 | 功能 |
|
||
|---------|---------|------|
|
||
| `open` | `openall4` | 1-4路全开 |
|
||
| `close` | `closeall4` | 1-4路全关 |
|
||
| `open1`~`open8` | `open1`~`open8` | 第N路开 |
|
||
| `close1`~`close8` | `close1`~`close8` | 第N路关 |
|
||
| `guanggao-guan` | `closeall4` | 广告关闭（全关） |
|
||
|
||
## Modbus 指令格式
|
||
|
||
本项目支持 Modbus TCP/UDP 协议，指令为16进制字符串：
|
||
|
||
```
|
||
示例：000100000008010F006400010001
|
||
│ │ │ │ │ │ │ │ │ │ │
|
||
│ │ │ │ │ │ │ │ │ │ └── 数据值 (01=开, 00=关)
|
||
│ │ │ │ │ │ │ │ │ └──── 寄存器数量
|
||
│ │ │ │ │ │ │ │ └─────── 起始地址 (64=100)
|
||
│ │ │ │ │ │ │ └────────── 功能码 (0F=写多个线圈)
|
||
│ │ │ │ │ │ └──────────── 单元标识
|
||
│ │ │ │ └───────────────── 协议标识
|
||
│ │ │ └─────────────────── 长度
|
||
│ └─────────────────────── 事务标识
|
||
└────────────────────────── 事务标识
|
||
```
|
||
|
||
## 代码生成器用法
|
||
|
||
```bash
|
||
# 检查配置是否正确
|
||
python3 scripts/generate.py --check
|
||
|
||
# 生成代码
|
||
python3 scripts/generate.py
|
||
|
||
# 查看帮助
|
||
python3 scripts/generate.py --help
|
||
```
|
||
|
||
## 日志文件
|
||
|
||
| 文件 | 说明 |
|
||
|-----|------|
|
||
| `log/{device_id}.log` | 设备监听服务的日志 |
|
||
| `log/crond-{device_id}.log` | 保活检查的日志 |
|
||
|
||
日志自动轮转：每天清理7天前的日志。
|
||
|
||
## 注意事项
|
||
|
||
1. **不要直接修改** `bin/` 和 `crond/` 下的文件，这些文件是自动生成的，重新生成时会覆盖。
|
||
|
||
2. **修改配置后必须重新运行** `python3 scripts/generate.py` 才能生效。
|
||
|
||
3. 确保每个设备的 `listen_port` 不冲突，无论 TCP 还是 UDP，端口都不能重复。
|
||
|
||
4. UDP 是无连接协议，设备可能不会返回响应，这是正常现象。
|
||
|
||
5. 部署到生产环境前，请将 `base_dir` 修改为实际的部署路径（如 `/opt/upc_resent`）。
|