本册按功能分组讲解 SuperScreen 的全部命令:显示区域(screen)、内容投放(web/plugin 与类型键)、内容操控(control)、缓存(cache)、语音播报(speech)、背景音乐(bgm)、系统与配置(system/config)。
消息通道

命令经 ThingBoot 平台 MQTT 通道传输,主题格式 thing/{productKey}/{deviceKey}/{topic}/{side}(/server 云端→设备,/client 设备→云端)。本产品 productKey 固定 xtjhFX4o8x。

消息信封(上行/下行一致):

包装键

产品命令按包装键区分(裸命令会报错,包装键是唯一标准写法):

包装键功能
screen布局与窗口:显示区域的增删改查、打开/关闭/显隐/清空
web内容投放:向区域下发网页 URL(含 cookie/header/POST/vars/interval)
plugin插件投放:按插件 slug 投放(name 必填,v/vars 可选)
image 等内容快捷命令:image / document / video / audio / text 模板投放
control内容操控:滚动/缩放/翻页/音量/进度/刷新/透传等(拍平信封)
cache缓存:设备级媒体缓存开关与清理
speech语音播报:文本、语言、音量、语速、队列控制
bgm背景音乐:不入队的 URL 播放与队列控制(不占显示区域)
system系统命令(SDK 内置):info/network/state/reg/ntp 等

注意:旧信封 {"display":{...}} 已废弃(屏端报 invalid param: display),网页投放一律用 web。

应答规范
  • 成功:{"ret":"ok"};查询类命令直接返回数据(无 ret 包装)
  • 失败:{"ret":"error","msg":"..."}(区域不存在 / 参数非法 invalid param: <key> / 校验失败 / 类型不适用 unsupported)
  • 应答携带原命令的 mid,平台据此关联请求与应答
显示区域的命名与坐标(所有命令通用)
  • 首次启动自动创建覆盖整个显示器的区域 a1 并设为默认显示区域;
  • 默认显示区域:布局中记录 default 字段;未显式设置时取添加最早且未删除的区域。设备必须有一个默认显示区域;
  • 区域至少保留一个(最后一个不可删除);自动命名从 a1 起补空缺(a1/a3 存在时新区域为 a2);
  • 可改名为英文+数字,不可重复,不可用 default(保留字);
  • position 为像素数组 [top, left, width, height, layer?],第 5 参数 layer 为叠放次序(越大越靠前,缺省 0);渲染按 layer 升序叠放,同 layer 按名称排序;
  • 投放/screen 命令未指定 area 时作用于默认显示区域;control 的 area 必选;open/close/show/hide 未指定时作用于全部;
  • 空区域中央显示灰色半透明占位信息(区域名、分辨率、位置)。