polar-ble-tools 0.2.0

Unofficial local BLE tooling for supported Polar devices.

polar-ble-tools

Independent Python tools for working with supported Polar wearable devices over Bluetooth Low Energy.

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

Capabilities

• discover, pair, and connect devices through Linux BlueZ;
• issue PMD commands and manage offline recording;
• use PFTP to list, retrieve, and manage device files;
• retrieve raw .REC recordings with SHA-256 manifests and guarded cleanup;
• retrieve passive .BPB files and decode supported data with local schemas;
• 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 --accept-license

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

List and collect raw recordings:

polar-ble raw --mac-address AA:BB:CC:DD:EE:FF list
polar-ble raw --mac-address AA:BB:CC:DD:EE:FF collect

Review a cleanup without deleting device files:

polar-ble raw --mac-address AA:BB:CC:DD:EE:FF cleanup --all --dry-run

See device setup, offline recording, and raw retrieval before performing device mutations.

Compatibility

Controlled hardware validation covers Polar Loop Gen 2 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-assisted 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 download, inspection, generation, verification, activation, and removal are explicit polar-ble sdk commands. Package installation and import never perform those operations. See SDK integration.

REC decoding is optional and local-only. It requires a separately installed SDK and a user-built decoder; no SDK source or decoder binary is distributed:

polar-ble sdk decoder build
polar-ble rec status
polar-ble rec decode PPI0.REC --output PPI0.jsonl

See REC decoding for prerequisites, protocol, cache, security boundary, and limitations; see compatibility for the evidence-backed matrix.

Documentation and development

• Configuration and CLI
• CLI reference
• Python API reference
• Architecture
• Troubleshooting
• Contributor guide
• Development
• Release process
• 0.2.0 release notes

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.