# 智能健身教练 ***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.*** --- 本项目以 Quectel Pi M2 智能主控板作为 AI 边缘计算平台，通过 USB 摄像头实时识别 17 个人体关键点，对深蹲、开合跳、高抬腿、弓步蹲、侧平举、马步蹲六种健身动作进行 **实时计次（计时）、动作纠错和语音播报**，打造一块开箱即用的 AI 健身镜。 应用由 M2 板载 NPU（6 TOPS）完成 AI 姿态识别推理（约 55 毫秒/帧），全程 **离线运行**，画面与数据不离开设备；界面为中英双语漫画风格，语音支持中文（晓晓）与英文（Jenny）两种音色，适合边缘 AI 能力展示和智能健身产品原型评估。 # 开发配件清单 说明：以下为推荐开发配件，实际使用时可根据展示场景灵活调整。 | **配件名称** | **数量** | **规格参数** | | --- | --- | --- | | Quectel Pi M2 智能主控板 | 1 块 | - | | USB 摄像头（含麦克风） | 1 个 | UVC 协议，支持 720p MJPG | | 扬声器 | 1 个 | [2030腔体喇叭8Ω 2W方形喇叭高音质小体积扬声器]() | | HDMI 显示器（可选） | 1 个 | 有 HDMI 显示器也可，无屏可运行无界面模式 | | 网线 | 1 根 | 用于 SSH 登录与代码拉取 | | Type-C 电源适配器 | 1 个 | 主控板供电 | | 杜邦线/螺丝刀 | 若干 | - | # 配件实物参考 ```{image} images/image_UhJzbzlmUoGg9fxZyRbc6WULn5g.webp :width: 1067px :height: 602px :align: center ``` # 快速上手 ## 环境要求 - Quectel Pi M2 智能主控板，运行出厂 Debian 13 桌面环境（无需任何额外系统配置）。 - 一台可以进入 M2 桌面的 HDMI 显示器。 - 一个 USB UVC 摄像头和一只喇叭（3.5mm 或蓝牙）。 - **无需联网、无需安装任何依赖、无需编译**——安装包已内置全部运行环境（Python、AI 推理引擎、界面库）、AI 模型和中英文语音资源（解压后约 1GB）。 - 普通用户需在 `video`、`audio` 用户组，摄像头和声音才能正常使用。 ## 关键技术指标 应用的关键技术指标如下： | **项目** | **参数** | | --- | --- | | 姿态识别模型 | YOLO11n-pose，fp16 精度（不量化） | | 人体关键点 | 17 个，实时骨架跟随 | | AI 推理 | 板载 NPU（6 TOPS），约 55 毫秒/帧 | | 支持动作 | 深蹲、开合跳、高抬腿、弓步蹲、侧平举（计次）＋ 马步蹲（计时） | | 语音与界面 | 中英双语一键切换；语音离线播报，中文晓晓 / 英文 Jenny | | 运行方式 | 完全离线，画面与数据不离开设备 | | 安装体积 | 安装包约 215MB，解压后约 1GB（内置全部运行环境、模型与语音资源） | # 硬件连接 完成以下所有硬件的连接操作，连接接口示意图如下： ```{image} images/image_Z1wkb74VxoivPXxaaPOcfjobnZf.webp :width: 627px :height: 463px :align: center ``` 1. **显示连接**：HDMI线一端接主控板HDMI接口，另一端接显示器HDMI接口； 2. **网络连接**：千兆网线一端接主控板千兆网口，另一端接路由器网口（替代方案：通过Wi-Fi接入同一局域网）； 3. **输入设备连接**：USB键盘、鼠标接入主控板的两个USB-A接口，无线输入设备则将接收器插入USB口即可； 4. **供电连接**：USB-A电源线的USB-A端接电源适配器，USB-C端接入主控板标注 **POWER IN** 的电源口。 ## 一键部署 整个应用打包成一个自解压安装包 `ai-fitness-coach-installer.run`（约 215MB）。把它送到板子上执行一次即可，安装过程约 1~2 分钟。 **第 1 步：把安装包送到开发板**（两种方式任选其一） 方式 A —— U 盘拷贝（最直观）： 1. 把 `ai-fitness-coach-installer.run` 拷入 U 盘； 2. U 盘插入开发板，在文件管理器中把它复制到家目录。 方式 B —— adb 推送（开发调试常用）： ```bash adb push ai-fitness-coach-installer.run /home/q/ ``` **第 2 步：在开发板终端执行一条命令** 打开终端，进入安装包所在目录执行： ```bash ./ai-fitness-coach-installer.run ``` - 默认安装到当前用户主目录 `~/ai-fitness-coach`；也可以在命令后跟一个目录参数指定安装位置。 - root 用户与普通用户均可安装；重复执行会自动清理旧版本并重装。 **第 3 步：完成，双击启动** 安装完成后，打开文件管理器，进入 `ai-fitness-coach/code/`，**双击`ai-fitness-coach`** 即可运行——不是脚本，是编译好的启动器，双击直接执行，不会弹出「运行还是显示」对话框。 - 重复双击 = 自动重启应用（会先停掉旧实例）； - 按 **Esc** 退出应用； - 运行日志自动记录在 `~/.local/state/fitness-coach/app.log`。 # 应用使用方法 ## 主界面 ```{image} images/image_Ztrqb0OhworrlPxYWB0cdn1HnRC.webp :width: 800px :height: 506px :align: center ``` 主界面主要包含以下区域： 1. 顶部标题栏与语言切换（右上角 **EN / 中** 按钮）。 2. 实时预览区：镜像画面（符合自拍直觉）+ 17 个关键点骨架实时跟随，下方一排是「− ＋ 1.0x」数字变焦按钮。 3. 计数/计时卡片：显示当前动作的成绩。 4. 阶段栏：显示当前状态（待机中/站立/下蹲中/未检测到人等）和纠错提示。 5. 控制按钮：**▶ 开始训练（训练中变橙色「暂停」）、归零**、**结束训练**。 6. 动作选择框：点击展开动作列表弹层，六种动作即选即练，每行附「▶ 演示」参考视频按钮。 ## 开始训练：待机 → 训练中 → 暂停 应用启动后默认处于 **待机** 状态——只预览、不计次。这是有意设计的防干扰机制： 1. 点击蓝色 **▶ 开始训练**，语音播报「三、二、一，开始」，正式开始计次； 2. 训练中按钮变为橙色 **暂停**，点一下冻结成绩；暂停期间在镜头前随意走动、休息都不会被计入； 3. 再点 **▶ 继续训练** 恢复，成绩接着累计； 4. **归零** 按钮把次数和计时清零，重新开始一轮。 ## 切换训练动作 点击右侧选择框，在窗口内展开动作列表：**深蹲、开合跳、高抬腿、弓步蹲、侧平举、马步蹲** 六种动作任选（马步蹲显示坚持秒数，其余显示次数）。每一行右侧带「▶ 演示」按钮，点击后在视频区播放该动作的标准示范视频，播完自动收起，也可点 ✕ 提前关闭，跟练时作为动作参照；马步蹲暂未收录示范视频，点击时提示「该动作暂无演示视频」。 ```{image} images/image_OlT8bEcR1ohZnsxCUrucdGQrnla.webp :width: 800px :height: 506px :align: center ``` - 当前选中的动作前有 **▶** 箭头指示； - 切换时语音播报动作名称 + 「三、二、一，开始」； - 切换有 1.5 秒冷却和防误触保护，运动中手扫到屏幕不会误切。 - 点击弹层外的任意位置可收起列表；弹层固定在窗口内、紧贴选择框正下方展开。 ## 数字变焦 预览区下方提供「− ＋ 1.0x」三个变焦按钮：＋ 放大、− 缩小、**1.0x** 一键复位，右侧实时显示当前倍数。变焦范围 **0.5~3 倍**，步进 0.25 倍，也可以用键盘快捷键 `+`（放大）、`-`（缩小）、`0`（复位）控制。 变焦采用中心裁剪放大，**AI 识别与骨架跟随在放大后的画面上进行**——距离较远、人物在画面中偏小时，适当放大可以让关键点识别更稳定。 ## 中英文切换 点击右上角 **EN** 按钮，界面文案、提示信息与语音播报整体切换为英文；再点 **中** 切回中文。 ```{image} images/image_MBUibkl0SosRO1xWg4qcPdGDnMh.webp :width: 800px :height: 506px :align: center ``` ## 语音播报 喇叭直接接在主控板 3.5mm 音频口即可听到全部语音（也支持蓝牙音箱，跟随系统输出设备）： - 启动欢迎语与动作模式名（如「深蹲模式」）； - 「三、二、一，开始」倒计时； - 每次完成动作报数，每 10 个播报一次鼓励语； - 实时纠错提醒，例如「膝盖出镜了，后退一点」「弯腰了，请蹲下而非弯腰」。 ## 站位与动作要领 | **要点** | **建议** | | --- | --- | | 深蹲站位 | 距摄像头 **2.5~3.5 米**，正面朝向摄像头；下蹲时 **膝盖保持在画面内**（出镜会语音提醒） | | 深蹲标准 | 蹲到大腿差不多与地面平行（膝角约 115°）才计一次；蹲不到位会提示「上次蹲不够深（角度） 未计次」 | | 开合跳站位 | **全身入镜**，距 2.5~4 米；双脚分开超过 1.35 倍肩宽且手腕过头顶算「打开」，回到并拢计一次 | | 高抬腿 | **全身入镜**；任一膝抬至髋部高度（大腿抬平）再落地计 1 次，左右腿独立计次 | | 弓步蹲 | 正面朝向摄像头，一腿向前弓步下蹲；弯曲腿膝角低于约 135° 才计次，上身保持挺直（过度前倾不计次） | | 侧平举 | 双臂 **同时** 抬起、手腕过肩线计 1 次，双臂回落开始下一次；侧平举、前平举均可识别 | | 马步蹲 | 双脚分开超过 1.1 倍肩宽、蹲至膝角约 135° 以下开始计时；中途起身休息 **不清零**，坚持秒数持续累计 | | 光线 | 环境光线充足、避免逆光，识别更稳定 | # 应用演示 ## 演示视频 完整功能导览视频（约 81 秒，1280×810）：以 USB 摄像头实时画面为背景，自动走一遍应用全部功能入口——动作列表与标准动作示范（播完自动收起）、开始训练、计次演示、暂停/继续、归零、数字变焦、中英文切换、结束训练，配 AI 旁白与字幕。
ai-fitness-coach-demo-v5
# 常见问题排查 ## 启动后画面全黑或提示「未检测到人」 1. 确认 USB 摄像头已插好（可换一个 USB 口）。 2. 检查环境光线是否充足、是否逆光。 3. 确认人物在画面内且距离适中（2.5~3.5 米）。 4. 确认当前用户在 `video` 用户组：终端执行 `groups` 查看，缺失时执行 `sudo usermod -aG video "$USER"` 后重新登录。 ## 没有声音 1. 确认喇叭已接在主控板 3.5mm 音频口（或蓝牙已配对连接）。 2. 检查系统音量与输出设备（设置 → 声音，选择对应输出）。 3. 确认当前用户在 `audio` 用户组，缺失时执行 `sudo usermod -aG audio "$USER"` 后重新登录。 ## 深蹲不计数 按顺序检查： 1. 是否处于待机或暂停状态（需先点「▶ 开始训练 / 继续训练」）。 2. 是否站得太近：蹲下时膝盖或髋部出画面，界面会提示「膝盖出镜了，后退一点」——后退到 2.5 米以外。 3. 是否蹲得不够深：阶段栏会显示「上次蹲不够深（角度） 未计次」，蹲到大腿接近平行地面即可。 ## 开合跳不计数 开合跳要求 **全身入镜**。后退到 2.5~4 米，确保头顶和脚都在画面内；跳开时双脚间距超过 1.35 倍肩宽、双手手腕过头才算完整动作。 ## 双击启动器没反应 1. 确认双击的是 `ai-fitness-coach`（无扩展名的启动器），不是 `run.sh`。 2. 再双击一次即可——启动器会自动停掉旧实例并重启应用。 ## 想查看运行日志 ```bash tail -f ~/.local/state/fitness-coach/app.log ``` # 技术支持与贡献 如在使用或二次开发过程中遇到问题，建议提供：系统固件版本、摄像头型号、完整界面提示与 `app.log` 日志片段。欢迎在 [移远官方论坛]() 提交技术咨询，我们的技术支持团队将及时为您解答。 项目开源地址： https://github.com/Quectel-Pi/demo-ai-fitness-coach