Skip to content

feat: 支持 SDK 屏幕图片与实时帧传输 - #19

Merged
Mr-KID-github merged 1 commit into
codex/sdk-display-text-runtimefrom
codex/sdk-display-image-stream
Jul 31, 2026
Merged

feat: 支持 SDK 屏幕图片与实时帧传输#19
Mr-KID-github merged 1 commit into
codex/sdk-display-text-runtimefrom
codex/sdk-display-image-stream

Conversation

@Mr-KID-github

@Mr-KID-github Mr-KID-github commented Jul 31, 2026

Copy link
Copy Markdown
Contributor

背景

这是 issue #17 屏幕文字能力的后续数据面扩展:在设备已经开放 display.text 的基础上,让上位机能够直接发送 JPEG,并以受控帧率持续发送实时画面。

本 PR 为堆叠 PR,依赖 #18,当前以 codex/sdk-display-text-runtime 为 base;请先完成基础文字能力评审。

主要改动

  • 新增 app.robot.display.show_image(...),支持 JPEG 字节、ImageFrame 和本地路径。
  • 新增 app.robot.display.stream(..., fps=10),支持有限序列和实时生成器。
  • 使用 WSPK IMAGE/VIDEO 帧传输,视频流包含明确的首帧、关键帧和终止帧语义。
  • 阻塞式实时生成器在线程中取帧,不阻塞传输事件循环。
  • 主机发送前校验 JPEG:
    • 仅支持基线 JPEG,不支持渐进式 JPEG;
    • 最大分辨率 412x412;
    • 单帧最大 512 KiB。
  • 默认请求 10 FPS,SDK 上限 15 FPS;设备采用“最新待处理帧优先”,过载时不会无限积压。
  • 更新中英文使用文档。

TDD 与验证

  • 先补图片 API、协议封包、帧率边界、非法 JPEG、阻塞生成器和空流测试,再完成实现。
  • python -m pytest:287 passed。
  • python -m mypy src/watcherobot:52 个源文件无问题。
  • git diff --check:通过。

语义与限制

  • show_image() 返回代表图片已成功交给传输层,不代表设备已经完成解码和刷新;首版协议没有增加逐帧渲染 ACK。
  • 15 FPS 是 SDK 请求上限,不是硬件实测承诺。实际帧率受 JPEG 大小、Wi-Fi 和设备解码耗时影响。
  • 配套固件 PR 为 WatcheRobot_esp32#126;真机冒烟与持续帧率测试将在两侧代码联调后完成。

新增 display.show_image 与 display.stream 公共 API,支持 JPEG 字节、ImageFrame 和本地路径输入,并在发送前校验基线编码、尺寸及单帧大小边界。

通过 WSPK IMAGE/VIDEO 帧实现静态图片和限速实时帧发送;阻塞式帧生成器放到工作线程读取,避免占用传输事件循环,并使用终止帧明确结束视频流。

补充图片协议、能力协商、帧率限制、异常输入和传输节奏测试,同时更新中英文文档说明 15 FPS 上限与最新帧优先语义。

配套固件:WatcheRobot_esp32 仓库 codex/sdk-display-image-stream 分支。
@Mr-KID-github
Mr-KID-github marked this pull request as ready for review July 31, 2026 06:35
@Mr-KID-github
Mr-KID-github merged commit c9f7cb3 into codex/sdk-display-text-runtime Jul 31, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant