小观 Xiao Guan

冥想感知开源硬件 — 用呼吸和定力，观照当下

小观是一款开源冥想辅助设备。通过麦克风感知呼吸频率与深度，通过陀螺仪感知身体的晃动与定力。支持三种 M5Stack 硬件形态；无硬件时，可作为纯软件桌面冥想陪伴程序运行。

特性

呼吸检测 — 实时检测呼吸频率（6-30 bpm）和深度（浅 / 中 / 深），基于 IIR 带通滤波 + 峰值检测算法
定力评估 — 6 轴 IMU 加速度 → 滑动窗口方差 → 指数衰减映射 → 0-100 分稳定性评分
冥想引导 — 调息(2min) → 入定 → 结束，三阶段自动流转，颂钵音效提示
WiFi 实时看板 — 设备创建 WiFi 热点，手机浏览器即可查看呼吸曲线、定力趋势、历史记录
数据持久化 — SD 卡 / NVS 存储冥想记录，重启后自动恢复
纯软件模式 — 无硬件时用电脑麦克风 + 摄像头运行 Python 桌面陪伴程序
功耗优化 — 4 级功耗管理（全功能 → 暗屏 → 低功耗 → light sleep），Cardputer Adv 续航可达 13h+

支持的硬件

硬件	芯片	麦克风	IMU	电池	定位
M5Stack StickS3	ESP32-S3 (8MB+8MB PSRAM)	ES8311 I2S	BMI270	250mAh	音频质量最好，首选开发
M5Stack StickC Plus	ESP32-PICO-D4 (4MB)	SPM1423 PDM	MPU6886	120mAh	最小巧 (16.9g)，适合夹口罩
M5Stack Cardputer Adv	ESP32-S3FN8 (8MB)	ES8311 I2S	BMI270	1750mAh	56 键键盘 + SD 卡 + 3.5mm，续航最长

架构概览

graph TB
    subgraph 共享算法层 firmware/shared
        BD[BreathDetector]
        MA[MotionAnalyzer]
        MS[MeditationSession]
        PM[PowerManager]
        UI[UIRenderer]
        WS[WifiServer]
        SE[SoundEffects]
    end

    subgraph 设备固件
        S3[StickS3 main.cpp]
        SC[StickC Plus main.cpp]
        CA[Cardputer Adv main.cpp]
    end

    subgraph 纯软件版 companion
        CP[companion.py]
        VB[validate_breath.py]
    end

    S3 --> BD & MA & MS & PM & UI & WS & SE
    SC --> BD & MA & MS & PM & UI & WS
    CA --> BD & MA & MS & PM & UI & WS & SE

    CP --> VB

固件共享算法层以平台无关 C++ 实现，通过条件编译宏 (DEVICE_STICK_S3 / DEVICE_STICK_C_PLUS / DEVICE_CARDPUTER_ADV) 区分设备差异。

模块	职责	核心接口
`BreathDetector`	音频 → 呼吸频率 + 深度	`processAudioFrame()`, `getResult()`
`MotionAnalyzer`	IMU → 定力评分 (0-100)	`update()`, `getResult()`
`MeditationSession`	会话计时 / 阶段 / 统计	`start()`, `update()`, `getStats()`
`PowerManager`	电池 / 亮度 / light sleep	`recommendMode()`, `applyMode()`
`UIRenderer`	4 界面渲染	`drawMenu()`, `drawMeditationScreen()`
`WifiServer`	WiFi AP + Web 看板 + 历史	`begin()`, `updateLiveData()`
`SoundEffects`	PCM 颂钵 / 雨声合成	`synthSingingBowl()`, `synthRain()`

快速开始

前置条件

VS Code + PlatformIO IDE 插件
USB-C 数据线（非纯充电线）
Python 3.8+（仅纯软件版需要）

固件开发

# 1. 克隆仓库
git clone https://github.com/peace-lab-global/xiao-guan.git
cd xiao-guan

# 2. 用 VS Code + PlatformIO 打开设备目录
#    File → Open Folder → 选择 firmware/stickS3/（推荐首选）
#    等待 PlatformIO 下载工具链和依赖库（首次约 3-5 分钟）

# 3. 连接设备，编译 + 烧录
cd firmware/stickS3
pio run                  # 编译
pio run -t upload        # 烧录到设备
pio device monitor --baud 115200   # 串口监控

纯软件模式（无需硬件）

cd companion
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python3 companion.py               # 启动冥想陪伴
python3 validate_breath.py --simulate  # 算法验证（7/8 PASS）

详细步骤请参阅从零部署与调试指南

项目结构

xiao-guan/
├── firmware/
│   ├── shared/              # 共享 C++ 算法层（7 模块，平台无关）
│   │   ├── breath_detector.h/cpp     # 呼吸检测
│   │   ├── motion_analyzer.h/cpp     # 定力评估
│   │   ├── meditation_session.h/cpp  # 会话管理
│   │   ├── power_manager.h/cpp       # 功耗管理
│   │   ├── ui_renderer.h/cpp         # UI 渲染
│   │   ├── wifi_server.h/cpp         # WiFi Web 看板
│   │   └── sound_effects.h           # 音效合成
│   ├── stickS3/             # StickS3 固件
│   ├── stickC_plus/         # StickC Plus 固件
│   └── cardputer_adv/       # Cardputer Adv 固件
├── companion/
│   ├── companion.py         # 桌面冥想陪伴（麦克风 + 摄像头 + TUI）
│   ├── validate_breath.py   # 呼吸算法 Python 验证
│   └── requirements.txt
├── docs/
│   ├── project-design.md           # 架构设计与硬件规格
│   ├── getting-started.md          # 部署与调试指南
│   ├── implementation-status.md    # 实现进度追踪
│   └── M5-hardware-official-document/  # M5Stack 官方硬件参考
└── hardware/                # 3D 打印外壳（规划中）

技术栈

层级	技术
固件	C++17 / Arduino 框架 / PlatformIO
音频算法	分帧 RMS → IIR Butterworth 带通 (0.1-0.5 Hz, 4 阶 SOS) → 峰值检测
运动算法	三轴加速度方差 → 指数衰减映射
桌面软件	Python 3.8+ / NumPy / SciPy / sounddevice / OpenCV (可选)
通信	WiFi AP (ESP32 SoftAP) / SD 卡 / NVS 持久化
UI	M5GFX LCD 渲染 (固件) / ANSI 彩色 TUI (桌面)

WiFi 看板

设备启动后自动创建 WiFi 热点：

参数	值
SSID	`XiaoGuan`
密码	`meditate`
看板地址	`http://192.168.4.1`

手机连接 WiFi 后浏览器访问即可看到：实时呼吸曲线、定力趋势图、冥想会话信息、历史记录。

文档

文档	内容
用户手册	面向终端用户的使用指南：操作、WiFi 看板、桌面陪伴、FAQ
从零部署指南	环境搭建、三款设备烧录、传感器调试、FAQ
架构设计文档	完整 PinMap、算法流程、PlatformIO 配置、功耗数据
实现进度追踪	模块完成度、已知问题、后续路线
M5Stack 官方硬件参考	STL 模型、KiCad 封装、原理图

开发路线

环境搭建 → 传感器驱动 → 呼吸算法 + 定力算法 (并行)
  → 冥想会话 → 三硬件适配 → 数据记录
    → 纯软件版 (可独立并行) → 功耗优化 → 3D 外壳

建议从 StickS3 开始（音频芯片最好、内存最大），算法稳定后再移植到其他设备。

贡献指南

欢迎贡献！请按以下流程操作：

Fork 本仓库
创建特性分支：git checkout -b feature/your-feature
编写/修改代码并确保编译通过：pio run
提交变更：git commit -m "feat: add your feature"
推送并创建 Pull Request

代码规范

C++ 固件：遵循项目现有的 firmware/shared/ 模块结构，新算法放入共享层
Python：遵循 PEP 8，函数和类添加 docstring
Commit 消息：使用 Conventional Commits 格式
feat: 新功能 / fix: 修复 / docs: 文档 / refactor: 重构

报告问题

请使用 GitHub Issues 报告 Bug，包含：
- 设备型号和固件版本
- 串口日志输出
- 复现步骤

致谢

硬件平台：M5Stack — 提供开源硬件设计和文档
算法参考：音频呼吸检测基于 IIR 带通滤波 + 峰值检测经典方案
音效设计：颂钵合成参考金属共振泛音模型 (基频 + ADSR 包络)

许可

本项目基于 MIT License 开源。

小观 Xiao Guan

冥想感知开源硬件 — 用呼吸和定力，观照当下

小观是一款开源冥想辅助设备，通过麦克风感知呼吸频率和深度，通过陀螺仪感知身体的晃动和定力。支持手持、放在腿上、或挂在口罩边缘。

支持的硬件

硬件	芯片	特点
M5Stack StickS3	ESP32-S3	音频质量最好，适合呼吸检测
M5Stack StickC Plus	ESP32-PICO-D4	最小巧 (16.9g)，适合夹口罩
M5Stack Cardputer Adv	ESP32-S3FN8	续航最长 (1750mAh)，有键盘和SD卡

功能

呼吸检测：实时检测呼吸频率（次/分钟）和深度（浅/中/深）
定力评估：通过 IMU 检测身体微动，评估冥想稳定性（0-100分）
冥想引导：调息→入定→结束，三阶段引导
数据记录：SD卡/WiFi 保存冥想记录
纯软件模式：无硬件时可用电脑麦克风运行 Python 陪伴程序

项目结构

xiao-guan/
├── firmware/                  # 固件代码
│   ├── shared/                # 共享算法（呼吸检测、定力分析、会话管理、UI、功耗）
│   ├── stickS3/               # StickS3 固件
│   ├── stickC_plus/           # StickC Plus 固件
│   └── cardputer_adv/         # Cardputer Adv 固件
├── companion/                 # Python 纯软件冥想陪伴程序
├── docs/                      # 文档
└── hardware/                  # 3D打印外壳设计（规划中）

快速开始

固件开发（需要 PlatformIO）

# 1. 安装 VS Code + PlatformIO 插件

# 2. 用 PlatformIO 打开对应设备目录
#    例如：打开 firmware/stickS3/

# 3. 连接设备，点击 Upload 烧录

纯软件模式（需要 Python 3.8+）

cd companion
pip install -r requirements.txt

# 运行冥想陪伴程序
python companion.py

# 运行呼吸算法验证
python validate_breath.py --simulate    # 模拟测试
python validate_breath.py               # 实时麦克风测试

技术栈

固件：C++ / Arduino 框架 / PlatformIO
算法：音频 RMS 能量分析 + IIR 带通滤波 + 峰值检测
软件：Python / NumPy / SciPy / sounddevice
通信：WiFi AP / SD 卡存储

许可

MIT License

xiao-guan

小观～冥想辅助开源硬件