hubble-gateway-sdk-python 0.1.0__py3-none-any.whl

hubble_gateway/sender.py

@@ -0,0 +1,202 @@
+"""Packet sender: batches, deduplicates, and uploads BLE sightings."""
+
+import asyncio
+import time
+import uuid as uuid_mod
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import structlog
+
+from hubble_gateway.auth import GatewayAuth
+from hubble_gateway.models import BLEPacket, Location
+
+logger = structlog.get_logger(__name__)
+
+
+class _DedupEntry:
+    __slots__ = ("packet", "strongest_rssi", "sighting_count", "first_seen_ms")
+
+    def __init__(self, packet: BLEPacket) -> None:
+        self.packet = packet
+        self.strongest_rssi = packet.rssi
+        self.sighting_count = 1
+        self.first_seen_ms = int(packet.timestamp.timestamp() * 1000)
+
+    def merge(self, packet: BLEPacket) -> None:
+        self.sighting_count += 1
+        if packet.rssi > self.strongest_rssi:
+            self.strongest_rssi = packet.rssi
+            self.packet = packet
+
+
+class GatewaySender:
+    """Batches and uploads BLE sightings to the gateway API."""
+
+    def __init__(
+        self,
+        auth: GatewayAuth,
+        get_location: Callable[[], Awaitable[Location]] | None = None,
+        batch_size: int = 500,
+        upload_interval_s: float = 5.0,
+        dedup_window_s: float = 300.0,
+    ) -> None:
+        self._auth = auth
+        self._get_location = get_location
+        self._batch_size = batch_size
+        self._upload_interval = upload_interval_s
+        self._dedup_window = dedup_window_s
+        self._dedup_map: dict[tuple[str, str | None, str], _DedupEntry] = {}
+        self._dedup_lock = asyncio.Lock()
+        self._running = False
+        self._stats_sends = 0
+        self._stats_total = 0
+        self._stats_uploaded = 0
+        self._stats_devices: set[str] = set()
+
+    async def start(self) -> None:
+        self._running = True
+        self._apply_server_config()
+        asyncio.create_task(self._upload_loop())
+        if self._get_location:
+            asyncio.create_task(self._location_loop())
+        logger.info(
+            "Sender started",
+            gateway_id=self._auth.gateway_id,
+            upload_interval=self._upload_interval,
+            dedup_window=self._dedup_window,
+            batch_size=self._batch_size,
+        )
+
+    async def stop(self) -> None:
+        self._running = False
+        await self._flush()
+        logger.info(
+            "Sender stopped",
+            total_packets=self._stats_total,
+            uploaded=self._stats_uploaded,
+            sends=self._stats_sends,
+            unique_devices=len(self._stats_devices),
+        )
+
+    def add_packet(self, packet: BLEPacket) -> None:
+        self._stats_total += 1
+        self._stats_devices.add(packet.device_address)
+        key = (packet.device_address, packet.service_uuid_16bit, packet.service_data_hex)
+        existing = self._dedup_map.get(key)
+        if existing is not None:
+            age_ms = int(packet.timestamp.timestamp() * 1000) - existing.first_seen_ms
+            if age_ms < self._dedup_window * 1000:
+                existing.merge(packet)
+                return
+        self._dedup_map[key] = _DedupEntry(packet)
+
+    @property
+    def stats(self) -> dict[str, int]:
+        return {
+            "total_packets": self._stats_total,
+            "uploaded_packets": self._stats_uploaded,
+            "sends": self._stats_sends,
+            "unique_devices": len(self._stats_devices),
+            "buffer_size": len(self._dedup_map),
+        }
+
+    async def _upload_loop(self) -> None:
+        while self._running:
+            await asyncio.sleep(self._upload_interval)
+            if not self._dedup_map:
+                continue
+            await self._flush()
+
+    async def _location_loop(self) -> None:
+        _INTERVAL = 60.0
+        while self._running:
+            await asyncio.sleep(_INTERVAL)
+            if not self._get_location:
+                continue
+            try:
+                location = await self._get_location()
+                if location.latitude is not None and location.longitude is not None:
+                    await self._upload_location(location)
+            except Exception as e:
+                logger.warning("Location upload error", error=str(e))
+
+    async def _flush(self) -> None:
+        async with self._dedup_lock:
+            if not self._dedup_map:
+                return
+            entries = list(self._dedup_map.values())
+            self._dedup_map.clear()
+
+        location = Location()
+        if self._get_location:
+            try:
+                location = await self._get_location()
+            except Exception as e:
+                logger.warning("Failed to get location", error=str(e))
+
+        for i in range(0, len(entries), self._batch_size):
+            batch = entries[i : i + self._batch_size]
+            await self._upload_batch(batch, location)
+
+    async def _upload_batch(self, entries: list[_DedupEntry], location: Location) -> None:
+        gateway_id = self._auth.gateway_id
+        if not gateway_id:
+            return
+
+        batch_id = str(uuid_mod.uuid4())
+        packets_json = []
+        for entry in entries:
+            pkt = entry.packet.to_gateway_packet(
+                location=location, sighting_count=entry.sighting_count,
+            )
+            pkt["rssi"] = entry.strongest_rssi
+            packets_json.append(pkt)
+
+        body: dict[str, Any] = {
+            "batchId": batch_id,
+            "sentAtMillis": int(time.time() * 1000),
+            "packets": packets_json,
+        }
+
+        try:
+            resp = await self._auth.authenticated_request(
+                "POST", f"/api/v1/gateways/{gateway_id}/packets", json_body=body,
+            )
+            if resp.status_code in (200, 201, 202):
+                self._stats_sends += 1
+                self._stats_uploaded += len(entries)
+                sightings = sum(e.sighting_count for e in entries)
+                logger.info(
+                    "Batch uploaded",
+                    batch_id=batch_id[:8],
+                    packets=len(entries),
+                    sightings=sightings,
+                )
+            else:
+                logger.warning("Upload failed", status=resp.status_code, body=resp.text[:200])
+        except Exception as e:
+            logger.error("Upload error", error=str(e))
+
+    async def _upload_location(self, location: Location) -> None:
+        gateway_id = self._auth.gateway_id
+        if not gateway_id:
+            return
+        body: dict[str, Any] = {
+            "batchId": str(uuid_mod.uuid4()),
+            "sentAtMillis": int(time.time() * 1000),
+            "locations": [location.to_gateway_dict()],
+        }
+        try:
+            await self._auth.authenticated_request(
+                "POST", f"/api/v1/gateways/{gateway_id}/locations", json_body=body,
+            )
+        except Exception as e:
+            logger.warning("Location upload failed", error=str(e))
+
+    def _apply_server_config(self) -> None:
+        cfg = self._auth.server_config
+        if "uploadBatchSize" in cfg:
+            self._batch_size = min(int(cfg["uploadBatchSize"]), 500)
+        if "uploadIntervalMs" in cfg:
+            self._upload_interval = max(int(cfg["uploadIntervalMs"]) / 1000, 1)

hubble_gateway/ubx.py

@@ -0,0 +1,230 @@
+"""Async UBX NAV-PVT reader for u-blox receivers (ZED-F9P, NEO-M9N, etc.)."""
+
+from __future__ import annotations
+
+import asyncio
+import struct
+from dataclasses import dataclass
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+UBX_SYNC_1 = 0xB5
+UBX_SYNC_2 = 0x62
+NAV_CLASS = 0x01
+NAV_PVT_ID = 0x07
+NAV_PVT_PAYLOAD_LEN = 92
+READ_PVT_TIMEOUT_S = 10.0
+
+
+def _ubx_checksum(data: bytes) -> tuple[int, int]:
+    ck_a = 0
+    ck_b = 0
+    for byte in data:
+        ck_a = (ck_a + byte) & 0xFF
+        ck_b = (ck_b + ck_a) & 0xFF
+    return ck_a, ck_b
+
+
+def _ubx_frame(msg_class: int, msg_id: int, payload: bytes) -> bytes:
+    header = struct.pack("<BBH", msg_class, msg_id, len(payload))
+    body = header + payload
+    ck_a, ck_b = _ubx_checksum(body)
+    return b"\xb5\x62" + body + bytes([ck_a, ck_b])
+
+
+NAV_PVT_POLL = _ubx_frame(NAV_CLASS, NAV_PVT_ID, b"")
+
+
+@dataclass(slots=True)
+class UBXNavPVT:
+    itow_ms: int
+    year: int
+    month: int
+    day: int
+    hour: int
+    minute: int
+    second: int
+    valid: int
+    valid_date: bool
+    valid_time: bool
+    fix_type: int
+    flags: int
+    gnss_fix_ok: bool
+    num_sv: int
+    lat: float
+    lon: float
+    height_ellipsoid_m: float
+    alt_msl_m: float
+    hacc_m: float
+    vacc_m: float
+    ground_speed_ms: float
+    heading_deg: float
+    pdop: float
+
+
+def _parse_nav_pvt_payload(payload: bytes) -> UBXNavPVT:
+    if len(payload) != NAV_PVT_PAYLOAD_LEN:
+        raise ValueError(f"NAV-PVT payload length {len(payload)}, expected {NAV_PVT_PAYLOAD_LEN}")
+
+    itow_ms = struct.unpack_from("<I", payload, 0)[0]
+    year = struct.unpack_from("<H", payload, 4)[0]
+    month, day, hour, minute, second, valid = struct.unpack_from("<BBBBBB", payload, 6)
+    fix_type = payload[20]
+    flags = payload[21]
+    num_sv = payload[23]
+    lon_i, lat_i, height_mm, hmsl_mm = struct.unpack_from("<iiii", payload, 24)
+    hacc_mm, vacc_mm = struct.unpack_from("<II", payload, 40)
+    g_speed_mm_s, head_mot = struct.unpack_from("<ii", payload, 60)
+    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),
+        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,
+        pdop=pdop_raw / 100.0,
+    )
+
+
+class UBXReader:
+    """Async UBX reader that polls NAV-PVT from a serial port."""
+
+    def __init__(self, port: str, baud_rate: int = 38400) -> None:
+        self._port = port
+        self._baud_rate = baud_rate
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._buf = bytearray()
+
+    async def start(self) -> None:
+        import serial_asyncio
+
+        self._reader, self._writer = await serial_asyncio.open_serial_connection(
+            url=self._port, baudrate=self._baud_rate,
+        )
+        self._buf.clear()
+        logger.info("UBX reader connected", port=self._port, baud_rate=self._baud_rate)
+        await self._configure_uart()
+
+    async def _configure_uart(self) -> None:
+        """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", 0x20910008, 1)  # CFG-MSGOUT-UBX_NAV_PVT_UART2 = 1
+        payload = struct.pack("<BBH", 0x00, 0x07, 0x0000) + kv
+        frame = _ubx_frame(0x06, 0x8A, payload)
+        self._writer.write(frame)
+        await self._writer.drain()
+        await asyncio.sleep(0.2)
+        logger.info("UBX UART configured")
+
+    def _poll_pvt(self) -> None:
+        if self._writer is not None:
+            self._writer.write(NAV_PVT_POLL)
+
+    async def read_pvt(self) -> UBXNavPVT | None:
+        if self._reader is None:
+            raise RuntimeError("call start() first")
+
+        self._poll_pvt()
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + READ_PVT_TIMEOUT_S
+
+        while True:
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                return None
+
+            while len(self._buf) < 2:
+                chunk = await self._read_chunk(4096, remaining)
+                if not chunk:
+                    return None
+                self._buf.extend(chunk)
+                remaining = deadline - loop.time()
+                if remaining <= 0:
+                    return None
+
+            sync_at = self._buf.find(bytes([UBX_SYNC_1, UBX_SYNC_2]))
+            if sync_at < 0:
+                if len(self._buf) > 1:
+                    del self._buf[:-1]
+                elif len(self._buf) == 1 and self._buf[0] != UBX_SYNC_1:
+                    self._buf.clear()
+                continue
+
+            if sync_at > 0:
+                del self._buf[:sync_at]
+
+            need = 6
+            while len(self._buf) < need:
+                chunk = await self._read_chunk(need - len(self._buf), remaining)
+                if not chunk:
+                    return None
+                self._buf.extend(chunk)
+                remaining = deadline - loop.time()
+                if remaining <= 0:
+                    return None
+
+            payload_len = struct.unpack_from("<H", self._buf, 4)[0]
+            frame_len = 6 + payload_len + 2
+
+            while len(self._buf) < frame_len:
+                chunk = await self._read_chunk(frame_len - len(self._buf), remaining)
+                if not chunk:
+                    return None
+                self._buf.extend(chunk)
+                remaining = deadline - loop.time()
+                if remaining <= 0:
+                    return None
+
+            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)
+
+            if ck_a != exp_a or ck_b != exp_b:
+                del self._buf[0]
+                continue
+
+            del self._buf[:frame_len]
+
+            msg_class = body[0]
+            msg_id = body[1]
+            if (
+                msg_class == NAV_CLASS
+                and msg_id == NAV_PVT_ID
+                and payload_len == NAV_PVT_PAYLOAD_LEN
+            ):
+                try:
+                    return _parse_nav_pvt_payload(body[4:])
+                except ValueError:
+                    return None
+
+    async def _read_chunk(self, max_bytes: int, timeout_s: float) -> bytes | None:
+        if self._reader is None:
+            return None
+        try:
+            return await asyncio.wait_for(
+                self._reader.read(max(max_bytes, 1)), timeout=timeout_s
+            )
+        except asyncio.TimeoutError:
+            return None
+
+    async def stop(self) -> None:
+        if self._writer is not None:
+            self._writer.close()
+            try:
+                await self._writer.wait_closed()
+            except Exception:
+                pass
+            self._writer = None
+        self._reader = None
+        self._buf.clear()
+        logger.info("UBX reader stopped", port=self._port)

hubble_gateway_sdk_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: hubble-gateway-sdk-python
+Version: 0.1.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: 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).

hubble_gateway_sdk_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+hubble_gateway/__init__.py,sha256=yEpF8M0DMCqWkeRKYEzb4HRCj7qTdoXxjS2c4cnMkZ0,1148
+hubble_gateway/auth.py,sha256=WVlSeuVYpkGK0I_DGRfxxx1U0HKOG47zMnwaRkefLIE,9137
+hubble_gateway/config.py,sha256=OdEFHISltqQpYSJLIQa2k_jdG57s_aJaPTxMqfPS2v4,3135
+hubble_gateway/location.py,sha256=RQbQWfyBv7UPCenCqR6F_vIIvFof-4AdvPfaa0ws8t8,14862
+hubble_gateway/models.py,sha256=vQHGuC2RD5ph5d-Pj9G6kPurl89PKCoh_PBRDBZEXJs,4212
+hubble_gateway/scanner.py,sha256=W5NXt_pHBawO0yREwtnOP4LkVO6pxkl6Z-UQm3hopko,5269
+hubble_gateway/sender.py,sha256=61QlSMmATZKAJns3_0WkNOm7Tqlz3II5eGQnbBrvjfQ,7166
+hubble_gateway/ubx.py,sha256=_PCfqAbkVsB-fKjR9kMTSHpYZXX9sf-PufDICBC5JUI,7424
+hubble_gateway_sdk_python-0.1.0.dist-info/METADATA,sha256=iewTW8xgLOIdMqLAr-YIgqe5nTXjyS7Cq1KrwzPe7Tg,1915
+hubble_gateway_sdk_python-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+hubble_gateway_sdk_python-0.1.0.dist-info/licenses/LICENSE,sha256=L6iQZR753mEQy5DSX2zByjAG1GlwCKrZDk5lifagvDI,11397
+hubble_gateway_sdk_python-0.1.0.dist-info/RECORD,,

hubble_gateway_sdk_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any