mushtastic 0.1.0__py3-none-any.whl

mushtastic/__init__.py

@@ -0,0 +1,5 @@
+"""mushtastic package."""
+
+from .app import cli
+
+__all__ = ["cli"]

mushtastic/__main__.py

@@ -0,0 +1,5 @@
+from .app import cli
+
+
+if __name__ == "__main__":
+    cli()

mushtastic/app.py

@@ -0,0 +1,26 @@
+"""
+Meshtastic live logger with an interactive command prompt.
+- Archives every packet to sqlite db.
+- Lets you query nodes or send messages while it runs.
+
+This module assembles the full CLI from the rest of the package:
+`cli.py` defines the root shell group and top-level commands (`live`,
+`help`, `ble-scan`), and importing `mushtastic.commands` attaches the `node` and
+`packet` command groups to it.
+
+The REPL's `/command` tree (`mushtastic.repl_root.repl_root` +
+`mushtastic.repl_commands.*`) is a fully separate set of Click definitions -
+see README architecture notes - so it's assembled here too (imported
+for its registration side effect, same as `mushtastic.commands`), even though
+only `cli` itself needs exporting for the console-script entry point.
+
+Run via the `mush` console script (see `pyproject.toml`) or
+`python -m mushtastic` (see `__main__.py`) - this module isn't meant to
+be executed directly as a script, since it relies on relative imports.
+"""
+
+from .cli import cli
+from . import commands  # noqa: F401  (registers node/packet groups)
+from . import repl_commands  # noqa: F401  (registers REPL '/node' etc. commands)
+
+__all__ = ["cli"]

mushtastic/cli.py

@@ -0,0 +1,298 @@
+"""Root Click group plus shell-only, offline top-level commands.
+
+Radio operations and runtime debugging deliberately exist only in the REPL,
+which runs after `live` creates an interface. The `node` and `packet` command groups are defined in
+`mushtastic.commands.*` and attach themselves to the `cli` group defined here
+(imported by `mushtastic.app`, which is what actually assembles the full CLI).
+
+This is the *shell* command tree only (`mush <command>`, one-shot from
+argv). The REPL's `/<command>` tree is a fully separate set of Click
+command/group definitions under `mushtastic.repl_commands` (rooted at
+`mushtastic.repl_root.repl_root`) - see that package and the README
+architecture notes for why the two are kept independent. Both trees
+call into the same `mushtastic.services.*` functions for actual behavior, so
+a fix there benefits both sides automatically.
+"""
+
+from datetime import datetime
+from contextlib import contextmanager
+from pathlib import Path
+import json
+import threading
+
+from click_aliases import ClickAliasedGroup
+from bleak.exc import BleakError
+from meshtastic import ble_interface, serial_interface, tcp_interface
+from prompt_toolkit.patch_stdout import patch_stdout
+from prompt_toolkit.styles import Style
+from pubsub import pub
+import click
+import peewee
+from playhouse.migrate import SqliteMigrator, migrate
+
+from .colors import clr
+from .formatting import pprint
+from .history import DatabaseHistory
+from .models import Node, Packet, ReplHistory
+from .prompt import PromptMessage, bottom_toolbar
+from .radio import on_log, on_receive, wait_for_config, we_are_live
+from .repl import run_repl
+from .state import db, state
+
+
+###################
+# Root group
+###################
+
+def _close_iface(timeout=5.0):
+    """Close state.iface without letting the app hang forever.
+
+    meshtastic's BLEInterface can deadlock inside close()/disconnect()
+    (a bleak disconnected_callback re-entering close() from its own
+    asyncio event loop thread - see
+    https://github.com/meshtastic/python/issues/792, still open as of
+    meshtastic 2.7.10). Run close() in a daemon thread and give up
+    after `timeout` seconds instead of blocking the REPL exit forever;
+    the device side of the disconnect has normally already happened by
+    then, we're just waiting on the library's own bookkeeping.
+    """
+    iface = state.iface
+    if iface is None:
+        return
+    done = threading.Event()
+
+    def _do_close():
+        try:
+            iface.close()
+        finally:
+            done.set()
+
+    threading.Thread(target=_do_close, daemon=True).start()
+    if not done.wait(timeout):
+        pprint(
+            f"{clr.faint}Interface didn't close within {timeout:.0f}s "
+            f"(known meshtastic BLE bug), exiting anyway.{clr.reset}"
+        )
+
+
+def _ensure_packet_channel_column(db_obj):
+    """Add Packet.channel to databases created before the column existed."""
+    columns = {column.name for column in db_obj.get_columns(Packet._meta.table_name)}
+    if "channel" not in columns:
+        migrate(SqliteMigrator(db_obj).add_column("packet", "channel", Packet.channel))
+
+
+def _reconnect_serial_loop(stop_event, reconnecting, dev, iface_factory=None):
+    """Replace a disconnected serial interface, retrying until shutdown."""
+    iface_factory = iface_factory or serial_interface.SerialInterface
+    delay = 1
+    try:
+        while not stop_event.is_set():
+            # A reset signalled over a still-open stream is recovered by
+            # Meshtastic itself. If that recovery instead turns into a serial
+            # disconnect, stream becomes None and this loop takes over.
+            current_iface = state.iface
+            if getattr(current_iface, "stream", None) is not None:
+                if current_iface.isConnected.is_set():
+                    return
+                stop_event.wait(0.25)
+                continue
+            try:
+                iface = iface_factory(devPath=dev or None)
+                if stop_event.is_set():
+                    iface.close()
+                    return
+                # SerialInterface waits for Meshtastic config during its
+                # constructor, so myInfo is available before publishing it.
+                state.iface = iface
+                state.our_node_id = f"!{iface.myInfo.my_node_num:08x}"
+                pprint(f"{clr.faint}Radio reconnected.{clr.r}")
+                return
+            except Exception as error:
+                pprint(f"{clr.faint}Radio reconnect failed: {error}. Retrying in {delay}s.{clr.r}")
+                stop_event.wait(delay)
+                delay = min(delay * 2, 10)
+    finally:
+        reconnecting.clear()
+
+
+@contextmanager
+def _serial_reconnect_events(enabled, dev):
+    """Manage serial-radio reconnect callbacks for one live session."""
+    if not enabled:
+        yield
+        return
+
+    stop_reconnect = threading.Event()
+    reconnecting = threading.Event()
+
+    def on_connection_lost(interface):
+        if stop_reconnect.is_set() or interface is not state.iface or reconnecting.is_set():
+            return
+        reconnecting.set()
+        pprint(f"{clr.faint}Radio restarting; waiting for configuration.{clr.r}")
+        threading.Thread(
+            target=_reconnect_serial_loop,
+            args=(stop_reconnect, reconnecting, dev),
+            daemon=True,
+        ).start()
+
+    def on_connection_established(interface):
+        if stop_reconnect.is_set() or interface is not state.iface:
+            return
+        state.our_node_id = f"!{interface.myInfo.my_node_num:08x}"
+        pprint(f"{clr.faint}Radio connection established.{clr.r}")
+
+    pub.subscribe(on_connection_lost, "meshtastic.connection.lost")
+    pub.subscribe(on_connection_established, "meshtastic.connection.established")
+    try:
+        yield
+    finally:
+        stop_reconnect.set()
+        pub.unsubscribe(on_connection_lost, "meshtastic.connection.lost")
+        pub.unsubscribe(on_connection_established, "meshtastic.connection.established")
+
+
+@click.group(cls=ClickAliasedGroup, invoke_without_command=True)
+@click.version_option(None, "-v", "--version", package_name="mushtastic")
+@click.option("-d", "--debug", is_flag=True, help="Enable device debug logs.")
+@click.option("--database", type=str, help="SQLite database file path.")
+@click.option(
+    "--pos-fmt",
+    type=click.Choice(["latlon", "google", "osm"]),
+    required=False,
+    default="latlon",
+    help="Position display format.",
+)
+@click.pass_context
+def cli(ctx, debug=False, database=None, pos_fmt=None):
+    ctx.ensure_object(dict)
+    ctx.obj["db"] = db
+
+    # This callback re-runs every time a command is dispatched from the
+    # REPL loop (see repl.py), since Click re-invokes a Group's own
+    # callback whenever it dispatches to one of its subcommands. Only
+    # apply options and (re)connect the database on the very first
+    # (real, argv-driven) invocation - otherwise every REPL command
+    # would reset state.debug/position_format back to their defaults
+    # and leak a new sqlite connection on every keystroke.
+    if state.initialized:
+        return
+    if debug:
+        state.debug = True
+    state.db_path = Path("mush.db")
+    if database:
+        state.db_path = Path(database)
+    if pos_fmt:
+        state.position_format = pos_fmt
+    db_obj = peewee.SqliteDatabase(Path(state.db_path).expanduser())
+    db.initialize(db_obj)
+    db_obj.connect()
+    db_obj.create_tables([Node, Packet, ReplHistory])
+    _ensure_packet_channel_column(db_obj)
+    state.initialized = True
+
+
+@cli.command()
+@click.pass_context
+def help(ctx):
+    """Show Click's --help for the shell command tree (`mush --help`)."""
+    pprint(f"{clr.faint}{ctx.parent.command.get_help(ctx)}{clr.reset}")
+    pprint(f"{clr.faint} Use: 'command --help' with specific commands.{clr.reset}")
+
+
+@cli.command(name="ble-scan")
+def ble_scan():
+    """List nearby Meshtastic BLE devices without connecting to one."""
+    try:
+        devices = ble_interface.BLEInterface.scan()
+    except BleakError as error:
+        pprint(f"{clr.faint}BLE scan failed: {error}{clr.r}")
+        return
+
+    if not devices:
+        pprint(f"{clr.faint}No Meshtastic BLE devices found.{clr.r}")
+        return
+
+    for device in devices:
+        pprint(f"Found: name={device.name!r} address={device.address!r}")
+
+
+@cli.command(short_help="Connect to a radio and open the REPL.")
+@click.pass_context
+@click.option("--ble", type=str, help="Bluetooth device address.")
+@click.option("--tcp", type=str, help="TCP host or host:port.")
+@click.option("--dev", type=str, help="Serial device path.")
+def live(ctx: click.Context, ble=None, tcp=None, dev=None):
+    """
+    Connect to a radio and start an interactive REPL with all commands
+    loaded.
+
+    Usage: mush live [OPTIONS]
+    Options:
+        --ble   BLUETOOTH_DEVICE  - Connect to a bluetooth device.
+        --tcp   IP|URL:PORT       - Connect to TCP enabled device.
+        --dev   DEVICE_PATH       - Connect to USB attached device.
+    If no device is specified, it will try to autoconnect.
+
+    Once connected, commands are entered with a leading '/' (e.g.
+    '/node ls'). Anything typed without a leading '/' is sent as a text
+    message to the currently selected target (see '/target').
+
+    Shell-only: the radio is already live by the time the REPL prompt
+    starts, so this isn't available as a '/live' REPL command - there's
+    simply no such command in `mushtastic.repl_commands` (see that package).
+    """
+    if we_are_live():
+        raise Exception("Starting live session while we are live.")
+
+    if sum(v is not None for v in (ble, tcp, dev)) > 1:
+        raise Exception("Only 1 of the interfaces (ble,tcp,dev) can be used.")
+
+    state.iface = None
+    try:
+        if ble is not None:
+            state.iface = ble_interface.BLEInterface(address=ble or None)
+        elif tcp:
+            host, *p = tcp.split(":")
+            state.iface = tcp_interface.TCPInterface(
+                host=host, port=int(p[0]) if p else 4403)
+        else:
+            state.iface = serial_interface.SerialInterface(devPath=dev or None)
+        wait_for_config()
+    except Exception as error:
+        _close_iface()
+        state.iface = None
+        raise click.ClickException(f"Could not connect to radio: {error}") from None
+
+    state.our_node_id = f"!{state.iface.myInfo.my_node_num:08x}"
+    try:
+        us = Node.find(state.our_node_id)
+        if us.dev_metrics:
+            state.our_last_metrics = json.loads(us.dev_metrics)
+    except Packet.DoesNotExist:
+        pprint("Can't find our radio in DB yet...")
+
+    try:
+        with _serial_reconnect_events(ble is None and not tcp, dev):
+            with patch_stdout():
+                pub.subscribe(on_receive, "meshtastic.receive")
+                pub.subscribe(on_log, "meshtastic.log.line")
+                pprint(f"[{datetime.now()}] Connected to meshtastic console.")
+                style = Style.from_dict({
+                    "bottom-toolbar": "bg:#000000 bold",
+                    "packet-filter-toolbar": "#ffffff",
+                    "status-toolbar": "bg:#000000 #888888",
+                })
+                prompt_kwargs = {
+                    "history": DatabaseHistory(),
+                    "enable_history_search": True,
+                    "complete_while_typing": True,
+                    "bottom_toolbar": bottom_toolbar,
+                    "style": style,
+                    "message": PromptMessage(),
+                    }
+                pprint("Type '/' for a list of subcommands, 'ctrl+d' to exit.")
+                run_repl(prompt_kwargs)
+    finally:
+        _close_iface()

mushtastic/colors.py

@@ -0,0 +1,78 @@
+"""ANSI color/style constants used for terminal output."""
+
+
+class clr:
+    """
+    All 16 ANSI foreground colours, their 16 background counterparts,
+    plus a handful of style toggles.
+    """
+    # ───── Resets ─────────────────────────────────────────────────────────
+    reset = "\033[0m"
+    r     = reset
+    # ───── Styles ────────────────────────────────────────────────────────
+    bold       = "\033[1m"
+    faint      = "\033[2m"
+    italic     = "\033[3m"
+    underline  = "\033[4m"
+    inverse    = "\033[7m"
+    # ───── 8 standard foreground colours ────────────────────────────────
+    black   = "\033[30m"
+    red     = "\033[31m"
+    green   = "\033[32m"
+    yellow  = "\033[33m"
+    blue    = "\033[34m"
+    magenta = "\033[35m"
+    cyan    = "\033[36m"
+    white   = "\033[37m"
+    grey    = "\033[90m"
+    # ───── 8 bright foreground colours (a.k.a. “high-intensity”) ────────
+    bright_black   = "\033[90m"   # ≈ grey
+    bright_red     = "\033[91m"
+    bright_green   = "\033[92m"
+    bright_yellow  = "\033[93m"
+    bright_blue    = "\033[94m"
+    bright_magenta = "\033[95m"
+    bright_cyan    = "\033[96m"
+    bright_white   = "\033[97m"
+    # ───── 8 standard background colours ────────────────────────────────
+    black_bg   = "\033[40m"
+    red_bg     = "\033[41m"
+    green_bg   = "\033[42m"
+    yellow_bg  = "\033[43m"
+    blue_bg    = "\033[44m"
+    magenta_bg = "\033[45m"
+    cyan_bg    = "\033[46m"
+    white_bg   = "\033[47m"
+    # ───── 8 bright background colours ──────────────────────────────────
+    bright_black_bg   = "\033[100m"
+    bright_red_bg     = "\033[101m"
+    bright_green_bg   = "\033[102m"
+    bright_yellow_bg  = "\033[103m"
+    bright_blue_bg    = "\033[104m"
+    bright_magenta_bg = "\033[105m"
+    bright_cyan_bg    = "\033[106m"
+    bright_white_bg   = "\033[107m"
+
+
+def _node_color_parts(node_num):
+    """Return Meshtastic Android's RGB and contrasting foreground for a node."""
+    red = (node_num & 0xFF0000) >> 16
+    green = (node_num & 0x00FF00) >> 8
+    blue = node_num & 0x0000FF
+    brightness = (0.299 * red + 0.587 * green + 0.114 * blue) / 255
+    return red, green, blue, brightness > 0.5
+
+
+def node_text(node_num, text):
+    """Color node text using Meshtastic Android's node-number RGB mapping."""
+    red, green, blue, use_black = _node_color_parts(node_num)
+    foreground = clr.black if use_black else clr.white
+    background = f"\033[48;2;{red};{green};{blue}m"
+    return f"{background}{foreground}{text}{clr.reset}"
+
+
+def node_prompt_style(node_num):
+    """Return a prompt_toolkit style using the Android node-number colors."""
+    red, green, blue, use_black = _node_color_parts(node_num)
+    foreground = "#000000" if use_black else "#ffffff"
+    return f"bg:#{red:02x}{green:02x}{blue:02x} fg:{foreground}"

mushtastic/commands/__init__.py

@@ -0,0 +1,8 @@
+"""Command groups (`node`, `packet`) that attach themselves to
+the root `cli` group from `mushtastic.cli`.
+
+Importing this package (as `mushtastic.app` does) is what registers both
+groups - the imports below are for that side effect only.
+"""
+
+from . import node, packet  # noqa: F401

mushtastic/commands/node.py

@@ -0,0 +1,75 @@
+"""`node` command group: manage the local known-nodes table.
+
+This is the shell (`mush node ...`) side. The REPL (`/node ...`) side
+is a fully independent set of Click definitions in
+`mushtastic.repl_commands.node`; both call into `mushtastic.services.node.*` for
+actual behavior (see README architecture notes / `mushtastic.services`
+docstring).
+"""
+
+import click
+from click_aliases import ClickAliasedGroup
+
+from ..cli import cli
+from ..services import node as node_service
+
+
+@cli.group(
+    cls=ClickAliasedGroup,
+    invoke_without_command=True,
+    aliases=['n', 'nodes'],
+    short_help="Manage known nodes.",
+)
+@click.pass_context
+def node(ctx: click.Context):
+    """
+    Manipulate device/database known nodes.
+
+    Usage: node [COMMAND]
+    If used without a sub-command it will print known info about self.
+    """
+    if ctx.invoked_subcommand:
+        return
+    node_service.show_self()
+
+
+@node.command(name="list", aliases=["l", "ls"])
+@click.argument("limit", type=click.IntRange(min=1), required=False, default=100)
+def node_list(limit):
+    """
+    List recently heard known nodes.
+
+    Usage: node ls [COUNT]
+    """
+    node_service.list_nodes(limit)
+
+
+@node.command(name="rm")
+@click.argument("id", type=str, required=True)
+def node_rm(id):
+    """
+    Delete a node from the local DB.
+
+    Usage: node rm <ID>
+    """
+    node_service.rm_node(id)
+
+
+@node.command(name="show", aliases=["s", "i", "info"])
+@click.argument("name", type=str, required=True)
+def node_show(name):
+    """
+    Show known info about a node.
+
+    Usage: node show <SHORT_NAME|NODE_ID>
+    """
+    node_service.show_node(name)
+
+
+@node.command(name="count", aliases=["c"])
+def node_count():
+    """
+    Print the total number of nodes stored in the local DB.
+    Usage: node count
+    """
+    node_service.count_nodes()

mushtastic/commands/packet.py

@@ -0,0 +1,119 @@
+"""`packet` command group: query, inspect, reprocess, and import packets
+stored in the local database.
+
+This is the shell (`mush packet ...`) side. The REPL (`/packet ...`)
+side is a fully independent set of Click definitions in
+`mushtastic.repl_commands.packet`; both call into `mushtastic.services.packet.*`
+for actual behavior (see README architecture notes / `mushtastic.services`
+docstring).
+"""
+
+import click
+from click_aliases import ClickAliasedGroup
+
+from ..cli import cli
+from ..services import packet as packet_service
+
+
+@cli.group(cls=ClickAliasedGroup, aliases=['p', 'pkt', 'packets'], short_help="List stored packets.")
+@click.option("--id", type=str, help="Packet ID.")
+@click.option("--msg-id", type=int, help="Meshtastic message ID.")
+@click.option("--limit", type=int, help="Maximum number of packets.")
+@click.option("--portnum", type=str, help="Packet port number.")
+@click.option("--from-id", type=str, help="Sender node ID.")
+@click.option("--to-id", type=str, help="Recipient node ID.")
+@click.option("--id-start", type=str, help="First packet ID, inclusive.")
+@click.option("--id-end", type=str, help="Last packet ID, inclusive.")
+@click.option("--rx-time-start", type=int, help="Earliest receive timestamp.")
+@click.option("--rx-time-end", type=int, help="Latest receive timestamp.")
+@click.pass_context
+def packet(ctx: click.Context, id=None, msg_id=None, limit=None, portnum=None,
+    from_id=None, to_id=None, id_start=None, id_end=None,
+    rx_time_start=None, rx_time_end=None):
+    """
+    Print the last N packets stored in the database, with optional column
+    filters of the form field=value.
+
+    Usage:
+      packet ls <N> [field=value …]
+
+    Examples:
+      packet ls 20 # last 20 packets
+      packet --portnum=POSITION_APP ls # only position packets
+      packet ls 10 --from_id=!abcdef01 --to_id=^all
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["packets"] = packet_service.filter_packets(
+        id=id, msg_id=msg_id, limit=limit, portnum=portnum,
+        from_id=from_id, to_id=to_id, id_start=id_start, id_end=id_end,
+        rx_time_start=rx_time_start, rx_time_end=rx_time_end,
+    )
+
+
+@packet.command(name="show", aliases=["s"])
+@click.argument("id", type=str, required=False, default=None)
+@click.option("--raw", is_flag=True)
+@click.pass_context
+def packet_show(ctx, id=None, raw=False):
+    packet_service.show_packets(ctx.obj["packets"], id=id, raw=raw)
+
+
+@packet.command()
+@click.pass_context
+def process(ctx):
+    """
+    Process again one or all packets from the database.
+
+    Usage:
+    packet process ID (this is db entry ID, not msg_id)
+    packet process --all (process all db entries)
+    """
+    packet_service.process_packets(ctx.obj["packets"])
+
+
+@packet.command(name="import")
+@click.option("--merge", type=click.Choice(["append", "overwrite", "skip"],
+    case_sensitive=False), default="skip")
+def packet_import(merge="skip"):
+    packet_service.import_packet(merge=merge)
+
+
+@packet.command(name="list", aliases=["l", "ls"])
+@click.argument("limit", type=int, required=False, default=None)
+@click.pass_context
+def packet_list(ctx, limit):
+    """
+    Print the last N packets stored in the database, with optional column
+    filters of the form field=value.
+
+    Usage:
+      packet ls <N> [field=value …]
+
+    Examples:
+      packet ls 20                          # last 20 packets
+      packet ls 50 --portnum=POSITION_APP   # only position packets
+      packet ls 10 --from_id=!abcdef01 --to_id=^all
+    """
+    packet_service.list_packets(ctx.obj["packets"], limit=limit)
+
+
+@packet.command(name="portnums", aliases=["p"])
+def packet_portnums():
+    """
+    Show a count of each distinct portnum stored in the packets table.
+    Usage:  ports
+    """
+    packet_service.count_portnums()
+
+
+@packet.command(name="count", aliases=["c"])
+@click.pass_context
+def packet_count(ctx):
+    """
+    Print the number of packets in the currently filtered set.
+
+    Usage:
+      packet count                          # count of all packets
+      packet --portnum=POSITION_APP count   # count of position packets
+    """
+    packet_service.count_packets(ctx.obj["packets"])

mushtastic/decorators.py

@@ -0,0 +1,21 @@
+"""Click command decorators shared across command modules."""
+
+from functools import wraps
+import sys
+
+from .formatting import pprint
+from .radio import we_are_live
+
+
+def requires_radio(func):
+    """
+    Decorator that asserts we_are_live() before calling *func*.
+    """
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        if not we_are_live():
+            pprint("This service requires live radio.")
+            pprint("Use: 'mush live'")
+            sys.exit(1)
+        return func(*args, **kwargs)
+    return wrapper