# desktop-status-sign

**Repository Path**: dpp5258/desktop-status-sign

## Basic Information

- **Project Name**: desktop-status-sign
- **Description**: 基于黄山派 SF32LB52‑ULP 开发板，采用 BLE 实现电脑与硬件双向通信的桌面智能状态提示终端。基础必达功能采用瀑布开发，拓展功能采用敏捷增量迭代。支持消息提醒、多页面显示；拓展包含电脑状态监测、低功耗休眠、本地小游戏等。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-13
- **Last Updated**: 2026-11-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 桌面状态牌（Desktop Status Sign）

> 黄山派 SF32LB52 课程项目 P17。一块摆在桌上的 390×450 小屏，把**电脑的实时状态**（时间、电量、是否插电、网络、待办任务、闹钟、CPU/内存/磁盘）显示出来，并支持**闹钟/任务到点提醒（断连也响）**、**AI 助手问答并用板载喇叭念出来**、**室内光感建议**、**倾斜小游戏**。

| 一句话 | 说明 |
|---|---|
| 产品形态 | 板子负责显示 + 发声 + 触摸；**电脑负责采集、决策、写数据**（PC 是唯一写者） |
| 通信 | BLE 自定义 GATT + ASCII 行协议，**协议 v2.6**（`U=` / `C=` / `I=` / `ALM:` / `AI:` / `LUX:` / `S=` / `PING`） |
| 不做什么 | 板端不联网、不做端侧推理、不调屏幕亮度（P-8 已证伪）；中文只在喇叭里念，屏幕上只显示英文（字库限制） |

## 现在能做什么（7 个 app）

| app | 内容 | 需求 |
|---|---|---|
| **Home** | 大时钟 + 日期、BATT / NET / CHG / BLE、任务前 3 条、系统开机时长与 heap、footer `upd Ns`（最后更新时刻，断连变 `STALE`） | REQ-001/002/003 |
| **Task** | 任务列表：优先级着色（≥80 红 / ≥50 橙）、超长标题行内省略号、点进详情看全文 | REQ-003 |
| **Settings** | 屏保档位（15/30/60/always on）、是否显示网络项 —— **掉电不保存**（RAM 桩，见已知限制） | REQ-203 |
| **Alarm** | 最多 4 条闹钟（一次性/每天重复），到点弹窗 + 响铃；断连仍生效；60 s 自动关闭；10 min 漏触发宽限 | REQ-208/213 |
| **AI** | 摘要 + 四项指标 + 状态行 + 三个请求按钮（SPEAK / STOP / MUTE）。回答由 PC 侧大模型生成、数字经白名单校验、板载喇叭念中文 | REQ-210/213 |
| **LUX** | 室内光感三档建议（DARK / OK / BRIGHT + 一句话），**只给建议不调亮度**；阈值 12/32 来自实测 | REQ-207 |
| **Game** | 倾斜跑酷小游戏，单 canvas 自绘、三档难度、最高分持久化 | REQ-209 |
| **立牌页**（不是 app，容器第 3 页） | 首页**往右滑**进入，整屏一张卡通图，常亮不睡屏；PC 端「🖼 立牌」可把任意图片在 **1.24~3.1 秒内换掉（走 BLE，不刷机）**（实测：128×144 1.24 s / 130×150 1.43 s / 195×225 3.1 s），断电回到固件内置图 | C-15（非需求项，见 `docs/01` §9） |

PC 端配套程序（`host/`）共 **7 个页面**：任务管理、设备状态、闹钟、AI 助手（含自然语言指令「3 分钟后提醒我喝水」）、游戏成绩、光感建议、立牌卡。

## 快速开始

### 1. 编译固件并烧录

```powershell
# 需要 SiFli SDK v2.5.1 + 工具链（见 training/T0）
. <你的 SDK 根>\sdk_env.ps1
cd project
scons --board=sf32lb52-lchspi-ulp -j8          # 产物 project/build_.../main.bin

# 烧录（sftool 随 SDK 工具链安装；COMx 换成你的下载口）
sftool.exe -p COM6 -c SF32LB52 -m nor write_flash `
  "bootloader\bootloader.bin@0x12010000" "main.bin@0x12020000" "ftab\ftab.bin@0x12000000"
```

> 注意：**打开串口会复位板子**（DTR/RTS 接在复位线上）。若要同时抓串口日志与 BLE 连接，
> 顺序是：先开串口 → 等约 9 s 板子启动完 → 再连 BLE。

### 2. 跑 PC 端

```powershell
pip install -r requirements.txt
python host/app.py --connect --addr <板端MAC> --log     # --log 把链路日志镜像到控制台
```

GUI 顶部有连接条（可扫描选板），连接成功后会把 MAC 记到 `host/data/session.json`，下次 `--connect` 直接复用。

> **日常入口只有一个：`host/app.py`。** `host/main.py` 是 2026-10-18 之前的无界面推送脚本，
> 能力已被 `app.py` 完全覆盖，**只保留 `--dry-run`（不连板子、打印会发什么）供排障**。

### 3. 不启 GUI 也能测

```powershell
python tools/say.py --text "测试播报"                    # 让板子念任意中文（TTS + 流式下发）
python tools/ask.py --q "电量还有多少"                    # 事实 → 模型措辞 → 数字校验 → 板端播报
python tools/ask.py --cmd "3 分钟后提醒我喝水" --yes      # 自然语言建闹钟
python tools/serial_log.py --port COM6 --seconds 60 --out my.log   # 串口取证
```

## 目录结构

```
desktop-status-sign/
├── project/                SiFli SDK 工程（SConstruct、proj.conf、板级配置）
├── src/                    板端固件：app_container（三级导航）+ apps/<模块>/ + app_ble（协议）+ app_audio
├── host/                   PC 端（PyQt6）：core/（链路·推送·契约）modules/（上下文·助手·TTS·指令）ui/pages/
├── docs/                   过程文档：00 计划 / 01 需求 / 02 设计 / 03 测试计划 / 04 测试报告 / 05 研制总结 / 06 风险台账 / 固件清单
├── evidence/               证据：M2 预研、M3 真机验收（**索引在 `evidence/M3/README.md`**）
├── release/                交付用可烧录固件（bootloader / main / ftab，校验值见 `docs/固件清单.md`）
├── tools/                  工具 28 个：say / ask / serial_log / memsize / gen_prompts / gen_standee / push_image / soak_long / ble_soak2 / 各模块自检……（见 tools/README.md）
└── scripts/                课程检查：check_all、check_manifest、check_devlog、new_devlog
```

## 验收状态（2026-11-08 板前验收完成，2026-11-14 文档收口）

23 条需求：**通过 17**、部分通过 2（REQ-204 降级口径、REQ-209 帧率判据按 C-13 放宽）、
不适用 4、**未执行 0**。逐条结论与证据见
[`docs/04-测试报告.md`](docs/04-测试报告.md) §5 的覆盖矩阵。

最终交付固件 `main.bin` **2,486,420 B**，Flash **29.6%** / SRAM **61.7%** / PSRAM **12.6%**，
提交号与校验值见 [`docs/固件清单.md`](docs/固件清单.md)，可烧录文件在 `release/`。
交付标签：**`v1.0.1`**（最终交付 · 文档收口版）/ `v1.0.0`（2026-11-08 板前验收版，保留不动）——两者之间只有文档提交，固件同一份。

**必须先说的三件事**（都在报告里如实记录，不是隐藏项）：

1. **REQ-207「读取失败显示 `--`」这一步不可执行**：SDK 的 `LTR303_ReadVisible()` 读失败即 `RT_ASSERT`，固件会停住，页面失败分支走不到（三档实测本身通过）；
2. **REQ-209 的 Hard 档 14.1 fps 低于最初的 15 fps**：判据已按 **C-13** 调整为 12 fps —— **这是放宽判据，不是优化到位**；
3. **板端上没有中文**：字库从未集成（REQ-007 暂缓，`docs/06` R-22），任务标题与闹钟标签在下发前统一 ASCII 化；**能听见中文（PC 端 TTS），看不见中文**。

其他已知限制（BLE 无鉴权、板端 RTC 无电池需 PC 对时、设置项掉电不保存、串口未接入行协议、
**固件不是字节级可复现**）见 [`docs/06-风险与问题台账.md`](docs/06-风险与问题台账.md)
与 `manifest.yaml` 的 `known_issues`。

## 从零复现（别人 clone 下来要装什么）

| 依赖 | 版本 / 说明 |
|---|---|
| SiFli SDK | **v2.5.1**（`course.config.json` 锁定），激活脚本 `sdk_env.ps1` 把 scons 与 `arm-none-eabi-*` 放进 PATH |
| 板型 | `sf32lb52-lchspi-ulp`（黄山派 SF32LB52） |
| PC 端 Python | 3.13（用官方 CPython，**不要用 conda**：PyInstaller 打不出 BLE 需要的 DLL） |
| PC 端依赖 | `pip install -r requirements.txt`（PyQt6 / bleak / pyserial / pillow / psutil / edge-tts / miniaudio） |
| 固件编译 | `. <SDK根>\sdk_env.ps1` → `cd project` → `scons --board=sf32lb52-lchspi-ulp -j8` |
| 内存账单 | 同一个已激活的终端里 `python tools/memsize.py`（没激活会因找不到 `arm-none-eabi-size` 而只报 Flash） |

> AI 助手页需要 `AI_API_KEY` 环境变量（或 `temp/_apikey.txt`，已被 `.gitignore` 忽略）。
> **密钥不进仓库、不打进 exe**；没有 key 时该页会明确提示并禁用，其余功能不受影响。

## 文档导航

| 想了解 | 看这个 |
|---|---|
| 需求与判据、变更记录（C-01…C-15） | [`docs/01-需求规格说明.md`](docs/01-需求规格说明.md) |
| 架构、模块契约、协议追踪表 | [`docs/02-方案设计说明.md`](docs/02-方案设计说明.md)、[`docs/design/协议契约.md`](docs/design/协议契约.md) |
| 用例与执行情况 | [`docs/03-测试计划.md`](docs/03-测试计划.md)、[`docs/04-测试报告.md`](docs/04-测试报告.md) |
| 交付固件与校验值 | [`docs/固件清单.md`](docs/固件清单.md)、`release/` |
| 现场怎么演示、怎么答问（**只带这一页**） | [`docs/guides/答辩速查一页纸.md`](docs/guides/答辩速查一页纸.md)（电梯词/数字对账/问答/兜底）；逐幕素材见 [`docs/guides/演示讲解脚本.md`](docs/guides/演示讲解脚本.md) |
| 答辩 PPT（结构说明 + 可直接改的 pptx） | [`docs/guides/答辩PPT骨架.md`](docs/guides/答辩PPT骨架.md)、`docs/答辩PPT骨架.pptx` |
| 每周做了什么、踩了什么坑 | [`docs/devlog/`](docs/devlog/) |
| 历史过程文档（**非交付物**） | [`docs/internal/`](docs/internal/)：组员开工指南、答辩前问题清单——已标"历史存档"，勿据此判断项目进度 |
| 交给评审的清单 | [`manifest.yaml`](manifest.yaml) |

---

# 附录：课程脚手架规范（原文保留）

> 本仓库的 `scripts/`、`.githooks/`、`training/`、`course.config.json` 等来自课程统一起点脚手架，
> 未改动其检查逻辑。下面这些规范是评分依据，原样保留。

## 重要提醒

1. **不要用 `git commit --no-verify`**，也不要删改 `.githooks/`、`scripts/check_*.py`、`course.config.json`、`CLAUDE.md`/`AGENTS.md`——这些改动会出现在历史里。
2. agent 写的文档/代码/日志，**你必须读过、验证过**再提交；`AI协作:` 里写的“人工修正”必须是真的。
3. 没有条件做的物理验证，如实写进 `known_issues`；编造证据按学术诚信处理。
4. 密钥、令牌、隐私信息不要进仓库，也不要出现在 `logs/` 里。
5. `src/` 下只有 `main.c` 含 `main()`；新增模块不要再定义 `main`。`project/` 下的 `SConstruct`、`Kconfig`、`rtconfig.py` 是 SDK 骨架，不要随意改。
6. 编译产物在 `project/` 下生成（`build_*/`、`sifli_sdk/`、`src/`，已在 .gitignore），不要提交。

## 常见问题

**Q：初始状态为什么有 FAIL？** 开发日志的 FAIL 来自还没写日志；manifest 的警告来自模板未填写，都是预期的，按训练逐个处理。

**Q：不在 GitHub 上，能用 Gitee 吗？** 可以。所有检查都是本地 Python 脚本，CI 可用任意平台的流水线执行 `python scripts/check_all.py`。

**Q：我的 agent 工具读不到 CLAUDE.md/AGENTS.md？** 把 `AGENTS.md` 全文粘贴到会话开头，并在 `manifest.yaml` 里如实填写 `dev_agent.tool`。

**Q：Windows 下钩子不生效？** 使用 Git for Windows，确认 `git config core.hooksPath` 为 `.githooks`；仍有问题时运行 `python scripts/check_commit_msg.py --log` 手动自查，并告知教师。