智能花园养护机 · 项目总览（Orange Pi Zero 2W）

这是「项目卷宗」的总览篇：一份档案看全智能花园养护机——它是什么、五层架构怎么分、硬件与目录地图、时间线与现状。细节按链接跳到另外三份卷宗，方法论与完整复盘在博客长文里。

#一、元信息

#二、一分钟看懂

• 这是什么：植物养护机。主控香橙派 Zero 2W + 自研底板，底层自研 C 命令行驱动，上层 Python 网页面板、Home Assistant 仪表盘、微信小程序、华为云 IoTDA、离线语音控制全套接齐。
• 能干什么：皮带滑台升降（闭环步进 429mm 行程，软限位不碰开关）、两路 24V 灯带调光、两路三色指示灯、水泵、超声波水位（空 40cm / 满 12cm）、电源监测 INA219x3、摄像头快照（装在滑台上）、29 条离线语音指令。
• 设计基调：硬件操作只走一个入口（garden-cli），一次调用干一件事，跨进程状态用文件交换——「哑工具 + 聪明胶水」的组合让上层怎么换都不伤底层。

#三、系统架构：五层与三条铁律

text[硬件] ZDT X42S 闭环步进(UART /dev/ttyS5 115200) / PCA9685(I2C) / INA219x3(I2C)
       AHT20 / BH1750 / ADS1115(I2C) / RCWL-1670 水位(GPIO) / 硬件PWM灯带 / 限位+按键(GPIO)
   |
[garden-driver]  C 程序  ~/garden-driver/garden-cli   <- 一切硬件操作的唯一入口
   |  subprocess
[garden-server]  Flask :8080  ~/garden-server/server.py   <- HTTP API + 网页面板
   |  HTTP
[garden-mqtt-bridge]  ~/garden-mqtt-bridge/bridge.py      <- HA 实体发现 + 命令转发
[garden-voice]   ~/garden-voice/garden-voice.py           <- 本地离线语音控制(Vosk)
   |
[Home Assistant]  docker :8123   仪表盘(分区视图)     [华为云 IoTDA] [微信小程序]

三条铁律（违反必出事，全部是血泪实测）：

1. 硬件操作只经 garden-cli，禁止在 server / voice / bridge 层直接碰 I2C / GPIO / UART；
2. 华为云对接不得改动现有 HA 链路（详见 garden-mqtt-bridge/HANDOVER-HUAWEI-IOT.md）；
3. 语音命令的 API 调用必须放后台线程——同步调用会卡死识别主循环（坑 27）。

#四、硬件清单

#五、目录地图

本地工作副本在 D:\ai\TREA\orangepi\，板上 ~/garden-*。核心目录：

#六、时间线与现状

已完成：回零标定（429mm）、急停三步、继续键全链路、水位标定 40→12cm、七彩 10s/圈、呼吸压暗、电源 6s 采样、HA 仪表盘 v5、离线语音 29 词、水泵幽灵自开修复、工具脚本持久化。

待办：

• [紧急] 备份并更换 SD 卡（间歇性只读 EROFS，全盘 img 已备好）；
• 「继续」功能最终确认（curl 返回 NO_TARGET=已部署；404=按交接 v2 4.1 节重发 server.py）；
• 语音硬件升级：USB 声卡 + 外接麦克风（几十元，插上改一个环境变量即可）；
• HAL 分层重构（需求书 V1.1 已定稿，待执行 / 验收）。

运维速查：6 个 systemd 服务应全部 active——garden-server / garden-mqtt-bridge / garden-voice / garden-local / mjpg-streamer / garden-tools。garden-local（物理按键接管 + 限位急停）每 10 分钟自动轮换重启是设计行为，不是故障。

#七、卷宗导航

本卷宗共 4 篇，互相引用，建议按序阅读：

• 项目总览（本篇）——是什么、架构、现状；
• HAL 分层重构执行需求书（V1.1 档案）——给 AI 执行者的完整契约：签名表、移植红线、坑位清单、验收标准；
• garden-cli 命令速查与急救卡——日常运维与出问题时的 6 步急救；
• 踩坑索引（34 坑主题分组）——全部坑位的一句话教训 + 跳转。

博客侧的完整叙事：

• 一次嵌入式联调踩的 17 个坑——坑 1~17 的「现象-排查-根因-修法」完整复盘；
• 开箱到 SSH：香橙派 Zero 2W 首次点亮全流程——项目的起点；
• 我是怎么给 AI 写执行需求书的——HAL 需求书背后的方法论。

#八、更新日志