Meshtastic Network Visualizer

A real-time network visualizer for Meshtastic mesh networks featuring force-directed graph visualization, session management, and live updates with <100ms response times.

Features

🎯 Core Features

• Force-Directed Graph: Dynamic network topology visualization (not radar/radial)
• Real-time Updates: <100ms response time for all network events
• Session Management: View only current session data, with everything archived to SQLite
• Live Animations: Node discovery fade-ins, packet flow tracers, connection pulses

📊 Visualization

• Color-coded Signal Strength:
  • 🟢 Green: Excellent (>-75dBm)
  • 🟡 Yellow: Good (-75 to -85dBm)
  • 🟠 Orange: Weak (-85 to -95dBm)
  • 🔴 Red: Poor (<-95dBm)
• Battery Status: Visual indicators for power levels
• Network Topology: Direct vs multi-hop connections
• Active Nodes Sidebar: Live list sorted by activity
• Event Ticker: Scrolling feed of network events

📡 Device Support

• RAK 4631 connected via USB-C (primary target)
• Auto-detection of Meshtastic devices
• Support for all Meshtastic hardware models

Quick Start

Prerequisites

• Python 3.8+
• Node.js 16+
• RAK 4631 or compatible Meshtastic device connected via USB-C

Installation & Running

# Clone the repository
git clone <repository-url>
cd meshtastic-visualizer

# Run the start script
./start.sh

The start script will:

1. Install Python dependencies
2. Install frontend dependencies
3. Initialize the database
4. Start the backend server (port 8000)
5. Start the frontend dev server (port 5173)

Manual Setup

If you prefer manual setup:

# Install Python dependencies
pip3 install -r requirements.txt

# Install frontend dependencies
cd frontend
npm install
cd ..

# Start backend
uvicorn backend.main:app --reload --port 8000

# In another terminal, start frontend
cd frontend
npm run dev

Usage

1. Connect your RAK 4631 via USB-C
2. Open browser at http://localhost:5173
3. Click "Connect" to connect to your device
4. Watch as nodes appear and the network forms
5. Use "New Session" to clear the display and start fresh

Controls

• Click nodes to select and view details
• Hover nodes for quick information
• Zoom/Pan the network graph
• Event ticker shows real-time activity

Architecture

Technology Stack

• Backend: FastAPI + WebSocket + Python Meshtastic API
• Frontend: React + TypeScript + Cytoscape.js (WebGPU renderer)
• Database: SQLite with session-based architecture
• Real-time: WebSocket for <100ms updates

Project Structure

meshtastic-visualizer/
├── backend/              # FastAPI server
│   ├── main.py          # Main application
│   ├── meshtastic_connector.py  # Device interface
│   ├── database.py      # SQLite operations
│   └── models.py        # Data models
├── frontend/            # React application
│   └── src/
│       ├── components/  # UI components
│       ├── services/    # WebSocket service
│       └── App.tsx      # Main app
├── requirements.txt     # Python dependencies
├── start.sh            # Startup script
└── README.md           # This file

Development

Backend Development

The backend uses FastAPI with automatic reload:

uvicorn backend.main:app --reload --port 8000

API documentation available at: http://localhost:8000/docs

Frontend Development

The frontend uses Vite for fast HMR:

cd frontend
npm run dev

Database

SQLite database is created automatically at meshtastic.db. Schema includes:

• Sessions management
• Node information and history
• Message storage
• Network topology
• Telemetry data

API Endpoints

WebSocket

• ws://localhost:8000/ws - Real-time data stream

REST API

• GET /api/session/current - Get current session
• POST /api/session/new - Start new session
• GET /api/nodes - Get active nodes
• GET /api/messages - Get recent messages
• GET /api/topology - Get network topology
• POST /api/device/connect - Connect to device
• POST /api/device/disconnect - Disconnect from device
• GET /api/device/status - Get connection status

Troubleshooting

Device Not Found

• Ensure RAK 4631 is connected via USB-C (data cable, not charge-only)
• On Linux: Add user to dialout group: sudo usermod -a -G dialout $USER
• On macOS: Check System Preferences > Security for USB permissions

Connection Issues

• Check that no other application is using the serial port
• Try specifying device path manually in the Connect dialog
• Restart the Meshtastic device

Performance

• For networks >50 nodes, ensure hardware acceleration is enabled in browser
• The WebGPU renderer will automatically activate for large networks
• Check browser console for performance warnings

Contributing

Contributions welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with a real Meshtastic device
5. Submit a pull request

License

MIT License - See LICENSE file for details

Acknowledgments

• Meshtastic project for the amazing mesh networking platform
• Cytoscape.js team for the powerful graph visualization library
• FastAPI for the high-performance Python web framework

Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Join the Meshtastic Discord community
• Check the Meshtastic documentation

---

Built with ❤️ for the Meshtastic community