本册按功能分组讲解 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 未指定时作用于全部;
- 空区域中央显示灰色半透明占位信息(区域名、分辨率、位置)。