python-igps-ble 0.1.0__tar.gz

python_igps_ble-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,62 @@
+# 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/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-igps-ble"
+version = "0.1.0"
+description = "Pure-Python BLE library for the iGPSPORT iGS10S cycling computer (presence, battery, device info)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Hudson Brendon", email = "contato.hudsonbrendon@gmail.com" }]
+dependencies = ["bleak>=0.22"]
+
+[project.urls]
+Homepage = "https://github.com/hudsonbrendon/python-igps-ble"
+Issues = "https://github.com/hudsonbrendon/python-igps-ble/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "ruff>=0.5"]
+
+[project.scripts]
+igps-ble = "igps_ble.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

python_igps_ble-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

python_igps_ble-0.1.0/src/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__"]

python_igps_ble-0.1.0/src/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()

python_igps_ble-0.1.0/src/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

python_igps_ble-0.1.0/src/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"

python_igps_ble-0.1.0/src/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

python_igps_ble-0.1.0/src/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

python_igps_ble-0.1.0/src/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/src/python_igps_ble.egg-info/PKG-INFO

@@ -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/src/python_igps_ble.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/igps_ble/__init__.py
+src/igps_ble/__main__.py
+src/igps_ble/client.py
+src/igps_ble/const.py
+src/igps_ble/models.py
+src/igps_ble/parser.py
+src/igps_ble/scanner.py
+src/python_igps_ble.egg-info/PKG-INFO
+src/python_igps_ble.egg-info/SOURCES.txt
+src/python_igps_ble.egg-info/dependency_links.txt
+src/python_igps_ble.egg-info/entry_points.txt
+src/python_igps_ble.egg-info/requires.txt
+src/python_igps_ble.egg-info/top_level.txt
+tests/test_client.py
+tests/test_parser.py
+tests/test_scanner.py

python_igps_ble-0.1.0/src/python_igps_ble.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

python_igps_ble-0.1.0/src/python_igps_ble.egg-info/entry_points.txt

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

python_igps_ble-0.1.0/src/python_igps_ble.egg-info/requires.txt

@@ -0,0 +1,6 @@
+bleak>=0.22
+
+[dev]
+pytest>=8
+pytest-asyncio>=0.23
+ruff>=0.5

python_igps_ble-0.1.0/src/python_igps_ble.egg-info/top_level.txt

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

python_igps_ble-0.1.0/tests/test_client.py

@@ -0,0 +1,100 @@
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from igps_ble.client import IGPSClient
+from igps_ble.const import (
+    BATTERY_LEVEL_UUID,
+    FIRMWARE_REVISION_UUID,
+    HARDWARE_REVISION_UUID,
+    MANUFACTURER_NAME_UUID,
+    MODEL_NUMBER_UUID,
+    SOFTWARE_REVISION_UUID,
+)
+
+
+def _fake_bleak_client(reads):
+    """BleakClient mock: services presentes p/ os UUIDs em `reads`, reads roteados."""
+
+    async def read_gatt_char(uuid):
+        if uuid not in reads:
+            raise KeyError(uuid)
+        return reads[uuid]
+
+    client = MagicMock()
+    client.__aenter__ = AsyncMock(return_value=client)
+    client.__aexit__ = AsyncMock(return_value=False)
+    client.connect = AsyncMock()
+    client.disconnect = AsyncMock()
+    client.read_gatt_char = AsyncMock(side_effect=read_gatt_char)
+    services = MagicMock()
+    services.get_characteristic = lambda uuid: object() if uuid in reads else None
+    client.services = services
+    return client
+
+
+def _igs10s_reads():
+    """O que o iGS10S real expõe (recon 2026-05-31): sem bateria, sem model,
+    firmware na Software Revision (0x2A28), hardware na 0x2A27."""
+    return {
+        MODEL_NUMBER_UUID: b"iGS10S\x00",
+        SOFTWARE_REVISION_UUID: b"V1.15",
+        HARDWARE_REVISION_UUID: b"V1.00",
+        MANUFACTURER_NAME_UUID: b"iGPSPORT",
+    }
+
+
+@pytest.mark.asyncio
+async def test_read_state_firmware_from_software_revision():
+    fake = _fake_bleak_client(_igs10s_reads())
+    with patch("igps_ble.client.BleakClient", return_value=fake):
+        client = IGPSClient("AA:BB:CC:DD:EE:FF", name="iGS10S", rssi=-44)
+        state = await client.async_read_state()
+
+    assert state.firmware == "V1.15"  # vem do 0x2A28
+    assert state.hardware == "V1.00"  # vem do 0x2A27
+    assert state.model == "iGS10S"
+    assert state.manufacturer == "iGPSPORT"
+    assert state.rssi == -44
+    assert state.battery_level is None  # iGS10S não tem Battery Service
+
+
+@pytest.mark.asyncio
+async def test_read_state_firmware_falls_back_to_2a26():
+    # Aparelho que usa a Firmware Revision (0x2A26) clássica, sem 0x2A28.
+    reads = {
+        FIRMWARE_REVISION_UUID: b"2.0.1",
+        MANUFACTURER_NAME_UUID: b"iGPSPORT",
+    }
+    fake = _fake_bleak_client(reads)
+    with patch("igps_ble.client.BleakClient", return_value=fake):
+        client = IGPSClient("AA:BB:CC:DD:EE:FF")
+        state = await client.async_read_state()
+
+    assert state.firmware == "2.0.1"
+
+
+@pytest.mark.asyncio
+async def test_read_state_battery_present_is_parsed():
+    reads = {**_igs10s_reads(), BATTERY_LEVEL_UUID: bytes([0x57])}
+    fake = _fake_bleak_client(reads)
+    with patch("igps_ble.client.BleakClient", return_value=fake):
+        client = IGPSClient("AA:BB:CC:DD:EE:FF")
+        state = await client.async_read_state()
+
+    assert state.battery_level == 87
+
+
+@pytest.mark.asyncio
+async def test_read_state_missing_model_is_none():
+    reads = {
+        SOFTWARE_REVISION_UUID: b"V1.15",
+        MANUFACTURER_NAME_UUID: b"iGPSPORT",
+    }
+    fake = _fake_bleak_client(reads)
+    with patch("igps_ble.client.BleakClient", return_value=fake):
+        client = IGPSClient("AA:BB:CC:DD:EE:FF", name="iGS10S")
+        state = await client.async_read_state()
+
+    assert state.model is None
+    assert state.firmware == "V1.15"

python_igps_ble-0.1.0/tests/test_parser.py

@@ -0,0 +1,31 @@
+from igps_ble.parser import decode_device_string, parse_battery_level
+
+
+def test_battery_level_reads_single_byte_percent():
+    # Padrão SIG 0x2A19: 1 byte uint8 = porcentagem. 0x57 = 87%.
+    assert parse_battery_level(bytes([0x57])) == 87
+
+
+def test_battery_level_zero_and_full():
+    assert parse_battery_level(bytes([0x00])) == 0
+    assert parse_battery_level(bytes([0x64])) == 100
+
+
+def test_battery_level_empty_returns_none():
+    assert parse_battery_level(b"") is None
+
+
+def test_battery_level_out_of_range_clamped():
+    # Alguns aparelhos devolvem 0xFF ("desconhecido"); tratamos como None.
+    assert parse_battery_level(bytes([0xFF])) is None
+
+
+def test_decode_device_string_strips_nul_and_whitespace():
+    # Strings do Device Info vêm UTF-8, às vezes com NUL de padding.
+    assert decode_device_string(b"iGS10S\x00") == "iGS10S"
+    assert decode_device_string(b"  V1.20 \x00") == "V1.20"
+
+
+def test_decode_device_string_empty_returns_none():
+    assert decode_device_string(b"") is None
+    assert decode_device_string(b"\x00\x00") is None

python_igps_ble-0.1.0/tests/test_scanner.py

@@ -0,0 +1,46 @@
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from igps_ble.scanner import discover_devices, is_igps_device
+
+
+def _adv(local_name, rssi=-50, service_uuids=None):
+    return SimpleNamespace(
+        local_name=local_name, rssi=rssi, service_uuids=service_uuids or []
+    )
+
+
+def test_is_igps_device_matches_known_prefixes():
+    assert is_igps_device("iGS10S") is True
+    assert is_igps_device("iGPSPORT iGS10S") is True
+    assert is_igps_device("iGS520") is True
+
+
+def test_is_igps_device_rejects_others():
+    assert is_igps_device("JBL Charge 5") is False
+    assert is_igps_device("") is False
+    assert is_igps_device(None) is False
+
+
+@pytest.mark.asyncio
+async def test_discover_devices_filters_and_maps():
+    bledev = SimpleNamespace(address="AA:BB:CC:DD:EE:FF", name="iGS10S")
+    other = SimpleNamespace(address="11:22:33:44:55:66", name="TV")
+    discovered = {
+        "AA:BB:CC:DD:EE:FF": (bledev, _adv("iGS10S", rssi=-44)),
+        "11:22:33:44:55:66": (other, _adv("TV", rssi=-70)),
+    }
+    with patch(
+        "igps_ble.scanner.BleakScanner.discover",
+        new=AsyncMock(return_value=discovered),
+    ):
+        results = await discover_devices(timeout=1.0)
+
+    assert len(results) == 1
+    state = results[0]
+    assert state.address == "AA:BB:CC:DD:EE:FF"
+    assert state.name == "iGS10S"
+    assert state.rssi == -44
+    assert state.battery_level is None  # scan não conecta