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

hubble_gateway/location.py

@@ -0,0 +1,423 @@
+"""Location providers: fixed, serial NMEA GPS, UBX (ZED-F9P), gpsd."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import platform
+from abc import ABC, abstractmethod
+
+import structlog
+
+from hubble_gateway.models import Location
+
+logger = structlog.get_logger(__name__)
+
+
+def parse_nmea_coordinate(value: str, direction: str) -> float | None:
+    """Parse NMEA coordinate (DDMM.MMMMM or DDDMM.MMMMM) to decimal degrees."""
+    if not value or not direction:
+        return None
+    try:
+        dot_pos = value.find(".")
+        if dot_pos < 2:
+            return None
+        deg_digits = 3 if len(value.split(".")[0]) > 4 else 2
+        degrees = float(value[:deg_digits])
+        minutes = float(value[deg_digits:])
+        decimal = degrees + (minutes / 60.0)
+        if direction in ("S", "W"):
+            decimal = -decimal
+        return decimal
+    except (ValueError, IndexError):
+        return None
+
+
+class LocationProvider(ABC):
+    """Abstract base class for location providers."""
+
+    @abstractmethod
+    async def get_location(self) -> Location: ...
+
+    @abstractmethod
+    async def start(self) -> None: ...
+
+    @abstractmethod
+    async def stop(self) -> None: ...
+
+
+class FixedLocationProvider(LocationProvider):
+    """Returns a static configured location."""
+
+    def __init__(self, latitude: float | None, longitude: float | None) -> None:
+        self._location = Location(
+            latitude=latitude,
+            longitude=longitude,
+            source="fixed" if latitude and longitude else "unknown",
+        )
+
+    async def get_location(self) -> Location:
+        return self._location
+
+    async def start(self) -> None:
+        logger.info(
+            "Fixed location provider",
+            lat=self._location.latitude,
+            lon=self._location.longitude,
+        )
+
+    async def stop(self) -> None:
+        pass
+
+
+class GPSKalmanFilter:
+    """Simple 2D Kalman filter for GPS position smoothing."""
+
+    def __init__(
+        self,
+        process_noise: float = 1e-10,
+        measurement_noise: float = 2e-8,
+    ) -> None:
+        self._process_noise = process_noise
+        self._measurement_noise = measurement_noise
+        self._state_lat: float | None = None
+        self._state_lon: float | None = None
+        self._p_lat: float = 1.0
+        self._p_lon: float = 1.0
+
+    def update(self, lat: float, lon: float) -> tuple[float, float]:
+        if self._state_lat is None or self._state_lon is None:
+            self._state_lat = lat
+            self._state_lon = lon
+            return lat, lon
+
+        self._p_lat += self._process_noise
+        self._p_lon += self._process_noise
+
+        k_lat = self._p_lat / (self._p_lat + self._measurement_noise)
+        k_lon = self._p_lon / (self._p_lon + self._measurement_noise)
+
+        self._state_lat = self._state_lat + k_lat * (lat - self._state_lat)
+        self._state_lon = self._state_lon + k_lon * (lon - self._state_lon)
+
+        self._p_lat = (1 - k_lat) * self._p_lat
+        self._p_lon = (1 - k_lon) * self._p_lon
+
+        return self._state_lat, self._state_lon
+
+
+class SerialGPSLocationProvider(LocationProvider):
+    """Reads NMEA sentences from a serial GPS with Kalman filtering.
+
+    Supports common Pi GPS hats that output GPRMC/GPGGA over a UART serial port.
+    """
+
+    def __init__(
+        self,
+        port: str = "/dev/ttyAMA0",
+        baud_rate: int = 9600,
+        fallback_lat: float | None = None,
+        fallback_lon: float | None = None,
+    ) -> None:
+        self._port = port
+        self._baud_rate = baud_rate
+        self._fallback_lat = fallback_lat
+        self._fallback_lon = fallback_lon
+        self._location = Location(
+            latitude=fallback_lat,
+            longitude=fallback_lon,
+            source="gps-fallback" if fallback_lat else "unknown",
+            gps_state="off",
+        )
+        self._running = False
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._fix_count = 0
+        self._kalman = GPSKalmanFilter()
+        self._hdop: float | None = None
+        self._altitude: float | None = None
+        self._sat_count: int | None = None
+        self._speed_ms: float | None = None
+        self._course_deg: float | None = None
+
+        if fallback_lat is not None and fallback_lon is not None:
+            self._kalman.update(fallback_lat, fallback_lon)
+
+    async def get_location(self) -> Location:
+        return self._location
+
+    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._running = True
+        self._location.gps_state = "searching"
+        logger.info("Serial GPS started", port=self._port, baud=self._baud_rate)
+        asyncio.create_task(self._read_loop())
+
+    async def _read_loop(self) -> None:
+        while self._running and self._reader:
+            try:
+                line = await asyncio.wait_for(self._reader.readline(), timeout=5.0)
+                sentence = line.decode("ascii", errors="ignore").strip()
+                if sentence.startswith(("$GPGGA", "$GNGGA")):
+                    self._parse_gga(sentence)
+                elif sentence.startswith(("$GPRMC", "$GNRMC")):
+                    self._parse_rmc(sentence)
+            except asyncio.TimeoutError:
+                logger.debug("GPS read timeout")
+            except Exception as e:
+                logger.warning("GPS read error", error=str(e))
+                await asyncio.sleep(0.1)
+
+    def _parse_gga(self, sentence: str) -> None:
+        try:
+            if "*" in sentence:
+                sentence = sentence.split("*")[0]
+            parts = sentence.split(",")
+            if len(parts) < 10:
+                return
+            quality = int(parts[6]) if parts[6] else 0
+            if quality == 0:
+                return
+            self._sat_count = int(parts[7]) if parts[7] else None
+            self._hdop = float(parts[8]) if parts[8] else None
+            self._altitude = float(parts[9]) if parts[9] else None
+        except (ValueError, IndexError):
+            pass
+
+    def _parse_rmc(self, sentence: str) -> None:
+        try:
+            if "*" in sentence:
+                sentence = sentence.split("*")[0]
+            parts = sentence.split(",")
+            if len(parts) < 7 or parts[2] != "A":
+                return
+            lat = parse_nmea_coordinate(parts[3], parts[4])
+            lon = parse_nmea_coordinate(parts[5], parts[6])
+            if len(parts) > 7 and parts[7]:
+                self._speed_ms = float(parts[7]) * 0.514444
+            if len(parts) > 8 and parts[8]:
+                self._course_deg = float(parts[8])
+            if lat is not None and lon is not None:
+                filtered_lat, filtered_lon = self._kalman.update(lat, lon)
+                self._fix_count += 1
+                self._location = Location(
+                    latitude=filtered_lat,
+                    longitude=filtered_lon,
+                    altitude=self._altitude,
+                    source="gps",
+                    gps_state="fix",
+                    fix_count=self._fix_count,
+                    hdop=self._hdop,
+                    sat_count=self._sat_count,
+                    speed_ms=self._speed_ms,
+                    course_deg=self._course_deg,
+                )
+                if self._fix_count <= 5 or self._fix_count % 60 == 0:
+                    logger.info(
+                        "GPS fix",
+                        fix=self._fix_count,
+                        lat=round(filtered_lat, 6),
+                        lon=round(filtered_lon, 6),
+                        sats=self._sat_count,
+                        hdop=self._hdop,
+                    )
+        except Exception as e:
+            logger.warning("Failed to parse RMC", error=str(e))
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._writer:
+            self._writer.close()
+        logger.info("Serial GPS stopped", fixes=self._fix_count)
+
+
+class UBXLocationProvider(LocationProvider):
+    """Reads UBX NAV-PVT from a u-blox receiver (ZED-F9P, NEO-M9N)."""
+
+    def __init__(
+        self,
+        port: str,
+        baud_rate: int = 38400,
+        fallback_lat: float | None = None,
+        fallback_lon: float | None = None,
+        poll_interval_s: float = 1.0,
+    ) -> None:
+        self._port = port
+        self._baud_rate = baud_rate
+        self._fallback_lat = fallback_lat
+        self._fallback_lon = fallback_lon
+        self._poll_interval = poll_interval_s
+        self._reader = None
+        self._running = False
+        self._fix_count = 0
+        self._location = Location(
+            latitude=fallback_lat,
+            longitude=fallback_lon,
+            source="gps-fallback" if fallback_lat else "unknown",
+            gps_state="off",
+        )
+
+    async def start(self) -> None:
+        from hubble_gateway.ubx import UBXReader
+
+        self._reader = UBXReader(port=self._port, baud_rate=self._baud_rate)
+        await self._reader.start()
+        self._running = True
+        self._location.gps_state = "searching"
+        asyncio.create_task(self._read_loop())
+        logger.info("UBX location provider started", port=self._port)
+
+    async def get_location(self) -> Location:
+        return self._location
+
+    async def _read_loop(self) -> None:
+        while self._running and self._reader:
+            try:
+                pvt = await self._reader.read_pvt()
+                if pvt and pvt.gnss_fix_ok and pvt.fix_type >= 2:
+                    self._fix_count += 1
+                    self._location = Location(
+                        latitude=pvt.lat,
+                        longitude=pvt.lon,
+                        altitude=pvt.alt_msl_m,
+                        horizontal_accuracy=pvt.hacc_m,
+                        vertical_accuracy=pvt.vacc_m,
+                        source="gps",
+                        gps_state="fix",
+                        fix_count=self._fix_count,
+                        hdop=pvt.pdop,
+                        sat_count=pvt.num_sv,
+                        speed_ms=pvt.ground_speed_ms,
+                        course_deg=pvt.heading_deg,
+                    )
+                    if self._fix_count <= 5 or self._fix_count % 60 == 0:
+                        logger.info(
+                            "UBX fix",
+                            fix=self._fix_count,
+                            lat=round(pvt.lat, 7),
+                            lon=round(pvt.lon, 7),
+                            sats=pvt.num_sv,
+                            hacc=round(pvt.hacc_m, 2),
+                        )
+                elif pvt:
+                    self._location.gps_state = "searching"
+                    self._location.sat_count = pvt.num_sv
+            except Exception as e:
+                logger.warning("UBX read error", error=str(e))
+            await asyncio.sleep(self._poll_interval)
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._reader:
+            await self._reader.stop()
+            self._reader = None
+        logger.info("UBX location provider stopped", fixes=self._fix_count)
+
+
+class GPSDLocationProvider(LocationProvider):
+    """Location from the gpsd daemon (requires gpsd-py3)."""
+
+    def __init__(self) -> None:
+        self._location = Location(source="gpsd", gps_state="off")
+        self._running = False
+
+    async def get_location(self) -> Location:
+        return self._location
+
+    async def start(self) -> None:
+        try:
+            import gpsd
+            gpsd.connect()
+            self._running = True
+            logger.info("GPSD location provider started")
+            asyncio.create_task(self._update_loop())
+        except ImportError:
+            logger.warning("gpsd-py3 not installed; pip install gpsd-py3")
+            raise
+        except Exception as e:
+            logger.error("Failed to connect to gpsd", error=str(e))
+            raise
+
+    async def _update_loop(self) -> None:
+        import gpsd
+
+        while self._running:
+            try:
+                packet = gpsd.get_current()
+                if packet.mode >= 2:
+                    self._location = Location(
+                        latitude=packet.lat,
+                        longitude=packet.lon,
+                        altitude=packet.alt if packet.mode >= 3 else None,
+                        horizontal_accuracy=packet.error.get("x"),
+                        source="gpsd",
+                        gps_state="fix",
+                    )
+                else:
+                    self._location.gps_state = "searching"
+            except Exception as e:
+                logger.warning("GPSD error", error=str(e))
+            await asyncio.sleep(1.0)
+
+    async def stop(self) -> None:
+        self._running = False
+        logger.info("GPSD stopped")
+
+
+async def create_location_provider(
+    gps_enabled: bool = False,
+    fixed_lat: float | None = None,
+    fixed_lon: float | None = None,
+    gps_port: str | None = None,
+    gps_baud_rate: int = 9600,
+    gps_module: str = "nmea",
+) -> LocationProvider:
+    """Create the appropriate location provider.
+
+    Priority when gps_enabled:
+    1. UBX (gps_module="zed_f9p" and serial port exists)
+    2. Serial NMEA (gps_module="nmea" and serial port exists)
+    3. gpsd
+    4. Fixed fallback
+    """
+    if gps_enabled and platform.system() == "Linux":
+        if gps_module == "zed_f9p" and gps_port and os.path.exists(gps_port):
+            try:
+                provider = UBXLocationProvider(
+                    port=gps_port,
+                    baud_rate=gps_baud_rate,
+                    fallback_lat=fixed_lat,
+                    fallback_lon=fixed_lon,
+                )
+                await provider.start()
+                return provider
+            except Exception as e:
+                logger.warning("UBX GPS unavailable, trying NMEA", error=str(e))
+
+        if gps_port and os.path.exists(gps_port):
+            try:
+                provider = SerialGPSLocationProvider(
+                    port=gps_port,
+                    baud_rate=gps_baud_rate,
+                    fallback_lat=fixed_lat,
+                    fallback_lon=fixed_lon,
+                )
+                await provider.start()
+                return provider
+            except Exception as e:
+                logger.warning("Serial GPS unavailable, trying gpsd", error=str(e))
+
+        try:
+            provider = GPSDLocationProvider()
+            await provider.start()
+            return provider
+        except Exception:
+            logger.warning("gpsd unavailable, using fixed location")
+
+    provider = FixedLocationProvider(fixed_lat, fixed_lon)
+    await provider.start()
+    return provider

hubble_gateway/models.py

@@ -0,0 +1,118 @@
+"""Data models for BLE packets and locations."""
+
+import base64
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+def uuid_to_16bit(full_uuid: str) -> str:
+    """Extract 16-bit short form from a full 128-bit BLE UUID.
+
+    ``0000FCA6-0000-1000-8000-00805F9B34FB`` -> ``FCA6``
+    """
+    return full_uuid[4:8].upper()
+
+
+class Location(BaseModel):
+    """Geographic location."""
+
+    latitude: float | None = None
+    longitude: float | None = None
+    altitude: float | None = None
+    horizontal_accuracy: float | None = None
+    vertical_accuracy: float | None = None
+    source: str = "unknown"
+    gps_state: str = "off"
+    fix_count: int = 0
+    hdop: float | None = None
+    sat_count: int | None = None
+    speed_ms: float | None = None
+    course_deg: float | None = None
+
+    def to_gateway_dict(self, timestamp_ms: int | None = None) -> dict[str, Any]:
+        """Convert to gateway-api location format."""
+        result: dict[str, Any] = {
+            "latitude": self.latitude if self.latitude is not None else 0.0,
+            "longitude": self.longitude if self.longitude is not None else 0.0,
+            "horizontalAccuracyMeters": (
+                self.horizontal_accuracy if self.horizontal_accuracy is not None else 10.0
+            ),
+            "timestampMillis": timestamp_ms or int(datetime.now(timezone.utc).timestamp() * 1000),
+        }
+        if self.altitude is not None:
+            result["altitude"] = self.altitude
+        if self.vertical_accuracy is not None:
+            result["verticalAccuracyMeters"] = self.vertical_accuracy
+        return result
+
+
+class BLEPacket(BaseModel):
+    """A single BLE advertisement packet."""
+
+    device_address: str = Field(description="BLE device MAC address")
+    device_name: str | None = Field(default=None)
+    rssi: int = Field(description="RSSI in dBm")
+    service_uuids: list[str] = Field(default_factory=list)
+    manufacturer_data: dict[int, bytes] = Field(default_factory=dict)
+    service_data: dict[str, bytes] = Field(default_factory=dict)
+    tx_power: int | None = Field(default=None)
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    service_uuid: str | None = Field(
+        default=None,
+        description="Matched service UUID (set by scanner)",
+    )
+
+    class Config:
+        json_encoders = {
+            bytes: lambda v: v.hex(),
+            datetime: lambda v: v.isoformat(),
+        }
+
+    def get_matched_service_data(self) -> bytes | None:
+        """Get service data for the matched service UUID."""
+        if self.service_uuid:
+            target = self.service_uuid.lower()
+            for uid, data in self.service_data.items():
+                if uid.lower() == target:
+                    return data
+        for uid, data in self.service_data.items():
+            return data
+        return None
+
+    @property
+    def service_data_hex(self) -> str:
+        """Hex of matched service data (dedup key component)."""
+        data = self.get_matched_service_data()
+        return data.hex() if data else ""
+
+    @property
+    def service_uuid_16bit(self) -> str | None:
+        """16-bit short form of matched UUID (e.g. 'FCA6')."""
+        if self.service_uuid:
+            return uuid_to_16bit(self.service_uuid)
+        return None
+
+    def to_gateway_packet(
+        self, location: Location | None = None, sighting_count: int = 1
+    ) -> 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
+        )
+        ts_ms = int(self.timestamp.timestamp() * 1000)
+
+        packet: dict[str, Any] = {
+            "deviceAddress": self.device_address,
+            "rssi": self.rssi,
+            "timestampMillis": ts_ms,
+            "serviceUuid": self.service_uuid_16bit,
+            "sightingCount": sighting_count,
+        }
+        if service_data_b64:
+            packet["serviceData"] = service_data_b64
+        if location:
+            packet["location"] = location.to_gateway_dict(timestamp_ms=ts_ms)
+        return packet

hubble_gateway/scanner.py

@@ -0,0 +1,154 @@
+"""BLE scanner using bleak with multi-UUID filtering."""
+
+import asyncio
+from collections.abc import Callable
+from datetime import datetime, timezone
+
+import structlog
+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, uuid_to_16bit
+
+logger = structlog.get_logger(__name__)
+
+
+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.
+    """
+
+    def __init__(
+        self,
+        service_uuids: list[str] | None = None,
+        scan_duration: float = 5.0,
+        on_packet: Callable[[BLEPacket], None] | None = None,
+        adapter: str | None = None,
+    ) -> None:
+        self._service_uuids = [u.lower() for u in (service_uuids or DEFAULT_SERVICE_UUIDS)]
+        self._scan_duration = scan_duration
+        self._on_packet = on_packet
+        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._uuid_variants: dict[str, str] = {}
+        for full_uuid in self._service_uuids:
+            short = full_uuid[4:8]
+            canonical = f"0000{short}-0000-1000-8000-00805f9b34fb"
+            self._uuid_variants[full_uuid] = full_uuid
+            self._uuid_variants[short] = full_uuid
+            self._uuid_variants[canonical] = full_uuid
+
+    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:
+        adv_uuids = [str(u).lower() for u in advertisement_data.service_uuids or []]
+        matched_uuid = self._match_service_uuid(adv_uuids)
+        if matched_uuid is None:
+            return
+
+        addr = device.address
+        if addr not in self._seen_devices:
+            self._seen_devices.add(addr)
+        self._devices_this_scan.add(addr)
+        self._total_packets += 1
+
+        packet = BLEPacket(
+            device_address=addr,
+            device_name=device.name or advertisement_data.local_name,
+            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()},
+            tx_power=advertisement_data.tx_power,
+            timestamp=datetime.now(timezone.utc),
+            service_uuid=matched_uuid,
+        )
+
+        short = uuid_to_16bit(matched_uuid)
+        logger.debug(
+            "BLE packet",
+            uuid=short,
+            addr=addr[-8:],
+            rssi=packet.rssi,
+            name=packet.device_name,
+        )
+
+        if self._on_packet:
+            self._on_packet(packet)
+
+    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,
+            scan_duration=self._scan_duration,
+            adapter=self._adapter or "default",
+        )
+
+        scanner_kwargs: dict = {
+            "detection_callback": self._detection_callback,
+            "service_uuids": self._service_uuids,
+        }
+        if self._adapter:
+            scanner_kwargs["adapter"] = self._adapter
+
+        while self._running:
+            if self._paused:
+                await asyncio.sleep(0.5)
+                continue
+            try:
+                self._devices_this_scan.clear()
+                async with BleakScanner(**scanner_kwargs) as _scanner:
+                    await asyncio.sleep(self._scan_duration)
+                logger.debug(
+                    "Scan cycle",
+                    devices=len(self._devices_this_scan),
+                    total_unique=len(self._seen_devices),
+                    total_packets=self._total_packets,
+                )
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error("Scanner error", error=str(e))
+                await asyncio.sleep(2.0)
+
+        logger.info("Scanner stopped", total_devices=len(self._seen_devices))
+
+    async def stop(self) -> None:
+        self._running = False
+
+    def pause(self) -> None:
+        self._paused = True
+
+    def resume(self) -> None:
+        self._paused = False
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
+    @property
+    def stats(self) -> dict[str, int]:
+        return {
+            "total_packets": self._total_packets,
+            "unique_devices": len(self._seen_devices),
+            "active_devices": len(self._devices_this_scan),
+        }