通信协议详解

如果您想开发自己的控制端（如手机 App、桌面管理软件），可以参考本章节详细了解 PowerControlClient 的通信协议。

1. UDP 设备发现协议

设备发现基于 UDP 广播机制，允许控制端在不知道 IP 的情况下发现局域网内的设备。

• 端口: 42002
• 模式: 请求/响应 (Request/Response)

发现流程

1. 控制端向 255.255.255.255:42002 发送广播包。
2. 客户端收到广播包后，校验 server_id。
3. 客户端向控制端的发送源 IP 和端口回复单播响应包。

数据包结构

请求包 (Request)

{
  "type": "discovery",
  "action": "ping",
  "server_id": "power-control-server" // 必须匹配，否则会被忽略
}

响应包 (Response)

{
  "type": "discovery",
  "action": "pong",
  "mac": "00:11:22:33:44:55",   // 客户端的 MAC 地址
  "response_time": 1734267001, // 响应时间戳 (Unix Timestamp)
  "timestamp": 1734267001      // 同上
}

2. TCP 控制协议

TCP 协议提供可靠的命令传输通道，适合需要确认命令送达的场景。

• 端口: 42001
• 连接方式: 长连接或短连接均可，建议发送完命令接收响应后断开。

交互流程

1. 建立 TCP 连接。
2. 发送 JSON 格式的命令字符串。
3. 接收 JSON 格式的响应字符串。
4. (可选) 断开连接。

数据包结构

命令包 (Command)

{
  "cmd": "poweroff",          // 指令: "poweroff" | "reboot"
  "mac": "aa:bb:cc:dd:ee:ff"  // 目标MAC，或 "all"
}

响应包 (Response)

{
  "status": "success",        // 状态: "success" | "error" | "skipped"
  "message": "Executing shutdown command" // 详细信息
}

3. HTTP 协议

HTTP 协议基于 RESTful 风格，适合 Web 集成和脚本调用。

• 端口: 42000

接口列表

路径	方法	描述	参数
/	POST	执行电源命令	JSON Body
/health	GET	健康检查	无
/control	GET	Web 控制台	无

错误处理

HTTP 接口会返回标准的 HTTP 状态码：

• 200 OK: 请求成功处理。
• 400 Bad Request: JSON 格式错误。
• 405 Method Not Allowed: HTTP 方法错误 (如 GET 访问 POST 接口)。
• 500 Internal Server Error: 服务器内部错误。

响应体通常也是 JSON 格式：

{
  "status": "error",
  "message": "Method not allowed"
}