主题
6.3 魔法打印接入
魔法打印是 JoyInside 的"语音 + 内容生成"场景:在对话过程中根据上下文生成图片,并完成图片打印。有独立协议,
contentType统一使用适用创作 / 社交 / 伴学 / 互动四类场景。打印机外设 + AI 硬件形态。
6.3.1 硬件策略:按键 A/B
| 按键 | 功能 |
|---|---|
| 按键 A | 长按开关机 / 快速双击进入配网 / 短按唤醒语音 |
| 按键 B | 打印任务控制(打印 / 暂停打印) |
6.3.2 三态机:打印态 / 唤醒态 / 关机态
| 状态 | 与服务端 | 收音 | 打印 |
|---|---|---|---|
| 打印态 | 建联 | 不收音 | 可打印 |
| 唤醒态 | 建联 | 可收音 | 可打印 |
| 关机态 | 断联 | 不收音 | 不打印 |
状态流转
- 开机后自动建联,设备处于打印态可打印
- 按键 A 开启对话,设备处于唤醒态可对话
- 按键 A 退出对话,设备退出唤醒态回到打印态
- 关机后设备处于关机态
⚠ 设备处于打印态时需一直保持与服务端 WS 连接,去除 10 分钟自动断联逻辑(打印态需常连)。
6.3.3 下行事件(云→端)
魔法打印事件 contentType 统一使用 PRINT。
下行事件主体
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| code | string | 是 | 200 成功,其他错误 |
| msg | string | 是 | 状态描述 |
| requestId | string | 是 | 请求唯一标识 |
| mid | string | 是 | 消息唯一标识 |
| uid | string | 是 | 用户唯一标识 |
| t | long | 是 | 服务端处理时间戳(毫秒) |
| contentType | string | 是 | 固定 PRINT |
| content.roundId | string | 是 | 消息轮次 index |
| content.eventType | string | 是 | 事件类型 |
| content.eventData | object | 是 | 事件数据 |
PRINT_START(开始打印)
下发打印任务参数和图片地址列表,端侧按顺序将地址列表中的图片打印出来。
| 字段 | 类型 | 必选 | 说明 | 枚举 | 默认值 |
|---|---|---|---|---|---|
| printTaskId | string | 是 | 打印任务 Id | ||
| printMode | string | 否 | 打印类型 | 普通打印 normalPrint / 双色打印 dualColorPrint / 高清打印 hdGrayscalePrint | normalPrint |
| printThickness | string | 是 | 打印浓度 | 4-16 | 8 |
| paperType | string | 是 | 纸张类型 | 黑标纸 blackMarkPaper / 连续纸 continuousPaper / 缝隙纸 gapPaper | continuousPaper |
| printDirection | string | 是 | 打印方向 | 横向 landscape / 纵向 portrait | landscape |
| imgUrlList | List | 是 | 打印图片 url 列表 |
IMAGE_DISPLAY(图片上屏)
生成图片上屏展示。
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| printTaskId | string | 是 | 打印任务 Id |
| imageId | string | 否 | 图片 id |
| imgUrl | string | 是 | 图片地址 |
PRINT_STOP(结束打印)
结束当前打印任务。
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| printTaskId | string | 是 | 打印任务 Id |
PRINT_CONFIG(设置打印机)
设置打印机参数,若值为空则不设置对应字段。
| 字段 | 类型 | 必选 | 说明 | 枚举 |
|---|---|---|---|---|
| printMode | string | 否 | 打印类型 | normalPrint / dualColorPrint / hdGrayscalePrint |
| printThickness | string | 是 | 打印浓度 | 4-16 |
| paperType | string | 是 | 纸张类型 | blackMarkPaper / continuousPaper / gapPaper |
| printDirection | string | 是 | 打印方向 | landscape / portrait |
PRINT_STATUS_QUERY(查询打印机状态)
◻ 暂不下发:该事件与上行
PRINT_STATUS配套,云端当前不做打印机状态查询。
查询打印机状态,端侧收到事件时按"主动上报设备状态"上报。
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| — | — | — | eventData 为 null |
6.3.4 上行事件(端→云)
⚠ 本节三个上行事件(
PRINT_STATUS/PRINT_SUCCESS/PRINT_IMAGE)当前为协议预留通道,云端暂未消费,端侧可暂不实现。
- 打印为单向下发、不等回执:云端下发
PRINT_START成功即视为任务已下发,不依赖端侧回执,也不会因端侧未上报而重试。- 因此缺纸 / 卡纸 / 开盖 / 过热 / 低电量 / 打印失败等情况需由端侧自行提示用户(屏幕、灯效或本地语音),云端无法感知、不会主动播报。
- 已按协议实现上行事件的设备无需下线:云端只是当前不消费,后续能力开放时可直接复用。
上行事件主体
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| mid | string | 是 | 消息唯一标识 |
| uid | string | 是 | 用户唯一标识 |
| t | long | 是 | 服务端处理时间戳(毫秒) |
| contentType | string | 是 | 固定 PRINT |
| content.eventType | string | 是 | 上行事件类型 |
| content.eventData | object | 是 | 事件数据 |
PRINT_STATUS(主动上报 / 查询响应)
⚠ 预留通道,暂未使用:云端当前不消费该事件,端侧可暂不实现。
两种用途:① 设备异常时主动上报状态;② 收到 PRINT_STATUS_QUERY 下行事件时响应。
| 字段 | 类型 | 必选 | 说明 | 枚举 |
|---|---|---|---|---|
| battery | string | 是 | 电量 | |
| printerStatus | List | 是 | 设备状态(可能多种并存) | 正常 normal / 过热 overHeat / 开盖 coverOpen / 缺纸 paperOut / 低电量 lowBattery |
PRINT_SUCCESS(上报打印成功状态)
⚠ 预留通道,暂未使用:打印为单向下发、不等回执,云端当前不消费该事件,端侧可暂不实现。
打印成功后主动上报状态。
| 字段 | 类型 | 必选 | 说明 | 枚举 |
|---|---|---|---|---|
| printTaskId | string | 是 | 打印任务 Id | |
| printSuccess | int | 是 | 打印结果 | 0 失败 / 1 成功 |
PRINT_IMAGE(打印上屏图片)
⚠ 预留通道,暂未使用:云端当前不消费该事件,端侧可暂不实现。生图打印 技能的打印由语音确认触发;物理按键触发打印属端侧自有逻辑,无需依赖此上行事件。
点击打印按钮打出当前图片。
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| printTaskId | string | 是 | 打印任务 Id |
| imageId | string | 是 | 图片 id |
6.3.5 事件速查
| 方向 | 事件 | 用途 | 云端当前状态 |
|---|---|---|---|
| 下行 | PRINT_START | 开始打印(含图片列表 + 打印参数) | ✅ 已使用 |
| 下行 | IMAGE_DISPLAY | 图片上屏展示 | ✅ 已使用 |
| 下行 | PRINT_STOP | 结束打印任务 | ◻ 暂不下发 |
| 下行 | PRINT_CONFIG | 设置打印机参数 | ◻ 暂不下发(打印浓度/纸型/方向由端侧自行设定) |
| 下行 | PRINT_STATUS_QUERY | 查询打印机状态 | ◻ 暂不下发(与上行 PRINT_STATUS 配套) |
| 上行 | PRINT_STATUS | 主动上报异常 / 响应查询 | ⚠ 预留通道,暂未使用,可暂不实现 |
| 上行 | PRINT_SUCCESS | 上报打印成功状态 | ⚠ 预留通道,暂未使用,可暂不实现 |
| 上行 | PRINT_IMAGE | 打印上屏图片 | ⚠ 预留通道,暂未使用,可暂不实现 |
最小可用集:端侧实现
IMAGE_DISPLAY(图片上屏)+PRINT_START(打印)两个下行事件,即可完整跑通 生图打印 技能。交互建议:生图耗时约 8 秒,建议在平台侧开启「生图期间禁用 ASR」,并由端侧在这段时间给出等待态交互引导(「正在画…」加载动画 / 灯效),收到
IMAGE_DISPLAY后恢复收音并引导用户回答「要不要打印」;若长时间未收到IMAGE_DISPLAY,端侧按自身超时机制自动恢复监听。
下一步
- 魔法打印排查:读 第 9 章 §9.4 有声书/内容播放类 —— 不打印/打印异常/状态查询失败
- 平台侧配置:读运营平台产品说明 技能库 - 生图打印 —— 图片格式、是否打印、生图期间禁用 ASR、预览/打印尺寸等参数怎么配
- 回看 WS 基础:读 4.4 WebSocket语音通道 ——
contentType机制 - 服务端链路:读 4.6 服务端链路设计 —— ASR/Flow/TTS 三模块如何处理打印指令
- 其他场景:读 6.1 指令与控制 / 6.2 媒体资源接入 / 6.4 视觉对话接入