V2 业务命令

本页集中放业务 JSON 命令。所有命令都通过 BLUFI Custom Data 发送，并携带新的 request_id。

命令总览

命令	参数	用途	前置状态	结果顺序
set_volume	value: 0..100	设置音量	已鉴权	command_ack → state.volume
set_brightness	value: 0..100	设置亮度	已鉴权	command_ack → state.brightness
set_wifi	ssid、password	配置 Wi-Fi	恢复状态可直接使用；AUTH_REQUIRED 先鉴权	connecting → connected 或失败
peer_radar_start	duration_ms，默认/最大 60000	开启发现窗口	已鉴权	started → peer_found → peer_discovery_done
peer_radar_stop	无	停止发现窗口	已启动或已停止	新 request_id 的 stopping / already_stopped；最终 peer_discovery_done 归属启动 ID
reboot	无	重启设备	已鉴权	rebooting，随后断开

设置音量

请求：

{"command":"set_volume","request_id":"volume-001","params":{"value":50}}

成功响应：

{"type":"command_ack","request_id":"volume-001","code":0,"message":"ok","state":{"volume":50}}

失败响应：invalid_volume 或 audio_unsupported。

设置亮度

请求：

{"command":"set_brightness","request_id":"brightness-001","params":{"value":80}}

成功响应：

{"type":"command_ack","request_id":"brightness-001","code":0,"message":"ok","state":{"brightness":80}}

失败响应：invalid_brightness 或 screen_unsupported。

配置 Wi-Fi

请求：

{"command":"set_wifi","request_id":"wifi-001","params":{"ssid":"MyWiFi","password":"password123"}}

立即响应：

{"type":"command_ack","request_id":"wifi-001","code":0,"message":"connecting"}

最终响应：

{"type":"command_ack","request_id":"wifi-001","code":0,"message":"connected","state":{"network":"WIFI_CONNECTED"}}

失败响应：wifi_connect_failed 或 wifi_config_failed。SSID 最长 32 字节，密码最长 64 字节且可为空。双网下不关闭 4G、不手动切换路由。

附近设备发现

启动请求：

{"command":"peer_radar_start","request_id":"radar-001","params":{"duration_ms":30000}}

启动响应：

{"type":"command_ack","request_id":"radar-001","code":0,"message":"started","state":{"duration_ms":30000}}

发现事件：

{"type":"peer_found","request_id":"radar-001","data":{"device_id":"Xiaoji-A4CB8FD5C1F4","rssi":-48}}

结束响应：

{"type":"peer_discovery_done","request_id":"radar-001","code":0,"reason":"timeout","count":1,"devices":[{"device_id":"Xiaoji-A4CB8FD5C1F4","rssi":-48}]}

停止请求：

{"command":"peer_radar_stop","request_id":"radar-stop-001","params":{}}

停止响应：

{"type":"command_ack","request_id":"radar-stop-001","code":0,"message":"stopping"}
{"type":"peer_discovery_done","request_id":"radar-001","code":0,"reason":"stopped","devices":[]}

停止命令是幂等的：重复停止返回 already_stopped；timeout 是正常结束，不是失败。每次 peer_radar_start、peer_radar_stop 都生成新的 request_id，但停止后的最终结束事件继续归属启动窗口的 ID。

重启设备

请求：

{"command":"reboot","request_id":"reboot-001","params":{}}

响应：

{"type":"command_ack","request_id":"reboot-001","code":0,"message":"rebooting"}

设备返回 rebooting 后重启并断开连接。

通用错误

code	含义
-1	invalid_json
-2	状态或参数错误，如 device_unbound、network_unavailable
-3	unknown_command
-4	硬件不支持或执行失败

失败响应必须保留原 request_id。payload 超过 512 字节时返回 payload_too_large。