176 lines
6.2 KiB
Markdown
176 lines
6.2 KiB
Markdown
# MQTT 标准操作手册（OPC 智能园区大屏系统）
|
||
|
||
> 通过 MQTT 对前端大屏进行集中控制：切页、页面操作、媒体控制、视觉开关、状态上报。
|
||
|
||
## 1. Broker 连接
|
||
|
||
| 项 | 值 | 说明 |
|
||
|---|---|---|
|
||
| 地址 | `192.168.1.3` | 局域网 EMQX Broker |
|
||
| TCP 端口 | `1883` | MQTT 标准端口（后端/命令行用） |
|
||
| WebSocket 端口 | `8083` | 前端浏览器用（`ws://192.168.1.3:8083/mqtt`） |
|
||
| 用户名/密码 | `backend/.env` 的 `MQTT_USERNAME` / `MQTT_PASSWORD` | 连接鉴权 |
|
||
|
||
## 2. 频道（Topic）
|
||
|
||
| Topic | 方向 | 载荷 | 用途 |
|
||
|---|---|---|---|
|
||
| `opc/display/command` | 服务端 → 前端 | 指令信封 | **控制指令**（切页/页面操作/媒体/视觉） |
|
||
| `opc/dashboard/tick` | 服务端 → 前端 | 园区数据快照 | 数据大屏实时刷新（2.2s） |
|
||
| `opc/display/heartbeat` | 前端 → 服务端 | `{client_id, page, ts}` | 大屏在线心跳（10s） |
|
||
| `opc/frontend/state` | 前端 → 服务端 | `{client_id, page, ts}` | **页面状态即时上报**（路由变化即发） |
|
||
| `opc/display/ack` | 前端 → 服务端 | 指令回执 | 指令确认（可选） |
|
||
|
||
## 3. 统一指令信封
|
||
|
||
所有控制指令发到 `opc/display/command`，JSON 格式：
|
||
|
||
```json
|
||
{
|
||
"cmd_id": "uuid", // 指令 ID（可选）
|
||
"ts": 1755490000000, // 时间戳 ms（可选）
|
||
"action": "navigate", // 命令名（必填）
|
||
"params": { "page": "/ai" } // 参数（按命令）
|
||
}
|
||
```
|
||
|
||
后端 `hub.publish_command(action, params)` 自动生成信封；命令行手动发送时只需 `action` + `params`。
|
||
|
||
## 4. 命令全集
|
||
|
||
### 4.1 页面切换
|
||
|
||
| action | params | 效果 |
|
||
|---|---|---|
|
||
| `navigate` | `page: "/" \| "/twin" \| "/ai" \| "/voice" \| "/wall" \| "/screen"`（或别名 home/twin/ai/voice/wall/screen/数据大屏/企业展示墙…） | 切换到指定页面 |
|
||
| `navigate_rel` | `delta: 1 \| -1` | 向右 / 向左循环切换页面 |
|
||
|
||
### 4.2 全局视觉识别
|
||
|
||
| action | params | 效果 |
|
||
|---|---|---|
|
||
| `vision_set` | `enabled: true \| false` | 开启 / 关闭全局人物识别（YOLO 人脸/姿态/手势） |
|
||
|
||
### 4.3 AI 助手页（/ai）
|
||
|
||
| action | params | 效果 |
|
||
|---|---|---|
|
||
| `ai_input` | `text: "介绍一下入驻政策"` | 输入问题并自动发送 |
|
||
| `ai_preset` | `index: 0 \| 1 \| 2` | 选择预设问题并发送 |
|
||
| `ai_company` | `action: "next" \| "prev"` | 切换展示企业 |
|
||
| `ai_zone` | `zone: "加速区" \| "国际区" \| "成长区"` | 切换企业分区 |
|
||
|
||
### 4.4 语音对话页（/voice）
|
||
|
||
| action | params | 效果 |
|
||
|---|---|---|
|
||
| `voice_start` | — | 启动语音对话 |
|
||
| `voice_stop` | — | 关闭语音对话 |
|
||
| `voice_refresh` | — | 刷新页面 |
|
||
|
||
### 4.5 媒体轮播页（/screen）
|
||
|
||
| action | params | 效果 |
|
||
|---|---|---|
|
||
| `play` / `pause` | — | 播放 / 暂停 |
|
||
| `next` / `prev` | — | 下一项 / 上一项 |
|
||
| `set_mode` | `mode: sequential \| shuffle \| loop` | 播放模式 |
|
||
| `play_target` | `path: "媒体路径"` | 播放指定媒体 |
|
||
| `settings_changed` | 设置对象 | 应用设置变更 |
|
||
| `playlist_changed` | — | 重新加载播放列表 |
|
||
|
||
### 4.6 企业展示墙页（/wall）
|
||
|
||
> 39 家入驻企业信息缓慢滚动展示墙（数据来源：《入驻企业信息表》）
|
||
|
||
| action | params | 效果 |
|
||
|---|---|---|
|
||
| `wall_pause` | — | 暂停滚动 |
|
||
| `wall_resume` | — | 继续滚动 |
|
||
| `wall_speed` | `speed: slow \| normal \| fast` | 滚动速度：慢速 150s / 标准 80s / 快速 40s 一圈 |
|
||
|
||
### 4.7 全局
|
||
|
||
| action | params | 效果 |
|
||
|---|---|---|
|
||
| `alert` | `text: "通知内容"` | 全局通知弹窗 |
|
||
| `show_card` | 卡片数据 | 展示信息卡片 |
|
||
| `minimize` | — | 最小化窗口（Tauri） |
|
||
|
||
## 5. 命令行发送
|
||
|
||
### mosquitto_pub（推荐，需安装 `mosquitto-clients`）
|
||
|
||
```bash
|
||
# 切页到 AI 助手
|
||
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
|
||
-t opc/display/command \
|
||
-m '{"action":"navigate","params":{"page":"/ai"}}'
|
||
|
||
# 向左切页
|
||
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
|
||
-t opc/display/command -m '{"action":"navigate_rel","params":{"delta":-1}}'
|
||
|
||
# 关闭人物识别
|
||
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
|
||
-t opc/display/command -m '{"action":"vision_set","params":{"enabled":false}}'
|
||
|
||
# AI 页提问
|
||
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
|
||
-t opc/display/command -m '{"action":"ai_input","params":{"text":"介绍一下入驻政策"}}'
|
||
|
||
# 切换企业分区
|
||
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
|
||
-t opc/display/command -m '{"action":"ai_zone","params":{"zone":"国际区"}}'
|
||
|
||
# 语音启动 / 媒体下一项
|
||
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
|
||
-t opc/display/command -m '{"action":"voice_start","params":{}}'
|
||
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
|
||
-t opc/display/command -m '{"action":"next","params":{}}'
|
||
|
||
# 切到企业展示墙 / 暂停滚动
|
||
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
|
||
-t opc/display/command -m '{"action":"navigate","params":{"page":"/wall"}}'
|
||
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
|
||
-t opc/display/command -m '{"action":"wall_pause","params":{}}'
|
||
```
|
||
|
||
### Python（paho-mqtt，后端 venv 自带）
|
||
|
||
```bash
|
||
cd /Volumes/Pine/mycode/DPM/dpm/backend
|
||
.venv/bin/python - <<'EOF'
|
||
import paho.mqtt.client as mqtt
|
||
|
||
def send(action, params=None):
|
||
c = mqtt.Client()
|
||
c.username_pw_set("用户名", "密码")
|
||
c.connect("192.168.1.3", 1883, 30)
|
||
c.publish("opc/display/command", str({"action": action, "params": params or {}}))
|
||
c.disconnect()
|
||
|
||
send("navigate", {"page": "/voice"})
|
||
send("ai_company", {"action": "next"})
|
||
send("voice_stop")
|
||
EOF
|
||
```
|
||
|
||
### MQTTX（图形界面）
|
||
|
||
1. 新建连接：`mqtt://192.168.1.3:1883`，填用户名/密码
|
||
2. 发布到 `opc/display/command`，消息体如上 JSON
|
||
|
||
## 6. 订阅调试
|
||
|
||
```bash
|
||
# 监听前端页面上报（验证"当前页面"）
|
||
mosquitto_sub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> -t 'opc/frontend/state'
|
||
|
||
# 监听心跳
|
||
mosquitto_sub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> -t 'opc/display/heartbeat'
|
||
|
||
# 监听全部指令
|
||
mosquitto_sub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> -t 'opc/display/command' -v
|
||
```
|