pyhubblenetwork 0.2.0__tar.gz → 0.3.0__tar.gz

{pyhubblenetwork-0.2.0 → pyhubblenetwork-0.3.0}/.gitignore

@@ -157,4 +157,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+#.idea/
+
+# Git worktrees
+.worktrees/

{pyhubblenetwork-0.2.0 → pyhubblenetwork-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyhubblenetwork
-Version: 0.2.0
+Version: 0.3.0
 Summary: Hubble SDK host-side tools
 Author-email: Paul Buckley <paul@hubble.com>
 License-Expression: Apache-2.0
@@ -139,8 +139,20 @@ If installed, the `hubblenetwork` command is available:
 ```bash
 hubblenetwork --help
 hubblenetwork ble scan
+hubblenetwork ble scan --payload-format hex
+hubblenetwork org get-packets --payload-format string
 ```
 
+### Payload format option
+
+Commands that output packet data (`ble scan`, `ble detect`, `org get-packets`) support the `--payload-format` flag to control how payloads are displayed:
+
+* `base64` (default) — encode payloads as base64
+* `hex` — display payloads as hexadecimal
+* `string` — decode payloads as UTF-8 text (falls back to `<invalid UTF-8>` if bytes are not valid UTF-8)
+
+This applies to all output formats (tabular, json, csv).
+
 ## Configuration
 
 Some functions read defaults from environment variables if not provided explicitly. Suggested variables:
@@ -207,5 +219,5 @@ ruff check src
 ## Releases & versioning
 
 * Follows **SemVer** (MAJOR.MINOR.PATCH).
-* Tagged releases (e.g., `v0.2.0`) publish wheels/sdists to PyPI.
+* Tagged releases (e.g., `v0.3.0`) publish wheels/sdists to PyPI.
 * Release process: (add short steps for how to cut a release—tagging, CI release job, PyPI publish credentials).

{pyhubblenetwork-0.2.0 → pyhubblenetwork-0.3.0}/README.md

@@ -116,8 +116,20 @@ If installed, the `hubblenetwork` command is available:
 ```bash
 hubblenetwork --help
 hubblenetwork ble scan
+hubblenetwork ble scan --payload-format hex
+hubblenetwork org get-packets --payload-format string
 ```
 
+### Payload format option
+
+Commands that output packet data (`ble scan`, `ble detect`, `org get-packets`) support the `--payload-format` flag to control how payloads are displayed:
+
+* `base64` (default) — encode payloads as base64
+* `hex` — display payloads as hexadecimal
+* `string` — decode payloads as UTF-8 text (falls back to `<invalid UTF-8>` if bytes are not valid UTF-8)
+
+This applies to all output formats (tabular, json, csv).
+
 ## Configuration
 
 Some functions read defaults from environment variables if not provided explicitly. Suggested variables:
@@ -184,5 +196,5 @@ ruff check src
 ## Releases & versioning
 
 * Follows **SemVer** (MAJOR.MINOR.PATCH).
-* Tagged releases (e.g., `v0.2.0`) publish wheels/sdists to PyPI.
+* Tagged releases (e.g., `v0.3.0`) publish wheels/sdists to PyPI.
 * Release process: (add short steps for how to cut a release—tagging, CI release job, PyPI publish credentials).

{pyhubblenetwork-0.2.0 → pyhubblenetwork-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyhubblenetwork"
-version = "0.2.0"
+version = "0.3.0"
 requires-python = ">=3.9"
 authors = [
   { name="Paul Buckley", email="paul@hubble.com" },
@@ -45,6 +45,7 @@ include = [
 # ---- Testing & dev tooling ----
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["src"]
 markers = [
   "ble: tests that require BLE hardware/permissions",
   "integration: slow or environment-dependent tests",

{pyhubblenetwork-0.2.0 → pyhubblenetwork-0.3.0}/src/hubblenetwork/cli.py

@@ -13,7 +13,7 @@ from datetime import datetime
 from typing import Optional, List
 from tabulate import tabulate
 from hubblenetwork import Organization
-from hubblenetwork import Device, DecryptedPacket, EncryptedPacket
+from hubblenetwork import Device, DecryptedPacket
 from hubblenetwork import ble as ble_mod
 from hubblenetwork import ready as ready_mod
 from hubblenetwork import decrypt
@@ -28,6 +28,22 @@ _handler.setFormatter(logging.Formatter("%(levelname)s - %(message)s"))
 logger.addHandler(_handler)
 
 
+def _format_payload(payload, fmt: str) -> str:
+    """Format packet payload bytes for display."""
+    if not isinstance(payload, bytes):
+        return str(payload)
+    if fmt == "hex":
+        return payload.hex().upper()
+    elif fmt == "string":
+        try:
+            return payload.decode("utf-8")
+        except UnicodeDecodeError:
+            click.echo("Warning: payload contains non-UTF-8 bytes", err=True)
+            return "<invalid UTF-8>"
+    else:  # base64 (default)
+        return base64.b64encode(payload).decode("ascii")
+
+
 def _get_env_or_fail(name: str) -> str:
     val = os.getenv(name)
     if not val:
@@ -47,7 +63,7 @@ def _get_org_and_token(org_id, token) -> tuple[str, str]:
     return org_id, token
 
 
-def _packet_to_dict(pkt) -> dict:
+def _packet_to_dict(pkt, payload_format: str = "base64") -> dict:
     """Convert a packet to a dictionary for JSON serialization."""
     ts = datetime.fromtimestamp(pkt.timestamp).strftime("%c")
     data = {
@@ -59,24 +75,8 @@ def _packet_to_dict(pkt) -> dict:
     if isinstance(pkt, DecryptedPacket):
         data["counter"] = pkt.counter
         data["sequence"] = pkt.sequence
-        # Decode payload to string if possible, otherwise use hex
-        try:
-            data["payload"] = (
-                pkt.payload.decode("utf-8")
-                if isinstance(pkt.payload, bytes)
-                else str(pkt.payload)
-            )
-        except UnicodeDecodeError:
-            data["payload_hex"] = (
-                pkt.payload.hex()
-                if isinstance(pkt.payload, bytes)
-                else str(pkt.payload)
-            )
-    else:
-        # EncryptedPacket - show payload as hex
-        data["payload_hex"] = (
-            pkt.payload.hex() if isinstance(pkt.payload, bytes) else str(pkt.payload)
-        )
+
+    data["payload"] = _format_payload(pkt.payload, payload_format)
 
     if not pkt.location.fake:
         data["location"] = {
@@ -208,11 +208,12 @@ class _StreamingTablePrinter(_StreamingPrinterBase):
         "PAYLOAD": 20,
     }
 
-    def __init__(self):
+    def __init__(self, payload_format: str = "base64"):
         super().__init__()
         self._header_printed = False
         self._headers: List[str] = []
         self._column_config: dict = {}
+        self._payload_format = payload_format
 
     def _determine_columns(self, pkt) -> tuple[List[str], dict]:
         """Determine column headers and configuration based on packet type."""
@@ -271,7 +272,7 @@ class _StreamingTablePrinter(_StreamingPrinterBase):
             row.append(f"{loc.lat:.6f},{loc.lon:.6f}")
 
         if self._column_config["is_decrypted"]:
-            row.append(f'"{pkt.payload}"')
+            row.append(_format_payload(pkt.payload, self._payload_format))
 
         # Print the data row
         click.echo(self._format_row(row))
@@ -282,9 +283,10 @@ class _StreamingTablePrinter(_StreamingPrinterBase):
 class _StreamingJsonPrinter(_StreamingPrinterBase):
     """Print packets as a streaming JSON array."""
 
-    def __init__(self):
+    def __init__(self, payload_format: str = "base64"):
         super().__init__()
         self._array_started = False
+        self._payload_format = payload_format
 
     @property
     def suppress_info_messages(self) -> bool:
@@ -292,7 +294,7 @@ class _StreamingJsonPrinter(_StreamingPrinterBase):
 
     def print_row(self, pkt) -> None:
         """Print a single packet as JSON."""
-        pkt_dict = _packet_to_dict(pkt)
+        pkt_dict = _packet_to_dict(pkt, self._payload_format)
         if not self._array_started:
             click.echo("[")
             self._array_started = True
@@ -321,13 +323,12 @@ _STREAMING_PRINTERS = {
 }
 
 
-def _print_packets_tabular(pkts: List) -> None:
+def _print_packets_tabular(pkts: List, payload_format: str = "base64") -> None:
     """Print packets in a formatted table using tabulate."""
     if not pkts:
         click.echo("No packets!")
         return
 
-    # For batch printing, use the full table format
     first_pkt = pkts[0]
     is_decrypted = isinstance(first_pkt, DecryptedPacket)
     has_real_location = not first_pkt.location.fake
@@ -353,50 +354,37 @@ def _print_packets_tabular(pkts: List) -> None:
             row.append(f"{loc.lat:.6f},{loc.lon:.6f}")
 
         if is_decrypted:
-            row.append(f'"{pkt.payload}"')
+            row.append(_format_payload(pkt.payload, payload_format))
 
         rows.append(row)
 
     click.echo("\n" + tabulate(rows, headers=headers, tablefmt="grid"))
 
 
-def _print_packets_csv(pkts) -> None:
+def _print_packets_csv(pkts, payload_format: str = "base64") -> None:
     click.echo("timestamp, datetime, latitude, longitude, payload")
     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()
+        payload_str = _format_payload(pkt.payload, payload_format)
         click.echo(
-            f'{pkt.timestamp}, {ts}, {pkt.location.lat:.6f}, {pkt.location.lon:.6f}, "{payload}"'
+            f'{pkt.timestamp}, {ts}, {pkt.location.lat:.6f}, {pkt.location.lon:.6f}, "{payload_str}"'
         )
 
 
-def _print_packets_json(pkts) -> None:
+def _print_packets_json(pkts, payload_format: str = "base64") -> None:
     """Print packets as a JSON array."""
-    json_packets = [_packet_to_dict(pkt) for pkt in pkts]
+    json_packets = [_packet_to_dict(pkt, payload_format) for pkt in pkts]
     click.echo(json.dumps(json_packets, indent=2))
 
 
-_OUTPUT_FORMATS = {
-    "csv": "_print_packets_csv",
-    "tabular": "_print_packets_tabular",
-    "json": "_print_packets_json",
-}
-
-
-def _print_packets(pkts, output: str = "tabular") -> None:
-    if not output:
-        _print_packets_tabular(pkts)
-        return
-
-    format_key = output.lower().strip()
-    if format_key in _OUTPUT_FORMATS:
-        func = globals()[_OUTPUT_FORMATS[format_key]]
-        func(pkts)
+def _print_packets(pkts, output: str = "tabular", payload_format: str = "base64") -> None:
+    format_key = (output or "tabular").lower().strip()
+    if format_key == "json":
+        _print_packets_json(pkts, payload_format)
+    elif format_key == "csv":
+        _print_packets_csv(pkts, payload_format)
     else:
-        _print_packets_tabular(pkts)
+        _print_packets_tabular(pkts, payload_format)
 
 
 def _print_device(dev: Device) -> None:
@@ -483,6 +471,20 @@ def ble() -> None:
     show_default=False,
     help="Key to decrypt packets (base64 encoded, required)",
 )
+@click.option(
+    "--days",
+    "-d",
+    type=int,
+    default=2,
+    show_default=True,
+    help="Number of days to check back when decrypting",
+)
+@click.option(
+    "--eid-pool-size",
+    type=int,
+    default=None,
+    help="Use counter-based EID with given pool size (0..N-1) instead of UTC-based",
+)
 @click.option(
     "--format",
     "-o",
@@ -492,16 +494,29 @@ def ble() -> None:
     show_default=True,
     help="Output format",
 )
+@click.option(
+    "--payload-format",
+    "payload_format",
+    type=click.Choice(["base64", "hex", "string"], case_sensitive=False),
+    default="base64",
+    show_default=True,
+    help="Encoding format for packet payload",
+)
 @click.option(
     "--debug",
     is_flag=True,
     default=False,
     help="Enable debug logging to stderr",
 )
+@click.pass_context
 def ble_detect(
+    ctx,
     timeout: Optional[int] = None,
     key: str = None,
+    days: int = 2,
+    eid_pool_size: Optional[int] = None,
     output_format: str = "tabular",
+    payload_format: str = "base64",
     debug: bool = False,
 ) -> None:
     """
@@ -516,6 +531,14 @@ def ble_detect(
     """
     use_json = output_format.lower() == "json"
 
+    # Validate --eid-pool-size and --days mutual exclusivity
+    if eid_pool_size is not None:
+        days_source = ctx.get_parameter_source("days")
+        if days_source == click.core.ParameterSource.COMMANDLINE:
+            raise click.UsageError(
+                "--eid-pool-size and --days are mutually exclusive"
+            )
+
     # Set log level based on debug flag
     logger.setLevel(logging.DEBUG if debug else logging.WARNING)
 
@@ -565,7 +588,9 @@ def ble_detect(
         logger.debug("Packet received, attempting decryption...")
 
         # Attempt to decrypt the packet
-        decrypted_pkt = decrypt(decoded_key, pkt)
+        decrypted_pkt = decrypt(
+            decoded_key, pkt, days=days, eid_pool_size=eid_pool_size
+        )
 
         if decrypted_pkt:
             # If we can decrypt it, output success
@@ -574,20 +599,22 @@ def ble_detect(
             )
             logger.info("Packet decrypted successfully!")
 
+            payload_str = _format_payload(decrypted_pkt.payload, payload_format)
             if use_json:
                 result = {
                     "success": True,
                     "packet": {
                         "datetime": datetime_str,
                         "rssi": decrypted_pkt.rssi,
-                        "payload_bytes": len(decrypted_pkt.payload),
+                        "payload": payload_str,
+                        "counter": decrypted_pkt.counter,
                     },
                 }
                 click.echo(json.dumps(result))
             else:
                 click.secho("[SUCCESS] ", fg="green", nl=False)
                 click.echo(
-                    f"Packet decrypted: {datetime_str}, RSSI: {decrypted_pkt.rssi} dBm, {len(decrypted_pkt.payload)} bytes"
+                    f"Packet decrypted: {datetime_str}, RSSI: {decrypted_pkt.rssi} dBm, payload: {payload_str}, counter: {decrypted_pkt.counter}"
                 )
             return
 
@@ -631,6 +658,12 @@ def ble_detect(
     show_default=True,
     help="Number of days to check back when decrypting",
 )
+@click.option(
+    "--eid-pool-size",
+    type=int,
+    default=None,
+    help="Use counter-based EID with given pool size (0..N-1) instead of UTC-based",
+)
 @click.option("--ingest", is_flag=True, help="Ingest packets to backend (requires key)")
 @click.option(
     "--format",
@@ -641,13 +674,25 @@ def ble_detect(
     show_default=True,
     help="Output format for packets",
 )
+@click.option(
+    "--payload-format",
+    "payload_format",
+    type=click.Choice(["base64", "hex", "string"], case_sensitive=False),
+    default="base64",
+    show_default=True,
+    help="Encoding format for packet payload",
+)
+@click.pass_context
 def ble_scan(
+    ctx,
     timeout: Optional[int] = None,
     count: Optional[int] = None,
     ingest: bool = False,
     key: Optional[str] = None,
     days: int = 2,
+    eid_pool_size: Optional[int] = None,
     output_format: str = "tabular",
+    payload_format: str = "base64",
 ) -> None:
     """
     Scan for UUID 0xFCA6 and print packets as they are found.
@@ -658,11 +703,21 @@ def ble_scan(
       hubblenetwork ble scan -o json --timeout 10
       hubblenetwork ble scan -n 5              # Stop after 5 packets
     """
+    # Validate --eid-pool-size constraints
+    if eid_pool_size is not None:
+        if not key:
+            raise click.UsageError("--eid-pool-size requires --key")
+        days_source = ctx.get_parameter_source("days")
+        if days_source == click.core.ParameterSource.COMMANDLINE:
+            raise click.UsageError(
+                "--eid-pool-size and --days are mutually exclusive"
+            )
+
     # Get the appropriate streaming printer
     printer_class = _STREAMING_PRINTERS.get(
         output_format.lower(), _StreamingTablePrinter
     )
-    printer = printer_class()
+    printer = printer_class(payload_format=payload_format)
 
     if not printer.suppress_info_messages:
         click.secho("[INFO] Scanning for Hubble devices... (Press Ctrl+C to stop)")
@@ -703,7 +758,9 @@ def ble_scan(
 
             # If we have a key, attempt to decrypt
             if decoded_key:
-                decrypted_pkt = decrypt(decoded_key, pkt, days=days)
+                decrypted_pkt = decrypt(
+                    decoded_key, pkt, days=days, eid_pool_size=eid_pool_size
+                )
                 if decrypted_pkt:
                     printer.print_row(decrypted_pkt)
                     # We only allow ingestion of packets you know the key of
@@ -2227,9 +2284,17 @@ def set_device_name(org: Organization, device_id: str, name: str) -> None:
     show_default=True,
     help="Number of days to query back (from now)",
 )
+@click.option(
+    "--payload-format",
+    "payload_format",
+    type=click.Choice(["base64", "hex", "string"], case_sensitive=False),
+    default="base64",
+    show_default=True,
+    help="Encoding format for packet payload",
+)
 @pass_orgcfg
 def get_packets(
-    org: Organization, device_id: str, output_format: str = "tabular", days: int = 7
+    org: Organization, device_id: str, output_format: str = "tabular", days: int = 7, payload_format: str = "base64"
 ) -> None:
     """
     Retrieve and display packets for a device.
@@ -2241,7 +2306,7 @@ def get_packets(
     """
     device = Device(id=device_id)
     packets = org.retrieve_packets(device, days=days)
-    _print_packets(packets, output_format)
+    _print_packets(packets, output_format, payload_format)
 
 
 def main(argv: Optional[list[str]] = None) -> int:

{pyhubblenetwork-0.2.0 → pyhubblenetwork-0.3.0}/src/hubblenetwork/crypto.py

@@ -75,19 +75,29 @@ def _check_tag_matches(
 
 
 def decrypt(
-    key: bytes, encrypted_pkt: EncryptedPacket, days: int = 2
+    key: bytes,
+    encrypted_pkt: EncryptedPacket,
+    days: int = 2,
+    eid_pool_size: Optional[int] = None,
 ) -> Optional[DecryptedPacket]:
+    if eid_pool_size is not None and days != 2:
+        raise ValueError("Cannot specify both eid_pool_size and days")
+
     parsed = ParsedPacket(encrypted_pkt)
     keylen = len(key)
 
-    time_counter = int(datetime.now(timezone.utc).timestamp()) // 86400
+    if eid_pool_size is not None:
+        candidates = range(eid_pool_size)
+    else:
+        time_counter = int(datetime.now(timezone.utc).timestamp()) // 86400
+        candidates = (time_counter + t for t in range(-days, days + 1))
 
-    for t in range(-days, days + 1):
-        if _check_tag_matches(key, time_counter + t, parsed):
+    for candidate in candidates:
+        if _check_tag_matches(key, candidate, parsed):
             daily_key = _get_encryption_key(
-                key, time_counter + t, parsed.seq_no, keylen=keylen
+                key, candidate, parsed.seq_no, keylen=keylen
             )
-            nonce = _get_nonce(key, time_counter + t, parsed.seq_no, keylen=keylen)
+            nonce = _get_nonce(key, candidate, parsed.seq_no, keylen=keylen)
             decrypted_payload = _aes_decrypt(daily_key, nonce, parsed.encrypted_payload)
             return DecryptedPacket(
                 timestamp=encrypted_pkt.timestamp,
@@ -97,7 +107,7 @@ def decrypt(
                 tags={},
                 payload=decrypted_payload,
                 rssi=encrypted_pkt.rssi,
-                counter=time_counter + t,
+                counter=candidate,
                 sequence=parsed.seq_no,
             )
     return None

{pyhubblenetwork-0.2.0 → pyhubblenetwork-0.3.0}/src/hubblenetwork/device.py

@@ -1,5 +1,6 @@
 # hubble/device.py
 from __future__ import annotations
+import base64
 from dataclasses import dataclass
 from typing import Dict, Optional
 
@@ -18,6 +19,17 @@ class Device:
     created_ts: Optional[int] = None
     active: Optional[bool] = False
 
+    def __str__(self) -> str:
+        key_str = (
+            base64.b64encode(self.key).decode("ascii")
+            if isinstance(self.key, bytes)
+            else self.key
+        )
+        return (
+            f"Device(id={self.id!r}, key={key_str!r}, name={self.name!r}, "
+            f"tags={self.tags!r}, created_ts={self.created_ts!r}, active={self.active!r})"
+        )
+
     @classmethod
     def from_json(cls, json):
         return cls(

pyhubblenetwork-0.3.0/tests/test_cli_payload.py

@@ -0,0 +1,249 @@
+import base64
+import pytest
+from unittest.mock import MagicMock
+from hubblenetwork.packets import EncryptedPacket, DecryptedPacket
+from hubblenetwork.packets import Location
+
+
+def fake_location():
+    loc = MagicMock(spec=Location)
+    loc.fake = True
+    loc.lat = 0.0
+    loc.lon = 0.0
+    return loc
+
+
+def make_encrypted_packet(payload: bytes) -> EncryptedPacket:
+    return EncryptedPacket(
+        timestamp=1700000000,
+        location=fake_location(),
+        payload=payload,
+        rssi=-70,
+    )
+
+
+def make_decrypted_packet(payload: bytes) -> DecryptedPacket:
+    return DecryptedPacket(
+        timestamp=1700000000,
+        device_id="dev123",
+        device_name="Test Device",
+        location=fake_location(),
+        tags={},
+        payload=payload,
+        rssi=-70,
+        counter=42,
+        sequence=1,
+    )
+
+
+class TestFormatPayload:
+    """Tests for the _format_payload helper."""
+
+    def test_base64_encoding(self):
+        from hubblenetwork.cli import _format_payload
+        assert _format_payload(b'\x01\x02\x03', "base64") == "AQID"
+
+    def test_hex_encoding_uppercase(self):
+        from hubblenetwork.cli import _format_payload
+        assert _format_payload(b'\xab\xc6\x79', "hex") == "ABC679"
+
+    def test_hex_encoding_all_zeros(self):
+        from hubblenetwork.cli import _format_payload
+        assert _format_payload(b'\x00\x00', "hex") == "0000"
+
+    def test_string_encoding_valid_utf8(self):
+        from hubblenetwork.cli import _format_payload
+        assert _format_payload(b'hello world', "string") == "hello world"
+
+    def test_string_encoding_invalid_utf8_returns_fallback(self, capsys):
+        from hubblenetwork.cli import _format_payload
+        result = _format_payload(b'\xff\xfe', "string")
+        assert result == "<invalid UTF-8>"
+
+    def test_string_encoding_invalid_utf8_warns_to_stderr(self, capsys):
+        from hubblenetwork.cli import _format_payload
+        _format_payload(b'\xff\xfe', "string")
+        captured = capsys.readouterr()
+        assert "Warning" in captured.err
+
+    def test_empty_bytes_base64(self):
+        from hubblenetwork.cli import _format_payload
+        assert _format_payload(b'', "base64") == ""
+
+    def test_empty_bytes_hex(self):
+        from hubblenetwork.cli import _format_payload
+        assert _format_payload(b'', "hex") == ""
+
+    def test_non_bytes_passthrough(self):
+        from hubblenetwork.cli import _format_payload
+        assert _format_payload("already a string", "base64") == "already a string"
+
+
+class TestPacketToDict:
+    """Tests for _packet_to_dict payload encoding."""
+
+    def test_encrypted_packet_payload_is_base64(self):
+        from hubblenetwork.cli import _packet_to_dict
+        raw = b'\x01\x02\x03\xff'
+        pkt = make_encrypted_packet(raw)
+        result = _packet_to_dict(pkt)
+        assert "payload" in result
+        assert result["payload"] == base64.b64encode(raw).decode("ascii")
+        assert "payload_hex" not in result
+
+    def test_decrypted_packet_payload_is_base64(self):
+        from hubblenetwork.cli import _packet_to_dict
+        raw = b'\xde\xad\xbe\xef'
+        pkt = make_decrypted_packet(raw)
+        result = _packet_to_dict(pkt)
+        assert "payload" in result
+        assert result["payload"] == base64.b64encode(raw).decode("ascii")
+        assert "payload_hex" not in result
+
+    def test_decrypted_packet_utf8_payload_still_base64(self):
+        """Even valid UTF-8 should be base64 encoded."""
+        from hubblenetwork.cli import _packet_to_dict
+        raw = b'hello world'
+        pkt = make_decrypted_packet(raw)
+        result = _packet_to_dict(pkt)
+        assert result["payload"] == base64.b64encode(raw).decode("ascii")
+
+    def test_empty_payload_is_base64(self):
+        from hubblenetwork.cli import _packet_to_dict
+        pkt = make_encrypted_packet(b'')
+        result = _packet_to_dict(pkt)
+        assert result["payload"] == ""
+
+    def test_encrypted_packet_payload_hex(self):
+        from hubblenetwork.cli import _packet_to_dict
+        raw = b'\xab\xc6\x79'
+        pkt = make_encrypted_packet(raw)
+        result = _packet_to_dict(pkt, payload_format="hex")
+        assert result["payload"] == "ABC679"
+
+    def test_decrypted_packet_payload_string(self):
+        from hubblenetwork.cli import _packet_to_dict
+        raw = b'sensor:42'
+        pkt = make_decrypted_packet(raw)
+        result = _packet_to_dict(pkt, payload_format="string")
+        assert result["payload"] == "sensor:42"
+
+    def test_decrypted_packet_payload_string_invalid_utf8(self, capsys):
+        from hubblenetwork.cli import _packet_to_dict
+        raw = b'\xff\xfe'
+        pkt = make_decrypted_packet(raw)
+        result = _packet_to_dict(pkt, payload_format="string")
+        assert result["payload"] == "<invalid UTF-8>"
+        captured = capsys.readouterr()
+        assert "Warning" in captured.err
+
+
+class TestStreamingTablePrinter:
+    """Tests for tabular payload display."""
+
+    def test_table_row_payload_is_base64(self, capsys):
+        from hubblenetwork.cli import _StreamingTablePrinter
+        raw = b'\x01\x02\x03'
+        pkt = make_decrypted_packet(raw)
+        printer = _StreamingTablePrinter()
+        printer.print_row(pkt)
+        captured = capsys.readouterr()
+        expected_b64 = base64.b64encode(raw).decode("ascii")
+        assert expected_b64 in captured.out
+
+
+class TestStreamingTablePrinterPayloadFormat:
+    """Tests for _StreamingTablePrinter with non-default payload formats."""
+
+    def test_hex_format(self, capsys):
+        from hubblenetwork.cli import _StreamingTablePrinter
+        raw = b'\xab\xc6\x79'
+        pkt = make_decrypted_packet(raw)
+        printer = _StreamingTablePrinter(payload_format="hex")
+        printer.print_row(pkt)
+        captured = capsys.readouterr()
+        assert "ABC679" in captured.out
+
+    def test_string_format_valid_utf8(self, capsys):
+        from hubblenetwork.cli import _StreamingTablePrinter
+        raw = b'sensor:42'
+        pkt = make_decrypted_packet(raw)
+        printer = _StreamingTablePrinter(payload_format="string")
+        printer.print_row(pkt)
+        captured = capsys.readouterr()
+        assert "sensor:42" in captured.out
+
+    def test_default_is_still_base64(self, capsys):
+        from hubblenetwork.cli import _StreamingTablePrinter
+        raw = b'\x01\x02\x03'
+        pkt = make_decrypted_packet(raw)
+        printer = _StreamingTablePrinter()
+        printer.print_row(pkt)
+        captured = capsys.readouterr()
+        assert base64.b64encode(raw).decode("ascii") in captured.out
+
+
+class TestStreamingJsonPrinterPayloadFormat:
+    """Tests for _StreamingJsonPrinter with non-default payload formats."""
+
+    def test_hex_format(self, capsys):
+        from hubblenetwork.cli import _StreamingJsonPrinter
+        raw = b'\xab\xc6\x79'
+        pkt = make_decrypted_packet(raw)
+        printer = _StreamingJsonPrinter(payload_format="hex")
+        printer.print_row(pkt)
+        captured = capsys.readouterr()
+        assert "ABC679" in captured.out
+
+    def test_default_is_base64(self, capsys):
+        from hubblenetwork.cli import _StreamingJsonPrinter
+        raw = b'\x01\x02\x03'
+        pkt = make_decrypted_packet(raw)
+        printer = _StreamingJsonPrinter()
+        printer.print_row(pkt)
+        captured = capsys.readouterr()
+        assert base64.b64encode(raw).decode("ascii") in captured.out
+
+
+class TestBatchPrinters:
+    """Tests for _print_packets_* functions with payload_format."""
+
+    def test_tabular_hex(self, capsys):
+        from hubblenetwork.cli import _print_packets_tabular
+        raw = b'\xab\xc6\x79'
+        pkt = make_decrypted_packet(raw)
+        _print_packets_tabular([pkt], payload_format="hex")
+        captured = capsys.readouterr()
+        assert "ABC679" in captured.out
+
+    def test_tabular_default_base64(self, capsys):
+        from hubblenetwork.cli import _print_packets_tabular
+        raw = b'\x01\x02\x03'
+        pkt = make_decrypted_packet(raw)
+        _print_packets_tabular([pkt])
+        captured = capsys.readouterr()
+        assert base64.b64encode(raw).decode("ascii") in captured.out
+
+    def test_json_hex(self, capsys):
+        from hubblenetwork.cli import _print_packets_json
+        raw = b'\xab\xc6\x79'
+        pkt = make_decrypted_packet(raw)
+        _print_packets_json([pkt], payload_format="hex")
+        captured = capsys.readouterr()
+        assert "ABC679" in captured.out
+
+    def test_csv_hex(self, capsys):
+        from hubblenetwork.cli import _print_packets_csv
+        raw = b'\xab\xc6\x79'
+        pkt = make_decrypted_packet(raw)
+        _print_packets_csv([pkt], payload_format="hex")
+        captured = capsys.readouterr()
+        assert "ABC679" in captured.out
+
+    def test_csv_string(self, capsys):
+        from hubblenetwork.cli import _print_packets_csv
+        raw = b'temp:25'
+        pkt = make_decrypted_packet(raw)
+        _print_packets_csv([pkt], payload_format="string")
+        captured = capsys.readouterr()
+        assert "temp:25" in captured.out

pyhubblenetwork-0.3.0/tests/test_counter_eid.py

@@ -0,0 +1,214 @@
+"""Tests for counter-based EID decryption (eid_pool_size parameter)."""
+
+import struct
+import pytest
+from click.testing import CliRunner
+from Crypto.Cipher import AES
+
+from hubblenetwork.crypto import (
+    _get_encryption_key,
+    _get_nonce,
+    _get_auth_tag,
+    decrypt,
+)
+from hubblenetwork.packets import EncryptedPacket, Location
+
+
+# ---------------------------------------------------------------------------
+# Helpers – build a valid BLE advertisement payload for a given counter value
+# ---------------------------------------------------------------------------
+
+def _encrypt_payload(key: bytes, counter_value: int, seq_no: int, plaintext: bytes) -> bytes:
+    """Encrypt plaintext the same way firmware does and return a BLE adv payload."""
+    keylen = len(key)
+    daily_key = _get_encryption_key(key, counter_value, seq_no, keylen=keylen)
+    nonce = _get_nonce(key, counter_value, seq_no, keylen=keylen)
+
+    cipher = AES.new(daily_key, AES.MODE_CTR, nonce=nonce)
+    ciphertext = cipher.encrypt(plaintext)
+
+    auth_tag = _get_auth_tag(daily_key, ciphertext)
+
+    # BLE adv layout: seq_no (2 big-endian) + 4 padding bytes + auth_tag (4) + ciphertext
+    seq_bytes = struct.pack(">H", seq_no & 0x3FF)
+    padding = b"\x00" * 4
+    return seq_bytes + padding + auth_tag + ciphertext
+
+
+def _make_encrypted_packet(key: bytes, counter_value: int, seq_no: int, plaintext: bytes) -> EncryptedPacket:
+    """Build an EncryptedPacket whose auth_tag matches *counter_value*."""
+    payload = _encrypt_payload(key, counter_value, seq_no, plaintext)
+    return EncryptedPacket(
+        timestamp=1700000000,
+        location=Location(lat=0.0, lon=0.0, fake=True),
+        payload=payload,
+        rssi=-70,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+# Deterministic 32-byte key (AES-256-CTR)
+_KEY_256 = bytes(range(32))
+# Deterministic 16-byte key (AES-128-CTR)
+_KEY_128 = bytes(range(16))
+
+
+# ---------------------------------------------------------------------------
+# decrypt() with eid_pool_size
+# ---------------------------------------------------------------------------
+
+class TestCounterEidDecrypt:
+    """Test decrypt() counter-based EID mode."""
+
+    def test_decrypt_finds_counter_value(self):
+        """decrypt() with eid_pool_size finds the correct counter."""
+        counter_value = 7
+        pkt = _make_encrypted_packet(_KEY_256, counter_value, seq_no=1, plaintext=b"hello")
+
+        result = decrypt(_KEY_256, pkt, eid_pool_size=32)
+
+        assert result is not None
+        assert result.payload == b"hello"
+        assert result.counter == counter_value
+
+    def test_decrypt_counter_zero(self):
+        """Counter value 0 is found."""
+        pkt = _make_encrypted_packet(_KEY_256, 0, seq_no=5, plaintext=b"zero")
+
+        result = decrypt(_KEY_256, pkt, eid_pool_size=10)
+
+        assert result is not None
+        assert result.counter == 0
+        assert result.payload == b"zero"
+
+    def test_decrypt_counter_at_pool_boundary(self):
+        """Counter value N-1 (last in pool) is found."""
+        pool_size = 16
+        pkt = _make_encrypted_packet(_KEY_128, pool_size - 1, seq_no=2, plaintext=b"edge")
+
+        result = decrypt(_KEY_128, pkt, eid_pool_size=pool_size)
+
+        assert result is not None
+        assert result.counter == pool_size - 1
+        assert result.payload == b"edge"
+
+    def test_decrypt_counter_outside_pool_returns_none(self):
+        """Counter value >= pool_size is not found."""
+        pkt = _make_encrypted_packet(_KEY_256, 50, seq_no=3, plaintext=b"miss")
+
+        result = decrypt(_KEY_256, pkt, eid_pool_size=32)
+
+        assert result is None
+
+    def test_decrypt_wrong_key_returns_none(self):
+        """Wrong key doesn't match any counter."""
+        pkt = _make_encrypted_packet(_KEY_256, 5, seq_no=1, plaintext=b"data")
+        wrong_key = bytes(range(1, 33))
+
+        result = decrypt(wrong_key, pkt, eid_pool_size=32)
+
+        assert result is None
+
+    def test_decrypt_aes128_counter_mode(self):
+        """Counter-based decryption works with AES-128 keys."""
+        pkt = _make_encrypted_packet(_KEY_128, 3, seq_no=10, plaintext=b"aes128")
+
+        result = decrypt(_KEY_128, pkt, eid_pool_size=8)
+
+        assert result is not None
+        assert result.payload == b"aes128"
+        assert result.counter == 3
+
+    def test_decrypt_preserves_packet_metadata(self):
+        """Decrypted packet retains timestamp, rssi, location, sequence."""
+        pkt = _make_encrypted_packet(_KEY_256, 2, seq_no=42, plaintext=b"meta")
+
+        result = decrypt(_KEY_256, pkt, eid_pool_size=10)
+
+        assert result is not None
+        assert result.timestamp == 1700000000
+        assert result.rssi == -70
+        assert result.sequence == 42
+
+
+# ---------------------------------------------------------------------------
+# Validation: eid_pool_size + days mutual exclusivity
+# ---------------------------------------------------------------------------
+
+class TestCounterEidValidation:
+    """Test that eid_pool_size and days are mutually exclusive."""
+
+    def test_raises_when_both_eid_pool_size_and_days_set(self):
+        pkt = _make_encrypted_packet(_KEY_256, 0, seq_no=1, plaintext=b"x")
+
+        with pytest.raises(ValueError, match="Cannot specify both"):
+            decrypt(_KEY_256, pkt, days=5, eid_pool_size=10)
+
+    def test_eid_pool_size_with_default_days_is_ok(self):
+        """eid_pool_size + days=2 (the default) should NOT raise."""
+        pkt = _make_encrypted_packet(_KEY_256, 0, seq_no=1, plaintext=b"ok")
+
+        result = decrypt(_KEY_256, pkt, days=2, eid_pool_size=10)
+        assert result is not None
+
+
+# ---------------------------------------------------------------------------
+# CLI option validation (ble scan / ble detect)
+# ---------------------------------------------------------------------------
+
+class TestCliEidPoolSizeOptions:
+    """Test --eid-pool-size CLI option validation."""
+
+    @pytest.fixture
+    def runner(self):
+        return CliRunner()
+
+    def test_scan_eid_pool_size_without_key_errors(self, runner):
+        from hubblenetwork.cli import cli
+
+        result = runner.invoke(cli, ["ble", "scan", "--eid-pool-size", "32"])
+        assert result.exit_code != 0
+        assert "requires --key" in result.output or "requires --key" in (result.exception and str(result.exception) or "")
+
+    def test_scan_eid_pool_size_with_days_errors(self, runner):
+        from hubblenetwork.cli import cli
+
+        result = runner.invoke(cli, [
+            "ble", "scan",
+            "--key", "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+            "--eid-pool-size", "32",
+            "--days", "3",
+        ])
+        assert result.exit_code != 0
+
+    def test_detect_eid_pool_size_with_days_errors(self, runner):
+        from hubblenetwork.cli import cli
+
+        result = runner.invoke(cli, [
+            "ble", "detect",
+            "--key", "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+            "--eid-pool-size", "32",
+            "--days", "3",
+        ])
+        assert result.exit_code != 0
+
+    def test_scan_help_shows_eid_pool_size(self, runner):
+        from hubblenetwork.cli import cli
+
+        result = runner.invoke(cli, ["ble", "scan", "--help"])
+        assert "--eid-pool-size" in result.output
+
+    def test_detect_help_shows_eid_pool_size(self, runner):
+        from hubblenetwork.cli import cli
+
+        result = runner.invoke(cli, ["ble", "detect", "--help"])
+        assert "--eid-pool-size" in result.output
+
+    def test_detect_help_shows_days(self, runner):
+        from hubblenetwork.cli import cli
+
+        result = runner.invoke(cli, ["ble", "detect", "--help"])
+        assert "--days" in result.output