diff --git a/README.md b/README.md index 99259107..250c7016 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ A modern web dashboard for monitoring and managing your [MeshCore](https://meshc Built on [pyMC_Repeater](https://github.com/rightup/pyMC_Repeater) by [RightUp](https://github.com/rightup), pyMC Console provides real-time visibility into your mesh network with an intuitive, feature-rich interface. +![Topology Analysis Overview](docs/images/analyzer-overview.gif) + ## How It All Fits Together The MeshCore Python ecosystem has three components: @@ -46,7 +48,68 @@ The MeshCore Python ecosystem has three components: - Console provides the web UI; Repeater provides the backend API and radio control - You can upgrade Console independently without touching Repeater/Core -## Features +## Feature Highlights + +### πŸ—ΊοΈ Mesh Topology Analysis + +The topology analyzer reconstructs your network's structure from packet paths using a **Viterbi HMM decoder** β€” resolving prefix collisions with physics-based constraints and observation evidence. + +![Topology Analysis](docs/images/analyzer-overview.gif) + +- **Deep Analysis** β€” One-click full topology rebuild from 75K packets +- **Viterbi HMM decoding** β€” Hidden Markov Model resolves prefix collisions using geographic distance and LoRa range constraints +- **Ghost node discovery** β€” Detects unknown repeaters when no known candidate is geographically plausible +- **3D terrain mode** β€” Real-world topographic terrain with hillshading; markers and edges drape onto the landscape +- **3D arc edges** β€” Topology edges rendered as elevated arcs via deck.gl (GPU-accelerated) +- **Edge confidence visualization** β€” Line thickness scales with observation count; color indicates certainty +- **Wardriving overlay** β€” H3 hexagonal tiles from coverage servers with SNR-based coloring + +### πŸ“‘ Link Quality Radar + +The polar chart visualizes all contacts at their actual compass bearing and distance from your node. + +![Link Quality Polar](docs/images/linkquality-demo.gif) + +- **Zero-hop neighbors** β€” Colored by SNR quality (green β†’ yellow β†’ orange β†’ red) +- **Non-neighbors** β€” Rendered at 33% opacity to distinguish direct RF contacts +- **Hover interaction** β€” Full opacity with detailed signal metrics tooltip + +### πŸ“Š Statistics Dashboard + +Comprehensive RF metrics and network composition analysis. + +![Statistics View](docs/images/statsview-expose.gif) + +- **Airtime utilization** β€” RX/TX spectrum with peak and mean metrics +- **Packet types treemap** β€” Distribution of ADVERT, TXT_MSG, ACK, RESPONSE, etc. +- **Network composition** β€” Breakdown of repeaters, companions, and room servers +- **RF noise floor** β€” Heatmap showing interference patterns over time +- **Prefix disambiguation health** β€” Confidence metrics for topology inference + +### πŸ›€οΈ Packet Path Tracing + +Click any packet to visualize its route through the mesh with hop-by-hop confidence indicators. + +![Path Trace Demo](docs/images/trace-demo.gif) + +- **Confidence coloring** β€” Green (100%), Yellow (50-99%), Orange (25-49%), Red (<25%), Gray (ghost node) +- **Interactive map** β€” Shows the resolved path with all intermediate hops +- **Signal details** β€” RSSI, SNR, and timing for each packet + +### 🎨 Themes & Terminal + +Six color schemes and a built-in terminal for direct repeater interaction. + +![Themes and Terminal](docs/images/terminal-and-themes.gif) + +- **Color schemes** β€” Seoul256, Gruvbox, Deus, Gotham, Sonokai, Kanagawa +- **Background images** β€” Multiple ambient backgrounds with adjustable brightness +- **Terminal** β€” Direct CLI access to the repeater for advanced operations +- **Live logs** β€” Stream from repeater daemon with DEBUG/INFO toggle + +--- + +## All Features ### Dashboard - **Live packet metrics** β€” Received, forwarded, dropped packets with sparkline charts @@ -55,35 +118,13 @@ The MeshCore Python ecosystem has three components: - **Time range selector** β€” View stats from 20 minutes to 7 days - **Recent packets** β€” Live feed of incoming traffic with centralized polling (every 3s) -![Dashboard](docs/images/dashboard.png) - -### Statistics -- **Airtime utilization** β€” RX/TX utilization spectrum with peak and mean metrics -- **Link quality polar** β€” Neighbor signal strength plotted by compass bearing -- **Network composition** β€” Breakdown of repeaters, companions, and room servers -- **Packet types treemap** β€” Distribution of ADVERT, TXT_MSG, ACK, RESPONSE, etc. -- **RF noise floor** β€” Noise floor heatmap showing interference patterns over time -- **Prefix disambiguation** β€” Health metrics for the topology inference system - -![Statistics](docs/images/statistics.png) - ### Contacts & Topology -- **Interactive map** β€” MapLibre GL with dark theme, neighbor positions, and smooth animations -- **3D terrain mode** β€” Toggle real-world topographic terrain with hillshading; all markers and edges drape onto the landscape -- **3D arc edges** β€” Topology edges and neighbor lines render as elevated arcs via deck.gl PathLayer (GPU-accelerated) -- **Viterbi HMM path decoding** β€” Hidden Markov Model resolves prefix collisions using physics-based transition costs and observation evidence -- **Ghost node discovery** β€” Unknown repeaters detected when no known candidate is geographically plausible; locations estimated from anchor midpoints -- **Deep Analysis** β€” One-click full topology rebuild from 75K packets with Viterbi decoding -- **Edge confidence** β€” Line thickness and opacity scale with observation count and certainty -- **Animated edges** β€” Trace-in effect on toggle, smooth fade-out +- **Interactive map** β€” MapLibre GL with dark theme, smooth animations - **Filter toggles** β€” Solo view for hub nodes, direct neighbors, or traffic-based filtering - **Loop detection** β€” Identifies redundant paths (double-line rendering) - **High-contrast markers** β€” Light fill with dark outline ensures visibility against any overlay -- **Path health panel** β€” Health scores, weakest links, and latency estimates for observed routes +- **Path health panel** β€” Health scores, weakest links, and latency estimates - **Mobile node detection** β€” Identifies volatile nodes that appear/disappear frequently -- **Wardriving coverage overlay** β€” H3 hexagonal tiles from external coverage servers (e.g., coverage.wcmesh.com) with SNR-based coloring - -![Topology Map](docs/images/topology.png) ### Packets - **Searchable history** β€” Filter by type, route, time range @@ -94,18 +135,11 @@ The MeshCore Python ecosystem has three components: - **Mode toggle** β€” Forward (repeating) or Monitor (RX only) - **Duty cycle** β€” Enable/disable enforcement - **Radio config** β€” Live frequency, power, SF, bandwidth changes -- **Theme selection** β€” Six color schemes (Seoul256, Gruvbox, Deus, Gotham, Sonokai, Kanagawa) -- **Background images** β€” Multiple ambient backgrounds with adjustable brightness - -![Settings](docs/images/settings.png) ### System & Logs - **System resources** β€” 20-minute rolling CPU and memory utilization chart - **Disk usage** β€” Storage utilization with progress bar - **Temperature** β€” Multi-sensor temperature gauges with threshold coloring -- **Live logs** β€” Stream from repeater daemon with DEBUG/INFO toggle - -![System](docs/images/system.png) ## Quick Start @@ -363,8 +397,6 @@ Before Viterbi decoding, candidates are scored using four-factor analysis inspir The system maintains up to 75,000 packets in session memory (~2.5 days at 30k/day) for comprehensive topology evidence. -![Prefix Disambiguation](docs/images/disambiguation.png) - ### Edge Rendering Topology edges are rendered with visual cues indicating confidence: diff --git a/docs/images/analyzer-overview.gif b/docs/images/analyzer-overview.gif new file mode 100644 index 00000000..2f58a3e9 Binary files /dev/null and b/docs/images/analyzer-overview.gif differ diff --git a/docs/images/dashboard.png b/docs/images/dashboard.png deleted file mode 100644 index f91ec8b3..00000000 Binary files a/docs/images/dashboard.png and /dev/null differ diff --git a/docs/images/disambiguation.png b/docs/images/disambiguation.png deleted file mode 100644 index 1df79c9f..00000000 Binary files a/docs/images/disambiguation.png and /dev/null differ diff --git a/docs/images/linkquality-demo.gif b/docs/images/linkquality-demo.gif new file mode 100644 index 00000000..cf7a9415 Binary files /dev/null and b/docs/images/linkquality-demo.gif differ diff --git a/docs/images/neighbors.png b/docs/images/neighbors.png deleted file mode 100644 index c75a7a59..00000000 Binary files a/docs/images/neighbors.png and /dev/null differ diff --git a/docs/images/settings.png b/docs/images/settings.png deleted file mode 100644 index 3d0e68da..00000000 Binary files a/docs/images/settings.png and /dev/null differ diff --git a/docs/images/statistics.png b/docs/images/statistics.png deleted file mode 100644 index 96b680a3..00000000 Binary files a/docs/images/statistics.png and /dev/null differ diff --git a/docs/images/statsview-expose.gif b/docs/images/statsview-expose.gif new file mode 100644 index 00000000..8b9b7fb3 Binary files /dev/null and b/docs/images/statsview-expose.gif differ diff --git a/docs/images/system.png b/docs/images/system.png deleted file mode 100644 index 84ba1d4c..00000000 Binary files a/docs/images/system.png and /dev/null differ diff --git a/docs/images/terminal-and-themes.gif b/docs/images/terminal-and-themes.gif new file mode 100644 index 00000000..7e3798c5 Binary files /dev/null and b/docs/images/terminal-and-themes.gif differ diff --git a/docs/images/topology.png b/docs/images/topology.png deleted file mode 100644 index 9c564d85..00000000 Binary files a/docs/images/topology.png and /dev/null differ diff --git a/docs/images/trace-demo.gif b/docs/images/trace-demo.gif new file mode 100644 index 00000000..7bb9f50a Binary files /dev/null and b/docs/images/trace-demo.gif differ