95 lines
10 KiB
Markdown
95 lines
10 KiB
Markdown
# 奇妙小屏幕控制器（核桃派 ZeroW）协作指南
|
||
|
||
本目录是可以单独拿走、独立开发和部署的核桃派项目。处理任务前先读本文件，再读 `整体开发需求/`、`测试相关资料/如何测试/` 和与任务有关的硬件资料。本项目不得依赖外层移植目录、原树莓派工作区、旧设备配置或旧设备凭据。
|
||
|
||
## 1. 固定硬件和边界
|
||
|
||
- 主控：核桃派 ZeroW，H618，Debian 12 Server。
|
||
- 屏幕：单块 `RGB-Matrix-P3-64x64-F`，HUB75，64×64，1/32 扫描，ABCDE 行地址。
|
||
- 真实驱动：项目自带 `walnutpi-h618-hub75` C 驱动，通过 `/dev/mem` 访问 H618 PI bank；不得回退或依赖 `rpi-rgb-led-matrix`。
|
||
- ADC：M5Stack Unit ADC v1.1 / ADS1110，`/dev/i2c-1`，地址 `0x48`。
|
||
- 生产程序、持久数据和运行数据分别位于 `/opt/matrix-screen-controller`、`/var/lib/matrix-screen-controller`、`/run/matrix-screen-controller`。
|
||
- 当前设备和开发机凭据只保存在 `测试相关资料/核桃派的用户名和密码和ip/用户名密码ip.txt`，不得复制到源码、日志、普通文档或回复。正式 IMG 的发布目录 `README.md` 是唯一例外：它必须写明该未修改镜像内故意公开的默认账户与 Wi-Fi 四项值，并警告用户修改；不得把当前设备或开发机凭据误写为镜像默认值。
|
||
|
||
### 1.1 私有调试凭据门禁
|
||
|
||
- `测试相关资料/核桃派的用户名和密码和ip/用户名密码ip.example.txt` 是可提交示例；同目录 `用户名密码ip.txt` 是被根 `.gitignore` 精确排除的唯一真实调试记录。不得把真实值写回示例。
|
||
- 凡 SSH、远端命令、实机部署、镜像定制、网络登录或其他需要设备身份的任务，先从仓库根目录运行 `python "测试相关资料/核桃派的用户名和密码和ip/prepare_credentials.py"`。不要先读取、回显或自行猜测凭据。
|
||
- 私有文件不存在时，准备脚本只从示例创建副本并停止。agent 必须暂停当前远端步骤，明确让用户编辑仓库相对路径 `测试相关资料/核桃派的用户名和密码和ip/用户名密码ip.txt`，等待用户确认后重新运行检查；不得在示例值未替换时继续。
|
||
- 私有文件已存在时不得覆盖、重建或格式化。检查失败只报告缺失字段名或格式问题，不输出字段值；聊天、命令行、日志、测试夹具、补丁和提交摘要中均不得出现真实值。
|
||
- 提交前运行 `python "核桃派软件源代码/scripts/check_repository_hygiene.py"`。发现真实凭据进入 Git 候选、开发机绝对路径、私钥或高可信秘密时必须停止，不得用扩大忽略范围掩盖本应修正的公开文件。
|
||
|
||
## 2. 需求与测试编号
|
||
|
||
- `WEB-*`：网页、REST、WebSocket、交互和安全入口。
|
||
- `DISPLAY-*`：显示服务、帧、方向、字体、动画、mock 与 H618 真实驱动。
|
||
- `CONFIG-*`：schema、默认值、迁移、持久数据和损坏保护。
|
||
- `DEPLOY-*`：编译、systemd、权限、离线部署、更新和清理。
|
||
- `HW-*`：核桃派排针、HUB75、ADC、供电和扫描参数。
|
||
- `TEST-*`：本机、板端无负载、实屏、ADC、重启、清理和独立性验收。
|
||
|
||
新增或改变行为时，先更新 `整体开发需求/` 的稳定编号，再改 `核桃派软件源代码/`，最后同步 `测试相关资料/如何测试/` 的映射和合格标准。
|
||
|
||
## 3. 分层验证
|
||
|
||
- 本机 mock 验证确定性业务、REST、WebSocket、配置、字体、模板、动图和前端测试。
|
||
- 核桃派无负载验证编译、寄存器映射、线程调度、双缓冲、截止统计和异常清屏；在该门槛通过前禁止接屏。
|
||
- HUB75 实屏测试按全黑、红、绿、蓝、白、四角、关键行、方向、文字、图片、动画逐项执行；上一项失败就停止，只排查对应线组。
|
||
- ADC 测试按总线、地址、原始读取、同点万用表校准、正常档、单个低压档、恢复逐项执行，不合并人工动作。
|
||
- 有清晰摄像头时由 Codex 判断；画面缺失或有拍频、曝光、视角歧义时必须等待用户确认。
|
||
|
||
## 4. 人工停顿与电气安全
|
||
|
||
任何拔卡、插卡、断电接线、上电、万用表读数或调压都必须分阶段暂停。暂停时明确当前完成项、是否断电、用户只做什么、回复什么、下一步测什么。没有用户确认，不把物理结果写成通过。
|
||
|
||
- 接线前核桃派和屏幕都必须断电。
|
||
- HUB75 屏幕使用独立 5V 供电并与核桃派共地；不得用 GPIO 供电。
|
||
- ADC 在实屏基础画面通过后才连接；不得带电插拔。
|
||
- 低压阶梯一次只要求一个安全档位，读完软件状态和实屏结果后才给下一档。
|
||
|
||
## 5. 网络和依赖
|
||
|
||
核桃派没有 VPN。板端不得默认访问 GitHub、PyPI 或其他境外服务并长时间重试。
|
||
|
||
1. Debian 包优先使用已验证可达的国内镜像；修改源前记录原值和回退方法。
|
||
2. Python/C 源码或 wheel 若只有境外来源，由有 VPN 的电脑下载并校验，再上传离线安装。
|
||
3. 每个离线包保存 SHA-256 清单；板端安装使用 `--no-index --find-links` 或明确的本地路径。
|
||
4. 不关闭电脑 VPN，不把本机工具目录或盘符固化进项目文档和部署脚本。
|
||
5. SSH 后先在远端用 `command -v` 和版本命令检查工具，不能因电脑有工具就假设板端也有。
|
||
6. 普通功能开发不读取或重建大型镜像；只有用户明确要求导出镜像、维护离线材料或更新编辑器时才进入 `发布更新相关/` 的发布流程。
|
||
7. 新增或删除板端 Python、Debian 或原生命令依赖时属于功能修改的一部分：必须同步 `发布更新相关/其他依赖/` 的文件、SHA-256 和生命周期清单。停用依赖删除二进制并登记原因，不能等待下次镜像导出再补。
|
||
8. OTA 和可刷镜像共用 `核桃派软件源代码/VERSION` 与根目录 `发布记录.json`；只有明确导出成功才推进版本，失败不得占号或留下半成品目录。
|
||
9. 可部署的功能新增或优化必须同步更新 `核桃派软件源代码/FEATURE_UPDATED_AT`，格式固定为精确到分钟的北京时间 `YYYY-MM-DDTHH:MM+08:00`。单纯 OTA/镜像导出、重复部署和文档修改不得改写该时间。
|
||
|
||
## 6. 数据生命周期
|
||
|
||
- OTA 等跨主服务停启存活的任务必须显式保护共享运行目录。`RuntimeDirectoryPreserve=restart` 不保留单独 `systemctl stop` 的目录；主服务使用 `yes`，旧版本在停服前通过事务临时 drop-in 保护并核验。不得只改新包内尚未生效的 unit，也不得只用 mkdir 掩盖请求/进度已丢失。运行目录仍随整机重启清空。
|
||
- 涉及 systemd RuntimeDirectory、停启、回滚或独立任务的修改，必须补真实 systemd 生命周期测试。模拟 systemctl 通过不能写成真实 OTA 通过。日志写入失败不能阻止恢复动作；一次性故障证据写归档，稳定测试要求写需求与测试流程。
|
||
|
||
- 持久数据：配置、校准、模板、动图、字体和用户资源，统一保留在 `/var/lib/matrix-screen-controller`。
|
||
- 可再生数据：缩略图等专用缓存，随持久源保存，只按登记规则清理。
|
||
- 运行数据：帧快照、锁、boot 标记和临时状态，统一放 `/run/matrix-screen-controller`。
|
||
- `/opt/matrix-screen-controller` 只含可替换程序、venv、原生驱动和部署文件。
|
||
- schema 逐级单向迁移；损坏、未知字段、未来版本或不安全迁移必须保留原文件并拒绝启动，只有文件不存在才创建默认值。
|
||
|
||
## 7. 真实驱动规则
|
||
|
||
- 14 根 HUB75 信号集中使用 PI bank；物理脚 3/5 留给 I²C，物理脚 32 保留。
|
||
- C 刷新线程必须双缓冲并只在完整帧边界交换；帧格式固定 RGB888，bitplane 固定 7 bit。
|
||
- 默认 100 Hz，允许 15、20、30、45、60、80、100 Hz；状态必须报告实际刷新率、帧数、截止丢失数和最后错误。
|
||
- 刷新线程尝试 CPU3 绑定、实时优先级、内存锁定和 performance governor；能力不足必须明确报告，不能伪造优化已生效。
|
||
- 启动先保持 OE 禁用并清黑；异常、关闭、重建和进程退出都必须先禁用 OE、清空输出、恢复 GPIO 安全输入状态并释放映射。
|
||
- 正常 WebSocket 断开不得记为显示异常或在 close 后再次发送。
|
||
|
||
## 8. 清理和独立性
|
||
|
||
- 不提交 `.venv`、`__pycache__`、`.pytest_cache`、`node_modules`、运行数据、测试数据、主机密钥或历史移植临时文件。
|
||
- 临时部署、构建目录、wheelhouse 和临时 systemd unit 在验证后按明确绝对路径清理。
|
||
- 最终把本目录复制到隔离临时位置，从文档命令重新构建和运行测试；任何引用目录外文件的路径都视为失败。
|
||
- 一次性结果写在交付或 `各种归档/<时间戳>_用途/README.md`，不写进可重复测试流程。
|
||
- `发布更新相关/导出包/<版本>/` 是可随时删除的大型 IMG 发布产物。发现历史导出 IMG 缺失时，默认视为用户为节省空间主动删除，属于正常情况；不报缺失故障、不追补、不自动重建，也不得因此阻塞开发、常规测试或后续构建。源码、文档命令和后续构建不得引用其中任何文件。
|
||
- `发布更新相关/OTA数据包/` 中的 OTA 今后长期保留，不按可删除缓存清理；已缺失的 OTA 1.0.1 是用户接受的历史例外，不再追补、提醒或阻塞开发及使用。保留原发布记录，后续构建仍不得依赖历史包。
|
||
- 普通开发不检查历史 IMG 是否齐全；只有用户明确要求处理某个镜像时，才核对该任务实际需要的输入文件。官方基线和其他离线依赖按各自规则管理。
|
||
- 仓库内描述工作区文件时使用相对路径或 `<仓库根目录>`、`<受保护临时目录>` 等文字占位符，不固化盘符、Windows 用户目录、macOS 用户目录或开发者 home。核桃派上的 `/opt`、`/var/lib`、`/run`、`/boot`、`/usr/local` 等固定部署路径不属于此限制。
|
||
- 私有 Git 仓库保留正式 IMG、OTA、离线依赖、编辑器程序和历史归档；大体积二进制允许使用 Git LFS，不能通过扩大 `.gitignore` 省略应保留内容。只有秘密、本机状态、运行数据和可再生缓存由根 `.gitignore` 排除。
|