garden-cli 命令速查与急救卡

日常运维两张卡：命令速查卡（怎么用）与急救卡（出问题按顺序做什么）。全部命令板上实测，退出码 2 = 结构化失败，不是崩溃。

#一、元信息

#二、CLI 命令速查

bashCLI=~/garden-driver/garden-cli
$CLI motor position      # 位置/误差/转速/mm/占行程%（JSON）
$CLI motor drive         # 驱动器状态: 堵转/编码器/校准表/固件/开闭环  <- 排查首选
$CLI motor protect-clear # 撞死点后驱动器自锁 -> 解开
$CLI motor move 50       # 定位 50%（软限位映射后实际落 [3%,97%]）
$CLI motor up | down     # 走到软限位就停
$CLI motor calibrate     # 全自动标定（速度 12% + 末端降速）
$CLI motor stop          # 急停
$CLI status              # 全家桶 JSON

要点：motor drive 是排查电机问题的第一入口——先看驱动器自述状态，再看代码；move 的百分位是「占行程百分比」，经过软限位映射后实际落点在 [3%, 97%]。

#三、出问题急救六步

bash1. systemctl is-active ...                # 服务活着吗
2. curl -s :8080/api/status               # 面板有数据吗
3. $CLI motor drive                       # 堵转？protect-clear
4. ps -eo pid,etime,args | grep '[g]arden-cli motor' -> kill   # 残留进程占锁（别用 pkill -f）
5. journalctl -u garden-server/-voice -n 30                # 看日志
6. echo t > ~/garden-data/_t              # SD 卡还写得进吗

#四、标准工作流（每次改代码后）

bash1. 找板子:  powershell -File board_find2.ps1
2. 上传:    scp <文件> orangepi@<IP>:/tmp/     # 复杂命令一律写 .sh 再 scp
3. 板端:    echo orangepi | sudo -S cp /tmp/x /目标路径
4. 生效:
   - Python 文件:  systemctl restart garden-server / garden-mqtt-bridge / garden-voice
   - C 源码:       cd ~/garden-driver && sed -i 's/\r$//' src/*.c include/*.h && make
                   # 改了 config.h 和 .c 都要传！改了 limits/gpio 要重启 garden-local
5. 验证:    curl -s http://127.0.0.1:8080/api/status | python3 -m json.tool

#五、连接与环境

#六、GPIO 行号速查（gpiod line offset）

⚠️ 限位与按键：开关一端接 GND + 上拉 → 低电平 = 已触发。271=上 / 272=下，别交换。

#七、ZDT X42S 协议速查

地址 0x01，/dev/ttyS5 115200 8N1，帧尾 0x6B。固件 FW_Ver=201，X 固件，开环模式。手册：x42s.txt / x42s_manual.pdf。

#八、机构与标定参数（include/config.h）

行程实测 427~429mm，标定后自动停靠 20%。验收数据留档：25% 误差 0.99%、50% 0.39%、75% 0.01%、100% 0.02%；软限位全程限位开关零触发。

#九、相关链接

• 项目总览——系统架构与现状
• HAL 分层重构执行需求书（V1.1）——本速查是任务 0 回归清单的命令底表
• 踩坑索引——急救卡里每个「第一嫌疑」的完整来龙去脉
• 一次嵌入式联调踩的 17 个坑——协议帧、锁、标定背后的坑
• 开箱到 SSH：香橙派首次点亮——板子连接与配网基础

#十、更新日志