python-igps-ble 0.1.0__py3-none-any.whl

igps_ble/__init__.py

@@ -0,0 +1,7 @@
+"""Pure-Python BLE library for the iGPSPORT iGS10S cycling computer."""
+
+from .models import IGPSDeviceState
+
+__version__ = "0.1.0"
+
+__all__ = ["IGPSDeviceState", "__version__"]

igps_ble/__main__.py

@@ -0,0 +1,46 @@
+"""CLI: `igps-ble scan` e `igps-ble info <ADDRESS>`."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+
+from .client import IGPSClient
+from .scanner import discover_devices
+
+
+async def _scan(timeout: float) -> None:
+    devices = await discover_devices(timeout=timeout)
+    if not devices:
+        print("Nenhum iGPSPORT encontrado. Ligue o aparelho e aproxime.")
+        return
+    for d in devices:
+        print(f"{d.address}  rssi={d.rssi}  name={d.name}")
+
+
+async def _info(address: str) -> None:
+    state = await IGPSClient(address).async_read_state()
+    print(f"Endereço:     {state.address}")
+    print(f"Modelo:       {state.model}")
+    print(f"Firmware:     {state.firmware}")
+    print(f"Fabricante:   {state.manufacturer}")
+    print(f"Bateria:      {state.battery_level}%")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="igps-ble")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    p_scan = sub.add_parser("scan", help="Procura aparelhos iGPSPORT por perto")
+    p_scan.add_argument("--timeout", type=float, default=10.0)
+    p_info = sub.add_parser("info", help="Conecta e lê bateria/device-info")
+    p_info.add_argument("address")
+
+    args = parser.parse_args()
+    if args.cmd == "scan":
+        asyncio.run(_scan(args.timeout))
+    elif args.cmd == "info":
+        asyncio.run(_info(args.address))
+
+
+if __name__ == "__main__":
+    main()

igps_ble/client.py

@@ -0,0 +1,69 @@
+"""Client async que conecta no iGS10S e lê as characteristics em escopo.
+
+Único módulo que abre conexão BLE. Aceita um BleakClient já criado (ou um
+BLEDevice) — útil pra reaproveitar a conexão do bleak-retry-connector no HA.
+"""
+
+from __future__ import annotations
+
+from bleak import BleakClient
+
+from .const import (
+    BATTERY_LEVEL_UUID,
+    FIRMWARE_REVISION_UUID,
+    HARDWARE_REVISION_UUID,
+    MANUFACTURER_NAME_UUID,
+    MODEL_NUMBER_UUID,
+    SOFTWARE_REVISION_UUID,
+)
+from .models import IGPSDeviceState
+from .parser import decode_device_string, parse_battery_level
+
+
+class IGPSClient:
+    """Lê presença/bateria/device-info de um iGS10S via BLE."""
+
+    def __init__(
+        self, address: str, name: str = "iGS10S", rssi: int | None = None
+    ) -> None:
+        self._address = address
+        self._name = name
+        self._rssi = rssi
+
+    async def async_read_state(self) -> IGPSDeviceState:
+        """Conecta, lê o que o aparelho expõe, e devolve o snapshot."""
+        async with BleakClient(self._address) as client:
+            battery = await self._read(client, BATTERY_LEVEL_UUID)
+            model = await self._read(client, MODEL_NUMBER_UUID)
+            # O iGS10S expõe o firmware na Software Revision (0x2A28); outros
+            # aparelhos usam a Firmware Revision (0x2A26). Tentamos as duas.
+            firmware = await self._read(client, SOFTWARE_REVISION_UUID)
+            if firmware is None:
+                firmware = await self._read(client, FIRMWARE_REVISION_UUID)
+            hardware = await self._read(client, HARDWARE_REVISION_UUID)
+            manufacturer = await self._read(client, MANUFACTURER_NAME_UUID)
+
+        return IGPSDeviceState(
+            address=self._address,
+            name=self._name,
+            rssi=self._rssi,
+            battery_level=parse_battery_level(battery) if battery is not None else None,
+            model=decode_device_string(model) if model is not None else None,
+            firmware=decode_device_string(firmware) if firmware is not None else None,
+            hardware=decode_device_string(hardware) if hardware is not None else None,
+            manufacturer=(
+                decode_device_string(manufacturer)
+                if manufacturer is not None
+                else None
+            ),
+        )
+
+    @staticmethod
+    async def _read(client: BleakClient, uuid: str) -> bytes | None:
+        """Lê a char se ela existir; None se o aparelho não a expõe."""
+        if client.services.get_characteristic(uuid) is None:
+            return None
+        try:
+            return await client.read_gatt_char(uuid)
+        except Exception:  # noqa: BLE001 - char some/erra => trata como ausente
+            return None

igps_ble/const.py

@@ -0,0 +1,26 @@
+"""UUIDs Bluetooth SIG e defaults do iGPSPORT iGS10S.
+
+UUIDs confirmados no recon (docs/RECON_FINDINGS.md). Ajuste NAME_PREFIXES
+para o local_name exato observado na Task 1.
+"""
+
+# Battery Service / characteristic (Bluetooth SIG).
+BATTERY_SERVICE_UUID = "0000180f-0000-1000-8000-00805f9b34fb"
+BATTERY_LEVEL_UUID = "00002a19-0000-1000-8000-00805f9b34fb"
+
+# Device Information Service / characteristics (Bluetooth SIG).
+DEVICE_INFO_SERVICE_UUID = "0000180a-0000-1000-8000-00805f9b34fb"
+MODEL_NUMBER_UUID = "00002a24-0000-1000-8000-00805f9b34fb"
+FIRMWARE_REVISION_UUID = "00002a26-0000-1000-8000-00805f9b34fb"
+HARDWARE_REVISION_UUID = "00002a27-0000-1000-8000-00805f9b34fb"
+# O iGS10S reporta o firmware na Software Revision (0x2A28), não na
+# Firmware Revision (0x2A26, ausente). Confirmado no recon 2026-05-31.
+SOFTWARE_REVISION_UUID = "00002a28-0000-1000-8000-00805f9b34fb"
+MANUFACTURER_NAME_UUID = "00002a29-0000-1000-8000-00805f9b34fb"
+
+# Prefixos de local_name usados pra reconhecer o aparelho no advertisement.
+# Confirme/ajuste com o que a Task 1 observou.
+NAME_PREFIXES = ("iGS10S", "iGPSPORT", "iGS")
+
+MANUFACTURER = "iGPSPORT"
+DEFAULT_MODEL = "iGS10S"

igps_ble/models.py

@@ -0,0 +1,23 @@
+"""Modelo imutável do estado lido do iGS10S."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class IGPSDeviceState:
+    """Snapshot do que a lib conseguiu ler do aparelho.
+
+    Campos opcionais ficam None quando o aparelho não expõe a characteristic
+    correspondente (ex.: sem Battery Service => battery_level None).
+    """
+
+    address: str
+    name: str
+    rssi: int | None = None
+    battery_level: int | None = None
+    model: str | None = None
+    firmware: str | None = None
+    hardware: str | None = None
+    manufacturer: str | None = None

igps_ble/parser.py

@@ -0,0 +1,21 @@
+"""Parsers puros (sem I/O) para os bytes das characteristics SIG."""
+
+from __future__ import annotations
+
+
+def parse_battery_level(data: bytes) -> int | None:
+    """Battery Level (0x2A19): 1 byte uint8, 0..100. None se ausente/inválido."""
+    if not data:
+        return None
+    value = data[0]
+    if value > 100:
+        return None
+    return value
+
+
+def decode_device_string(data: bytes) -> str | None:
+    """Device Information string UTF-8; remove NUL de padding e espaços."""
+    if not data:
+        return None
+    text = data.decode("utf-8", errors="replace").replace("\x00", "").strip()
+    return text or None

igps_ble/scanner.py

@@ -0,0 +1,32 @@
+"""Descoberta BLE do iGS10S (toca o adaptador Bluetooth)."""
+
+from __future__ import annotations
+
+from bleak import BleakScanner
+
+from .const import NAME_PREFIXES
+from .models import IGPSDeviceState
+
+
+def is_igps_device(local_name: str | None) -> bool:
+    """True se o nome de advertisement bate com um prefixo conhecido do iGPSPORT."""
+    if not local_name:
+        return False
+    return any(local_name.startswith(prefix) for prefix in NAME_PREFIXES)
+
+
+async def discover_devices(timeout: float = 10.0) -> list[IGPSDeviceState]:
+    """Escaneia e devolve um IGPSDeviceState por aparelho iGPSPORT visto.
+
+    Não conecta — campos de bateria/device-info ficam None aqui.
+    """
+    discovered = await BleakScanner.discover(timeout=timeout, return_adv=True)
+    results: list[IGPSDeviceState] = []
+    for address, (device, adv) in discovered.items():
+        name = adv.local_name or device.name
+        if not is_igps_device(name):
+            continue
+        results.append(
+            IGPSDeviceState(address=address, name=name, rssi=adv.rssi)
+        )
+    return results

python_igps_ble-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: python-igps-ble
+Version: 0.1.0
+Summary: Pure-Python BLE library for the iGPSPORT iGS10S cycling computer (presence, battery, device info)
+Author-email: Hudson Brendon <contato.hudsonbrendon@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hudsonbrendon/python-igps-ble
+Project-URL: Issues, https://github.com/hudsonbrendon/python-igps-ble/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: bleak>=0.22
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+
+# python-igps-ble
+
+Pure-Python BLE library for the **iGPSPORT iGS10S** cycling computer.
+
+Reads, over standard Bluetooth Low Energy, what the device exposes to
+third parties: **presence**, **battery level**, and **device info**
+(model / firmware / manufacturer). The proprietary `.fit` sync used by the
+official iGPSPORT app is **out of scope** (see `ha-igps-ble/docs/PROTOCOL.md`).
+
+> Built to back the [`ha-igps-ble`](https://github.com/hudsonbrendon/ha-igps-ble)
+> Home Assistant integration, but usable standalone.
+
+## Install
+
+```bash
+pip install python-igps-ble
+```
+
+## CLI
+
+```bash
+igps-ble scan                 # procura aparelhos iGPSPORT por perto
+igps-ble info AA:BB:CC:DD:EE:FF   # bateria + device-info
+```
+
+## Uso programático
+
+```python
+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)
+
+asyncio.run(main())
+```
+
+## Escopo
+
+| Dado | Suportado | Fonte |
+|------|-----------|-------|
+| Presença | ✅ | advertisement BLE |
+| Bateria % | ✅* | Battery Service `0x180F` |
+| Modelo / firmware | ✅* | Device Information `0x180A` |
+| Velocidade / distância / pedalada | ❌ | sync proprietário (não exposto por BLE) |
+
+\* depende de o iGS10S expor o serviço SIG correspondente — confirmado por recon.
+
+## Desenvolvimento
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+## Licença
+
+MIT

python_igps_ble-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+igps_ble/__init__.py,sha256=eeV-l5_0sdRkAEPeB9uUUE4G2dZ-rCq1T6y1UJhDWbk,178
+igps_ble/__main__.py,sha256=mCoZbDckv8FDd613fWJE0pTaCVwv2fG3Snn2V6KhWGY,1414
+igps_ble/client.py,sha256=f66p39IP5g-UVkOn30JACZrjOOPuQs5IGJ6_7g665gg,2728
+igps_ble/const.py,sha256=0PfoY4CCFypAJ4bEKyBpFLDZufB6aRZKd04IFdI35sM,1161
+igps_ble/models.py,sha256=H6UNnnMfVovc0EsqYHyC0oIPPvnJ99i8Vi9y_SyWL-I,620
+igps_ble/parser.py,sha256=IkY_fpODaJkXwSilkA5JzXks1VEP5MsoHjf4aOr9JtE,627
+igps_ble/scanner.py,sha256=aJj3bE_K9ky9fJKicKLrRoWf1YSeXZRRsGghpzBauP4,1085
+python_igps_ble-0.1.0.dist-info/METADATA,sha256=QX_XkHtYvVZV8Dg7aNWzuIYMCo7P9bvi8z1aV-QHjcs,2253
+python_igps_ble-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_igps_ble-0.1.0.dist-info/entry_points.txt,sha256=WmO3pSZ-qD2ZfHtnxxqyvUycW8LEwMFIJIC1k7oFSuY,52
+python_igps_ble-0.1.0.dist-info/top_level.txt,sha256=69O33W2-0wC37bi3yvYxMJqOVdk612_CqJYgxErMS8A,9
+python_igps_ble-0.1.0.dist-info/RECORD,,

python_igps_ble-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_igps_ble-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+igps-ble = igps_ble.__main__:main

python_igps_ble-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+igps_ble