readme

.gitignore

@@ -174,3 +174,5 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 
+.idea/
+.vscode/

README.md

@@ -1,2 +1,41 @@
-# relay
+# 通信中继器
 
+## 概述
+
+用于辅助猪场主控和场内各子系统通讯
+
+## 详细描述
+
+### 与猪场主控通信
+
+WebSocket协议
+
+### 与场内子系统通信
+
+#### 物理层
+
+LoRa：低功耗广域网物理层技术，提供远距离无线传输能力
+
+#### 数据链路层和网络层
+
+LoRaWAN：基于LoRa物理层的广域网协议，提供设备认证、加密和网络管理
+
+#### 传输层
+
+CoAP：受限应用协议，轻量级的RESTful协议，适用于资源受限设备
+
+#### 应用层
+
+LwM2M：轻量级机器到机器协议，提供设备管理、固件更新等功能
+
+#### 数据格式
+
+SenML：传感器标记语言，标准化的传感器数据表示格式
+
+#### 协议栈选择优势：
+
+* 低功耗：适合电池供电或节能要求高的场景
+* 远距离传输：LoRa技术可实现数公里覆盖
+* 标准化：采用业界标准协议，便于系统集成和扩展
+* 安全性：LoRaWAN和CoAP均提供安全机制
+* 互操作性：基于标准协议，便于与不同厂商设备集成

RELAY_API.md

@@ -0,0 +1,271 @@
+# 中继程序接口定义
+
+本文档定义了猪场控制器系统主动向中继程序发送请求时使用的接口规范。
+
+## 1. 概述
+
+中继程序作为猪场控制器系统与现场设备之间的桥梁，负责接收来自控制器系统的指令并转发给相应的设备，同时将设备的响应和状态信息回传给控制器系统。
+
+通信方式采用WebSocket协议，确保双向实时通信。
+
+## 2. WebSocket连接
+
+### 2.1 连接建立
+
+设备通过WebSocket连接到平台，连接地址格式：
+```
+ws://[server_address]:[port]/ws/device?device_id=[device_id]
+```
+
+参数说明：
+- `device_id`: 中继设备唯一标识符
+
+### 2.2 心跳机制
+
+为保持连接活跃状态，中继设备需要定期发送心跳消息：
+
+**心跳请求**
+```json
+{
+  "type": "heartbeat",
+  "device_id": "relay-001",
+  "timestamp": "2023-01-01T12:00:00Z"
+}
+```
+
+## 3. 指令接口
+
+### 3.1 设备控制指令
+
+平台向中继设备发送设备控制指令。
+
+**请求格式**
+```json
+{
+  "type": "command",
+  "command": "control_device",
+  "data": {
+    "device_type": "fan",
+    "device_id": "fan-001",
+    "action": "on"
+  },
+  "timestamp": "2023-01-01T12:00:00Z"
+}
+```
+
+**参数说明**
+- `type`: 消息类型，固定为"command"
+- `command`: 指令名称，固定为"control_device"
+- `data`: 指令数据
+  - `device_type`: 设备类型 (如: fan, water_curtain)
+  - `device_id`: 设备唯一标识符
+  - `action`: 执行动作 (如: on, off)
+- `timestamp`: 指令发送时间
+
+### 3.2 查询设备状态指令
+
+平台向中继设备发送查询设备状态指令。
+
+**请求格式**
+```json
+{
+  "type": "command",
+  "command": "query_device_status",
+  "data": {
+    "device_id": "fan-001"
+  },
+  "timestamp": "2023-01-01T12:00:00Z"
+}
+```
+
+**参数说明**
+- `type`: 消息类型，固定为"command"
+- `command`: 指令名称，固定为"query_device_status"
+- `data`: 指令数据
+  - `device_id`: 设备唯一标识符
+- `timestamp`: 指令发送时间
+
+### 3.3 查询所有设备状态指令
+
+平台向中继设备发送查询所有设备状态指令。
+
+**请求格式**
+```json
+{
+  "type": "command",
+  "command": "query_all_device_status",
+  "timestamp": "2023-01-01T12:00:00Z"
+}
+```
+
+**参数说明**
+- `type`: 消息类型，固定为"command"
+- `command`: 指令名称，固定为"query_all_device_status"
+- `timestamp`: 指令发送时间
+
+## 4. 响应接口
+
+### 4.1 设备控制响应
+
+中继设备执行控制指令后，向平台发送响应。
+
+**响应格式**
+```json
+{
+  "type": "response",
+  "command": "control_device",
+  "data": {
+    "device_id": "fan-001",
+    "status": "success",
+    "message": "设备控制成功"
+  },
+  "timestamp": "2023-01-01T12:00:05Z"
+}
+```
+
+### 4.2 设备状态响应
+
+中继设备响应设备状态查询指令。
+
+**响应格式**
+```json
+{
+  "type": "response",
+  "command": "query_device_status",
+  "data": {
+    "device_id": "fan-001",
+    "status": "running",
+    "power": 220,
+    "current": 5.2
+  },
+  "timestamp": "2023-01-01T12:00:05Z"
+}
+```
+
+### 4.3 所有设备状态响应
+
+中继设备响应所有设备状态查询指令。
+
+**响应格式**
+```json
+{
+  "type": "response",
+  "command": "query_all_device_status",
+  "data": [
+    {
+      "device_id": "fan-001",
+      "device_type": "fan",
+      "status": "running"
+    },
+    {
+      "device_id": "curtain-001",
+      "device_type": "water_curtain",
+      "status": "stopped"
+    }
+  ],
+  "timestamp": "2023-01-01T12:00:05Z"
+}
+```
+
+## 5. 请求-响应机制
+
+平台在发送指令后会等待中继设备的响应，超时时间由配置文件决定，默认为5秒。
+
+### 5.1 同步等待响应
+
+平台发送指令后会阻塞等待中继设备返回响应，直到：
+1. 收到中继设备的响应消息
+2. 超时（由配置文件决定，默认5秒）
+
+### 5.2 响应处理
+
+平台接收到响应后会：
+1. 解析响应数据
+2. 根据响应结果更新设备控制记录
+3. 向前端返回操作结果
+
+### 5.3 超时处理
+
+如果在指定时间内未收到中继设备的响应，平台会：
+1. 记录超时错误日志
+2. 向前端返回超时错误信息
+3. 设备控制记录中标记为失败状态
+
+## 6. 配置说明
+
+WebSocket请求超时时间可以通过配置文件进行设置：
+
+```yaml
+# WebSocket配置
+websocket:
+  # WebSocket请求超时时间(秒)
+  timeout: 5
+```
+
+如果没有配置或配置值无效，系统将使用默认的5秒超时时间。
+
+## 7. 响应结构定义
+
+平台提供统一的响应结构定义，用于处理中继设备返回的响应：
+
+### 7.1 CommandResponse 结构体
+
+```go
+type CommandResponse struct {
+    // DeviceID 设备ID
+    DeviceID string
+    
+    // Command 命令名称
+    Command string
+    
+    // Data 响应数据
+    Data interface{}
+    
+    // Status 响应状态
+    Status string
+    
+    // Message 响应消息
+    Message string
+    
+    // Timestamp 时间戳
+    Timestamp time.Time
+}
+```
+
+### 7.2 响应处理规则
+
+1. `Status` 字段：表示操作的整体状态，如 "success"、"failed" 等
+2. `Message` 字段：提供人类可读的操作结果描述
+3. `Data` 字段：包含具体的操作结果数据
+4. 如果响应中的 `Data` 是一个对象且包含 `status` 和 `message` 字段，系统会自动提取并填充到对应的结构体字段中
+
+## 8. 消息类型说明
+
+| 类型 | 说明 |
+|------|------|
+| command | 平台向中继设备发送的指令 |
+| response | 中继设备向平台发送的响应 |
+| heartbeat | 心跳消息 |
+
+## 9. 设备类型说明
+
+| 类型 | 说明 |
+|------|------|
+| fan | 风机设备 |
+| water_curtain | 水帘设备 |
+
+## 10. 动作说明
+
+| 动作 | 说明 |
+|------|------|
+| on | 开启设备 |
+| off | 关闭设备 |
+
+## 11. 状态说明
+
+| 状态 | 说明 |
+|------|------|
+| success | 操作成功 |
+| failed | 操作失败 |
+| running | 设备运行中 |
+| stopped | 设备已停止 |