pyhubblenetwork 0.0.1__py3-none-any.whl

hubblenetwork/__init__.py

@@ -0,0 +1,27 @@
+# hubblenetwork/__init__.py
+"""
+Hubble Python SDK — public API façade.
+Import from here; internal module layout may change without notice.
+"""
+
+from . import ble
+from . import cloud
+
+from .packets import Location, EncryptedPacket, DecryptedPacket
+from .device import Device
+from .org import Organization
+from .crypto import decrypt
+
+__all__ = [
+    "ble",
+    "cloud",
+    "decrypt",
+    "Location",
+    "EncryptedPacket",
+    "DecryptedPacket",
+    "Device",
+    "Organization",
+    "flash_elf",
+    "fetch_elf",
+    "patch_elf",
+]

hubblenetwork/ble.py

@@ -0,0 +1,93 @@
+# hubblenetwork/ble.py
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timezone
+from typing import Optional
+import geocoder
+
+from bleak import BleakScanner
+
+# Import your dataclass
+from .packets import (
+    Location,
+    EncryptedPacket,
+)
+
+"""
+16-bit UUID 0xFCA6 in 128-bit Bluetooth Base UUID form
+
+Bluetooth spec defines a base UUID 0000xxxx-0000-1000-8000-00805F9B34FB.
+Any 16-bit (or 32-bit) UUID is expanded into that base by substituting xxxx.
+
+Libraries normalize to consistent 128-bit strings so you don’t have to guess
+whether a platform will report 16- vs 128-bit in scan results.
+
+In bleak, AdvertisementData.service_uuids and the keys in AdvertisementData.service_data
+are 128-bit strings. So matching against the normalized 128-bit form is the most portable.
+"""
+_TARGET_UUID = "0000fca6-0000-1000-8000-00805f9b34fb"
+
+
+def _get_location() -> Location:
+    geo = geocoder.ip("me")
+    lat, lon = geo.latlng
+    return Location(lat=lat, lon=lon)
+
+
+def scan(timeout: float) -> Optional[EncryptedPacket]:
+    """
+    Scan for a BLE advertisement that includes service data for UUID 0xFCA6 and
+    return it as an EncryptedPacket (payload=data bytes, rssi from the adv).
+    Returns None if nothing is found within `timeout` seconds.
+
+    This is a synchronous convenience wrapper around an asyncio scanner.
+    """
+
+    async def _scan_async(ttl: float) -> List[EncryptedPacket]:
+        done = asyncio.Event()
+        packets = []
+
+        def on_detect(device, adv_data) -> None:
+            nonlocal packets
+            # Normalize to a dict; bleak provides service_data as {uuid_str: bytes}
+            service_data = getattr(adv_data, "service_data", None) or {}
+            payload = None
+
+            # Keys are 128-bit UUID strings; compare lowercased
+            for uuid_str, data in service_data.items():
+                if (uuid_str or "").lower() == _TARGET_UUID:
+                    payload = bytes(data)
+                    break
+
+            if payload is not None:
+                rssi = getattr(adv_data, "rssi", getattr(device, "rssi", 0)) or 0
+                packets.append(
+                    EncryptedPacket(
+                        timestamp=int(datetime.now(timezone.utc).timestamp()),
+                        location=_get_location(),
+                        payload=payload,
+                        rssi=int(rssi),
+                    )
+                )
+
+        # Start scanning and wait for first match or timeout
+        async with BleakScanner(detection_callback=on_detect):
+            try:
+                await asyncio.wait_for(done.wait(), timeout=ttl)
+            except asyncio.TimeoutError:
+                pass
+
+        return packets
+
+    # Run the async scanner. If there's already a running event loop (e.g., Jupyter),
+    # you can adapt this to use `await _scan_async(timeout)` instead.
+    try:
+        return asyncio.run(_scan_async(timeout))
+    except RuntimeError:
+        # Fallback for environments with an active loop (e.g., notebooks/async apps)
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            # Create a task and block until it’s done via a new Future
+            return loop.run_until_complete(_scan_async(timeout))  # type: ignore[func-returns-value]
+        return loop.run_until_complete(_scan_async(timeout))

hubblenetwork/cli.py

@@ -0,0 +1,309 @@
+# hubblenetwork/cli.py
+from __future__ import annotations
+
+import click
+import os
+import json
+import time
+import base64
+import sys
+from datetime import timezone, datetime
+from typing import Optional
+from hubblenetwork import Organization
+from hubblenetwork import Device, DecryptedPacket, EncryptedPacket
+from hubblenetwork import ble as ble_mod
+from hubblenetwork import decrypt
+
+
+def _get_env_or_fail(name: str) -> str:
+    val = os.getenv(name)
+    if not val:
+        raise click.ClickException(f"[ERROR] {name} environment variable not set")
+    return val
+
+
+def _get_org_and_token(org_id, token) -> tuple[str, str]:
+    """
+    Helper function that checks if the given token and/or org
+    are None and gets the env var if not
+    """
+    if not token:
+        token = _get_env_or_fail("HUBBLE_API_TOKEN")
+    if not org_id:
+        org_id = _get_env_or_fail("HUBBLE_ORG_ID")
+    return org_id, token
+
+
+def _print_packets_pretty(pkts) -> None:
+    """Pretty-print an EncryptedPacket."""
+    for pkt in pkts:
+        ts = datetime.fromtimestamp(pkt.timestamp).strftime("%c")
+        loc = pkt.location
+        loc_str = (
+            f"{loc.lat:.6f},{loc.lon:.6f}"
+            if getattr(loc, "lat", None) is not None
+            else "unknown"
+        )
+        click.echo(click.style("=== BLE packet ===", bold=True))
+        click.echo(f"time:    {ts}")
+        click.echo(f"rssi:    {pkt.rssi} dBm")
+        click.echo(f"loc:     {loc_str}")
+        # Show both hex and length
+        if isinstance(pkt, DecryptedPacket):
+            click.echo(f'payload: "{pkt.payload}"')
+        elif isinstance(pkt, EncryptedPacket):
+            click.echo(f"payload: {pkt.payload.hex()} ({len(pkt.payload)} bytes)")
+
+
+def _print_packets_csv(pkts) -> None:
+    for pkt in pkts:
+        ts = datetime.fromtimestamp(pkt.timestamp).strftime("%c")
+        if isinstance(pkt, DecryptedPacket):
+            payload = pkt.payload
+        elif isinstance(pkt, EncryptedPacket):
+            payload = pkt.payload.hex()
+        click.echo(f"{ts}, {pkt.location.lat:.6f}, {pkt.location.lon:.6f}, {payload}")
+
+
+def _print_packets_kepler(pkts) -> None:
+    """
+    https://kepler.gl/demo
+
+    Can ingest this JSON to visualize a travel path for a device.
+    """
+    data = {
+        "type": "FeatureCollection",
+        "features": [
+            {
+                "type": "Feature",
+                "properties": {"vendor": "A"},
+                "geometry": {"type": "LineString", "coordinates": []},
+            }
+        ],
+    }
+
+    for pkt in pkts:
+        row = [pkt.location.lon, pkt.location.lat, 0, pkt.timestamp]
+        data["features"][0]["geometry"]["coordinates"].append(row)
+    click.echo(json.dumps(data))
+
+
+def _print_packets(pkts, output: str = "pretty") -> None:
+    func_name = f"_print_packets_{output.lower().strip()}"
+    func = getattr(sys.modules[__name__], func_name, None)
+    if callable(func):
+        func(pkts)
+    else:
+        _print_packets_pretty(pkts)
+
+
+def _print_device(dev: Device) -> None:
+    click.echo(f'id: "{dev.id}", ', nl=False)
+    click.echo(f'name: "{dev.name}", ', nl=False)
+    click.echo(f"tags: {str(dev.tags)}, ", nl=False)
+    ts = datetime.fromtimestamp(dev.created_ts).strftime("%c")
+    click.echo(f'created: "{ts}", ', nl=False)
+    click.echo(f"active: {str(dev.active)}", nl=False)
+    if dev.key:
+        click.secho(f', key: "{dev.key}"')
+    else:
+        click.echo("")
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+def cli() -> None:
+    """Hubble SDK CLI."""
+    # top-level group; subcommands are added below
+
+
+@cli.group()
+def ble() -> None:
+    """BLE utilities."""
+    # subgroup for BLE-related commands
+
+
+@ble.command("scan")
+@click.option(
+    "--timeout",
+    "-t",
+    type=int,
+    default=5,
+    show_default=False,
+    help="Timeout when scanning",
+)
+@click.option(
+    "--key",
+    "-k",
+    type=str,
+    default=None,
+    show_default=False,
+    help="Attempt to decrypt any received packet with the given key",
+)
+@click.option("--ingest", is_flag=True)
+def ble_scan(timeout, ingest: bool = False, key: str = None) -> None:
+    """
+    Scan for UUID 0xFCA6 and print the first packet found within TIMEOUT seconds.
+
+    Example:
+      hubblenetwork ble scan 1
+    """
+    click.secho(
+        f"[INFO] Scanning for Hubble devices (timeout={timeout}s)... ", nl=False
+    )
+    pkts = ble_mod.scan(timeout=timeout)
+    if len(pkts) == 0:
+        click.secho(f"[WARNING] No packet found within {timeout:.2f}s", fg="yellow")
+        raise SystemExit(1)
+    click.echo("[COMPLETE]")
+
+    click.echo("\n[INFO] Encrypted packets received:")
+    _print_packets(pkts)
+
+    # If we have a key, attempt to decrypt
+    if key:
+        key = bytearray(base64.b64decode(key))
+        decrypted_pkts = []
+        for pkt in pkts:
+            decrypted_pkt = decrypt(key, pkt)
+            if decrypted_pkt:
+                decrypted_pkts.append(decrypted_pkt)
+        if len(decrypted_pkts) > 0:
+            click.echo("\n[INFO] Locally decrypted packets:")
+            _print_packets(decrypted_pkts)
+        else:
+            click.secho("\n[WARNING] No locally decryptable packets found", fg="yellow")
+
+    if ingest:
+        click.echo("[INFO] Ingesting packet(s) into the backend... ", nl=False)
+        org = Organization(
+            org_id=_get_env_or_fail("HUBBLE_ORG_ID"),
+            api_token=_get_env_or_fail("HUBBLE_API_TOKEN"),
+        )
+        for pkt in pkts:
+            org.ingest_packet(pkt)
+        click.echo("[SUCCESS]")
+
+
+@cli.group()
+def org() -> None:
+    """Organization utilities."""
+    # subgroup for organization-related commands
+
+
+@click.option(
+    "--org-id",
+    "-o",
+    type=str,
+    default=None,
+    show_default=False,
+    help="Organization ID (if not using HUBBLE_ORG_ID env var)",
+)
+@click.option(
+    "--token",
+    "-t",
+    type=str,
+    default=None,
+    show_default=False,  # show default in --help
+    help="Token (if not using HUBBLE_API_TOKEN env var)",
+)
+@org.command("list-devices")
+def list_devices(org_id, token) -> None:
+    org_id, token = _get_org_and_token(org_id, token)
+
+    org = Organization(org_id=org_id, api_token=token)
+    devices = org.list_devices()
+    for device in devices:
+        _print_device(device)
+
+
+@click.option(
+    "--org-id",
+    "-o",
+    type=str,
+    default=None,
+    show_default=False,
+    help="Organization ID (if not using HUBBLE_ORG_ID env var)",
+)
+@click.option(
+    "--token",
+    "-t",
+    type=str,
+    default=None,
+    show_default=False,  # show default in --help
+    help="Token (if not using HUBBLE_API_TOKEN env var)",
+)
+@org.command("register_device")
+def register_device(org_id, token) -> None:
+    org_id, token = _get_org_and_token(org_id, token)
+
+    org = Organization(org_id=org_id, api_token=token)
+    click.secho(str(org.register_device()))
+
+
+@org.command("get-packets")
+@click.argument("device-id", type=str)
+@click.option(
+    "--org-id",
+    "-o",
+    type=str,
+    default=None,
+    show_default=False,
+    help="Organization ID (if not using HUBBLE_ORG_ID env var)",
+)
+@click.option(
+    "--token",
+    "-t",
+    type=str,
+    default=None,
+    show_default=False,  # show default in --help
+    help="Token (if not using HUBBLE_API_TOKEN env var)",
+)
+@click.option(
+    "--output",
+    type=str,
+    default=None,
+    show_default=False,  # show default in --help
+    help="Output format (None, pretty, csv)",
+)
+@click.option(
+    "--days",
+    "-d",
+    type=int,
+    default=7,
+    show_default=False,  # show default in --help
+    help="Number of days to query back (from now)",
+)
+def get_packets(device_id, org_id, token, output: str = None, days: int = 7) -> None:
+    org_id, token = _get_org_and_token(org_id, token)
+
+    org = Organization(org_id=org_id, api_token=token)
+    device = Device(id=device_id)
+    packets = org.retrieve_packets(device, days=days)
+    _print_packets(packets, output)
+
+
+@cli.group()
+def demo() -> None:
+    """Demo functionality"""
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    """
+    Entry point used by console_scripts.
+
+    Returns a process exit code instead of letting Click call sys.exit for easier testing.
+    """
+    try:
+        # standalone_mode=False prevents Click from calling sys.exit itself.
+        cli.main(args=argv, prog_name="hubble", standalone_mode=False)
+    except SystemExit as e:
+        return int(e.code)
+    except Exception as e:  # safety net to avoid tracebacks in user CLI
+        click.secho(f"Unexpected error: {e}", fg="red", err=True)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    # Forward command-line args (excluding the program name) to main()
+    raise SystemExit(main())

hubblenetwork/cloud.py

@@ -0,0 +1,180 @@
+# hubble/cloud_api.py
+from __future__ import annotations
+import httpx
+import time
+import base64
+from typing import Any, Optional
+from collections.abc import MutableMapping
+from .packets import EncryptedPacket, DecryptedPacket
+from .device import Device
+from .errors import (
+    BackendError,
+    NetworkError,
+    APITimeout,
+    raise_for_response,
+)
+
+_API_BASE: str = "https://api.hubble.com/api"
+
+
+def _auth_headers(api_token: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_token}",
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+
+
+def _list_devices_endpoint(org_id: str) -> str:
+    return f"/org/{org_id}/devices"
+
+
+def _register_device_endpoint(org_id: str) -> str:
+    return f"/v2/org/{org_id}/devices"
+
+
+def _retrive_org_packets_endpoint(org_id: str) -> str:
+    return f"/org/{org_id}/packets"
+
+
+def _ingest_packets_endpoint(org_id: str) -> str:
+    return f"/org/{org_id}/packets"
+
+
+def cloud_request(
+    method: str,
+    path: str,
+    *,
+    api_token: Optional[str] = None,
+    json: Any = None,
+    timeout_s: float = 10.0,
+    params: Optional[MutableMapping[str, Any]] = None,
+) -> Any:
+    """
+    Make a single HTTP request to the Hubble Cloud API and return parsed JSON.
+
+    - `method`: "GET", "POST", etc.
+    - `path`: endpoint path (e.g., "/devices" or "orgs/{id}/devices")
+    - `api_token`: API token for auth (optional, but recommended)
+    - `org_id`: if provided, will be added as query param `orgId=<org_id>`
+               (skip or embed in `path` if your endpoint uses a path param instead)
+    - `json`: request JSON body (for POST/PUT/PATCH)
+    - `timeout_s`: request timeout in seconds
+    - `params`: optional HTTP request parameters
+    """
+    path = path.lstrip("/")
+    url = f"{_API_BASE}/{path}"
+
+    # headers
+    headers: MutableMapping[str, str] = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    if api_token:
+        headers["Authorization"] = f"Bearer {api_token}"
+
+    try:
+        with httpx.Client(timeout=timeout_s) as client:
+            resp = client.request(
+                method.upper(), url, params=params, headers=headers, json=json
+            )
+    except httpx.TimeoutException as e:
+        raise APITimeout(f"Request timed out: {method} {url}") from e
+    except httpx.HTTPError as e:
+        raise NetworkError(f"Network error: {method} {url}: {e}") from e
+
+    if resp.status_code != 200:
+        body = None
+        try:
+            body = resp.json()
+        except Exception:
+            body = resp.text
+        raise_for_response(resp.status_code, body=body)
+
+    # Parse JSON body
+    try:
+        return resp.json()
+    except ValueError as e:
+        # Server said "application/json" but body isn't JSON
+        raise BackendError(f"Non-JSON response from {url}") from e
+
+
+def ingest(*, org_id: str, api_token: str, packet: EncryptedPacket) -> None:
+    """Push an encrypted packet to the cloud."""
+    pass
+
+
+def register_device(
+    *, org_id: str, api_token: str, name: Optional[str] = None
+) -> Device:
+    """Create a new device and return it."""
+    data = {
+        "n_devices": 1,
+        "encryption": "AES-256-CTR",
+    }
+    return cloud_request(
+        method="POST",
+        path=_register_device_endpoint(org_id),
+        api_token=api_token,
+        json=data,
+    )
+
+
+def list_devices(*, org_id: str, api_token: str) -> list[Device]:
+    """
+    List devices for the org (keys typically omitted).
+
+    Returns:
+        json response from server
+
+    """
+    return cloud_request(
+        method="GET",
+        path=_list_devices_endpoint(org_id),
+        api_token=api_token,
+    )
+
+
+def retrieve_packets(
+    *, org_id: str, api_token: str, device_id: Optional[str] = None, days: int = 7
+) -> Optional[DecryptedPacket]:
+    """Fetch decrypted packets for a device."""
+    params = {"start": (int(time.time()) - (days * 24 * 60 * 60))}
+    if device_id:
+        params["device_id"] = device_id
+    return cloud_request(
+        method="GET",
+        path=_retrive_org_packets_endpoint(org_id),
+        api_token=api_token,
+        params=params,
+    )
+
+
+def ingest_packet(*, org_id: str, api_token: str, packet: EncryptedPacket) -> None:
+    body = {
+        "ble_locations": [
+            {
+                "location": {
+                    "latitude": packet.location.lat,
+                    "longitude": packet.location.lon,
+                    "timestamp": packet.timestamp,
+                    "horizontal_accuracy": 42,
+                    "altitude": 42,
+                    "vertical_accuracy": 42,
+                },
+                "adv": [
+                    {
+                        "payload": base64.b64encode(packet.payload).decode("utf-8"),
+                        "rssi": packet.rssi,
+                        "timestamp": packet.timestamp,
+                    }
+                ],
+            }
+        ]
+    }
+    return cloud_request(
+        method="POST",
+        path=_ingest_packets_endpoint(org_id),
+        api_token=api_token,
+        json=body,
+    )

hubblenetwork/crypto.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+from Crypto.Cipher import AES
+from Crypto.Hash import CMAC
+from Crypto.Protocol.KDF import SP800_108_Counter
+from datetime import datetime, timezone
+
+from .packets import EncryptedPacket, DecryptedPacket
+
+# Valid values are 16 and 32, respectively for AES-128 and AES-256
+_HUBBLE_AES_KEY_SIZE = 32
+
+_HUBBLE_AES_NONCE_SIZE = 12
+_HUBBLE_AES_TAG_SIZE = 4
+
+
+def _generate_kdf_key(key: bytes, key_size: int, label: str, context: int) -> bytes:
+    label = label.encode()
+    context = str(context).encode()
+
+    return SP800_108_Counter(
+        key,
+        key_size,
+        lambda session_key, data: CMAC.new(session_key, data, AES).digest(),
+        label=label,
+        context=context,
+    )
+
+
+def _get_nonce(key: bytes, time_counter: int, counter: int) -> bytes:
+    nonce_key = _generate_kdf_key(key, _HUBBLE_AES_KEY_SIZE, "NonceKey", time_counter)
+
+    return _generate_kdf_key(nonce_key, _HUBBLE_AES_NONCE_SIZE, "Nonce", counter)
+
+
+def _get_encryption_key(key: bytes, time_counter: int, counter: int) -> bytes:
+    encryption_key = _generate_kdf_key(
+        key, _HUBBLE_AES_KEY_SIZE, "EncryptionKey", time_counter
+    )
+
+    return _generate_kdf_key(encryption_key, _HUBBLE_AES_KEY_SIZE, "Key", counter)
+
+
+def _get_auth_tag(key: bytes, ciphertext: bytes) -> bytes:
+    computed_cmac = CMAC.new(key, ciphertext, AES).digest()
+
+    return computed_cmac[:_HUBBLE_AES_TAG_SIZE]
+
+
+def _aes_decrypt(key: bytes, session_nonce: bytes, ciphertext: bytes) -> bytes:
+    cipher = AES.new(key, AES.MODE_CTR, nonce=session_nonce)
+
+    return cipher.decrypt(ciphertext)
+
+
+def decrypt(
+    key: bytes, encrypted_pkt: EncryptedPacket, days: int = 2
+) -> Optional[DecryptedPacket]:
+    ble_adv = encrypted_pkt.payload
+    seq_no = int.from_bytes(ble_adv[0:2], "big") & 0x3FF
+    device_id = ble_adv[2:6].hex()
+    auth_tag = ble_adv[6:10]
+    encrypted_payload = ble_adv[10:]
+    day_offset = 0
+
+    time_counter = int(datetime.now(timezone.utc).timestamp()) // 86400
+
+    for t in range(-days, days + 1):
+        daily_key = _get_encryption_key(key, time_counter + t, seq_no)
+        tag = _get_auth_tag(daily_key, encrypted_payload)
+
+        if tag == auth_tag:
+            day_offset = t
+            nonce = _get_nonce(key, time_counter, seq_no)
+            decrypted_payload = _aes_decrypt(daily_key, nonce, encrypted_payload)
+            return DecryptedPacket(
+                timestamp=encrypted_pkt.timestamp,
+                device_id="",
+                device_name="",
+                location=encrypted_pkt.location,
+                tags=[],
+                payload=decrypted_payload,
+                rssi=encrypted_pkt.rssi,
+                counter=None,
+                sequence=None,
+            )
+    return None