1
This commit is contained in:
zj
295
README.md
Normal file
295
README.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# 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`）。
|
||||
Reference in New Issue
Block a user