Jean-Pierre MartineauandClaude Opus 4.8 43353f83a9 Initial commit: MeshTools with device discovery & selection
MeshTools is a Rich+Questionary interactive / Typer-scriptable toolkit for
tuning a MeshCore mesh over a serial companion device, with SQLite-logged runs
and Plotly visualizations. Includes the skeleton (trace, info, history),
TX-power optimization, and a MockDevice simulator (--mock).

Device discovery & selection:
- core/discovery.py: enumerate serial ports (pyserial), flag/sort likely LoRa
  hardware by USB vendor id, stable_id for replug-safe identity.
- core/device_store.py: remember the last successfully connected device in
  <config_dir>/devices.json (independent of --db).
- core/selection.py: non-interactive resolver (--port > profile > remembered >
  sole device > guidance error) for the CLI.
- ui/device_picker.py + menu startup: interactive picker preselecting the
  remembered default; banner reflects the choice.
- tools/devices.py: `meshtools devices` lists/marks attached devices.
- AppContext resolves the port and records last-known-good on connect success.

Fixes:
- theme.py: force UTF-8 on stdout/stderr so glyphs don't crash legacy consoles.
- connection.py: friendly message when meshcore is missing; pin meshcore>=2.3.
- trace/tx-optimize: fall back to free-text target entry when the device
  reports no contacts (autocomplete requires non-empty choices).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-20 17:02:34 -04:00

MeshTools

A modern, extensible command-line toolkit for tuning and exploring a MeshCore mesh through a serial-connected companion device.

MeshTools is interactive by default (a Rich + Questionary menu) and fully scriptable (every menu option is also a Typer subcommand). Every run is logged to SQLite and can be turned into interactive HTML visualizations.

Features

Feature Status What it does
Trace ✅ skeleton Run repeated path traces to a target and aggregate per-hop SNR.
Device info ✅ skeleton Show the connected companion device's identity and radio config.
History / DB ✅ skeleton Every tool execution and measurement is persisted and queryable.
TX-power optimization ✅ working Sweep transmit power (coarse + refine), converge on the best signal, optionally apply, render an interactive chart.
Path optimization 🚧 planned Discover and score mesh paths from neighbors outward.
Visualizations 🟡 partial Plotly TX-sweep chart (HTML) done; pyvis mesh graph + time-series planned.

Install

pip install -e ".[dev]"

Python 3.10+ is required (matching the meshcore library).

Usage

# Interactive menu (default)
meshtools

# Scripted: every menu option is also a subcommand
meshtools trace --target Alice --samples 10 --profile yagi
meshtools tx-optimize --target Alice --samples 6 --step 3 --apply
meshtools info
meshtools history

# No radio attached? Use the built-in simulator for development.
meshtools --mock trace --target Alice

Architecture

MeshTools is layered so features are added by dropping a single file in meshtools/tools/:

cli.py        Typer app; no subcommand -> interactive menu
context.py    AppContext (console, config, repository, device) dependency container
core/         Domain: models, config + device profiles, connection abstraction (+ mock)
tools/        Pluggable "menu options"; each self-registers and gets logging for free
services/     Algorithms (trace aggregation, tx search, path exploration) — no UI
persistence/  SQLite schema, repository, structured logging
ui/           Rich theme/widgets + Questionary menu
viz/          Plotly / pyvis renderers -> HTML & PNG

Adding a feature means subclassing Tool, decorating it with @register, and implementing run(). The same registry builds both the CLI and the menu, and the base class wraps every execution in a logged runs row automatically.

S
Description
No description provided
Readme Apache-2.0
21 MiB
0 Stars 1 Watchers 0 Forks
2026-11-12 14:05:38 +00:00
Languages
Python 99%
Shell 0.9%