christianmeurer/whoop-reader

# whoop-reader 用于 **Whoop 4.0** 健身手环的开源 BLE 数据读取器。 通过蓝牙低功耗（BLE）连接到 Whoop 4.0，并读取实时传感器数据——心率、R-R 间期、SpO2、皮肤温度和加速度计读数。专为研究人员、极客以及希望直接获取自身原始生物识别数据的任何人而构建。 ## 工作原理 Whoop 4.0 公开了一个自定义 BLE GATT 服务（`61080000-8d6d-82b8-614a-1c8cb0f8dcc6`），其中包含用于命令、响应、事件、数据流传输和诊断的五个特征。该工具向设备发送命令帧，并解析返回的 96 字节实时数据包。 协议知识来源于社区的逆向工程： - [jogolden/whoomp](https://github.com/jogolden/whoomp) -- Python CLI + Web Bluetooth，发现了 GATT 服务/特征 UUID - [bWanShiTong/reverse-engineering-whoop](https://github.com/bWanShiTong/reverse-engineering-whoop) -- 记录了命令/响应代码 - [jacc/whoop-re](https://github.com/jacc/whoop-re) -- REST API 逆向工程 - [Gadgetbridge](https://codeberg.org/Freeyourgadget/Gadgetbridge) 方法论：捕获 HCI snoop 日志、使用 Wireshark 分析，然后进行实现 ## 它能读取哪些数据 | 字段 | 状态 | 字节 | |-------|--------|-------| | 心率 (BPM) | 已解码 | 1-2 | | R-R 间期 (ms) | 已解码 | 3-4 | | SpO2 (%) | 已解码 | 5 | | 皮肤温度 (C) | 已解码 | 6 | | 加速度计 X/Y/Z | 候选（未确认） | 7-12 | | 运动强度 | 候选（未确认） | 13 | | PPG 振幅 | 候选（未确认） | 14-15 | | 环境光 | 候选（未确认） | 16-17 | | PPG 信号质量 | 候选（未确认） | 18-19 | | 电池电量 | 已解码 | （单独命令） | | 设备信息 | 已解码 | （单独命令） | 96 字节实时数据包的第 20-91 字节尚未被解码。它们可能包含额外的传感器通道（陀螺仪、呼吸频率、PPG 波形样本）。代码库在每个字节位置都包含结构化的 TODO 注释，以便贡献者进行补充。 ## 安装设置 需要 Python 3.10+ 和支持 BLE 的蓝牙适配器。 ``` # Clone the repo git clone https://github.com/whoop-reader/whoop-reader.git cd whoop-reader # Install in development mode pip install -e ".[dev]" ``` ### 平台说明 - **Linux**：可能需要 `bluez` 并以 root 身份运行（或将你的用户添加到 `bluetooth` 组） - **macOS**：使用内置蓝牙栈即可开箱即用 - **Windows**：需要 Windows 10+ 和兼容的蓝牙适配器 ## 使用方法 ### 扫描设备 ``` whoop-reader scan whoop-reader scan --timeout 15 ``` ### 检查电池 ``` whoop-reader battery --address AA:BB:CC:DD:EE:FF ``` 如果省略 `--address`，工具将进行扫描并让你从发现的设备中选择。 ### 设备信息 ``` whoop-reader info --address AA:BB:CC:DD:EE:FF ``` ### 流式传输实时数据 ``` # Stream to console whoop-reader stream --address AA:BB:CC:DD:EE:FF # Stream to CSV file whoop-reader stream --address AA:BB:CC:DD:EE:FF --output session.csv # Stream to JSON lines file whoop-reader stream --address AA:BB:CC:DD:EE:FF --output session.jsonl --format jsonl # Stop after 100 packets whoop-reader stream --address AA:BB:CC:DD:EE:FF --count 100 # Verbose logging (shows raw BLE traffic) whoop-reader -v stream --address AA:BB:CC:DD:EE:FF ``` 按 `Ctrl+C` 停止流式传输。数据在每个数据包后都会刷新到磁盘，因此中断时不会丢失任何数据。 ### Python API ``` import asyncio from whoop_reader.ble import scan_for_whoops, WhoopConnection async def main(): devices = await scan_for_whoops() async with WhoopConnection(devices[0]) as whoop: print(f"Battery: {await whoop.get_battery()}%") async for packet in await whoop.stream_realtime(): print(f"HR: {packet.heart_rate_bpm} BPM") if packet.heart_rate_bpm and packet.heart_rate_bpm > 180: break await whoop.stop_realtime() asyncio.run(main()) ``` ## 项目结构 ``` whoop-reader/ whoop_reader/ __init__.py -- Package metadata protocol.py -- BLE UUIDs, command codes, CRC-32 implementation parser.py -- 96-byte packet parser, response parsers ble.py -- Connection management (scan, connect, notify, stream) export.py -- CSV and JSON/JSONL export (batch and streaming) cli.py -- Click CLI (scan, connect, info, battery, stream) pyproject.toml -- Package configuration (hatchling) LICENSE -- MIT README.md ``` ## 协议详情 ### CRC-32 Whoop 4.0 使用 CRC-32 变体，其参数为： - 多项式：`0x04C11DB7` - 初始值：`0xFFFFFFFF` - 输入/输出反射：是 - 最终 XOR：`0xF43F44AC` ### 命令帧格式 ``` [0xAA] [CMD] [LENGTH_LO] [LENGTH_HI] [PAYLOAD...] [CRC32_LE] ``` ### 实时数据包 96 字节，通过 `61080004-8d6d-82b8-614a-1c8cb0f8dcc6` 作为 BLE 通知发送。最后 4 字节是前 92 字节的 CRC-32。 ## 法律声明 本项目是根据《数字千年版权法》（DMCA）第 1201(f) 条关于逆向工程的豁免条款，为实现 Whoop 硬件与第三方软件之间的互操作性而进行的独立、社区驱动的互操作性努力。 本项目不提取、分发或修改专有固件、算法或受版权保护的内容。它仅观察并记录 BLE 通信协议。 ## 免责声明 本项目与 Whoop, Inc. 无关，未获其认可，也不存在任何关联关系。所有商标均归其各自所有者所有。 本软件按“原样”提供，不提供任何担保。使用风险自负。作者不对您设备的运行、保修状态或 Whoop 订阅受到的任何影响负责。 此工具仅从您自己的设备读取数据。它不绕过任何订阅付费墙，不修改固件，也不访问 Whoop 的云服务。 ## 许可证 MIT -- 参见 [LICENSE](LICENSE)。

标签：BLE, GATT, PPG, Python, SpO2, Whoop 4.0, 云资产清单, 代码示例, 传感器, 健康监测, 健身追踪, 加速度计, 可穿戴设备, 实时流, 开源, 心率, 数据分析, 数据读取, 无后门, 物联网, 生物数据, 皮肤温度, 研究工具, 蓝牙, 计算机取证, 逆向工具, 逆向工程