控制指令接入
接入方式
外部系统使用现有控制指令通道,不需要为设备通信单独建立另一套连接方式。
| 通道 | 默认连接方式 | 报文边界 |
|---|---|---|
| TCP | 连接播控设备的 9092 端口。 | 每条 JSON 报文后附加换行。 |
| UDP 单播 | 向播控设备的 9093 或 9094 端口发送。 | 每个数据报发送一条 JSON 报文。 |
| UDP 广播 | 向目标局域网的广播地址发送,目标端口为 9093 或 9094;9094 兼容原有广播控制服务。 | 每个数据报发送一条 JSON 报文。 |
| WebSocket | 播控设备主动连接配置的控制服务器,默认使用 2225 端口;此端口位于服务器一侧。 | 沿现有连接发送 JSON 文本帧。 |
以上为当前默认实现,服务器地址与连接端口以实际部署为准。9093 与 9094 使用同一段接收逻辑,均可接收单播或广播,并非一个只收单播、另一个只收广播。广播能否送达还取决于局域网路由、防火墙和无线网络隔离设置。网页管理端不是本机 TCP、UDP 控制服务的接收终端。
指令支持范围
TCP、UDP 单播、UDP 广播和 WebSocket 共用同一套指令解析及分发。下列指令无需因传输通道不同而改变 JSON 结构,也没有广播专用的指令白名单。
下方“完整指令说明”按类别逐条列出名称、参数、完整报文示例与执行说明。type 大小写应与表格保持一致。
进度报文 video_progress、audio_progress 也能被各入口解析,但它们属于状态上报,不是播放操作。统一支持解析不代表每个平台都具备对应系统功能,实际执行仍受平台实现、权限、软件激活状态和当前媒体状态限制。进度主动推送通过已有 WebSocket 连接发送,不会因为收到 UDP 广播而改为 UDP 广播推送。
回复差异
| 通道 | 当前回复行为 |
|---|---|
| TCP | 每条指令返回一行 JSON;ping 返回心跳结果,get_progress 返回当前媒体进度。 |
| UDP 单播、广播 | 除鼠标指令外,将 JSON 回复单播至请求发送者的地址与源端口;广播请求不会广播回复。鼠标指令为单向发送,不回复。 |
| WebSocket | 接收到的指令进入同一分发流程,但目前没有 TCP、UDP 的逐条即时回复逻辑,不能依赖同样的接收确认、心跳回复或即时进度查询回复;主动状态推送独立处理。 |
设备发现端口
| 项目 | 说明 |
|---|---|
| 监听协议与端口 | UDP 60000,专门用于设备发现,不执行控制指令。 |
| 推荐请求 | 直接发送文本 1111111111,不需要 JSON 包装。 |
| 兼容请求 | 文本包含 discovery、ping 或 find_device 时,也按发现请求处理。 |
| 回复目标 | 发送者的 UDP 60002 端口;请求源端口不是 60002 时,还向源端口回复。 |
| 回复字段 | ip、mac、status、device_name、device_type。其中 status 为 online。 |
例如,设备通信指令应发到 TCP 9092、UDP 9093/9094 或已有 WS 控制连接,不能发到发现端口 60000。
指令使用顶层 type 标识。现有素材和播放控制保留原有参数位置;新增 send_command 的编号放在 data 内,不应把所有旧指令机械改成嵌套参数。
一.执行设备通信指令
{"type":"send_command","data":{"id":12}}
| 字段 | 要求 |
|---|---|
type | 固定为 send_command。 |
data.id | 当前接收端数据库中已保存的设备指令编号,必须为正整数,支持长整型。 |
建议在“设备通信 → 关联协议”的操作栏点击“复制控制命令”,直接取得报文。
执行流程:
外部系统发送报文 → 播控设备接收并校验 → 按编号查询设备与协议 → 编码发送内容 → 执行 TCP、UDP 或串口发送。
- 调用安卓设备,就由安卓设备执行;调用桌面设备,就由该电脑执行。
- 不同播控设备的本地编号不一定指向同一条指令,不要跨设备直接复用编号。
- 外部无需重复发送地址、端口、波特率或原始协议内容。
- 沿用现有激活校验,不新增文件传输配对码或远程桌面验证流程。
- 设备指令使用独立顺序队列,等待外设连接不阻塞素材切换和播放控制;不承诺它与播放指令之间具有跨队列的严格先后关系。
- 发送失败不自动重试。
接收确认
{"code":"0000","msg":"OK"}
该回复适用于 TCP 和会回复的 UDP 控制请求,只确认指令已接收,不表示发送已经完成,更不表示外设已经执行。WebSocket 当前不逐条返回此确认。
缺失编号、编号非正数、超出长整型范围或报文格式无效时按未知指令处理,TCP、UDP 回复 4000。编号有效但记录不存在、设备连接失败、串口无权限等属于后续执行错误,应查看接收端运行日志。
需要立即获得发送调用结果的既有网页管理接口,与本节控制通道的接收确认语义不同,不应混用判断方式。
二.切换素材
{"type":"switch_media","media_type":"video","path":"素材的唯一标识"}
media_type 选择对应素材类型,path 在当前实现中填写素材的唯一标识,不是发送端电脑的磁盘路径。
常用类型包括:
| 类型 | 值 |
|---|---|
| 视频 | video |
| 音乐 | audio |
| 图片 | image |
| 网页 | web |
| 演示文稿 | ppt |
| 办公文档 | office |
先确认素材已上传并完成索引,再使用查询得到的标识发送切换指令。
三.完整指令说明
表中“无”表示除顶层 type 外不需要其他参数。所有示例均为完整 JSON 报文;TCP 发送时还需在报文末尾追加换行。
设备通信与素材播放
| 指令名称 | type | 参数 | 完整报文示例 | 执行说明 |
|---|---|---|---|---|
| 执行设备指令 | send_command | data.id:必填,正整数,支持长整型。 | {"type":"send_command","data":{"id":12}} | 按本机指令编号查询设备和协议,再发送 TCP、UDP 或串口数据。编号必须存在于接收端;详细流程见上文。 |
| 切换素材 | switch_media | media_type:必填,素材类型;path:必填,素材唯一标识。 | {"type":"switch_media","media_type":"video","path":"素材唯一标识"} | 切换并展示对应素材。类型与编号说明见上文,不传发送端磁盘路径。 |
| 开始或恢复播放 | play | 无。 | {"type":"play"} | 对当前视频或音乐开始、恢复播放;图片全屏时启动轮播。没有已加载音频且未处于视频、音乐、图片全屏时,尝试打开配置的启动播放内容。 |
| 暂停播放 | pause | 无。 | {"type":"pause"} | 暂停当前视频;其他状态转交音乐播放器。图片轮播暂停请使用 stop_slideshow。 |
| 从头重播 | replay | 无。 | {"type":"replay"} | 当前视频或音乐回到开头并播放。 |
| 进入待机 | standby | 无。 | {"type":"standby"} | 停止当前展示并进入配置的待机画面;未配置待机内容时返回仪表盘。 |
音量控制
| 指令名称 | type | 参数 | 完整报文示例 | 执行说明 |
|---|---|---|---|---|
| 设置音量 | set_volume | level:必填,整数,使用 0 至 100。 | {"type":"set_volume","level":50} | 设置百分比音量,应用音量或系统音量由播放设置决定。 |
| 增大音量 | volume_up | 无。 | {"type":"volume_up"} | 在当前值基础上增加十个百分点,最高为 100。 |
| 减小音量 | volume_down | 无。 | {"type":"volume_down"} | 在当前值基础上减少十个百分点,最低为 0。 |
| 切换静音 | mute | 无。 | {"type":"mute"} | 切换静音状态,再次执行会取消静音,并非固定设置为静音。 |
播放进度与循环
| 指令名称 | type | 参数 | 完整报文示例 | 执行说明 |
|---|---|---|---|---|
| 跳转到指定时间 | seek_to | media_type:必填,建议为 video 或 audio;seconds:必填,长整型非负秒数。 | {"type":"seek_to","media_type":"video","seconds":30} | 跳转到视频或音乐第30秒。传 audio 控制音乐。 |
| 快进 | fast_forward | 无。 | {"type":"fast_forward"} | 按播放器固定步长快进当前视频或音乐,不接收自定义秒数;指定时间请使用 seek_to。 |
| 快退 | rewind | 无。 | {"type":"rewind"} | 按播放器固定步长快退当前视频或音乐,不接收自定义秒数。 |
| 开启循环 | loop | 无。 | {"type":"loop"} | 将当前视频或音乐的播放模式设为循环,同时更新对应播放设置。 |
| 关闭循环 | stop_loop | 无。 | {"type":"stop_loop"} | 将播放模式设为不循环,播放结束后的行为由播放设置决定,不立即停止播放。 |
手动跳转和远程跳转共用播放设置中的视频跳转方式,实际定位精度及恢复画面的速度受素材与播放平台影响。
图片浏览与轮播
| 指令名称 | type | 参数 | 完整报文示例 | 执行说明 |
|---|---|---|---|---|
| 下一张图片 | next_image | 无。 | {"type":"next_image"} | 在当前全屏图片列表中切换到下一张。 |
| 上一张图片 | prev_image | 无。 | {"type":"prev_image"} | 在当前全屏图片列表中切换到上一张。 |
| 开始轮播 | start_slideshow | 无。 | {"type":"start_slideshow"} | 启动当前图片列表的自动轮播,间隔使用已有设置;标记弹窗打开期间暂不自动切换。 |
| 停止轮播 | stop_slideshow | 无。 | {"type":"stop_slideshow"} | 停止图片自动轮播,保留当前图片展示。 |
这些指令面向已有的图片全屏会话,不会自行按文件路径打开图片。
演示文稿与翻页
| 指令名称 | type | 参数 | 完整报文示例 | 执行说明 |
|---|---|---|---|---|
| 下一页或下一项 | next_slide | 无。 | {"type":"next_slide"} | 图片全屏时切下一张,视频全屏时切下一项,其余情况交给文稿控制器翻到下一页。 |
| 上一页或上一项 | prev_slide | 无。 | {"type":"prev_slide"} | 图片全屏时切上一张,视频全屏时切上一项,其余情况交给文稿控制器翻到上一页。 |
| 第一页或第一项 | first_slide | 无。 | {"type":"first_slide"} | 图片、视频全屏时切到列表第一项,其余情况交给文稿控制器翻到第一页。 |
| 关闭演示文稿 | close_ppt | 无。 | {"type":"close_ppt"} | 请求文稿控制器关闭当前受控文稿。实际效果取决于平台及文稿软件支持,不等同于关闭所有办公软件进程。 |
外部演示软件依赖平台文稿控制器;安卓不能直接沿用桌面的办公软件控制能力。
鼠标控制
| 指令名称 | type | 参数 | 完整报文示例 | 执行说明 |
|---|---|---|---|---|
| 相对移动 | mouseMove | dx、dy:整数,默认均为 0。 | {"type":"mouseMove","dx":20,"dy":-10} | 桌面光标相对当前位置移动,单位为屏幕像素;正值分别向右、向下。不是千分比绝对坐标。 |
| 按住左键拖动 | mouseDrag | dx、dy:整数,默认均为 0。 | {"type":"mouseDrag","dx":20,"dy":0} | 桌面按住左键后相对移动;后续约一秒没有拖动消息时自动松开。 |
| 滚轮滚动 | mouseWheel | deltaY、deltaX:整数,默认均为 0。 | {"type":"mouseWheel","deltaY":1,"deltaX":0} | 桌面使用 -deltaY 驱动纵向滚轮,正值向上;当前实现不使用 deltaX。 |
| 左键单击 | mouseClick | clickType:字符串,默认 click。 | {"type":"mouseClick","clickType":"click"} | 在当前光标位置单击。当前桌面处理器不区分 clickType 的值,不支持通过该字段保持按下或单独抬起。 |
| 右键单击 | mouseRightClick | 无。 | {"type":"mouseRightClick"} | 在当前光标位置执行一次右键单击。 |
| 左键双击 | mouseDoubleClick | 无。 | {"type":"mouseDoubleClick"} | 在当前光标位置连续执行两次左键单击。 |
本表对应 TCP、UDP 和 WS 控制指令入口,当前由桌面端执行;安卓该入口的鼠标处理为空操作。远程桌面连接使用独立输入协议,不能将其坐标与按键参数套用到本表。
系统与窗口
| 指令名称 | type | 参数 | 完整报文示例 | 执行说明 |
|---|---|---|---|---|
| 显示桌面 | showDesktop | 无。 | {"type":"showDesktop"} | 桌面端模拟 Win + D,按系统行为显示或恢复桌面。 |
| 打开开始菜单 | showStartMenu | 无。 | {"type":"showStartMenu"} | 桌面端模拟 Windows 键。 |
| 返回或退出当前状态 | webReturn | 无。 | {"type":"webReturn"} | 桌面端模拟 Esc,具体作用由当前获得焦点的窗口决定,并非浏览器历史后退。 |
| 刷新 | refresh | 无。 | {"type":"refresh"} | 桌面端模拟 Ctrl + R,作用于当前获得焦点的窗口。 |
| 最大化应用 | maximize | 无。 | {"type":"maximize"} | 桌面端尝试将应用窗口置前并最大化。 |
| 放大 | zoomIn | 无。 | {"type":"zoomIn"} | 桌面端模拟 Ctrl + =,由当前窗口处理缩放。 |
| 缩小 | zoomOut | 无。 | {"type":"zoomOut"} | 桌面端模拟 Ctrl + -,由当前窗口处理缩放。 |
| 关机 | shutdown | 无。 | {"type":"shutdown"} | 桌面端调用系统关机,实际执行取决于系统权限。 |
| 重启 | restart | 无。 | {"type":"restart"} | 桌面端调用系统重启,实际执行取决于系统权限。 |
本组当前由桌面端平台处理器执行,安卓入口为空操作;接收到 OK 不能证明系统操作已经执行。涉及键盘模拟的操作由焦点窗口接收。
通信与进度查询
| 指令名称 | type | 参数 | 完整报文示例 | 执行说明 |
|---|---|---|---|---|
| 心跳检测 | ping | 无。 | {"type":"ping"} | TCP、UDP 即时回复 {"code":"0000","msg":"pong"};WS 当前不自动返回该心跳响应。 |
| 查询当前进度 | get_progress | 无。 | {"type":"get_progress"} | TCP、UDP 返回当前媒体状态;没有状态时返回 {"code":"0000","msg":"OK","type":"none","data":null}。WS 当前不即时回复此查询。 |
| 开启进度推送 | push | 无。 | {"type":"push"} | 开启进度主动推送,由已有 WS 连接约每秒发送一次当前状态;通过 TCP、UDP 下发也不会在这些通道建立推送订阅。 |
| 停止进度推送 | stop_push | 无。 | {"type":"stop_push"} | 关闭进度主动推送,不停止媒体播放,也不阻止 TCP、UDP 的单次进度查询。 |
软件激活
| 指令名称 | type | 参数 | 完整报文示例 | 执行说明 |
|---|---|---|---|---|
| 指定授权码激活 | activate | code:可选,授权码;server_ip:可选,激活服务器地址;均为字符串或空值。 | {"type":"activate","code":"授权码","server_ip":"192.168.1.10"} | 有非空授权码时按授权码激活,授权码缺省或为空时转为自动激活。需激活服务可用,最终结果查看运行日志。 |
| 自动激活 | auto_activate | server_ip:可选,字符串或空值。 | {"type":"auto_activate","server_ip":"192.168.1.10"} | 向激活管理器发起自动激活;省略地址时由既有激活配置处理。 |
软件未激活时,业务处理层只放行激活及关机、重启等基础操作,其他播放和设备通信操作会被拒绝。TCP、UDP 的接收确认在业务校验前返回,因此仍应结合激活状态和日志判断结果。
状态上报报文
| 报文名称 | type | 参数 | 完整报文示例 | 处理说明 |
|---|---|---|---|---|
| 视频进度上报 | video_progress | position、duration:必填,长整型。 | {"type":"video_progress","position":30000,"duration":120000} | 接收模型可解析,但当前业务处理器不据此改变播放位置或时长;不能代替 seek_to。 |
| 音乐进度上报 | audio_progress | position、duration:必填,长整型。 | {"type":"audio_progress","position":30000,"duration":249000} | 接收模型可解析,但当前业务处理器不据此控制音乐。不能将本表的接收模型当作主动推送完整字段规范。 |
旧格式兼容
新接入建议使用上表中的标准 JSON。以下别名由公共解析器兼容,TCP、UDP 单播、UDP 广播和 WS 均使用相同规则。
| 对应指令 | 兼容纯文本 | 兼容 JSON 顶层 type |
|---|---|---|
| 关机 | shutdown、关机 | 标准值 shutdown。 |
| 重启 | restart、reboot、重启 | 标准值 restart;不支持 JSON reboot。 |
| 查询进度 | get_progress、getprogress、query_progress、progress | get_progress、getprogress、query_progress、get_media_progress。 |
| 快进 | fast_forward、fastforward、快进 | fast_forward、fastforward。 |
| 快退 | rewind、快退 | rewind。 |
纯文本别名会去除首尾空白并忽略英文字母大小写;其他指令不支持直接发送纯文本名称,例如 play 应使用 {"type":"play"}。无法解析的报文按未知指令处理,TCP、UDP 返回 4000,WS 不即时回复错误报文。
四.联调顺序
- 在目标设备配置设备、协议和关联指令。
- 点击发送测试,确认外设确实执行。
- 复制当前指令的控制命令,通过现有通道发送。
- 检查接收确认,再查看接收端的发送结果日志。
- 最后验证相册标记或外部业务流程中的实际动作。
自动化测试覆盖报文解析、复制内容、队列行为和真实 TCP 控制接收;不能替代真实外设、串口驱动与安卓权限的现场验证。