andrewkomkov/cycplus-m2-sync
GitHub: andrewkomkov/cycplus-m2-sync
一款开源的 Android 与桌面端工具，通过蓝牙 LE 将 Cycplus M2 / XOSS 码表的骑行数据直接同步到 Health Connect 并导出原始 .fit 文件，全程无需厂商云或官方 App。
Stars: 0 | Forks: 0
# M2 Sync — Cycplus M2 / XOSS 码表 → Health Connect
[](https://github.com/andrewkommov/cycplus-m2-sync/actions/workflows/build.yml)
[](https://github.com/andrewkomkov/cycplus-m2-sync/releases)
[](LICENSE)
通过蓝牙 LE 将 **Cycplus M2**（以及其他 XOSS 系列）GPS 码表中的骑行记录直接下载到您的
Android 手机，将其写入 **Health Connect**，并可将原始的 `.fit` 文件导出到任意位置 —— **无需厂商云，无需账户，无需 XOSS App**。
[阅读俄语版](README.ru.md)
| 流量消耗少，且诚实公开 | 同一应用，英语界面 |
| --- | --- |
|  |  |
## 为什么开发此应用
官方的常规流程会将每次骑行记录发送到厂商的云，而且 Google 也在淘汰这部分服务：**Google Fit API 将于 2026 年底关闭**，Fit 应用正被 Google Health 取代，而 **Health Connect** 将成为所有应用现在通信的设备端存储。
此应用直接将数据写入 Health Connect，因此您的骑行记录会直达 Google Health、Strava、Garmin Connect 及其他可读取该数据的地方 —— 并且 `.fit` 文件完全归您所有。
## 功能
- **蓝牙 LE 同步** — 自动寻找码表，仅下载新的骑行记录（228 KB 约 13 秒）
- **Health Connect 导入** — 包含 GPS 路线、心率、踏频、速度、距离、海拔增量的骑行记录；暂停部分会作为分段写入，因此*移动时间*保持准确
- **无重复** — 通过 `clientRecordId` 去重，重新运行同步是安全的
- **原始 `.fit` 导出** — 一次分享一条或多条骑行记录，带有易读的文件名，例如
`2026-07-24_10-30_40.99km_cycplus-m2.fit`
- **完全支持通过 ADB 脚本控制** — 每个操作均可在无头模式下运行，无需点击
- **Material 3 UI** 支持动态配色，提供英语和俄语本地化
- **设备卡片** — 直接从设备读取型号、固件、电量和可用内存
## 安装
从 [Releases](https://github.com/andrewkomkov/cycplus-m2-sync/releases) 获取 APK 并
安装，或者从源码构建：
```
git clone https://github.com/andrewkomkov/cycplus-m2-sync.git
cd cycplus-m2-sync/android
./gradlew :app:assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
```
要求：Android 13 或更高版本，且支持 Health Connect（内置于 Android 14+）。
权限可以直接在应用中授予（锁形图标），或者完全通过终端授予：
```
for p in BLUETOOTH_SCAN BLUETOOTH_CONNECT POST_NOTIFICATIONS; do
adb shell pm grant dev.komkov.m2sync android.permission.$p
done
for p in WRITE_EXERCISE WRITE_EXERCISE_ROUTE WRITE_HEART_RATE WRITE_DISTANCE \
WRITE_SPEED WRITE_ELEVATION_GAINED READ_EXERCISE READ_HEART_RATE READ_DISTANCE; do
adb shell pm grant dev.komkov.m2sync android.permission.health.$p
done
```
## 通过终端使用
```
S="adb shell am start-foreground-service -n dev.komkov.m2sync/.SyncService -a dev.komkov.m2sync"
$S.SCAN # look for the bike computer
$S.SYNC # download new rides and import them
$S.SYNC -e name M2_XXXX # target a specific device
$S.INFO # firmware, battery, free memory
$S.IMPORT # import already downloaded files only
$S.IMPORT -e force 1 # re-import everything (after changing import logic)
$S.STATUS # what is stored locally
$S.VERIFY # read back from Health Connect and compare
$S.PERMS # permission strings Health Connect expects
adb logcat -s M2SYNC # follow the work
```
下载的文件位于 `/storage/emulated/0/Android/data/dev.komkov.m2sync/files/fit`：
```
adb pull /storage/emulated/0/Android/data/dev.komkov.m2sync/files/fit ./rides
```
## 支持的设备
已在 **Cycplus M2** 上验证，固件版本 V1.4.0。
XOSS 系列均使用相同的 Nordic UART + YMODEG 协议，因此在调整 `--name` 前缀后，以下设备预计也可使用：XOSS G / G+ Gen1 / G2+ / Gen3 / NAV / Sprint，Cycplus M1 / M3，CooSpo BC102 / BC107 / BC200。较新的型号（NAV, G2+）使用 `workouts.json` 而不是 `filelist.txt` 来列出骑行记录 —— 目前尚未支持。欢迎反馈使用报告。
## 哪些数据会写入 Health Connect
| Health Connect 记录 | `.fit` 中的来源 |
| --- | --- |
| `ExerciseSessionRecord` (骑行) + `ExerciseRoute` | session + 1 Hz GPS 轨迹 |
| `ExerciseSegment` (骑行 / 暂停) | 记录中的间隔 |
| `HeartRateRecord` | 每条记录的 `heart_rate` |
| `CyclingPedalingCadenceRecord` | `cadence` |
| `SpeedRecord`, `DistanceRecord` | `enhanced_speed`, session 总计 |
| `ElevationGainedRecord` | `total_ascent` |
**不会**写入卡路里数据 —— 因为 M2 不记录此数据。
## 协议
设备通过 Nordic UART Service 使用 YMODEM 进行通信。包含命令、特性及各型号差异的完整说明：[docs/PROTOCOL.md](docs/PROTOCOL.md)。
## 桌面工具（可选）
用于在无需手机的情况下拉取骑行记录，以及探测未知型号的 Python CLI：
```
pip install -r tools/requirements.txt
python tools/m2_cli.py scan # BLE devices nearby
python tools/m2_cli.py info # model, firmware, battery, free space
python tools/m2_cli.py sync # download new .fit into ./fit
python tools/m2_cli.py services # full GATT map — useful for new devices
python tools/fit_summary.py # what is inside the downloaded files
```
## 隐私
一切数据均保留在设备本地。无数据分析，无网络权限，无需账户。此应用仅通过蓝牙与您的码表通信，以及与同一部手机上的 Health Connect 通信。
## 致谢
- [ekspla/xoss_sync](https://github.com/ekspla/xoss_sync) — 本项目起步时所参考的协议
Python 实现
- [Kaiserdragon2/CycSync](https://github.com/Kaiserdragon2/CycSync) — 一个早期针对
Cycplus M2 的 Android 尝试
- [Garmin FIT SDK](https://github.com/garmin/fit-java-sdk) — FIT 解码
与 Cycplus、XOSS、Garmin 或 Google 无任何附属关系。
## 许可证
MIT — 查看 [LICENSE](LICENSE)。
标签：Health Connect, Kotlin, 数据同步, 物联网, 移动开发, 蓝牙低功耗(BLE), 运动健康, 逆向工具