polar-ble-tools

Offline-first Python tools for on-device data collection and local retrieval from supported Polar wearable devices over Bluetooth Low Energy.

Currently supported devices are Polar Loop Gen 2 and Polar Verity Sense. Support is limited to the controlled, device-specific behavior documented in the compatibility matrix.

polar-ble-tools supports workflows in which a wearable records data to its own storage and the resulting files are retrieved later over BLE. It provides device setup, offline recording control, PFTP file retrieval, integrity manifests, guarded cleanup, and optional local decoding for supported formats. Data collection and retrieval do not require Polar Flow.

This repository is deliberately limited to BLE tooling: protocol access, device-facing operations, local persistence safeguards, and helpers that make one BLE operation safe and usable. Higher-level application orchestration belongs in an orchestration layer built on these APIs, and is out of scope for this project.

polar-ble-tools is an unofficial community project. It is not affiliated with, endorsed by, sponsored by, or maintained by Polar Electro Oy.

Capabilities

• manage supported PMD offline recordings and recording settings;
• list, retrieve, and manage device-resident files through PFTP;
• retrieve raw .REC recordings with SHA-256 manifests and guarded cleanup;
• retrieve passive .BPB files and decode supported data with local schemas;
• discover, pair, trust, and connect devices through Linux BlueZ;
• validate and apply first-time-use (FTU) data;
• generate and verify optional local schemas from a separately obtained SDK;
• locally decode supported .REC files to validated JSONL with an optional SDK sidecar.

Installation

Device operations require Linux, BlueZ, and bluetoothctl. Python 3.11 or newer is supported.

python -m pip install polar-ble-tools
polar-ble --help

Install the optional schema compiler only for SDK-assisted FTU encoding and BPB decoding:

python -m pip install "polar-ble-tools[sdk]"
polar-ble sdk install

The installer asks for a simple y/N confirmation that proceeding accepts the Polar BLE SDK licence. This happens on every install/download invocation, including cache reuse. Use -y for non-interactive installation.

Quick start

Discover and pair a device:

polar-ble discover --scan-seconds 15 --name Polar
polar-ble pair --mac-address AA:BB:CC:DD:EE:FF --scan-seconds 15

First-time setup for Polar Loop Gen 2

For a Loop Gen 2 that has not completed first-time setup, copy the example FTU profile to a private location and replace every value. The profile contains personal physical data and must not be committed or placed in shared logs. FTU requires the optional generated-schema cache installed above.

Validate the profile without contacting the device, then apply it and confirm completion:

polar-ble ftu dry-run \
  --profile ~/.config/polar-ble-tools/ftu-profile.json
polar-ble ftu --mac-address AA:BB:CC:DD:EE:FF apply \
  --profile ~/.config/polar-ble-tools/ftu-profile.json
polar-ble ftu --mac-address AA:BB:CC:DD:EE:FF status

Passive data from Polar Loop Gen 2

After the device has accumulated data, replace the example dates with the bounded range to retrieve. Collection persists and hashes the raw .BPB files before optional decoding:

polar-ble passive --mac-address AA:BB:CC:DD:EE:FF \
  --from-date 2026-07-23 --to-date 2026-07-29 collect --decode

Omit --decode to collect raw passive files without an active schema cache.

Offline REC recordings

Polar Loop Gen 2 and Polar Verity Sense both support the raw REC workflow. Inspect the device-supported types and settings, start an ACC recording, then stop and collect it after the desired duration:

polar-ble raw --mac-address AA:BB:CC:DD:EE:FF types
polar-ble raw --mac-address AA:BB:CC:DD:EE:FF \
  settings --type ACC --full
polar-ble raw --mac-address AA:BB:CC:DD:EE:FF \
  start --type ACC --setting sample_rate=52
# Run the stop command after the desired recording duration.
polar-ble raw --mac-address AA:BB:CC:DD:EE:FF stop --type ACC
polar-ble raw --mac-address AA:BB:CC:DD:EE:FF collect --type ACC

Raw REC collection is SDK-free. Structured REC decoding is a separate, experimental workflow requiring the optional local sidecar.

See device setup for the complete FTU workflow. See offline recording, raw retrieval, and REC decoding for the complete REC workflows and supported types.

Compatibility

Controlled hardware validation covers Polar Loop Gen 2 and Polar Verity Sense on Linux/BlueZ. Other devices exposing the required PMD and PFTP services may work but are not confirmed for this release. See compatibility for the verified capability matrix and limitations.

Optional SDK functionality

The package does not distribute the Polar BLE SDK, Polar SDK schema files, or artefacts generated from those files. Optional SDK-assisted functionality uses an SDK copy separately obtained and licensed by the user. SDK operations are explicit commands; package installation and import never download, generate, or activate SDK material. Structured REC decoding additionally requires a locally built optional sidecar. See SDK integration, REC decoding, and compatibility for prerequisites and evidence-backed limitations.

Documentation

• Device setup
• Configuration and CLI
• CLI reference
• Python API reference
• Compatibility
• Troubleshooting
• Contributor guide

Licence and trademarks

Project-authored content is licensed under the Apache License 2.0. See NOTICE for attribution, trademark, and SDK-separation notices.

Polar and related product names are trademarks of Polar Electro Oy and are used solely to identify compatible devices.