matrix-screen-controller/移动端相关内容/开发要求/设备通信协议.md

奇妙小屏幕 BLE 控制协议 1.0

WiFi 通道扩展 1.2

能力 wifi_transport。加密 BLE transport.offer 返回 channel_id（16 随机字节小写 hex）、secret（32 随机字节 Base64）、device_id、host（当前 WiFi IPv4）、port=8080、path=/ws/mobile、expires_in_ms=10000。每次 offer 撤销前一候选；活动通道须先 close。BLE transport.close 在串行门禁内撤销候选与活动通道，作为回退执行屏障。session.、wifi.、task.get 与通道协商只走 BLE。

KDF：T=SHA256(ASCII(channel_id))；HKDF-SHA256(secret,salt=T,info=ASCII("QMS-WIFI-1")||T,length=72)。密钥及 nonce prefix 布局沿用 BLE Cipher，AAD 标签为 QMS-WIFI-1；双向序号独立从 0 开始，不共享 BLE 计数。最大加密记录 65536 字节。

WebSocket 首个二进制消息为 ASCII(channel_id) 的 32 字节加加密 JSON {device_id}，5 秒内送达；设备验证凭据、BLE 会话及身份后一次消费，返回加密 {device_id,ready:true}。之后每条二进制消息为加密 RPC JSON，格式沿用原协议；WiFi 请求编号独立递增。transport.ping 是 WiFi 唯一通道级方法，每 5 秒调用、5 秒超时，不延长 BLE 活跃时间。设备 10 秒无有效 WiFi 消息撤销通道。

会话锁串行业务和撤销；BLE 断开使 WiFi 失效。只读失败回退后可重取；写入结果不明不重放，回读并提示。旧凭据、错误身份、篡改、重放、非二进制、超长消息拒绝；凭据不进 URL/日志/磁盘。未认证连接不得踢掉合法通道。WiFi 建立不增加 mobile.generation；mobile.active_transport 为 ble/wifi/null。

本文是首版实现契约。Python／Kotlin 加密黄金向量、分片和 Android 13 真实 BLE 已有通过记录；各业务验收范围见测试结果归档，不能据此推断所有场景通过。命令只能进入设备公共业务服务，不调用网页 DOM，不提供 shell、任意路径或原生驱动地址。变化登记到跨端兼容记录。

1. GATT 与广播

项目	固定 UUID／行为
Service	9f57a001-6c31-4c58-bc22-1f728b641001
RX	9f57a002-6c31-4c58-bc22-1f728b641001，Write with response；手机到设备
TX	9f57a003-6c31-4c58-bc22-1f728b641001，Notify；设备到手机

使用传统可连接 BLE 广播，包含服务 UUID；扫描响应提供 QMS- 加短编号。完整昵称与持久 UUID 在握手后取得并缓存；首次扫描尚无昵称时显示产品名与短编号。改名不改变 ID。持久 UUID 在设备首次启动生成，放 /var/lib/matrix-screen-controller/mobile/identity.json，镜像构建不得携带已生成身份。短编号为 UUID 去连字符后的前 8 位，仅展示用。

禁用经典蓝牙配对及不必要的音频／文件传输 profile；GATT 不要求系统 bonding。不能保证其他工具完全无法建立物理连接；保证未完成本协议握手不得执行控制。手机先订阅 TX，再发送握手。连接后停止广播；服务端另外检查并拒绝第二个连接，不以“不广播”代替互斥。

10 秒内未完成握手释放连接。活动会话最多间隔 5 秒发送业务请求或 ping；当前 Android 前台每 2 秒轮询状态，后台释放前每 2 秒 ping。设备连续 20 秒未收到有效消息释放。单次普通命令超时 10 秒，WiFi 扫描 20 秒；耗时切网作为任务立即返回。设备检测断开后目标 5 秒内恢复广播，蓝牙硬件不可用时显示故障并有界退避重试，不阻止显示服务。

2. 分片与消息

所有整数使用网络字节序。每条 RX／TX 特征值是一个分片：magic:uint16=0x514d, wire:uint8=1, kind:uint8, message_id:uint32, index:uint16, count:uint16, total_length:uint32, payload:bytes。头长 16 字节，payload 上限为 ATT_MTU - 3 - 16；必须在 MTU 23 时也可工作，不能强制大 MTU。

kind：1 为 client hello，2 为 server hello，3 为加密记录，4 为握手拒绝。message_id 在当前方向逐条递增，重连归零。每方向仅允许一个重组消息，index 从 0 连续递增，count 与 total_length 必须一致；总消息不超过 65536 字节。重复、乱序、超长、类型未知或 15 秒未完成重组均丢弃并关闭会话，不允许部分消息触发业务。两端操作队列串行；已开始的帧消息完整发完，控制在下一条消息优先，缩略图和预览不得积压。

业务载荷为 UTF-8 JSON 对象。请求：{"id":"1","method":"status.get","params":{}}；成功：{"id":"1","ok":true,"result":{}}；失败：{"id":"1","ok":false,"error":{"code":"CONFLICT","message":"内容已改变，请刷新","retryable":false}}。id 为当前会话递增的十进制字符串，最大 64 字符；服务端只接受新的请求编号，重复编号返回错误而不再次执行变更。连接中断后不得自动重放变更；先回读状态，必要时请用户重试。

通用错误：BAD_REQUEST、NOT_READY、BUSY、UNSUPPORTED_VERSION、UNSUPPORTED_CAPABILITY、NOT_FOUND、CONFLICT、TIMEOUT、DEVICE_ERROR。message 不包含密码、内部路径、命令行、异常堆栈或设备调试身份。握手拒绝只含固定错误码。

3. 自动加密

传输上限补充：ServerHello 在未建立会话时一律按 MTU 23 分片。session.open 可携带整数 receive_mtu（23～517，缺省 23），表示手机当前实际可接收的 ATT MTU；后续下行取该值与 BlueZ 写入回调 MTU 的较小值。此字段只限制分片大小，不影响加密参数。针对实际手机报告 247、BlueZ 回调报告 517 的不一致情况，禁止仅依据 BlueZ 数值发送大通知；断线重置上限为 23。

使用成熟库的 P-256 ECDH、HKDF-SHA256 与 AES-256-GCM，不手写椭圆曲线／AES。客户端和服务端每次连接都生成新的临时密钥和 32 字节随机数，公钥使用 65 字节 SEC1 非压缩编码。JSON 内二进制为标准 Base64，包含必要 padding。

ClientHello 字段：protocol_major:1, protocol_minor:0, public_key, random。ServerHello 字段相同。协商拒绝未知主版本，不建立降级明文会话。握手 JSON 不包含手机名称或 WiFi 信息。

设 C、S 为收到的两个完整原始 hello JSON UTF-8 字节（不重新序列化），T=SHA256(uint32(len(C)) || C || uint32(len(S)) || S)。salt 为 SHA256(client_random || server_random)，IKM 为 ECDH 共享秘密，info 为 ASCII QMS-BLE-1 加 T。HKDF 输出 72 字节：前 32 为 c2s key，接着 32 为 s2c key，最后两个 4 字节分别为 c2s／s2c nonce prefix。

加密记录为 sequence:uint64 || ciphertext || tag:16bytes。每方向 sequence 从 0 开始且必须等于期望值；nonce 为该方向 4 字节 prefix 加 sequence；AAD 为 ASCII QMS-BLE-1、T、方向字节（c2s=0，s2c=1）和 sequence。序号不回绕；鉴别失败、重放、跳序、非法公钥立即释放会话。会话密钥只存内存，断开销毁。

第一条加密请求必须为 session.open，带手机昵称；设备成功回复才算控制会话建立、才通知网页。应用层加密防被动窃听，不认证正版 App，不抵御主动中间人；UUID、昵称和 APK 内置常量都不是认证凭据。

4. 业务接口

响应包含协议主次版本与 capabilities。客户端忽略未知可选字段；缺少必需字段为协议错误。不存在某能力时隐藏或禁用相关操作并解释，不猜测默认支持。时间、大小和单位固定在字段名及模型中；不把网页内部 config 整包当作移动端契约。

method	params	result 与业务边界
session.open	client_name	device_id, device_name, short_id, protocol_major, protocol_minor, capabilities, limits；名称规则见需求。
session.ping	空	alive:true；刷新有效会话活跃时间。
session.rename	client_name	回读当前名称并同步网页连接状态。
device.rename	name	更新持久设备昵称，返回身份元数据，不改变 UUID。
status.get	空	当前结构复用设备状态：state, screen, service, power, resources, network, frp, ui, system, mobile 等字段；手机使用的路径列于下文。不可用原因沿用各子对象定义，不能假设所有子对象均有 available 字段。
storage.get	空	设备与软件容量统计，复用现有有界缓存，单位 bytes。
settings.get	空	当前设置、可写字段、允许值及设置修订；不得带 WiFi 密码。
settings.patch	expected_revision, changes	仅允许亮度、方向、刷新率、性能模式、网络提示延迟；校验冲突后复用现有业务并回读。
wifi.scan	空	networks:[{ssid,security,signal_percent,connected}], scanned_at_ms；时间为 Unix 毫秒；同 SSID/安全类型去重取最强信号，隐藏 SSID 用手动输入。
wifi.get	空	已保存配置（不含密码）、password_configured、实际连接状态、待生效状态。
wifi.set	expected_revision, ssid, security, password_action, password?, ipv4_mode, address?, prefix?, gateway?, dns_servers, activation	password_action 为 keep／replace／none；none 仅开放网络；activation 为 immediate／next_boot；返回配置修订与可选 task_id。
task.get	task_id	state:pending/running/succeeded/failed, stage, error?；只允许查询本协议产生的有界任务，不提供任意系统任务入口。
library.list	cursor?, limit	默认 20、最大 50；返回库修订、条目和下一游标。条目含 type、id、revision、name、is_demo、playable、thumbnail_revision。翻页库变化返回 CONFLICT。
library.summary	空	返回 library_revision,item_count；与 library.list 使用同一目录视图和修订，供新版 App 判断缓存是否可复用。
library.preview	type,id,revision	返回 mime:image/png, data_base64，16×16 静态预览；动画使用首帧。
library.thumbnail	type,id,revision	返回 mime:image/png, data_base64，64×64 静态缩略图；动画使用首帧。
content.play	type,id,revision	使用既有内容解析与显示服务；过期拒绝，不能顺便修改默认内容。
content.default.get	空	当前默认内容元数据。
content.default.set	type,id,revision	保存并立即播放；失败按既有默认内容事务回滚，返回最终状态。
playback.patch	session_id,paused?,position_ms?,speed?	操作既有动画会话；过期会话 CONFLICT，速度限设备已有枚举。
frame.get	known_revision?	未变返回 unchanged:true；变化返回逻辑 RGB 帧的 PNG Base64、frame_revision、采样时间。不传完整动图。

settings 与 wifi 的 revision 为设备生成的不透明字符串，相关状态变化即更新；网页修改也必须更新同一修订。配置检查与提交在公共控制服务内串行执行，防止“检查通过后被另一个客户端覆盖”。错误不得回传旧密码或完整输入。

5. 生命周期与兼容

系统状态每 2 秒读取，容量进入设备页时读取，库按进入／刷新读取，缩略图仅为可见项排队且按设备 ID、条目 ID、修订缓存。后台立即停预览，30 秒关闭会话。重新连接获取完整状态，不把本地缓存写回设备。

BLE 只接收白名单方法。旧客户端遇新能力忽略；旧设备缺某能力时客户端明确提示。不兼容主版本停止控制并返回列表。蓝牙关闭、主服务重启、OTA 维护或适配器消失时失效会话不可复用；恢复后重新握手，不恢复旧密钥。

协议 1.1 增加 library_progressive capability；仅声明该能力的设备可调用 library.summary 和 library.preview。协议 1.0 的 library.list、library.thumbnail 和当前帧接口保持原义；旧 App 忽略新能力，新 App 遇旧设备读取完整目录并沿用 64×64 图。内容缓存不参与设备设置或控制写入。

6. 契约测试要求

共享固定的测试私钥、hello 原始字节、HKDF 输出、双向密文与分片向量；测试密钥明确仅为公开夹具，不能来自设备。Python 与 Kotlin 双向互验，覆盖 MTU 23、大 MTU、边界分片、非 ASCII 昵称、错误公钥、篡改、重放、断线、库翻页冲突、任务失败和主版本拒绝。接口最终字段模型及黄金向量必须随实现提交，未经测试不能写成协议验收通过。

7. 当前状态模型的维护边界

status.get 当前复用设备只读状态构造函数，不依赖 REST URL 或网页控件；它仍与设备状态字段存在结构耦合，不能宣称只有驱动改变才需要检查手机兼容。移动端当前使用 state.animation_playback（active、session_id、paused、position_ms、total_duration_ms、speed、supported_speeds）；其余状态作为详情展示。任何这些字段的删除、重命名、类型或含义变化必须按协议变更登记，不可随网页重构破坏旧 App。

frame.get 变化时提供 sampled_at_ms；unchanged 回复仅有 unchanged 与 frame_revision。App 用本机成功收到回复的时间表示新鲜度，避免设备与手机时钟偏差。缩略图缓存按当前连接隔离、按 type/id/revision 标识；断线清理，不把手机缓存写回设备。

2026-09-26 兼容扩展

library.list 的用户条目遵循设备持久混合顺序，顺序变化影响 library_revision 和游标。演示条目固定在用户条目之前。 task.get 可附加脱敏 error_code（AUTH_FAILED、NETWORK_UNAVAILABLE、IP_CONFIG_FAILED、UNKNOWN）；旧客户端可忽略。没有可靠原因时用 UNKNOWN。wifi.get 仍不含密码。协议主版本保持 1。

兼容说明：原 mobile.transport 为 BLE 统计对象，保持原义；实际链路新增 active_transport，不改变旧字段类型。

Android 动画浏览（2026-10-10）

协议 1.3 新增 library_animation capability。library.animation.info 参数 type/id/revision、offset（默认0）、limit（默认50，1..50），返回 revision、frame_count、frames（index/duration_ms）、next_offset。library.animation.chunk 参数 type/id/revision、tier（preview/full）、frame_index、offset；返回 revision、tier、frame_index、offset、total_bytes、sha256、data_base64、next_offset，每块原始 PNG 字节最多4096。帧维持16×16/64×64、源顺序与时长；错误使用现有 BAD_REQUEST/CONFLICT/NOT_FOUND。原接口与加密消息格式不变。