BLE Scale Sync

A cross-platform CLI tool that reads body composition data from 25+ BLE smart scales and exports to Garmin Connect, Strava, Intervals.icu, Runalyze, Wger, MQTT (Home Assistant), InfluxDB, Webhooks, Ntfy, Telegram, and local files (CSV/JSONL). No phone app needed. Your data stays on your device.

Documentation · Getting Started · Supported Scales · Exporters · FAQ

Why This Exists

Most BLE smart scales measure weight and body impedance over Bluetooth, but their companion apps have no way to sync data to Garmin Connect. The only workflow was: open the phone app, wait for it to sync, then manually type the numbers into Garmin. Every single time.

I didn't want to depend on a phone app. So I built this tool. A Raspberry Pi Zero 2W sits next to the scale, always on, always listening. Step on the scale, wait a few seconds, and the reading appears in Garmin Connect - no phone needed, no app, no manual entry. It just works.

If you can't have a Pi next to your scale, a cheap ESP32 proxy can sit nearby and relay BLE data over WiFi to a Docker server anywhere on your network. See the ESP32 BLE proxy guide.

Quick Start

Docker (Linux)

# Configure
docker run --rm -it --network host --cap-add NET_ADMIN --cap-add NET_RAW \
  --group-add "$(getent group bluetooth | cut -d: -f3)" -v /var/run/dbus:/var/run/dbus:ro \
  -v ./config.yaml:/app/config.yaml \
  -v ./garmin-tokens:/app/garmin-tokens \
  ghcr.io/kristianp26/ble-scale-sync:latest setup

# Run (continuous mode, auto-restart)
docker run -d --restart unless-stopped --network host \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --group-add "$(getent group bluetooth | cut -d: -f3)" --device /dev/rfkill \
  -v /var/run/dbus:/var/run/dbus:ro \
  -v ./config.yaml:/app/config.yaml:ro \
  -v ./garmin-tokens:/app/garmin-tokens:ro \
  -e CONTINUOUS_MODE=true \
  ghcr.io/kristianp26/ble-scale-sync:latest

Ideal for Raspberry Pi, NAS, and headless servers. Works alongside any Home Assistant install (Container, Core, OS) via MQTT auto-discovery.

Home Assistant Add-on

If you run Home Assistant OS or Supervised, one click is all it takes:

The badge opens your Home Assistant instance, confirms the repository, and shows BLE Scale Sync in the Add-on Store ready to install.

Prefer manual steps?

1. Settings > Add-ons > Add-on Store > three-dot menu > Repositories
2. Add https://github.com/KristianP26/ble-scale-sync and install BLE Scale Sync

The add-on handles config through the UI, auto-detects the Mosquitto broker for Home Assistant auto-discovery, and bootstraps Garmin tokens on first start. See the Home Assistant Add-on guide for the full option reference, MFA workaround, and custom config mode.

Note: Add-ons are not available on HA Container or HA Core installs (no Supervisor). Use the Docker method above instead. Sensors still appear in HA via MQTT auto-discovery.

Standalone (Node.js, Linux/macOS/Windows)

Runs natively on all major desktop and server operating systems. No containers required.

Zero clone, if you already have Node.js v22+:

npx ble-scale-sync setup                 # interactive wizard, writes ./config.yaml
CONTINUOUS_MODE=true npx ble-scale-sync  # always-on

config.yaml and .env are read from the directory you run the command in. Add npm install -g ble-scale-sync to keep the command on your PATH.

Or from a clone, which is what you want if you plan to contribute:

git clone https://github.com/KristianP26/ble-scale-sync.git
cd ble-scale-sync && npm install
npm run setup                       # interactive wizard
CONTINUOUS_MODE=true npm start      # always-on

Requires Node.js v22+ and a BLE adapter. See the full install guide for prerequisites and systemd service setup.

Features

• 25+ scale brands. Xiaomi (Mi Scale 2 passive broadcast), Renpho (Elis 1, ES-CS20M, QN-Scale), Eufy, Yunmai, Beurer (incl. BF720), Sanitas (incl. SBF70 body composition), Medisana, and more.
• 11 export targets. Garmin Connect, Strava, Intervals.icu, Runalyze, Wger, MQTT (Home Assistant), InfluxDB, Webhook, Ntfy, Telegram, File (CSV/JSONL).
• 10 body metrics. BIA-based body composition from weight + impedance.
• Multi-user. Automatic weight-based identification with per-user exporters.
• Historical sync. Replays a scale's onboard cache of offline measurements with their original timestamps to exporters that support back-dating (Garmin Connect, InfluxDB, File).
• Interactive setup wizard. Scale discovery (MAC or macOS CoreBluetooth UUID), exporter config, connectivity tests.
• BLE diagnostic tool. ble-scale-sync diagnose (or npm run diagnose from a clone) for detailed BLE troubleshooting.
• Home Assistant Add-on. One-click install via My Home Assistant badge, MQTT auto-discovery, UI-driven config, Garmin token bootstrap, and MFA workaround.
• ESP32 BLE proxy. Use a remote ESP32 as a BLE radio over MQTT, with a built-in embedded broker for zero-config setup, simplified Docker deployment, and optional display. Set ble.scale_mac for GATT-only scales (for example QN-Scale) so the ESP32 can connect autonomously the instant it sees the scale. It connects to both public-address and random-address GATT scales even when the controller misreports the address type, and connects with minimal delay so a briefly-connectable scale is reached before it sleeps.
• ESPHome Bluetooth proxy. Reuse an existing ESPHome BT proxy mesh (Home Assistant) as a BLE radio via Native API: broadcast and GATT scales (public and random BLE addresses), multi-proxy with RSSI auto-pick.
• Home Assistant Bluetooth. Use Home Assistant itself as the radio: subscribe to its Bluetooth advertisement stream over the websocket API, so every proxy HA already has (ESPHome, SMLIGHT SLZB, Shelly, local adapter) serves broadcast scales without taking it away from HA.
• BLE adapter selection. ble.adapter: hci1 for multi-adapter setups (Linux).
• Broadcast mode. Supports non-connectable scales that only advertise weight via BLE advertisements.
• Linux stability hardening. Auto-recovery for the BlueZ "stuck discovery" state via a consecutive-failure watchdog, plus optional systemd Type=notify integration for whole-loop freezes. The watchdog is idle-aware, so a scale that only advertises while in use does not trigger needless restarts when nobody is weighing.
• Update check. Optional, anonymous version check after each measurement (opt-out via update_check: false); see the auto update guide for Watchtower, systemd timer, and HA add-on recipes.
• Cross-platform. Linux (Docker + native), macOS, Windows.
• Private. Your data stays on your device, no vendor cloud.

Capturing raw BLE frames (debugging)

For reverse-engineering a scale protocol (e.g. decoding an undecoded impedance frame), the native BlueZ handler can dump every notify frame as hex and hold the GATT connection open past the weight-stable point so the scale finishes sending its trailing frames before disconnect.

• BLE_RAW_CAPTURE=true enables it (off by default; no effect on normal runs).
• BLE_RAW_CAPTURE_HOLD_SEC=20 sets how long to hold the link after the weight stabilizes (default 20s, keep it under 120).

# native
BLE_RAW_CAPTURE=true DEBUG=true CONTINUOUS_MODE=true npm start
# docker
docker run ... -e BLE_RAW_CAPTURE=true -e DEBUG=true ghcr.io/kristianp26/ble-scale-sync:dev

Step on the scale and look for [BLE] [RAW] <uuid> (<n>B): <hex> lines. The run still exports a weight-only reading. Applies to every GATT reading path (native BlueZ and noble, plus the ESP32 and ESPHome proxies).

Credits

• Scale protocols - many adapters ported from openScale (oliexdev and contributors); Eufy P2 / P2 Pro ported from bdr99/eufylife-ble-client; QN-Scale / FITINDEX and a few others reverse-engineered in this project
• Garmin upload - powered by garminconnect by cyberjunky
• BLE - node-ble (Linux), @abandonware/noble (Windows), @stoprocent/noble (macOS)
• ESP32 proxy - mqtt_as by peterhinch, aioble

Contributors

Contributing

See CONTRIBUTING.md for development setup, project structure, and how to add new scale adapters or exporters.

License

GPL-3.0. See LICENSE for details.

Star History