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

hubble_gateway_sdk_python-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      - name: Ruff check
+        run: ruff check .
+
+      - name: Ruff format
+        run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      - name: Pytest
+        run: pytest -q

hubble_gateway_sdk_python-0.2.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: hubble-gateway-sdk-python
+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
+Project-URL: Repository, https://github.com/HubbleNetwork/gateway-sdk-python
+Project-URL: Issues, https://github.com/HubbleNetwork/gateway-sdk-python/issues
+Author-email: Hubble Network <dev@hubblenetwork.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ble,bluetooth,gateway,hubble,iot,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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
+Requires-Dist: bleak>=0.21.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic-settings>=2.1.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: structlog>=23.2.0
+Provides-Extra: all
+Requires-Dist: gpsd-py3>=0.3.0; extra == 'all'
+Requires-Dist: pyserial-asyncio>=0.6; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: gpsd-py3>=0.3.0; extra == 'dev'
+Requires-Dist: pyserial-asyncio>=0.6; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: gps
+Requires-Dist: gpsd-py3>=0.3.0; extra == 'gps'
+Requires-Dist: pyserial-asyncio>=0.6; extra == 'gps'
+Description-Content-Type: text/markdown
+
+# hubble-gateway
+
+Python SDK for building Hubble Network BLE gateways. Import `hubble_gateway` in your application; this package is a library only (no CLI).
+
+## Server config
+
+gateway-api sends a `config` object (or `null`) in the registration, heartbeat
+and token-refresh responses. `GatewayAuth` stores it as `server_config`.
+`GatewaySender` reads it on every use, so each new response takes effect
+without a restart.
+
+| Key | Range | Overrides |
+| --- | --- | --- |
+| `uploadIntervalMs` | 60,000 – 3,600,000 | `upload_interval_s` |
+| `uploadBatchSize` | 1 – 500 | `batch_size` |
+| `dedupWindowMs` | 5,000 – 3,600,000 | `dedup_window_s` |
+
+- Each response replaces the stored config. It does not merge into it.
+- `config: null` clears it, and the local values apply again.
+- Out-of-range values are clamped. Values of the wrong type are ignored.
+- Uploaded packets carry the 16-bit form (`FCA6`) as `serviceUuid`.
+- Other keys (`activeUploadIntervalMs`, `activeDedupWindowMs`,
+  `uploadOnCellular`) are ignored: this SDK has no motion state or cellular gating.
+
+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)`.
+For a custom 128-bit UUID, the full UUID takes the place of the 16-bit one.
+
+- The first sighting of a key opens a window of `dedup_window_s`.
+- Repeats inside the window are dropped. If the first sighting is not uploaded
+  yet, a repeat adds to its sighting count and can raise its RSSI.
+- The window is fixed at the first sighting. Repeats do not extend it, so a
+  device that beacons all the time is reported once per window.
+- Windows survive uploads. An upload does not reset them.
+- Expired keys are removed. The map is capped at `MAX_DEDUP_KEYS` (100,000);
+  past the cap, the oldest key is removed first.

hubble_gateway_sdk_python-0.2.0/README.md

@@ -0,0 +1,51 @@
+# hubble-gateway
+
+Python SDK for building Hubble Network BLE gateways. Import `hubble_gateway` in your application; this package is a library only (no CLI).
+
+## Server config
+
+gateway-api sends a `config` object (or `null`) in the registration, heartbeat
+and token-refresh responses. `GatewayAuth` stores it as `server_config`.
+`GatewaySender` reads it on every use, so each new response takes effect
+without a restart.
+
+| Key | Range | Overrides |
+| --- | --- | --- |
+| `uploadIntervalMs` | 60,000 – 3,600,000 | `upload_interval_s` |
+| `uploadBatchSize` | 1 – 500 | `batch_size` |
+| `dedupWindowMs` | 5,000 – 3,600,000 | `dedup_window_s` |
+
+- Each response replaces the stored config. It does not merge into it.
+- `config: null` clears it, and the local values apply again.
+- Out-of-range values are clamped. Values of the wrong type are ignored.
+- Uploaded packets carry the 16-bit form (`FCA6`) as `serviceUuid`.
+- Other keys (`activeUploadIntervalMs`, `activeDedupWindowMs`,
+  `uploadOnCellular`) are ignored: this SDK has no motion state or cellular gating.
+
+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)`.
+For a custom 128-bit UUID, the full UUID takes the place of the 16-bit one.
+
+- The first sighting of a key opens a window of `dedup_window_s`.
+- Repeats inside the window are dropped. If the first sighting is not uploaded
+  yet, a repeat adds to its sighting count and can raise its RSSI.
+- The window is fixed at the first sighting. Repeats do not extend it, so a
+  device that beacons all the time is reported once per window.
+- Windows survive uploads. An upload does not reset them.
+- Expired keys are removed. The map is capped at `MAX_DEDUP_KEYS` (100,000);
+  past the cap, the oldest key is removed first.

{hubble_gateway_sdk_python-0.1.0 → 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.0"
+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.0 → 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.0"
+__version__ = "0.2.0"
 
 from hubble_gateway.auth import GatewayAuth
 from hubble_gateway.config import (

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

@@ -2,6 +2,7 @@
 
 import json
 import locale
+import math
 import platform
 import time
 from pathlib import Path
@@ -11,11 +12,70 @@ import httpx
 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, uuid_to_16bit
 
 logger = structlog.get_logger(__name__)
 
 _TOKEN_EXPIRY_MARGIN_S = 60
 
+# Server config keys this SDK applies, with the inclusive range gateway-api
+# allows for them. gateway-api may also send activeUploadIntervalMs,
+# activeDedupWindowMs and uploadOnCellular; Python has no motion state or
+# cellular gating, so those are dropped.
+SERVER_CONFIG_RANGES: dict[str, tuple[int, int]] = {
+    "uploadIntervalMs": (60_000, 3_600_000),
+    "uploadBatchSize": (1, 500),
+    "dedupWindowMs": (5_000, 3_600_000),
+}
+
+MAX_PAYLOAD_SERVICE_UUIDS = 8
+_HUBBLE_SERVICE_16 = uuid_to_16bit(HUBBLE_SERVICE_UUID)
+
+
+def _sanitize_payload_service_uuids(value: Any) -> list[str] | None:
+    """Normalize a payloadServiceUuids list to ordered 16-bit forms (``FEED``).
+
+    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: list[str] = []
+    for item in value:
+        u = normalize_service_uuid(item) if isinstance(item, str) else None
+        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]:
+    """Keep the keys this SDK uses, clamped to their ranges.
+
+    Values of the wrong type (null, strings, bools, NaN) are dropped, so the
+    local setting applies for that key.
+    """
+    if not isinstance(config, dict):
+        return {}
+    result: dict[str, Any] = {}
+    # The legacy scanServiceUuids key is ignored.
+    uuids = _sanitize_payload_service_uuids(config.get("payloadServiceUuids"))
+    if uuids is not None:
+        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)):
+            continue
+        if isinstance(value, float) and not math.isfinite(value):
+            continue
+        result[key] = min(max(int(value), low), high)
+    return result
+
 
 def _device_id() -> str:
     machine_id_path = Path("/etc/machine-id")
@@ -147,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):
@@ -173,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:
@@ -188,6 +251,7 @@ class GatewayAuth:
         self._device_token = dt
         self._refresh_token = rt
         self._expires_at_ms = int(time.time() * 1000) + exp * 1000
+        self._apply_server_config(data)
         self._persist_tokens()
         logger.info("Token refreshed", expires_in_s=exp)
         return True
@@ -197,14 +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] = {}
@@ -213,24 +285,33 @@ 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: dict[str, Any]) -> None:
-        config = data.get("config") or {}
-        for key in ("uploadIntervalMs", "uploadBatchSize", "scanIntervalMs", "featureFlags"):
-            if key in config:
-                self.server_config[key] = config[key]
+    def _apply_server_config(self, data: Any) -> None:
+        # The server sends the full effective config each time, so replace
+        # rather than merge: a removed override must not stick. A response
+        # without a "config" key says nothing and keeps the current config.
+        if not isinstance(data, dict) or "config" not in data:
+            return
+        self.server_config = sanitize_server_config(data["config"])
 
     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:
@@ -242,7 +323,7 @@ class GatewayAuth:
             self._device_token = data.get("deviceToken")
             self._refresh_token = data.get("refreshToken")
             self._expires_at_ms = data.get("expiresAtMs", 0)
-            self.server_config = data.get("serverConfig", {})
+            self.server_config = sanitize_server_config(data.get("serverConfig"))
             logger.info("Loaded persisted auth", gateway_id=self._gateway_id)
         except (json.JSONDecodeError, OSError) as exc:
             logger.warning("Failed to load persisted auth", error=str(exc))

{hubble_gateway_sdk_python-0.1.0 → 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,
@@ -53,15 +58,15 @@ class Settings(BaseSettings):
     # Batching and deduplication
     batch_size: int = Field(
         default=500,
-        description="Max packets per upload batch",
+        description="Max packets per upload batch (server uploadBatchSize overrides)",
     )
     upload_interval_seconds: float = Field(
-        default=5.0,
-        description="Seconds between upload flushes",
+        default=60.0,
+        description="Seconds between upload flushes (server uploadIntervalMs overrides)",
     )
     dedup_window_seconds: float = Field(
         default=300.0,
-        description="Deduplication window in seconds",
+        description="Deduplication window in seconds (server dedupWindowMs overrides)",
     )
 
     # Location

{hubble_gateway_sdk_python-0.1.0 → 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.0 → hubble_gateway_sdk_python-0.2.0}/src/hubble_gateway/models.py

@@ -1,18 +1,47 @@
 """Data models for BLE packets and locations."""
 
 import base64
+import re
 from datetime import datetime, timezone
 from typing import Any
 
 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}$")
+
+
+def normalize_service_uuid(value: str) -> str | None:
+    """Return the uppercase 128-bit form of a BLE service UUID, or None if invalid.
+
+    ``FCA6`` -> ``0000FCA6-0000-1000-8000-00805F9B34FB``. This is the form
+    bleak reports and filters on.
+    """
+    u = value.strip().upper()
+    if _UUID16_PATTERN.match(u):
+        return f"0000{u}{BLUETOOTH_BASE_UUID_SUFFIX}"
+    if _UUID128_PATTERN.match(u):
+        return u
+    return None
+
+
+def is_bluetooth_base_uuid(full_uuid: str) -> bool:
+    u = full_uuid.upper()
+    return len(u) == 36 and u.startswith("0000") and u.endswith(BLUETOOTH_BASE_UUID_SUFFIX)
+
 
 def uuid_to_16bit(full_uuid: str) -> str:
-    """Extract 16-bit short form from a full 128-bit BLE UUID.
+    """Short form of a BLE UUID, as the gateway-api packet schema expects.
 
-    ``0000FCA6-0000-1000-8000-00805F9B34FB`` -> ``FCA6``
+    ``0000FCA6-0000-1000-8000-00805F9B34FB`` -> ``FCA6``. A UUID that is not
+    on the Bluetooth Base UUID has no 16-bit form, so it is returned whole
+    (uppercase) rather than as a misleading slice.
     """
-    return full_uuid[4:8].upper()
+    if is_bluetooth_base_uuid(full_uuid):
+        return full_uuid[4:8].upper()
+    return full_uuid.upper()
 
 
 class Location(BaseModel):
@@ -89,7 +118,7 @@ class BLEPacket(BaseModel):
 
     @property
     def service_uuid_16bit(self) -> str | None:
-        """16-bit short form of matched UUID (e.g. 'FCA6')."""
+        """Short form of matched UUID (e.g. 'FCA6'); full form if not a Base UUID."""
         if self.service_uuid:
             return uuid_to_16bit(self.service_uuid)
         return None
@@ -99,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] = {