主题
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(查询打印机状态)
查询打印机状态,端侧收到事件时按"主动上报设备状态"上报。
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| — | — | — | eventData 为 null |
6.3.4 上行事件(端→云)
上行事件主体
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| 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_SUCCESS | 上报打印成功状态 |
| 上行 | PRINT_IMAGE | 打印上屏图片 |
下一步
- 魔法打印排查:读 第 9 章 §9.4 有声书/内容播放类 —— 不打印/打印异常/状态查询失败
- 回看 WS 基础:读 4.4 WebSocket语音通道 ——
contentType机制 - 服务端链路:读 4.6 服务端链路设计 —— ASR/Flow/TTS 三模块如何处理打印指令
- 其他场景:读 6.1 指令与控制 / 6.2 媒体资源接入 / 6.4 视觉对话接入