GottZ/open-PicPak

# open-picpak **open-picpak** 是一个围绕 PicPak 4.2″ 电子墨水屏相框开展的净室设计、独立于供应商的项目：包含逆向工程参考文档、可运行的工具、具备原厂产品从未有过功能的完整自定义固件，以及一个可自托管的后端。 一切开发均在公开环境下进行。 **状态** | 组件 | 状态 | |---|---| | `documentation/` | **已发布** | | `firmware/` | 尚未公开 | | `server/` | 尚未公开 | | `web-usb/` | 尚未公开 | | `scripts/` | 尚未公开 | ## 动机 我支持了这个 Kickstarter 项目，因为活动图片展示了**绿色和蓝色**——我以为我能以合理的价格买到一块成熟的彩色电子墨水屏。 但实际发货的是 **400 × 300 BWRY**：只有四种颜色——黑、白、红、黄。没有绿色，没有蓝色，也没有灰色。这个希望在第一次刷新时就破灭了。 更糟糕的是，原厂固件只做了最基础的工作。它只是一个单薄的、依赖云端的图像推送器：手机应用从供应商云端拉取照片和固件，并通过 BLE 推送。我原本希望开箱即用在这个设备上实现的所有功能都变得不可能——而且供应商有比我更长的时间来构建一个合适的固件，而我仅用了**一天**时间，就在自己的固件上搭建了一个完全可用的 Home Assistant WiFi 拉取相框。 因此，我正在打造这款设备本应拥有的固件（以及工具和后端）——**完全公开**，这样社区也能使用它。在下面计划的每个功能都真正落地之前，我不会停下脚步。 ## 这是什么 一套完整的构建方案，纯净开发： - 一份**文档 / 逆向工程参考**（介绍设备的真实情况）， - 一套**自定义 ESP-IDF 固件**，具备原厂从未有过的功能， - 一个**可自托管的后端**（Docker），为每个设备提供内容服务， - 以及用于刷写、配置和向设备传输数据的**工具**——无需任何云服务。 ## 状态 ### 他们做的 —— 原厂产品 - 4.2″ **400 × 300 BWRY** 电子墨水屏（仅限黑/白/红/黄；无绿/蓝/灰），仅支持全刷新（约 19 秒）。 - **ESP32-C3**，**仅限 BLE** 的固件 —— 完全没有接入 WiFi。 - **手机应用是强制的云端网关**：它从供应商云端拉取照片和固件，并通过 BLE 推送到设备。 - 700 个图像槽位，无设备端配置，无脚本功能，也没有独立的网络连接能力。 ### 我做的 - **对设备进行了端到端的逆向工程：** 硬件与引脚映射、flash / NVS / eFuse 布局、MAC 地址与序列号标识、外壳颜色编码、射频与掉电响应区间、完整的 BLE GATT 协议（包含基于 BLE 的 OTA 的 `0xFF01/02/03`），以及精确的 RGB→屏幕图像处理流水线（BT.601 最近色 + Atkinson 抖动）。 - **在一天内基于自定义 ESP-IDF 固件构建了一个完全可用的 Home Assistant WiFi 拉取相框**：唤醒（定时器/按钮） → 连接 WiFi → 拉取服务器渲染的图像 → 显示 → 进入深度睡眠。支持 **基于 WiFi 且经 SHA-256 校验的 OTA**，并强化了防掉电传输。 ### 我已发布的 - [x] [`documentation/device.md`](documentation/device.md) — 硬件、内存布局、标识、颜色、射频/掉电、BLE 概览、图像格式 - [x] [`documentation/ble-protocol.md`](documentation/ble-protocol.md) — 完整的原厂 BLE GATT / 通信帧 / OTA 规范 - [x] [`documentation/image-pipeline.md`](documentation/image-pipeline.md) — RGB→调色板（BT.601 + Atkinson 抖动），附带可运行的 JS 参考代码 - [x] MPL-2.0 许可证 ### 我计划的 项目的核心所在。重新实现我已经拥有的所有功能——循序渐进，以保持代码的整洁并在过程中不断完善——然后远远超越原厂固件的功能。 **文档** - [ ] 刷写与备份指南（esptool 参数、bootloader 模式、原厂恢复） - [ ] 逆向工程方法论（ESP 镜像 → ELF、radare2、Ghidra、blutter） - [ ] 自定义固件笔记（自适应 TX、OTA 块传输、流式头部陷阱） **`firmware/` — 自定义 ESP-IDF 固件** - [ ] **USB 大容量存储配置接口** — 一个虚拟文件系统覆盖层，通过文本文件作为配置 UI，使用 **TOML** 作为配置语言 *(未经测试的概念)* - [ ] **`control/` 动作文件夹** — 删除指定的“文件”即可运行相应操作（`reboot`、`test-wifi` 等） - [ ] **通过 TOML 进行 WiFi / IP 配置** — 预置 DHCP 和 WiFi **禁用**状态，直到完成配置 - [ ] **内嵌字体** — 用于设备端文本显示的点阵字体 + 简单的图形渲染 *(可行性待确认)* - [ ] **自调试屏幕** — 串口信息、MAC 地址、WiFi 状态、IP / 子网掩码 / 网关等 - [ ] **播放列表与轮播** — 轮播存储的图像，可配置循环间隔，远程**同步播放列表**（定时轮询更新——尚未实现），单帧远程拉取（Home Assistant 风格的后端），OTA URL - [ ] **虚拟 `picture/` 文件夹** — 将存储的图像作为可编辑的、颜色索引的 PNG 文件暴露出来 - [ ] **重新实现 BLE 协议栈** — 保持原有的 PicPak 应用能够继续管理存储的图像（闪存存储格式待定） - [ ] **利用上层 16 MB 的 flash 空间** — 让当前未寻址的区域变得可用 *(研究：交换机制 / 代码分页 —— 待定)* - [ ] **Lua 解释器** — 设备端的用户脚本支持 **`server/` — Docker 后端** - [ ] **序列号区分** — 为每个设备提供独立的相框画面 - [ ] 单帧远程后端，从 Home Assistant 概念验证中通用化而来 - [ ] 将 `web-usb/` 工具作为静态资源提供服务 **`web-usb/` — 浏览器工具（由后端提供服务）** - [ ] 刷写与原厂备份 / 恢复（esptool-js —— 无需本地安装） - [ ] 图像编辑器 / 上传器（基于 `image-pipeline.md` 的 JS 参考代码构建） **`scripts/` — 主机端工具** - [ ] BLE 客户端（无需手机应用即可推送 / 管理图像） - [ ] 开发与自动化辅助脚本 ## 仓库布局 ``` documentation/ reference & reverse-engineering docs (published) firmware/ custom ESP-IDF firmware (planned) server/ self-hostable Docker backend; serves web-usb (planned) web-usb/ browser flashing + image editor/uploader (planned) scripts/ host-side scripts / CLI tooling (planned) ``` `web-usb/` 和 `server/` 是相互耦合的：后端将浏览器工具作为静态资源打包发布，因此刷写、上传和配置都可以在同一个自托管的 URL 上完成。 ## 文档 | 文档 | 涵盖内容 | |---|---| | [device.md](documentation/device.md) | 硬件：ESP32-C3、BWRY 面板、完整引脚映射、flash/NVS/eFuse 布局、标识、颜色、射频/掉电、BLE 概览 | | [ble-protocol.md](documentation/ble-protocol.md) | 原厂 BLE 协议的逐字节详解：GATT 布局、通信帧、调度器、图像上传、基于 BLE 的 OTA | | [image-pipeline.md](documentation/image-pipeline.md) | 精确的 RGB→屏幕转换（BT.601 最近色 + 无钳位 Atkinson 抖动），附带支持 Web-USB 的 JS 参考实现 | ## 一句话硬件概述 ESP32-C3（400 KB SRAM，16 MB 可寻址 flash） · 4.2″ 400×300 BWRY 电子墨水屏（原厂仅限 BLE）。完整解析见 [`documentation/device.md`](documentation/device.md)。 ## 免责声明 open-picpak 是一个独立的、社区运营的项目。它**不隶属于、未获得授权，也未受到 AUTOHEART TECH CO., LTD（PicPak 的制造商）的认可**。 “PicPak” / “PICPAK” 以及任何相关的名称或商标均为 AUTOHEART TECH CO., LTD 的财产，此处仅用于标识本项目所针对的硬件。 这是一项**净室设计、旨在实现互操作**的工作：它通过逆向工程记录并重新实现了该设备的行为。**不包含或重新分发任何供应商的源代码、固件二进制文件、资产、密钥或机密**（参见上文的气隙隔离说明）。研究并测试你所拥有的程序的行为——以及出于互操作性目的进行的逆向工程——在欧盟法律下是被明确允许的（Directive 2009/24/EC, Arts. 5–6；在德国为 § 69e UrhG），而且计算机程序“本身”在欧盟是不可授予专利的（Art. 52 EPC）。作者居住在德国（欧盟），且非美国公民。尽管面临原始供应商的压力，类似的开源项目依然立足于同样的法律基础——例如 VideoLAN/VLC。 以上内容均不构成法律建议。 ## 作者与许可 由 **Jan-Stefan Janetzky (GottZ)** 创建并维护 — [git@gottz.de](mailto:git@gottz.de)。 采用 [Mozilla Public License 2.0](LICENSE) 许可。版权所有 © 2026 Jan-Stefan Janetzky。

标签：Docker, ESP-IDF, Python安全, rizin, 云资产清单, 安全防御评估, 数据可视化, 物联网, 电子墨水屏, 自定义固件, 请求拦截, 逆向工程