Repository navigation
Releases
v1.1.0 – standalone exe, tray settings, OBS overlay
No Python needed anymore: download fitbit-osc.exe below, put it in a folder of its own and double-click it. A heart icon appears in the tray. Then switch on heart-rate sharing once in Google Health (Connections → Fitbit Air → Share heart rate → Always visible). Full guide in the README.
Windows SmartScreen may warn because the file is not code-signed: More info → Run anyway. fitbit-osc.exe.sha256 holds the checksum. The exe is built by GitHub Actions from this tag.
New
- Standalone
fitbit-osc.exe. One file, runs in the tray, settings and log next to it. - Settings in the tray menu: VRChat chatbox, OBS overlay, Start with Windows, Start with SteamVR, settings file, log. All options are also stored in
config.json; command-line options still override them per run. - OSCQuery. With the default
"port": "auto"the bridge asks VRChat for its OSC port, so it also works when VRChat was started with--osc=.... Falls back to 9000. - OBS overlay. A local page (
http://127.0.0.1:8765/) with a beating heart and the BPM for a browser source. Size and colours via URL parameters. - Battery level in the tray and as the
HRBatteryparameter, for bands that report it. The Fitbit Air does not. --version, version info in the exe.
Improved
- No more frozen number on the avatar.
VRCOSC/Heartrate/EnabledandisHRActiveturn off after 5 s without a valid value, on 0 BPM or when the band reports no skin contact. - Leaving the room no longer removes the pairing. v1.0.0 unpaired after about 40 s without contact. Now the bridge scans briefly and only re-pairs when the band shows up under a new address, or keeps failing while in plain sight. Otherwise it keeps the pairing and retries with a growing pause.
- The tray status line updates. Before, it was built once and stayed at "No band connected".
- Heart-rate packets are parsed per the Bluetooth specification: skin contact, energy and RR-interval fields.
Under the hood
- Code split into the
fitbit_oscpackage.hr_osc.pyandregister_steamvr.pystay as entry points, so existing SteamVR registrations keep working after an update. - 33 automated tests, ruff, GitHub Actions for CI and for building the exe.
Upgrading from v1.0.0 (source install)
Download the new source, run install.bat once more (it adds zeroconf), done. Your pairing and SteamVR registration stay as they are.
v1.0.0 – reconnect fixes and Google Health guide
First tagged release of the Fitbit Air → VRChat heart-rate bridge: no phone app, no HypeRate/Pulsoid, no account. A Python tray program reads the pulse from the band over Bluetooth LE and sends it to VRChat via OSC.
Install
- Download Source code (zip) below and unpack it, e.g. to
C:\Tools\fitbit-osc. - Run
install.bat(needs Python 3.11+ from python.org). - On the phone, once: Google Health → Connections → Fitbit Air → Share heart rate → Always visible on.
start-tray.bat, orregister_steamvr.pyfor the SteamVR autostart.
Full guide in the README.
Fixes in this release
- No more exit on Bluetooth errors. Unplugging the adapter or switching the radio off ended the bridge; it now logs the error and retries every 10 s.
- Other heart-rate bands connect after pairing. The reconnect went by the Windows device name (
--name fitbit), so a Polar or Garmin band paired and then never connected. The address from the scan is used directly now. --name ""no longer matches every paired BLE device, which could have unpaired a mouse or controller after two failed attempts.- No needless reconnect right after subscribing when the band dropped briefly during service discovery.
- Silent drops are detected. 20 s without a measurement while Windows still reports "connected" counts as disconnected, so the avatar no longer freezes on the last value.
- No console window flashing every 10 s in the SteamVR autostart (tray mode), and the SteamVR check no longer blocks the heartbeat toggle.
- Short heart-rate packets are ignored, 0 BPM shows in the tray tooltip, a leaked device handle is closed.
Documentation
- New section on setting up heart-rate sharing in Google Health (Android and iPhone), what Share heart rate and Always visible do, one listener at a time, pairing happens on the PC, address changes, 0 BPM, battery.
- First-run walkthrough with the expected log lines, more troubleshooting entries.
Tested with
Fitbit Air, Windows 10, Python 3.14, TP-Link UB500 (Realtek RTL8761B). Counterfeit "CSR8510 A10" sticks do not work reliably, see the README.