meshmap 0.1.0__py3-none-any.whl

meshmap/__init__.py

@@ -0,0 +1,15 @@
+"""meshmap - A tool to scan and map meshcore network graphs."""
+
+from meshmap import crypto, decoder, models
+from meshmap.scanner import MeshScanner
+from meshmap.sniffer import PacketSniffer
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MeshScanner",
+    "PacketSniffer",
+    "models",
+    "decoder",
+    "crypto",
+]

meshmap/cli/__init__.py

@@ -0,0 +1,128 @@
+"""Command-line interface for meshmap using Click."""
+
+import asyncio
+import sys
+from pathlib import Path
+
+import click
+
+from .contacts import all_contacts
+from .discover_repeaters import discover_repeaters
+from .explore import explore
+from .export_key import export_key
+from .get_neighbours import get_neighbours_cmd
+from .guest_login import guest_login
+from .rf_discover import rf_discovery
+from .scan import scan, scan_zero_hop
+from .sniff import sniff
+
+
+def _load_sniff_keys(keyfiles: tuple) -> list[dict[str, str]]:
+    """Validate and load private key files for packet decryption."""
+    private_keys = []
+    for keyfile in keyfiles:
+        try:
+            key_hex = Path(keyfile).read_text().strip()
+        except Exception as exc:
+            raise click.BadParameter(f"Cannot read key file {keyfile}: {exc}") from exc
+
+        if len(key_hex) != 128 or not all(c in "0123456789abcdefABCDEF" for c in key_hex):
+            raise click.BadParameter(
+                f"{keyfile}: expected 128 hex characters (64-byte Ed25519 key), "
+                f"got {len(key_hex)} characters"
+            )
+        private_keys.append({"hex": key_hex, "file": str(keyfile)})
+    return private_keys
+
+
+@click.group(invoke_without_command=True)
+@click.option(
+    "--serial-port",
+    "-p",
+    required=True,
+    type=str,
+    help="Serial port to connect to (e.g., /dev/ttyUSB0 or COM3)",
+)
+@click.option(
+    "--debug/--no-debug", "-d", default=False, help="Enable low-level debug logging from meshcore"
+)
+@click.option(
+    "--verbose/--no-verbose", "-v", default=False, help="Print progress messages to stderr"
+)
+@click.option("--baudrate", "-b", default=115200, type=int, help="Serial port baud rate")
+@click.option(
+    "--sniff",
+    "sniff_active",
+    is_flag=True,
+    default=False,
+    help="Print RF packets in real-time while the command runs.",
+)
+@click.option(
+    "--sniff-key",
+    "sniff_keyfiles",
+    multiple=True,
+    type=click.Path(exists=True, path_type=Path),
+    help="Private key file for packet decryption (can be repeated).",
+)
+@click.pass_context
+def cli(
+    ctx,
+    serial_port: str,
+    debug: bool,
+    verbose: bool,
+    baudrate: int,
+    sniff_active: bool,
+    sniff_keyfiles: tuple,
+) -> None:
+    """Scan and map meshcore network graphs.
+
+    By default, scans for 0-hop nodes. Use subcommands for other operations.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["serial_port"] = serial_port
+    ctx.obj["debug"] = debug
+    ctx.obj["verbose"] = verbose
+    ctx.obj["baudrate"] = baudrate
+    ctx.obj["sniff_active"] = sniff_active
+    ctx.obj["sniff_keys"] = _load_sniff_keys(sniff_keyfiles) if sniff_keyfiles else []
+
+    if ctx.invoked_subcommand is None:
+        asyncio.run(
+            scan_zero_hop(
+                serial_port,
+                debug,
+                baudrate,
+                verbose=False,
+                sniff_active=sniff_active,
+                sniff_keys=ctx.obj["sniff_keys"],
+            )
+        )
+
+
+cli.add_command(scan)
+cli.add_command(all_contacts, name="contacts")
+cli.add_command(discover_repeaters, name="discover-repeaters")
+cli.add_command(explore)
+cli.add_command(get_neighbours_cmd, name="get-neighbours")
+cli.add_command(guest_login, name="guest-login")
+cli.add_command(rf_discovery, name="rf-discover")
+cli.add_command(sniff)
+cli.add_command(export_key, name="export-key")
+
+
+def main() -> int:
+    """Main entry point for the meshmap CLI."""
+    try:
+        cli(obj={})
+        return 0
+    except SystemExit as e:
+        return e.code if isinstance(e.code, int) else 0
+    except Exception:
+        import traceback
+
+        traceback.print_exc()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

meshmap/cli/contacts.py

@@ -0,0 +1,117 @@
+"""Contacts command - show all known contacts."""
+
+import asyncio
+import json
+import sys
+from datetime import UTC, datetime
+from typing import Any
+
+import click
+import yaml
+from rich.console import Console
+from rich.table import Table
+
+from meshmap.scanner import MeshScanner
+
+
+@click.command()
+@click.pass_context
+@click.option(
+    "--output",
+    "-o",
+    type=click.Choice(["table", "json", "yaml"], case_sensitive=False),
+    default="table",
+    show_default=True,
+    help="Output format.",
+)
+def all_contacts(ctx, output: str):
+    """Show all contacts (including unknown paths)."""
+    asyncio.run(
+        show_all_contacts(
+            ctx.obj["serial_port"],
+            ctx.obj["debug"],
+            ctx.obj["baudrate"],
+            output,
+            ctx.obj.get("sniff_active", False),
+            ctx.obj.get("sniff_keys", []),
+        )
+    )
+
+
+async def show_all_contacts(
+    serial_port: str,
+    debug: bool,
+    baudrate: int,
+    output: str,
+    sniff_active: bool = False,
+    sniff_keys: list | None = None,
+) -> None:
+    """Show all contacts."""
+    try:
+        scanner = MeshScanner(serial_port, debug=debug)
+        await scanner.connect()
+
+        if sniff_active:
+            await scanner.start_sniff(sniff_keys or [])
+
+        contacts = await scanner.get_all_contacts()
+
+        if output == "json":
+            click.echo(json.dumps(contacts, indent=2, sort_keys=True))
+        elif output == "yaml":
+            click.echo(yaml.dump(contacts, allow_unicode=True, sort_keys=True), nl=False)
+        else:
+            _print_contacts_table(contacts)
+
+        await scanner.disconnect()
+
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+def _print_contacts_table(contacts: dict[str, Any]) -> None:
+    """Render contacts as a rich table."""
+    console = Console()
+
+    table = Table(title=f"Contacts ({len(contacts)} total)", show_lines=False)
+    table.add_column("Name", style="bold cyan", no_wrap=True)
+    table.add_column("Public Key", style="dim")
+    table.add_column("Type", justify="center")
+    table.add_column("Path Len", justify="right")
+    table.add_column("Lat", justify="right")
+    table.add_column("Lon", justify="right")
+    table.add_column("Last Advert", style="dim")
+
+    def _path_sort_key(kv: tuple) -> int:
+        v = kv[1].get("out_path_len")
+        if v is None or v == -1:
+            return 1000
+        return v
+
+    sorted_contacts = sorted(contacts.items(), key=_path_sort_key)
+
+    for pubkey, contact in sorted_contacts:
+        name = contact.get("adv_name") or ""
+        ctype = contact.get("type", 0)
+        type_label = {1: "contact", 2: "repeater", 3: "chatroom"}.get(ctype, str(ctype))
+        path_len = contact.get("out_path_len")
+        path_str = "flood" if path_len == -1 else (str(path_len) if path_len is not None else "")
+        lat = contact.get("adv_lat")
+        lon = contact.get("adv_lon")
+        lat_str = f"{lat:.5f}" if lat is not None else ""
+        lon_str = f"{lon:.5f}" if lon is not None else ""
+        ts = contact.get("last_advert")
+        last_advert = datetime.fromtimestamp(ts, tz=UTC).strftime("%Y-%m-%d %H:%M:%S") if ts else ""
+
+        table.add_row(
+            name,
+            f"{pubkey[:16]}…",
+            type_label,
+            path_str,
+            lat_str,
+            lon_str,
+            str(last_advert),
+        )
+
+    console.print(table)

meshmap/cli/discover_repeaters.py

@@ -0,0 +1,137 @@
+"""discover-repeaters command - find 0-hop repeaters via active node discovery."""
+
+import asyncio
+import json
+import sys
+from datetime import UTC, datetime
+from typing import Any
+
+import click
+import yaml
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from meshmap.models import snr_color
+from meshmap.scanner import MeshScanner
+
+
+@click.command()
+@click.pass_context
+@click.option(
+    "--output",
+    "-o",
+    type=click.Choice(["table", "json", "yaml"], case_sensitive=False),
+    default="table",
+    show_default=True,
+    help="Output format.",
+)
+@click.option(
+    "--wait",
+    "-w",
+    default=10,
+    show_default=True,
+    type=int,
+    help="Seconds to listen for discovery responses.",
+)
+def discover_repeaters(ctx, output: str, wait: int):
+    """Discover repeaters reachable at 0 hops (directly connected).
+
+    Sends a NODE_DISCOVER_REQ control packet and collects responses from
+    nearby repeaters for WAIT seconds.
+    """
+    asyncio.run(
+        _discover_repeaters(
+            ctx.obj["serial_port"],
+            ctx.obj["debug"],
+            ctx.obj["baudrate"],
+            output,
+            wait,
+            ctx.obj.get("sniff_active", False),
+            ctx.obj.get("sniff_keys", []),
+        )
+    )
+
+
+async def _discover_repeaters(
+    serial_port: str,
+    debug: bool,
+    baudrate: int,
+    output: str,
+    wait: int,
+    sniff_active: bool = False,
+    sniff_keys: list | None = None,
+) -> None:
+    try:
+        scanner = MeshScanner(serial_port, debug=debug)
+        await scanner.connect()
+
+        # Load contacts first so the sniffer attaches instantly (no blocking
+        # ensure_contacts call inside attach()) and is active before we send
+        # the discovery request.
+        await scanner.get_all_contacts()
+
+        if sniff_active:
+            await scanner.start_sniff(sniff_keys or [])
+
+        repeaters = await scanner.discover_zero_hop_repeaters(wait_time=wait)
+
+        if output == "json":
+            click.echo(json.dumps(repeaters, indent=2))
+        elif output == "yaml":
+            click.echo(yaml.dump(repeaters, allow_unicode=True), nl=False)
+        else:
+            _print_table(repeaters)
+
+        await scanner.disconnect()
+
+    except KeyboardInterrupt:
+        click.echo("\nInterrupted.")
+        sys.exit(130)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        if debug:
+            import traceback
+
+            traceback.print_exc()
+        sys.exit(1)
+
+
+def _print_table(repeaters: list[dict[str, Any]]) -> None:
+    console = Console()
+    table = Table(title=f"0-hop repeaters ({len(repeaters)} found)", show_lines=False)
+    table.add_column("Name", style="bold cyan", no_wrap=True)
+    table.add_column("Public Key", style="dim")
+    table.add_column("SNR", justify="right", no_wrap=True)
+    table.add_column("Lat", justify="right")
+    table.add_column("Lon", justify="right")
+    table.add_column("Last Advert", style="dim")
+
+    repeaters_sorted = sorted(
+        repeaters,
+        key=lambda r: r.get("snr") or float("-inf"),
+        reverse=True,
+    )
+
+    for node in repeaters_sorted:
+        lat = node.get("lat")
+        lon = node.get("lon")
+        ts = node.get("last_advert")
+        last_advert = datetime.fromtimestamp(ts, tz=UTC).strftime("%Y-%m-%d %H:%M:%S") if ts else ""
+        snr = node.get("snr")
+        if snr is not None:
+            sc = snr_color(snr)
+            snr_cell = Text(f"{snr:+.1f} dB", style=sc)
+        else:
+            snr_cell = Text("—", style="dim")
+
+        table.add_row(
+            node.get("name") or "",
+            f"{node['public_key'][:16]}…",
+            snr_cell,
+            f"{lat:.5f}" if lat is not None else "",
+            f"{lon:.5f}" if lon is not None else "",
+            last_advert,
+        )
+
+    console.print(table)