04 Integration

控制指令接入

说明 TCP、UDP 单播与广播、WebSocket 的控制端口、指令范围和回复差异。

接入方式

外部系统使用现有控制指令通道,不需要为设备通信单独建立另一套连接方式。

通道默认连接方式报文边界
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_commanddata.id:必填,正整数,支持长整型。{"type":"send_command","data":{"id":12}}按本机指令编号查询设备和协议,再发送 TCP、UDP 或串口数据。编号必须存在于接收端;详细流程见上文。
切换素材switch_mediamedia_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_volumelevel:必填,整数,使用 0 至 100。{"type":"set_volume","level":50}设置百分比音量,应用音量或系统音量由播放设置决定。
增大音量volume_up无。{"type":"volume_up"}在当前值基础上增加十个百分点,最高为 100。
减小音量volume_down无。{"type":"volume_down"}在当前值基础上减少十个百分点,最低为 0。
切换静音mute无。{"type":"mute"}切换静音状态,再次执行会取消静音,并非固定设置为静音。

播放进度与循环

指令名称type参数完整报文示例执行说明
跳转到指定时间seek_tomedia_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参数完整报文示例执行说明
相对移动mouseMovedx、dy:整数,默认均为 0。{"type":"mouseMove","dx":20,"dy":-10}桌面光标相对当前位置移动,单位为屏幕像素;正值分别向右、向下。不是千分比绝对坐标。
按住左键拖动mouseDragdx、dy:整数,默认均为 0。{"type":"mouseDrag","dx":20,"dy":0}桌面按住左键后相对移动;后续约一秒没有拖动消息时自动松开。
滚轮滚动mouseWheeldeltaY、deltaX:整数,默认均为 0。{"type":"mouseWheel","deltaY":1,"deltaX":0}桌面使用 -deltaY 驱动纵向滚轮,正值向上;当前实现不使用 deltaX。
左键单击mouseClickclickType:字符串,默认 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参数完整报文示例执行说明
指定授权码激活activatecode:可选,授权码;server_ip:可选,激活服务器地址;均为字符串或空值。{"type":"activate","code":"授权码","server_ip":"192.168.1.10"}有非空授权码时按授权码激活,授权码缺省或为空时转为自动激活。需激活服务可用,最终结果查看运行日志。
自动激活auto_activateserver_ip:可选,字符串或空值。{"type":"auto_activate","server_ip":"192.168.1.10"}向激活管理器发起自动激活;省略地址时由既有激活配置处理。

软件未激活时,业务处理层只放行激活及关机、重启等基础操作,其他播放和设备通信操作会被拒绝。TCP、UDP 的接收确认在业务校验前返回,因此仍应结合激活状态和日志判断结果。

状态上报报文

报文名称type参数完整报文示例处理说明
视频进度上报video_progressposition、duration:必填,长整型。{"type":"video_progress","position":30000,"duration":120000}接收模型可解析,但当前业务处理器不据此改变播放位置或时长;不能代替 seek_to。
音乐进度上报audio_progressposition、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、progressget_progress、getprogress、query_progress、get_media_progress。
快进fast_forward、fastforward、快进fast_forward、fastforward。
快退rewind、快退rewind。

纯文本别名会去除首尾空白并忽略英文字母大小写;其他指令不支持直接发送纯文本名称,例如 play 应使用 {"type":"play"}。无法解析的报文按未知指令处理,TCP、UDP 返回 4000,WS 不即时回复错误报文。

四.联调顺序

  1. 在目标设备配置设备、协议和关联指令。
  2. 点击发送测试,确认外设确实执行。
  3. 复制当前指令的控制命令,通过现有通道发送。
  4. 检查接收确认,再查看接收端的发送结果日志。
  5. 最后验证相册标记或外部业务流程中的实际动作。

自动化测试覆盖报文解析、复制内容、队列行为和真实 TCP 控制接收;不能替代真实外设、串口驱动与安卓权限的现场验证。

© 2026 飞鸟智联