opc-backup/design/dpm/mqtt-commands.md

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 格式：

{
  "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）

# 切页到 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 自带）

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. 订阅调试

# 监听前端页面上报（验证"当前页面"）
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