MicheleMercuri/mondeer-bluetooth-scale-ha

# Mondeer 蓝牙秤 — Home Assistant 集成 一个针对 **Mondeer 蓝牙浴室秤**（及其所属的 OEM 系列）的 Python BLE 监听器，可通过 MQTT 与 Home Assistant 集成，此外还提供了一个 **原生 Android 伴侣应用** (Kotlin/Compose)，可显示实时读数、身体成分仪表盘，并支持导出到 **Health Connect**（从而让 Samsung Health、Google Fit、Fitbit 等应用自动读取数据）。 原有的 Android 应用 (`com.mondeer.scale`) 在 Android 14+ 上已停止运行，且制造商从未发布过更新。本项目是对该应用使用的 BLE 协议进行逆向工程的结果，随后用 Python 重新实现了该协议，使得该体重秤可以 **完全脱离手机** 使用：一台放在秤附近且始终开启的小型 PC 会捕获每一次称重数据，并将其推送到 Home Assistant。  称重过程实录（10 秒剪辑 — 站在秤上，监听器捕获到 BLE 广播，Telegram 通知送达）： https://github.com/user-attachments/assets/824917a9-eb28-4c1b-8bd9-1f998bba79bc Telegram 通知示例：  ## 功能 - **无需手机**：任何支持 BLE 4.0+ 且始终开启的 PC 均可作为桥接设备 - **完整的身体成分分析**：体重、脂肪百分比、水分百分比、骨量、肌肉、内脏脂肪、BMR (kcal)、BMI — 与 Android 应用显示的数值完全一致 - **多用户支持**：最多可在秤中注册 8 个家庭用户配置 - 内置 **意大利风格的 HA 仪表盘**（3 列家庭视图）— 易于重新定制样式 - **每次称重仅发送一次 Telegram 通知**（在 BIA 完成前会过滤掉初步记录） - **针对不稳定的 BT 芯片组具有强健性**：可配置的自动恢复、智能退避策略、可选的预先配对 - **无需 Android 应用** — 该秤完全由 Python 驱动 ## 工作原理 ``` ┌───────────┐ BLE ┌──────────────────┐ MQTT ┌─────────────────┐ │ Mondeer │◀──────▶│ Listener (PC) │─────────▶│ Mosquitto │ │ scale │ │ Python + Bleak │ │ + Home Assistant│ └───────────┘ └──────────────────┘ └─────────────────┘ ~10s window sensors, dashboard, per weighing automations, Telegram ``` 当有人站上秤时，秤会开启约 10 秒钟，广播一个主服务 UUID 为 `0xcc08` 的 BLE 外设，随后关机。监听器保持着一个永久运行的 BLE 扫描器，当广播数据包出现时进行即时连接，并在不到一秒的时间内完成完整的握手过程（绑定 → 配置文件注册 → 时间同步），从而为 BIA 测量留出足够的完成时间。 更详细的协议说明请参见 [docs/PROTOCOL.md](docs/PROTOCOL.md)。逆向工程的方法论记录在 [docs/REVERSE_ENGINEERING.md](docs/REVERSE_ENGINEERING.md) 中。 ## 快速开始 ### 1. 监听端（秤附近的任意 PC） 需要 **Python 3.10+** 和一个可正常工作的 BLE 适配器（BT 4.0 或更新版本）。 ``` git clone https://github.com/MicheleMercuri/mondeer-bluetooth-scale-ha.git cd mondeer-bluetooth-scale-ha python -m venv .venv .venv/bin/pip install -r listener/requirements.txt # Linux/macOS # .venv\Scripts\pip install -r listener/requirements.txt # Windows cp listener/config.example.yaml listener/config.yaml # 编辑 listener/config.yaml：HA url、MQTT credentials、family profiles python -m listener.scale_listener ``` 站上体重秤并观察日志：你应该能看到 `scale advertising` → `connect OK` → `VALID WEIGHT ...kg fat=...%`。 若要将此作为 Windows 后台服务安装（登录时自启动，崩溃时自动重启），请参见 [deploy/windows/README.md](deploy/windows/README.md)。 关于 systemd 的配置，请参见 [deploy/linux/README.md](deploy/linux/README.md) (TODO)。 ### 2. Home Assistant 端 将 [home_assistant/packages/bilancia.yaml](home_assistant/packages/bilancia.yaml) 复制到你的 HA `config/packages/` 目录中。它声明了： - 3 个 MQTT 传感器 `sensor.peso_`（每个家庭配置各一个） - 辅助实体 `input_select`/`input_number`，用于设定性别、年龄、身高、体重范围 — 可从仪表盘直接编辑 - 用于派生指标（BMI、状态、差值）的模板传感器 - 一个 Telegram 通知自动化（带有具备 `is_complete` 感知功能的过滤器） 然后，将 [home_assistant/dashboards/bilancia.yaml](home_assistant/dashboards/bilancia.yaml) 中的仪表盘视图添加到你的 Lovelace 配置中。 完整的 HA 集成指南：[docs/HOME_ASSISTANT.md](docs/HOME_ASSISTANT.md)。 ## 兼容性 Mondeer 体重秤与同一家 OEM 系列下的其他几个贴牌型号使用了相同的蓝牙芯片和协议。只要符合以下条件的 BLE 浴室秤，本监听器都应能正常工作（可能需要进行微调）： - 广播的主 BLE 服务为 `0xcc08` - 在 `cmd=2 data=4` 上发送 32 字节的体重记录 已识别的兼容广播模式的技术名称记录在 [docs/PROTOCOL.md](docs/PROTOCOL.md) 中。 非常欢迎大家报告可用/不可用的体重秤型号 — 请开启一个 issue，并附上设备名称、BT MAC OUI 以及几行 `pkt dev=...` 日志。 ## 仓库布局 ``` . ├── listener/ # Python BLE listener + MQTT publisher │ ├── parser.py # 20-byte BLE packet decoder, frame reassembly │ ├── scale_listener.py # main loop, BLE state machine │ ├── ha_push.py # MQTT publish + body comp memory │ ├── config.py # YAML + env vars config loader │ ├── config.example.yaml # template (copy to config.yaml) │ └── requirements.txt ├── home_assistant/ │ ├── packages/bilancia.yaml # MQTT sensors + helpers + automation │ └── dashboards/bilancia.yaml ├── android-app/ # WeighAi — Kotlin/Compose companion app │ ├── app/ # Compose UI, MQTT subscriber, Health Connect │ ├── releases/v1.0.0/ # release notes │ └── README.md ├── deploy/ │ └── windows/ # PowerShell scripts for Task Scheduler └── docs/ ├── PROTOCOL.md # BLE protocol description ├── REVERSE_ENGINEERING.md # methodology used to derive the protocol ├── DEPLOY.md # deployment notes (Windows/Linux) └── HOME_ASSISTANT.md # MQTT + HA integration details ``` ### Android 伴侣应用 — WeighAi 一款面向日常用户开发的原生 Kotlin/Compose 应用。设计上保证单用户隐私：每部手机只订阅其所有者的 MQTT 主题，家庭成员数据不会跨设备传输。功能包括： - 实时体重 + 带霓虹光效的 3D 风格动画主仪表盘 - 用于显示脂肪 / 水分 / 肌肉 / 骨量 / 内脏脂肪的迷你环形仪表盘 - 每项指标的趋势图（周 / 月 / 年） - Health Connect 导出 — Samsung Health、Google Fit、Fitbit 等应用会自动从中读取数据 - 通过 HA Companion App 深度链接刷新推送通知 构建说明请参见 [`android-app/`](android-app/)，更新日志请参见 [`android-app/releases/v1.0.0/RELEASE_NOTES.md`](android-app/releases/v1.0.0/RELEASE_NOTES.md)。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。 本项目 **与 Mondeer 或 CE-Link 没有任何附属关系**。此逆向工程是在欧盟指令 2009/24/EC (Art. 6) 以及美国等效的 DMCA §1201(f) 的互操作性例外条款下进行的。此处未重新分发原 Android APK 中的任何代码；仅对通过观察和分析得出的*协议*进行了文档记录。 ## 致谢 - [Bleak](https://github.com/hbldh/bleak) — 在 Windows 上通过 Python 进行 BLE 通信的唯一明智选择 - [Home Assistant](https://www.home-assistant.io/) — 本项目与之集成的家庭自动化平台 - [JADX](https://github.com/skylot/jadx) — 在逆向工程阶段用于反编译 Android APK

标签：Android应用, BLE协议, BMI监测, Compose, Fitbit, Google Fit, Health Connect, Home Assistant, Kotlin, Python, Samsung Health, Telegram通知, 云资产清单, 体脂秤, 健康监测, 多用户支持, 开源硬件, 无后门, 无手机依赖, 智能体重秤, 智能家居, 智能家居自动化, 替代官方应用, 物联网, 生物电阻抗分析(BIA), 蓝牙低能耗, 蓝牙监听器, 设备集成, 跨平台数据同步, 身体成分分析, 逆向工具, 逆向工程