python-igps-ble

Talk to an iGPSPORT iGS10S cycling computer over Bluetooth LE from Python — battery, internal sensors, ride status, stored activities, last GPS position and the rider/bike profile, through iGPSPORT's proprietary protobuf-over-Nordic-UART protocol (reverse engineered from the official app, no pairing or login needed).

This library powers the iGPSPORT iGS10S Home Assistant integration, but works standalone in any async Python project (or straight from the command line).

Protocol notes: ha-igps-ble/docs/PROTOCOL.md.

Features

• 🔌 Async BLE control built on bleak — works on Linux, macOS, and Windows.
• 🔍 Discovery helper — discover_devices() finds nearby iGPSPORT devices (presence + RSSI).
• 🏷️ Device info — manufacturer, hardware revision, firmware, serial and protocol version.
• 🔋 Battery — level (%) and voltage.
• 🌡️ Sensors — internal temperature, free memory, device clock.
• 🚴 Ride status — idle / recording / paused, live ride fields while recording, last GPS position.
• 🗂️ Activities — list of rides stored on the device (start time, size).
• 💾 .fit download — download_activity(session, id, size) with per-chunk CRC and size checks.
• 🧹 Maintenance — delete one/all activities, factory_control() (format, factory reset, settings reset, lock, logs, test mode), unbind, DFU mode.
• 🛰️ GPS — gps_control(), set_gnss(), set_gps_dynamic(), set_gps_position().
• 🧪 Raw — command(session, service, op, fields) for anything else.
• ⚙️ Profile — write rider weight/height/age/sex, wheel circumference, bike weight and time zone (set_profile).
• 🖥️ CLI — igps-ble scan / info for quick testing.

Requirements

• Python 3.11 or newer.
• A Bluetooth LE adapter (built-in or USB).
• An iGPSPORT iGS10S (other iGPSPORT models exposing the same standard services may also work).

Installation

pip install python-igps-ble

CLI usage

igps-ble scan                      # find nearby iGPSPORT devices
igps-ble info AA:BB:CC:DD:EE:FF     # connect and read everything

Library usage

import asyncio
from igps_ble import IGPSDeviceState
from igps_ble.scanner import discover_devices
from igps_ble.client import IGPSClient


async def main():
    for dev in await discover_devices(timeout=10):
        state: IGPSDeviceState = await IGPSClient(
            dev.address, dev.name
        ).async_read_state()
        print(state.manufacturer, state.model, state.firmware, state.battery_level)


asyncio.run(main())

IGPSClient accepts a bleak BLEDevice (preferred — e.g. from Home Assistant's shared scanner or a Bluetooth proxy) or a string MAC/UUID address.

API

Scope

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Credits

Built to back the ha-igps-ble Home Assistant integration. Author @hudsonbrendon.

License

MIT — see LICENSE.