hubble-gateway-sdk-python 0.1.1__tar.gz → 0.2.0__tar.gz

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/.github/workflows/ci.yml

@@ -27,11 +27,12 @@ jobs:
       - name: Install
         run: python -m pip install -e ".[dev]"
 
-      # `ruff format --check` is not enforced yet: the existing sources are not
-      # format-clean, and reformatting them belongs in its own PR.
-      - name: Ruff
+      - name: Ruff check
         run: ruff check .
 
+      - name: Ruff format
+        run: ruff format --check .
+
   test:
     runs-on: ubuntu-latest
     strategy:
@@ -50,16 +51,5 @@ jobs:
       - name: Install
         run: python -m pip install -e ".[dev]"
 
-      # pytest exits 5 when it collects no tests. main has no tests yet, so
-      # treat 5 as success until the first test file lands; every other
-      # non-zero code still fails the job.
       - name: Pytest
-        run: |
-          set +e
-          pytest -q
-          code=$?
-          if [ "$code" -eq 5 ]; then
-            echo "::notice::pytest collected no tests (exit 5); treating as success."
-            exit 0
-          fi
-          exit "$code"
+        run: pytest -q

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hubble-gateway-sdk-python
-Version: 0.1.1
+Version: 0.2.0
 Summary: Python SDK for building Hubble Network BLE gateways
 Project-URL: Homepage, https://github.com/HubbleNetwork/gateway-sdk-python
 Project-URL: Documentation, https://github.com/HubbleNetwork/gateway-sdk-python#readme
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Home Automation
 Classifier: Topic :: System :: Networking
 Requires-Python: >=3.10
@@ -65,6 +66,18 @@ without a restart.
 
 The local default upload interval is 60 s, the same as the server's floor.
 
+## Scanning
+
+`Scanner` always scans for the Hubble service `FCA6`, plus any configured
+payload services.
+
+- One advertisement gives at most one uploaded sighting: the first service, in
+  priority order (`FCA6` first), that has non-empty service data.
+- `stats["multi_payload_advertisements"]` counts advertisements that carried
+  service data for more than one payload service.
+- `Scanner(service_uuids=[...])` adds scan-only services. Matching
+  advertisements reach the `on_advertisement` callback and are not uploaded.
+
 ## Deduplication
 
 The dedup key is `(device address, 16-bit service UUID, service data hex)`.

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/README.md

@@ -24,6 +24,18 @@ without a restart.
 
 The local default upload interval is 60 s, the same as the server's floor.
 
+## Scanning
+
+`Scanner` always scans for the Hubble service `FCA6`, plus any configured
+payload services.
+
+- One advertisement gives at most one uploaded sighting: the first service, in
+  priority order (`FCA6` first), that has non-empty service data.
+- `stats["multi_payload_advertisements"]` counts advertisements that carried
+  service data for more than one payload service.
+- `Scanner(service_uuids=[...])` adds scan-only services. Matching
+  advertisements reach the `on_advertisement` callback and are not uploaded.
+
 ## Deduplication
 
 The dedup key is `(device address, 16-bit service UUID, service data hex)`.

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hubble-gateway-sdk-python"
-version = "0.1.1"
+version = "0.2.0"
 description = "Python SDK for building Hubble Network BLE gateways"
 readme = "README.md"
 license = "Apache-2.0"
@@ -19,6 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Home Automation",
     "Topic :: System :: Networking",
 ]

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/src/hubble_gateway/__init__.py

@@ -5,7 +5,7 @@ Import the components you need to build a gateway:
     from hubble_gateway import Scanner, GatewaySender, GatewayAuth, Location, BLEPacket
 """
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
 from hubble_gateway.auth import GatewayAuth
 from hubble_gateway.config import (

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/src/hubble_gateway/auth.py

@@ -13,7 +13,7 @@ import structlog
 
 from hubble_gateway import __version__
 from hubble_gateway.config import HUBBLE_SERVICE_UUID
-from hubble_gateway.models import is_bluetooth_base_uuid, normalize_service_uuid
+from hubble_gateway.models import is_bluetooth_base_uuid, normalize_service_uuid, uuid_to_16bit
 
 logger = structlog.get_logger(__name__)
 
@@ -29,25 +29,29 @@ SERVER_CONFIG_RANGES: dict[str, tuple[int, int]] = {
     "dedupWindowMs": (5_000, 3_600_000),
 }
 
-MAX_SCAN_SERVICE_UUIDS = 16
+MAX_PAYLOAD_SERVICE_UUIDS = 8
+_HUBBLE_SERVICE_16 = uuid_to_16bit(HUBBLE_SERVICE_UUID)
 
 
-def _sanitize_scan_service_uuids(value: Any) -> list[str] | None:
-    """Normalize a UUID list to uppercase 128-bit UUIDs, FCA6 first.
+def _sanitize_payload_service_uuids(value: Any) -> list[str] | None:
+    """Normalize a payloadServiceUuids list to ordered 16-bit forms (``FEED``).
 
-    Only 16-bit services are valid (short form or written out on the Bluetooth
-    Base UUID), because gateway-api ingest keys packets on 16-bit service IDs.
-    Other entries are dropped; FCA6 is always kept, as gateway-api does.
-    Returns None when the value is not a list.
+    Accepts the short form or the full form on the Bluetooth Base UUID, in any
+    case. Drops invalid entries and FCA6 (always scanned), dedupes, and keeps
+    the first MAX_PAYLOAD_SERVICE_UUIDS. Returns None when the value is not a
+    list.
     """
     if not isinstance(value, list):
         return None
-    result = [HUBBLE_SERVICE_UUID]
+    result: list[str] = []
     for item in value:
         u = normalize_service_uuid(item) if isinstance(item, str) else None
-        if u is not None and is_bluetooth_base_uuid(u) and u not in result:
-            result.append(u)
-    return result[:MAX_SCAN_SERVICE_UUIDS]
+        if u is None or not is_bluetooth_base_uuid(u):
+            continue
+        short = uuid_to_16bit(u)
+        if short != _HUBBLE_SERVICE_16 and short not in result:
+            result.append(short)
+    return result[:MAX_PAYLOAD_SERVICE_UUIDS]
 
 
 def sanitize_server_config(config: Any) -> dict[str, Any]:
@@ -59,9 +63,10 @@ def sanitize_server_config(config: Any) -> dict[str, Any]:
     if not isinstance(config, dict):
         return {}
     result: dict[str, Any] = {}
-    uuids = _sanitize_scan_service_uuids(config.get("scanServiceUuids"))
+    # The legacy scanServiceUuids key is ignored.
+    uuids = _sanitize_payload_service_uuids(config.get("payloadServiceUuids"))
     if uuids is not None:
-        result["scanServiceUuids"] = uuids
+        result["payloadServiceUuids"] = uuids
     for key, (low, high) in SERVER_CONFIG_RANGES.items():
         value = config.get(key)
         if isinstance(value, bool) or not isinstance(value, (int, float)):
@@ -202,7 +207,9 @@ class GatewayAuth:
         payload = _build_registration_payload()
         logger.info("Registering gateway", base_url=self._base_url)
         resp = await self._request(
-            "PUT", "/api/v1/gateways", json_body=payload,
+            "PUT",
+            "/api/v1/gateways",
+            json_body=payload,
             extra_headers={"X-Sdk-Key": self._sdk_key},
         )
         if resp.status_code not in (200, 201):
@@ -228,7 +235,8 @@ class GatewayAuth:
     async def _refresh(self) -> bool:
         logger.info("Refreshing device token")
         resp = await self._request(
-            "POST", "/api/v1/auth/refresh",
+            "POST",
+            "/api/v1/auth/refresh",
             json_body={"refreshToken": self._refresh_token},
         )
         if resp.status_code != 200:
@@ -253,15 +261,22 @@ class GatewayAuth:
             return
         payload = _build_registration_payload()
         resp = await self.authenticated_request(
-            "PUT", f"/api/v1/gateways/{self._gateway_id}", json_body=payload,
+            "PUT",
+            f"/api/v1/gateways/{self._gateway_id}",
+            json_body=payload,
         )
         if resp.status_code == 200:
             self._apply_server_config(resp.json())
             self._persist_tokens()
 
     async def _request(
-        self, method: str, path: str, json_body: dict[str, Any] | None = None,
-        *, authenticated: bool = False, extra_headers: dict[str, str] | None = None,
+        self,
+        method: str,
+        path: str,
+        json_body: dict[str, Any] | None = None,
+        *,
+        authenticated: bool = False,
+        extra_headers: dict[str, str] | None = None,
     ) -> httpx.Response:
         assert self._client is not None, "call start() first"
         headers: dict[str, str] = {}
@@ -270,7 +285,10 @@ class GatewayAuth:
         if extra_headers:
             headers.update(extra_headers)
         return await self._client.request(
-            method, f"{self._base_url}{path}", json=json_body, headers=headers,
+            method,
+            f"{self._base_url}{path}",
+            json=json_body,
+            headers=headers,
         )
 
     def _apply_server_config(self, data: Any) -> None:
@@ -283,13 +301,17 @@ class GatewayAuth:
 
     def _persist_tokens(self) -> None:
         self._token_path.parent.mkdir(parents=True, exist_ok=True)
-        self._token_path.write_text(json.dumps({
-            "gatewayId": self._gateway_id,
-            "deviceToken": self._device_token,
-            "refreshToken": self._refresh_token,
-            "expiresAtMs": self._expires_at_ms,
-            "serverConfig": self.server_config,
-        }))
+        self._token_path.write_text(
+            json.dumps(
+                {
+                    "gatewayId": self._gateway_id,
+                    "deviceToken": self._device_token,
+                    "refreshToken": self._refresh_token,
+                    "expiresAtMs": self._expires_at_ms,
+                    "serverConfig": self.server_config,
+                }
+            )
+        )
         self._token_path.chmod(0o600)
 
     def _load_persisted_tokens(self) -> None:

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/src/hubble_gateway/config.py

@@ -5,7 +5,9 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 
 HUBBLE_SERVICE_UUID = "0000FCA6-0000-1000-8000-00805F9B34FB"
 TILE_SERVICE_UUID = "0000FEED-0000-1000-8000-00805F9B34FB"
-DEFAULT_SERVICE_UUIDS = [HUBBLE_SERVICE_UUID, TILE_SERVICE_UUID]
+# FCA6 is always scanned. Other payload services come from the
+# payloadServiceUuids config key, so the compiled-in default is FCA6 only.
+DEFAULT_SERVICE_UUIDS = [HUBBLE_SERVICE_UUID]
 
 GATEWAY_API_BASE_URL = "https://gw-api.hubble.com"
 
@@ -38,8 +40,11 @@ class Settings(BaseSettings):
 
     # BLE scanning
     service_uuids: list[str] = Field(
-        default=DEFAULT_SERVICE_UUIDS,
-        description="BLE service UUIDs to scan for",
+        default_factory=list,
+        description=(
+            "Extra BLE service UUIDs to scan for. Scan-only: they reach "
+            "on_advertisement listeners and are not uploaded."
+        ),
     )
     scan_duration_seconds: float = Field(
         default=5.0,

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/src/hubble_gateway/location.py

@@ -150,7 +150,8 @@ class SerialGPSLocationProvider(LocationProvider):
         import serial_asyncio
 
         self._reader, self._writer = await serial_asyncio.open_serial_connection(
-            url=self._port, baudrate=self._baud_rate,
+            url=self._port,
+            baudrate=self._baud_rate,
         )
         self._running = True
         self._location.gps_state = "searching"
@@ -331,6 +332,7 @@ class GPSDLocationProvider(LocationProvider):
     async def start(self) -> None:
         try:
             import gpsd
+
             gpsd.connect()
             self._running = True
             logger.info("GPSD location provider started")

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/src/hubble_gateway/models.py

@@ -10,9 +10,7 @@ from pydantic import BaseModel, Field
 BLUETOOTH_BASE_UUID_SUFFIX = "-0000-1000-8000-00805F9B34FB"
 
 _UUID16_PATTERN = re.compile(r"^[0-9A-F]{4}$")
-_UUID128_PATTERN = re.compile(
-    r"^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$"
-)
+_UUID128_PATTERN = re.compile(r"^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$")
 
 
 def normalize_service_uuid(value: str) -> str | None:
@@ -130,9 +128,7 @@ class BLEPacket(BaseModel):
     ) -> dict[str, Any]:
         """Convert to gateway-api packet format."""
         payload_bytes = self.get_matched_service_data()
-        service_data_b64 = (
-            base64.b64encode(payload_bytes).decode() if payload_bytes else None
-        )
+        service_data_b64 = base64.b64encode(payload_bytes).decode() if payload_bytes else None
         ts_ms = int(self.timestamp.timestamp() * 1000)
 
         packet: dict[str, Any] = {

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/src/hubble_gateway/scanner.py

@@ -10,8 +10,8 @@ from bleak import BleakScanner
 from bleak.backends.device import BLEDevice
 from bleak.backends.scanner import AdvertisementData
 
-from hubble_gateway.config import DEFAULT_SERVICE_UUIDS
-from hubble_gateway.models import BLEPacket, is_bluetooth_base_uuid, uuid_to_16bit
+from hubble_gateway.config import HUBBLE_SERVICE_UUID
+from hubble_gateway.models import BLEPacket, normalize_service_uuid, uuid_to_16bit
 
 if TYPE_CHECKING:
     from hubble_gateway.auth import GatewayAuth
@@ -19,12 +19,38 @@ if TYPE_CHECKING:
 logger = structlog.get_logger(__name__)
 
 
+def _normalize_all(uuids: list[str]) -> list[str]:
+    """Lowercase 128-bit forms of the valid UUIDs, in order."""
+    result = []
+    for u in uuids:
+        full = normalize_service_uuid(u) if isinstance(u, str) else None
+        if full is not None:
+            result.append(full.lower())
+    return result
+
+
+def _dedupe(uuids: list[str]) -> list[str]:
+    return list(dict.fromkeys(uuids))
+
+
 class Scanner:
     """Continuous BLE scanner that filters by service UUID(s).
 
-    Supports scanning for multiple UUIDs simultaneously (e.g. Hubble FCA6
-    and Tile FEED). Works with both internal BLE adapters and external USB
-    dongles — pass ``adapter='hci1'`` to select a specific adapter.
+    Service classes:
+
+    - Hubble ``FCA6``: always scanned; service data is a payload.
+    - Payload services: the ``payloadServiceUuids`` list in
+      ``auth.server_config`` (0 to 8, ordered); service data is a payload.
+    - ``service_uuids``: scan-only; matching advertisements reach
+      ``on_advertisement`` but are not payloads.
+
+    One advertisement gives at most one payload, passed to ``on_packet``: the
+    first UUID with non-empty service data, in priority order ``FCA6`` then
+    the payload list. An advertisement with service data for more than one
+    payload UUID is counted in ``stats["multi_payload_advertisements"]``.
+
+    Works with both internal BLE adapters and external USB dongles — pass
+    ``adapter='hci1'`` to select a specific adapter.
     """
 
     def __init__(
@@ -34,19 +60,22 @@ class Scanner:
         on_packet: Callable[[BLEPacket], None] | None = None,
         adapter: str | None = None,
         auth: "GatewayAuth | None" = None,
+        on_advertisement: Callable[[BLEPacket], None] | None = None,
     ) -> None:
-        self._local_service_uuids = list(service_uuids or DEFAULT_SERVICE_UUIDS)
+        self._scan_only_uuids = _normalize_all(service_uuids or [])
         self._auth = auth
+        self._payload_uuids: list[str] = []
         self._service_uuids: list[str] = []
-        self._uuid_variants: dict[str, str] = {}
         self._scan_duration = scan_duration
         self._on_packet = on_packet
+        self._on_advertisement = on_advertisement
         self._adapter = adapter or None
         self._running = False
         self._paused = False
         self._seen_devices: set[str] = set()
         self._devices_this_scan: set[str] = set()
         self._total_packets = 0
+        self._multi_payload_advertisements = 0
         self._refresh_service_uuids()
 
     @property
@@ -54,49 +83,53 @@ class Scanner:
         """The UUIDs the current scan cycle filters on (lowercase 128-bit)."""
         return list(self._service_uuids)
 
-    def _effective_service_uuids(self) -> list[str]:
+    @property
+    def payload_service_uuids(self) -> list[str]:
+        """Payload UUIDs in priority order, ``FCA6`` first (lowercase 128-bit)."""
+        return list(self._payload_uuids)
+
+    def _effective_payload_uuids(self) -> list[str]:
+        configured: list[str] = []
         if self._auth is not None:
-            server = self._auth.server_config.get("scanServiceUuids")
-            if server:
-                return server
-        return self._local_service_uuids
+            value = self._auth.server_config.get("payloadServiceUuids")
+            if isinstance(value, list):
+                configured = value
+        return _dedupe([HUBBLE_SERVICE_UUID.lower(), *_normalize_all(configured)])
 
     def _refresh_service_uuids(self) -> bool:
-        """Adopt the effective UUID list; return True if it changed."""
-        uuids = [u.lower() for u in self._effective_service_uuids()]
-        if uuids == self._service_uuids:
+        """Adopt the effective UUID lists; return True if they changed."""
+        payload = self._effective_payload_uuids()
+        scan = _dedupe([*payload, *self._scan_only_uuids])
+        if payload == self._payload_uuids and scan == self._service_uuids:
             return False
-        variants: dict[str, str] = {}
-        for full_uuid in uuids:
-            variants[full_uuid] = full_uuid
-            # Only a Bluetooth Base UUID has a 16-bit alias; slicing any other
-            # UUID would match an unrelated 16-bit service.
-            if is_bluetooth_base_uuid(full_uuid):
-                variants[full_uuid[4:8]] = full_uuid
-        self._service_uuids = uuids
-        self._uuid_variants = variants
+        self._payload_uuids = payload
+        self._service_uuids = scan
         return True
 
-    def _match_service_uuid(self, advertised_uuids: list[str]) -> str | None:
-        for adv_uuid in advertised_uuids:
-            key = adv_uuid.lower()
-            if key in self._uuid_variants:
-                return self._uuid_variants[key]
-        return None
-
-    def _detection_callback(
-        self, device: BLEDevice, advertisement_data: AdvertisementData
-    ) -> None:
+    def _detection_callback(self, device: BLEDevice, advertisement_data: AdvertisementData) -> None:
         adv_uuids = [str(u).lower() for u in advertisement_data.service_uuids or []]
-        matched_uuid = self._match_service_uuid(adv_uuids)
+        raw_service_data = advertisement_data.service_data or {}
+        service_data: dict[str, bytes] = {}
+        for k, v in raw_service_data.items():
+            u = normalize_service_uuid(str(k))
+            if u is not None:
+                service_data[u.lower()] = v
+
+        with_payload = [u for u in self._payload_uuids if service_data.get(u)]
+        if len(with_payload) > 1:
+            self._multi_payload_advertisements += 1
+        payload_uuid = with_payload[0] if with_payload else None
+
+        matched_uuid = payload_uuid
+        if matched_uuid is None:
+            present = set(_normalize_all(adv_uuids)) | set(service_data)
+            matched_uuid = next((u for u in self._service_uuids if u in present), None)
         if matched_uuid is None:
             return
 
         addr = device.address
-        if addr not in self._seen_devices:
-            self._seen_devices.add(addr)
+        self._seen_devices.add(addr)
         self._devices_this_scan.add(addr)
-        self._total_packets += 1
 
         packet = BLEPacket(
             device_address=addr,
@@ -104,16 +137,22 @@ class Scanner:
             rssi=advertisement_data.rssi,
             service_uuids=adv_uuids,
             manufacturer_data=dict(advertisement_data.manufacturer_data or {}),
-            service_data={str(k): v for k, v in (advertisement_data.service_data or {}).items()},
+            service_data={str(k): v for k, v in raw_service_data.items()},
             tx_power=advertisement_data.tx_power,
             timestamp=datetime.now(timezone.utc),
             service_uuid=matched_uuid,
         )
 
-        short = uuid_to_16bit(matched_uuid)
+        if self._on_advertisement:
+            self._on_advertisement(packet)
+
+        if payload_uuid is None:
+            return
+
+        self._total_packets += 1
         logger.debug(
             "BLE packet",
-            uuid=short,
+            uuid=uuid_to_16bit(payload_uuid),
             addr=addr[-8:],
             rssi=packet.rssi,
             name=packet.device_name,
@@ -124,10 +163,10 @@ class Scanner:
 
     async def start(self) -> None:
         self._running = True
-        uuid_labels = [uuid_to_16bit(u) for u in self._service_uuids]
         logger.info(
             "Scanner started",
-            service_uuids=uuid_labels,
+            payload_service_uuids=[uuid_to_16bit(u) for u in self._payload_uuids],
+            service_uuids=[uuid_to_16bit(u) for u in self._service_uuids],
             scan_duration=self._scan_duration,
             adapter=self._adapter or "default",
         )
@@ -139,6 +178,7 @@ class Scanner:
             if self._refresh_service_uuids():
                 logger.info(
                     "Scan UUIDs changed",
+                    payload_service_uuids=[uuid_to_16bit(u) for u in self._payload_uuids],
                     service_uuids=[uuid_to_16bit(u) for u in self._service_uuids],
                 )
             scanner_kwargs: dict = {
@@ -184,4 +224,5 @@ class Scanner:
             "total_packets": self._total_packets,
             "unique_devices": len(self._seen_devices),
             "active_devices": len(self._devices_this_scan),
+            "multi_payload_advertisements": self._multi_payload_advertisements,
         }

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/src/hubble_gateway/sender.py

@@ -96,7 +96,9 @@ class GatewaySender:
         self._stats_total += 1
         self._stats_devices.add(packet.device_address)
         key: _DedupKey = (
-            packet.device_address, packet.service_uuid_16bit, packet.service_data_hex,
+            packet.device_address,
+            packet.service_uuid_16bit,
+            packet.service_data_hex,
         )
         now_ms = int(packet.timestamp.timestamp() * 1000)
         window_ms = self.dedup_window_s * 1000
@@ -206,7 +208,8 @@ class GatewaySender:
         packets_json = []
         for entry in entries:
             pkt = entry.packet.to_gateway_packet(
-                location=location, sighting_count=entry.sighting_count,
+                location=location,
+                sighting_count=entry.sighting_count,
             )
             pkt["rssi"] = entry.strongest_rssi
             packets_json.append(pkt)
@@ -219,7 +222,9 @@ class GatewaySender:
 
         try:
             resp = await self._auth.authenticated_request(
-                "POST", f"/api/v1/gateways/{gateway_id}/packets", json_body=body,
+                "POST",
+                f"/api/v1/gateways/{gateway_id}/packets",
+                json_body=body,
             )
             if resp.status_code in (200, 201, 202):
                 self._stats_sends += 1
@@ -247,7 +252,9 @@ class GatewaySender:
         }
         try:
             await self._auth.authenticated_request(
-                "POST", f"/api/v1/gateways/{gateway_id}/locations", json_body=body,
+                "POST",
+                f"/api/v1/gateways/{gateway_id}/locations",
+                json_body=body,
             )
         except Exception as e:
             logger.warning("Location upload failed", error=str(e))

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/src/hubble_gateway/ubx.py

@@ -80,15 +80,28 @@ def _parse_nav_pvt_payload(payload: bytes) -> UBXNavPVT:
     pdop_raw = struct.unpack_from("<H", payload, 76)[0]
 
     return UBXNavPVT(
-        itow_ms=itow_ms, year=year, month=month, day=day,
-        hour=hour, minute=minute, second=second, valid=valid,
-        valid_date=bool(valid & 0x01), valid_time=bool(valid & 0x02),
-        fix_type=fix_type, flags=flags, gnss_fix_ok=bool(flags & 0x01),
+        itow_ms=itow_ms,
+        year=year,
+        month=month,
+        day=day,
+        hour=hour,
+        minute=minute,
+        second=second,
+        valid=valid,
+        valid_date=bool(valid & 0x01),
+        valid_time=bool(valid & 0x02),
+        fix_type=fix_type,
+        flags=flags,
+        gnss_fix_ok=bool(flags & 0x01),
         num_sv=num_sv,
-        lat=lat_i / 1e7, lon=lon_i / 1e7,
-        height_ellipsoid_m=height_mm / 1000.0, alt_msl_m=hmsl_mm / 1000.0,
-        hacc_m=hacc_mm / 1000.0, vacc_m=vacc_mm / 1000.0,
-        ground_speed_ms=g_speed_mm_s / 1000.0, heading_deg=head_mot / 1e5,
+        lat=lat_i / 1e7,
+        lon=lon_i / 1e7,
+        height_ellipsoid_m=height_mm / 1000.0,
+        alt_msl_m=hmsl_mm / 1000.0,
+        hacc_m=hacc_mm / 1000.0,
+        vacc_m=vacc_mm / 1000.0,
+        ground_speed_ms=g_speed_mm_s / 1000.0,
+        heading_deg=head_mot / 1e5,
         pdop=pdop_raw / 100.0,
     )
 
@@ -107,7 +120,8 @@ class UBXReader:
         import serial_asyncio
 
         self._reader, self._writer = await serial_asyncio.open_serial_connection(
-            url=self._port, baudrate=self._baud_rate,
+            url=self._port,
+            baudrate=self._baud_rate,
         )
         self._buf.clear()
         logger.info("UBX reader connected", port=self._port, baud_rate=self._baud_rate)
@@ -117,7 +131,7 @@ class UBXReader:
         """Enable UBX NAV-PVT output on UART (persisted to flash)."""
         if self._writer is None:
             return
-        kv = struct.pack("<IB", 0x10750001, 1)   # CFG-UART2OUTPROT-UBX = true
+        kv = struct.pack("<IB", 0x10750001, 1)  # CFG-UART2OUTPROT-UBX = true
         kv += struct.pack("<IB", 0x20910008, 1)  # CFG-MSGOUT-UBX_NAV_PVT_UART2 = 1
         payload = struct.pack("<BBH", 0x00, 0x07, 0x0000) + kv
         frame = _ubx_frame(0x06, 0x8A, payload)
@@ -185,7 +199,7 @@ class UBXReader:
                 if remaining <= 0:
                     return None
 
-            body = bytes(self._buf[2:6 + payload_len])
+            body = bytes(self._buf[2 : 6 + payload_len])
             ck_a, ck_b = self._buf[6 + payload_len], self._buf[6 + payload_len + 1]
             exp_a, exp_b = _ubx_checksum(body)
 
@@ -211,9 +225,7 @@ class UBXReader:
         if self._reader is None:
             return None
         try:
-            return await asyncio.wait_for(
-                self._reader.read(max(max_bytes, 1)), timeout=timeout_s
-            )
+            return await asyncio.wait_for(self._reader.read(max(max_bytes, 1)), timeout=timeout_s)
         except asyncio.TimeoutError:
             return None
 

hubble_gateway_sdk_python-0.2.0/tests/test_payload_service_uuids.py

@@ -0,0 +1,305 @@
+import json
+from types import SimpleNamespace
+
+import httpx
+import pytest
+
+from hubble_gateway import scanner as scanner_mod
+from hubble_gateway.auth import GatewayAuth, sanitize_server_config
+from hubble_gateway.config import HUBBLE_SERVICE_UUID, TILE_SERVICE_UUID, Settings
+from hubble_gateway.models import uuid_to_16bit
+from hubble_gateway.scanner import Scanner
+
+FCA6 = HUBBLE_SERVICE_UUID.lower()
+FEED = TILE_SERVICE_UUID.lower()
+CUSTOM = "12345678-ABCD-1234-ABCD-1234567890AB"
+BASE_180F = "0000180f-0000-1000-8000-00805f9b34fb"
+BASE_181A = "0000181a-0000-1000-8000-00805f9b34fb"
+
+
+def _payload(raw):
+    return sanitize_server_config({"payloadServiceUuids": raw}).get("payloadServiceUuids")
+
+
+# --- config parsing / validation / clamping ---------------------------------
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        (["FEED"], ["FEED"]),
+        (["feed", "180f"], ["FEED", "180F"]),
+        ([], []),
+        (["FCA6"], []),
+        (["FCA6", "FEED", HUBBLE_SERVICE_UUID.lower()], ["FEED"]),
+        ([BASE_180F, "180F", "feed"], ["180F", "FEED"]),
+        ([BASE_180F.upper()], ["180F"]),
+        ([CUSTOM, CUSTOM.lower()], []),
+        (["00010000-0000-1000-8000-00805F9B34FB"], []),
+        (["FEED", "nope", 7, None, "FCA", "FEEDD", "", "FEED"], ["FEED"]),
+        ([" feed "], ["FEED"]),
+    ],
+)
+def test_payload_list_normalized(raw, expected):
+    assert _payload(raw) == expected
+
+
+def test_payload_list_order_kept():
+    assert _payload(["181A", "FEED", "180F"]) == ["181A", "FEED", "180F"]
+
+
+def test_payload_list_capped_at_8_after_filtering():
+    raw = ["FCA6", "nope"] + [f"{i:04X}" for i in range(1, 20)]
+    assert _payload(raw) == [f"{i:04X}" for i in range(1, 9)]
+
+
+@pytest.mark.parametrize("raw", [None, "FCA6,FEED", {"a": 1}, 5])
+def test_payload_list_wrong_type_dropped(raw):
+    assert "payloadServiceUuids" not in sanitize_server_config({"payloadServiceUuids": raw})
+
+
+def test_legacy_scan_service_uuids_ignored():
+    cfg = sanitize_server_config({"scanServiceUuids": ["FCA6", "FEED"], "uploadBatchSize": 10})
+    assert cfg == {"uploadBatchSize": 10}
+
+
+def test_legacy_key_alongside_new_key():
+    cfg = sanitize_server_config(
+        {"scanServiceUuids": ["FCA6", "180F"], "payloadServiceUuids": ["FEED"]}
+    )
+    assert cfg == {"payloadServiceUuids": ["FEED"]}
+
+
+def test_uuid_to_16bit():
+    assert uuid_to_16bit(FCA6) == "FCA6"
+    assert uuid_to_16bit(CUSTOM.lower()) == CUSTOM
+
+
+def test_settings_default_has_no_scan_only_uuids():
+    assert Settings(_env_file=None).service_uuids == []
+
+
+# --- scanner: one payload sighting per advertisement ------------------------
+
+
+def _auth(config=None):
+    return SimpleNamespace(server_config=config if config is not None else {})
+
+
+def _adv(service_data: dict, service_uuids: list | None = None):
+    device = SimpleNamespace(address="AA:BB:CC:DD:EE:FF", name=None)
+    adv = SimpleNamespace(
+        service_uuids=list(service_data) if service_uuids is None else service_uuids,
+        service_data=service_data,
+        manufacturer_data={},
+        rssi=-50,
+        tx_power=None,
+        local_name=None,
+    )
+    return device, adv
+
+
+def _scanner(payload=None, scan_only=None):
+    packets, adverts = [], []
+    cfg = {} if payload is None else {"payloadServiceUuids": payload}
+    s = Scanner(
+        service_uuids=scan_only,
+        on_packet=packets.append,
+        on_advertisement=adverts.append,
+        auth=_auth(cfg),
+    )
+    return s, packets, adverts
+
+
+def test_fca6_always_scanned_without_config():
+    s, _, _ = _scanner()
+    assert s.payload_service_uuids == [FCA6]
+    assert s.service_uuids == [FCA6]
+    assert Scanner().service_uuids == [FCA6]
+
+
+def test_filter_is_fca6_then_payload_then_scan_only_deduped():
+    s, _, _ = _scanner(payload=["FEED", "180F"], scan_only=["180F", CUSTOM, "fca6"])
+    assert s.payload_service_uuids == [FCA6, FEED, BASE_180F]
+    assert s.service_uuids == [FCA6, FEED, BASE_180F, CUSTOM.lower()]
+
+
+def test_fca6_only_advert_emits_one():
+    s, packets, _ = _scanner(payload=["FEED"])
+    s._detection_callback(*_adv({FCA6: b"\x01"}))
+    assert [p.to_gateway_packet()["serviceUuid"] for p in packets] == ["FCA6"]
+    assert s.stats["multi_payload_advertisements"] == 0
+
+
+def test_payload_uuid_emits():
+    s, packets, _ = _scanner(payload=["FEED"])
+    s._detection_callback(*_adv({FEED: b"\x02"}))
+    gp = packets[0].to_gateway_packet()
+    assert gp["serviceUuid"] == "FEED"
+    assert gp["serviceData"] == "Ag=="
+
+
+def test_two_payloads_in_one_advert_fca6_wins_and_is_counted():
+    s, packets, _ = _scanner(payload=["FEED"])
+    s._detection_callback(*_adv({FEED: b"\x02", FCA6: b"\x01"}))
+    assert len(packets) == 1
+    assert packets[0].to_gateway_packet()["serviceUuid"] == "FCA6"
+    assert packets[0].to_gateway_packet()["serviceData"] == "AQ=="
+    assert s.stats["multi_payload_advertisements"] == 1
+
+
+def test_two_payloads_list_order_wins():
+    s, packets, _ = _scanner(payload=["180F", "FEED"])
+    s._detection_callback(*_adv({FEED: b"\x02", BASE_180F: b"\x03"}))
+    assert [p.to_gateway_packet()["serviceUuid"] for p in packets] == ["180F"]
+    assert s.stats["multi_payload_advertisements"] == 1
+    assert s.stats["total_packets"] == 1
+
+
+def test_empty_service_data_skipped_in_priority():
+    s, packets, _ = _scanner(payload=["FEED"])
+    s._detection_callback(*_adv({FCA6: b"", FEED: b"\x02"}))
+    assert [p.to_gateway_packet()["serviceUuid"] for p in packets] == ["FEED"]
+    assert s.stats["multi_payload_advertisements"] == 0
+
+
+def test_listed_uuid_without_service_data_is_not_a_payload():
+    s, packets, adverts = _scanner(payload=["FEED"])
+    s._detection_callback(*_adv({}, service_uuids=[FEED]))
+    assert packets == []
+    assert len(adverts) == 1
+
+
+def test_payload_not_in_list_is_dropped():
+    s, packets, adverts = _scanner(payload=["FEED"])
+    s._detection_callback(*_adv({BASE_180F: b"\x03"}))
+    assert packets == [] and adverts == []
+
+
+def test_service_data_only_advert_matches():
+    s, packets, _ = _scanner(payload=["FEED"])
+    s._detection_callback(*_adv({FEED: b"\x02"}, service_uuids=[]))
+    assert [p.to_gateway_packet()["serviceUuid"] for p in packets] == ["FEED"]
+
+
+def test_scan_only_reaches_listener_not_upload():
+    s, packets, adverts = _scanner(payload=["FEED"], scan_only=["180F"])
+    s._detection_callback(*_adv({BASE_180F: b"\x03"}))
+    assert packets == []
+    assert [a.service_uuid for a in adverts] == [BASE_180F]
+    assert s.stats["total_packets"] == 0
+
+
+def test_scan_only_overlapping_payload_list_is_uploaded():
+    s, packets, adverts = _scanner(payload=["180F"], scan_only=["180F"])
+    s._detection_callback(*_adv({BASE_180F: b"\x03"}))
+    assert [p.to_gateway_packet()["serviceUuid"] for p in packets] == ["180F"]
+    assert len(adverts) == 1
+
+
+def test_empty_list_means_fca6_only():
+    s, packets, _ = _scanner(payload=[])
+    s._detection_callback(*_adv({FEED: b"\x02"}))
+    s._detection_callback(*_adv({FCA6: b"\x01"}))
+    assert [p.to_gateway_packet()["serviceUuid"] for p in packets] == ["FCA6"]
+
+
+def test_legacy_scan_list_in_scanner_config_is_ignored():
+    s = Scanner(auth=_auth({"scanServiceUuids": [FCA6, FEED]}))
+    assert s.service_uuids == [FCA6]
+
+
+# --- config arrival ---------------------------------------------------------
+
+
+async def test_scanner_applies_new_list_next_cycle(monkeypatch):
+    auth = _auth()
+    calls: list[list[str]] = []
+    s = Scanner(scan_duration=0, auth=auth)
+
+    class FakeBleak:
+        def __init__(self, **kwargs):
+            calls.append(list(kwargs["service_uuids"]))
+
+        async def __aenter__(self):
+            if len(calls) == 1:
+                auth.server_config = {"payloadServiceUuids": ["FEED", "180F"]}
+            elif len(calls) == 2:
+                auth.server_config = {}
+            else:
+                s._running = False
+            return self
+
+        async def __aexit__(self, *exc):
+            return False
+
+    monkeypatch.setattr(scanner_mod, "BleakScanner", FakeBleak)
+    await s.start()
+    assert calls == [[FCA6], [FCA6, FEED, BASE_180F], [FCA6]]
+
+
+async def test_auth_three_case_rule(tmp_path):
+    bodies = {"heartbeat": {}}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.url.path == "/api/v1/gateways":
+            return httpx.Response(
+                201,
+                json={
+                    "gatewayId": "gw-1",
+                    "deviceToken": "dt",
+                    "refreshToken": "rt",
+                    "expiresInSeconds": 3600,
+                    "config": {"payloadServiceUuids": ["FEED", "180F"]},
+                },
+            )
+        return httpx.Response(200, json=bodies["heartbeat"])
+
+    token_path = tmp_path / "a.json"
+    auth = GatewayAuth("k", "https://gw.test", token_path=str(token_path))
+    auth._client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+    assert await auth.ensure_authenticated()
+    s = Scanner(auth=auth)
+    assert s.payload_service_uuids == [FCA6, FEED, BASE_180F]
+    assert json.loads(token_path.read_text())["serverConfig"]["payloadServiceUuids"] == [
+        "FEED",
+        "180F",
+    ]
+
+    # No "config" key: keep the current list.
+    await auth.heartbeat()
+    assert auth.server_config["payloadServiceUuids"] == ["FEED", "180F"]
+
+    # Object without the field: FCA6 only.
+    bodies["heartbeat"] = {"config": {"uploadBatchSize": 10}}
+    await auth.heartbeat()
+    s._refresh_service_uuids()
+    assert s.payload_service_uuids == [FCA6]
+
+    # Object with the field again, then config: null clears it.
+    bodies["heartbeat"] = {"config": {"payloadServiceUuids": [BASE_181A.upper()]}}
+    await auth.heartbeat()
+    s._refresh_service_uuids()
+    assert s.payload_service_uuids == [FCA6, BASE_181A]
+
+    bodies["heartbeat"] = {"config": None}
+    await auth.heartbeat()
+    s._refresh_service_uuids()
+    assert s.payload_service_uuids == [FCA6]
+
+
+def test_persisted_legacy_scan_list_dropped_on_load(tmp_path):
+    token_path = tmp_path / "a.json"
+    token_path.write_text(
+        json.dumps(
+            {
+                "gatewayId": "gw-1",
+                "serverConfig": {
+                    "scanServiceUuids": [HUBBLE_SERVICE_UUID, TILE_SERVICE_UUID],
+                    "payloadServiceUuids": ["feed", "FCA6"],
+                },
+            }
+        )
+    )
+    auth = GatewayAuth("k", "https://gw.test", token_path=str(token_path))
+    assert auth.server_config == {"payloadServiceUuids": ["FEED"]}

{hubble_gateway_sdk_python-0.1.1 → hubble_gateway_sdk_python-0.2.0}/tests/test_server_config.py

@@ -166,10 +166,18 @@ async def test_heartbeat_persists_config(auth, server, tmp_path):
 
 def test_persisted_stale_keys_dropped(tmp_path):
     path = tmp_path / "auth.json"
-    path.write_text(json.dumps({
-        "gatewayId": "gw-1",
-        "serverConfig": {"uploadIntervalMs": 1_000, "scanIntervalMs": 5, "featureFlags": {}},
-    }))
+    path.write_text(
+        json.dumps(
+            {
+                "gatewayId": "gw-1",
+                "serverConfig": {
+                    "uploadIntervalMs": 1_000,
+                    "scanIntervalMs": 5,
+                    "featureFlags": {},
+                },
+            }
+        )
+    )
     a = GatewayAuth("sdk-key", "https://gw.test", token_path=str(path))
     assert a.server_config == {"uploadIntervalMs": 60_000}
 
@@ -260,8 +268,11 @@ async def test_dedup_keys_capped(auth, monkeypatch):
     for addr in ("A1", "A2", "A3", "A4", "A5"):
         sender.add_packet(_packet(addr, t0))
     assert sender.stats["dedup_keys"] == 3
-    assert list(sender._window_start_ms) == [("A3", "FCA6", "01"), ("A4", "FCA6", "01"),
-                                             ("A5", "FCA6", "01")]
+    assert list(sender._window_start_ms) == [
+        ("A3", "FCA6", "01"),
+        ("A4", "FCA6", "01"),
+        ("A5", "FCA6", "01"),
+    ]
 
 
 def test_default_upload_interval_is_60s(auth, monkeypatch):

hubble_gateway_sdk_python-0.1.1/tests/test_scan_service_uuids.py

@@ -1,156 +0,0 @@
-from types import SimpleNamespace
-
-import httpx
-import pytest
-
-from hubble_gateway import scanner as scanner_mod
-from hubble_gateway.auth import GatewayAuth, sanitize_server_config
-from hubble_gateway.config import HUBBLE_SERVICE_UUID, TILE_SERVICE_UUID
-from hubble_gateway.models import uuid_to_16bit
-from hubble_gateway.scanner import Scanner
-
-FCA6 = HUBBLE_SERVICE_UUID
-FEED = TILE_SERVICE_UUID
-CUSTOM = "12345678-ABCD-1234-ABCD-1234567890AB"
-BASE_180F = "0000180F-0000-1000-8000-00805F9B34FB"
-
-
-def _scan(raw):
-    return sanitize_server_config({"scanServiceUuids": raw}).get("scanServiceUuids")
-
-
-@pytest.mark.parametrize(
-    ("raw", "expected"),
-    [
-        (["FCA6", "FEED"], [FCA6, FEED]),
-        (["feed"], [FCA6, FEED]),
-        ([], [FCA6]),
-        (["180F", FCA6.lower()], [FCA6, BASE_180F]),
-        ([BASE_180F.lower(), "180F"], [FCA6, BASE_180F]),
-        ([CUSTOM.lower()], [FCA6]),
-        (["FEED", CUSTOM], [FCA6, FEED]),
-        (["00010000-0000-1000-8000-00805F9B34FB"], [FCA6]),
-        (["FEED", "nope", 7, None, "FCA", "FEED"], [FCA6, FEED]),
-    ],
-)
-def test_scan_list_normalized(raw, expected):
-    assert _scan(raw) == expected
-
-
-def test_scan_list_capped_at_16():
-    raw = [f"{i:04X}" for i in range(1, 40)]
-    result = _scan(raw)
-    assert len(result) == 16
-    assert result[0] == FCA6
-
-
-@pytest.mark.parametrize("raw", [None, "FCA6,FEED", {"a": 1}])
-def test_scan_list_wrong_type_ignored(raw):
-    assert _scan(raw) is None
-
-
-def test_uuid_to_16bit():
-    assert uuid_to_16bit(FCA6.lower()) == "FCA6"
-    assert uuid_to_16bit(CUSTOM.lower()) == CUSTOM
-
-
-def _auth(config=None):
-    return SimpleNamespace(server_config=config or {})
-
-
-def _adv(uuid: str, data: bytes = b"\x01"):
-    device = SimpleNamespace(address="AA:BB:CC:DD:EE:FF", name=None)
-    adv = SimpleNamespace(
-        service_uuids=[uuid],
-        service_data={uuid: data},
-        manufacturer_data={},
-        rssi=-50,
-        tx_power=None,
-        local_name=None,
-    )
-    return device, adv
-
-
-def test_scanner_local_list_without_server_config():
-    s = Scanner(service_uuids=[FCA6, FEED], auth=_auth())
-    assert s.service_uuids == [FCA6.lower(), FEED.lower()]
-
-
-def test_scanner_server_list_replaces_local():
-    packets = []
-    s = Scanner(
-        service_uuids=[FCA6, FEED],
-        on_packet=packets.append,
-        auth=_auth({"scanServiceUuids": [FCA6, BASE_180F]}),
-    )
-    assert s.service_uuids == [FCA6.lower(), BASE_180F.lower()]
-
-    s._detection_callback(*_adv(FEED.lower()))
-    assert packets == []
-
-    s._detection_callback(*_adv(BASE_180F.lower()))
-    assert packets[0].to_gateway_packet()["serviceUuid"] == "180F"
-
-    s._detection_callback(*_adv("fca6"))
-    assert packets[1].to_gateway_packet()["serviceUuid"] == "FCA6"
-
-
-def test_local_custom_uuid_has_no_16bit_alias():
-    s = Scanner(service_uuids=[CUSTOM])
-    assert s._match_service_uuid(["5678"]) is None
-
-
-async def test_scanner_applies_new_list_next_cycle(monkeypatch):
-    auth = _auth()
-    calls: list[list[str]] = []
-    s = Scanner(service_uuids=[FCA6, FEED], scan_duration=0, auth=auth)
-
-    class FakeBleak:
-        def __init__(self, **kwargs):
-            calls.append(list(kwargs["service_uuids"]))
-
-        async def __aenter__(self):
-            if len(calls) == 1:
-                auth.server_config = {"scanServiceUuids": [FCA6, BASE_180F]}
-            elif len(calls) == 2:
-                auth.server_config = {}
-            else:
-                s._running = False
-            return self
-
-        async def __aexit__(self, *exc):
-            return False
-
-    monkeypatch.setattr(scanner_mod, "BleakScanner", FakeBleak)
-    await s.start()
-    assert calls == [
-        [FCA6.lower(), FEED.lower()],
-        [FCA6.lower(), BASE_180F.lower()],
-        [FCA6.lower(), FEED.lower()],
-    ]
-
-
-async def test_auth_scan_list_absent_keeps_null_clears(tmp_path):
-    bodies = {"heartbeat": {}}
-
-    def handler(request: httpx.Request) -> httpx.Response:
-        if request.url.path == "/api/v1/gateways":
-            return httpx.Response(201, json={
-                "gatewayId": "gw-1", "deviceToken": "dt", "refreshToken": "rt",
-                "expiresInSeconds": 3600, "config": {"scanServiceUuids": ["FEED", "180F"]},
-            })
-        return httpx.Response(200, json=bodies["heartbeat"])
-
-    auth = GatewayAuth("k", "https://gw.test", token_path=str(tmp_path / "a.json"))
-    auth._client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
-    assert await auth.ensure_authenticated()
-    s = Scanner(service_uuids=[FCA6, FEED], auth=auth)
-    assert auth.server_config["scanServiceUuids"] == [FCA6, FEED, BASE_180F]
-
-    await auth.heartbeat()
-    assert auth.server_config["scanServiceUuids"] == [FCA6, FEED, BASE_180F]
-
-    bodies["heartbeat"] = {"config": None}
-    await auth.heartbeat()
-    s._refresh_service_uuids()
-    assert s.service_uuids == [FCA6.lower(), FEED.lower()]