Meshview

The project serves as a real-time monitoring and diagnostic tool for the Meshtastic mesh network. It provides detailed insights into network activity, including message traffic, node positions, and telemetry data.

Version 3.0.0 update - November 2025

Major Infrastructure Improvements:

• Database Migrations: Alembic integration for safe schema upgrades and database versioning
• Automated Backups: Independent database backup system with gzip compression (separate from cleanup)
• Development Tools: Quick setup script (setup-dev.sh) with pre-commit hooks for code quality
• Docker Support: Pre-built containers now available on GitHub Container Registry with automatic builds - ogarcia

New Features:

• Traceroute Return Path: Log and display return path data for traceroute packets - jschrempp
• Microsecond Timestamps: Added import_time_us columns for higher precision time tracking

Technical Improvements:

• Migration from manual SQL to Alembic-managed schema
• Container images use uv for faster dependency installation
• Python 3.13 support with slim Debian-based images
• Documentation collection in docs/ directory
• API routes moved to separate modules for better organization
• /version and /health endpoints added for monitoring

See README-Docker.md for container deployment and docs/ for technical documentation.

Version 2.0.7 update - September 2025

• New database maintenance capability to automatically keep a specific number of days of data.
• Added configuration for update intervals for both the Live Map and the Firehose pages.

Version 2.0.6 update - August 2025

• New Live Map (Shows packet feed live)
• New API /api/config (See API documentation)
• New API /api/edges (See API documentation)
• Adds edges to the map (click to see traceroute and neighbours)

Version 2.0.4 update - August 2025

• New statistic page with more data.
• New API /api/stats (See API documentation).
• Inprovement on "See Everything" and "Conversation" pages.
• Tracking of replies with links to original message.

Version 2.0.3 update - June 2025

• Moved more graphs to eCharts.
• Addedd smooth updating for "Conversations" and "See everything" sections.
• Now you can turn on and off "Quick Links".
• Network graphs are now dynamically generated depending on your mesh and the presets in use.
• Download node's packet information for the last 3 days to .csv file.
• Display distance traveled by packet.

Key Features

• Live Data Visualization: Users can view real-time data from the mesh network, including text messages, GPS positions, and node information.

• Interactive Map: The site offers an interactive map displaying the locations of active nodes, helping users identify network coverage areas.

• Mesh Graphs: Visual representations of the network's structure and connectivity are available, illustrating how nodes are interconnected.

• Packet Analysis: Detailed information on individual data packets transmitted within the network can be accessed, including payload content and transmission paths.

• Node Statistics: Users can explore statistics related to network traffic, such as top contributors and message volumes.

Samples of currently running instances:

• https://meshview.bayme.sh (SF Bay Area)
• https://www.svme.sh (Sacramento Valley)
• https://meshview.nyme.sh (New York)
• https://meshview.socalmesh.org (LA Area)
• https://map.wpamesh.net (Western Pennsylvania)
• https://meshview.chicagolandmesh.org (Chicago)
• https://meshview.mt.gt (Canadaverse)
• https://meshview.meshtastic.es (Spain)
• https://view.mtnme.sh (North Georgia / East Tennessee)
• https://meshview.lsinfra.de (Hessen - Germany)
• https://map.nswmesh.au (Sydney - Australia)
• https://meshview.pvmesh.org (Pioneer Valley, Massachusetts)
• https://meshview.louisianamesh.org (Louisiana)
• https://meshview.meshcolombia.co/ (Colombia)
• https://meshview-salzburg.jmt.gr/ (Salzburg / Austria)

---

Installing

Using Docker (Recommended)

The easiest way to run MeshView is using Docker. Pre-built images are available from GitHub Container Registry.

See README-Docker.md for complete Docker installation and usage instructions.

Manual Installation

Requires python3.13 or above.

Clone the repo from GitHub:

git clone https://github.com/pablorevilla-meshtastic/meshview.git
cd meshview

Quick Setup (Recommended)

Run the development setup script:

./setup-dev.sh

This will:

• Create Python virtual environment
• Install all requirements
• Install development tools (pre-commit, pytest)
• Set up pre-commit hooks for code formatting
• Create config.ini from sample

Manual Setup

Create a Python virtual environment:

python3 -m venv env

Install the environment requirements:

./env/bin/pip install -r requirements.txt

Install graphviz on MacOS or Debian/Ubuntu Linux:

sudo apt-get install graphviz

Copy sample.config.ini to config.ini:

cp sample.config.ini config.ini

Edit config.ini to match your MQTT and web server settings:

nano config.ini

Note

On MacOS set the bind configuration line to

bind = 127.0.0.1

Example:

# -------------------------
# Server Configuration
# -------------------------
[server]
# The address to bind the server to. Use * to listen on all interfaces.
bind = *

# Port to run the web server on.
port = 8081

# Path to TLS certificate (leave blank to disable HTTPS).
tls_cert =

# Path for the ACME challenge if using Let's Encrypt.
acme_challenge =


# -------------------------
# Site Appearance & Behavior
# -------------------------
[site]
# The domain name of your site.
domain =

# Site title to show in the browser title bar and headers.
title = Bay Area Mesh

# A brief message shown on the homepage.
message = Real time data from around the bay area and beyond.

# Starting URL when loading the index page.
starting = /chat

# Enable or disable site features (as strings: "True" or "False").
nodes = True
conversations = True
everything = True
graphs = True
stats = True
net = True
map = True
top = True

# Map boundaries (used for the map view).
# Defaults will show the San Francisco Bay Area
map_top_left_lat = 39
map_top_left_lon = -123
map_bottom_right_lat = 36
map_bottom_right_lon = -121

# Updates intervals in seconds, zero or negative number means no updates
# defaults will be 3 seconds
map_interval=3
firehose_interval=3

# Weekly net details
weekly_net_message = Weekly Mesh check-in. We will keep it open on every Wednesday from 5:00pm for checkins. The message format should be (LONG NAME) - (CITY YOU ARE IN) #BayMeshNet.
net_tag = #BayMeshNet

# -------------------------
# MQTT Broker Configuration
# -------------------------
[mqtt]
# MQTT server hostname or IP.
server = mqtt.bayme.sh

# Topics to subscribe to (as JSON-like list, but still a string).
topics = ["msh/US/bayarea/#", "msh/US/CA/mrymesh/#", "msh/US/CA/sacvalley"]

# Port used by MQTT (typically 1883 for unencrypted).
port = 1883

# MQTT username and password.
username = meshdev
password = large4cats


# -------------------------
# Database Configuration
# -------------------------
[database]
# SQLAlchemy connection string. This one uses SQLite with asyncio support.
connection_string = sqlite+aiosqlite:///packets.db


# -------------------------
# Database Cleanup Configuration
# -------------------------
[cleanup]
# Enable or disable daily cleanup
enabled = False
# Number of days to keep records in the database
days_to_keep = 14
# Time to run daily cleanup (24-hour format)
hour = 2
minute = 00
# Run VACUUM after cleanup
vacuum = False


# -------------------------
# Logging Configuration
# -------------------------
[logging]
# Enable or disable HTTP access logs from the web server
# When disabled, request logs like "GET /api/chat" will not appear
# Application logs (errors, startup messages, etc.) are unaffected
# Set to True to enable, False to disable (default: False)
access_log = False
# Database cleanup logfile location
db_cleanup_logfile = dbcleanup.log

---

Running Meshview

Start the database manager:

./env/bin/python startdb.py

Start the web server:

./env/bin/python main.py

Note

You can specify a custom config file with the --config flag:

./env/bin/python startdb.py --config /path/to/config.ini
./env/bin/python main.py --config /path/to/config.ini

Open in your browser: http://localhost:8081/

---

Running Meshview with mvrun.py

• mvrun.py starts both startdb.py and main.py in separate threads and merges the output.
• It accepts several command-line arguments for flexible deployment.

./env/bin/python mvrun.py

Command-line options:

• --config CONFIG - Path to the configuration file (default: config.ini)
• --pid_dir PID_DIR - Directory for PID files (default: .)
• --py_exec PY_EXEC - Path to the Python executable (default: ./env/bin/python)

Examples:

# Use a specific config file
./env/bin/python mvrun.py --config /etc/meshview/config.ini

# Store PID files in a specific directory
./env/bin/python mvrun.py --pid_dir /var/run/meshview

# Use a different Python executable
./env/bin/python mvrun.py --py_exec /usr/bin/python3

---

Setting Up Systemd Services (Ubuntu)

To run Meshview automatically on boot, create systemd services for startdb.py and main.py.

Note

You need to change the "User" and "/path/to/meshview" for your instance of the code on each service.

1. Service for startdb.py

Create:

sudo nano /etc/systemd/system/meshview-db.service

Paste:

[Unit]
Description=Meshview Database Initializer
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/meshview
ExecStart=/path/to/meshview/env/bin/python /path/to/meshview/startdb.py --config /path/to/meshview/config.ini
Restart=always
RestartSec=5
User=yourusername

[Install]
WantedBy=multi-user.target

2. Service for main.py

Create:

sudo nano /etc/systemd/system/meshview-web.service

Paste:

[Unit]
Description=Meshview Web Server
After=network.target meshview-db.service

[Service]
Type=simple
WorkingDirectory=/path/to/meshview
ExecStart=/path/to/meshview/env/bin/python /path/to/meshview/main.py --config /path/to/meshview/config.ini
Restart=always
RestartSec=5
User=yourusername

[Install]
WantedBy=multi-user.target

3. Enable and start the services

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable meshview-db
sudo systemctl enable meshview-web
sudo systemctl start meshview-db
sudo systemctl start meshview-web

4. Check status

systemctl status meshview-db
systemctl status meshview-web

TIP
After editing .service files, always run:

sudo systemctl daemon-reload

5. Database Maintenance

Database maintnance can now be done via the script itself here is the section from the configuration file.

• Simple to setup
• It will not drop any packets

# -------------------------
# Database Cleanup Configuration
# -------------------------
[cleanup]
# Enable or disable daily cleanup
enabled = False
# Number of days to keep records in the database
days_to_keep = 14
# Time to run daily cleanup (24-hour format)
hour = 2
minute = 00
# Run VACUUM after cleanup
vacuum = False

# -------------------------
# Logging Configuration
# -------------------------
[logging]
# Enable or disable HTTP access logs from the web server
access_log = False
# Database cleanup logfile location
db_cleanup_logfile = dbcleanup.log

Once changes are done you need to restart the script for changes to load.

Alternatively we can do it via your OS

• Create and save bash script below. (Modify /path/to/file/ to the correct path)
• Name it cleanup.sh
• Make it executable.

 #!/bin/bash

DB_FILE="/path/to/file/packets.db"


# Stop DB service
sudo systemctl stop meshview-db.service
sudo systemctl stop meshview-web.service

sleep 5
echo "Run cleanup..."
# Run cleanup queries
sqlite3 "$DB_FILE" <<EOF 
DELETE FROM packet WHERE import_time < datetime('now', '-14 day');
DELETE FROM packet_seen WHERE import_time < datetime('now', '-14 day');
DELETE FROM traceroute WHERE import_time < datetime('now', '-14 day');
DELETE FROM node WHERE last_update < datetime('now', '-14 day') OR last_update IS NULL OR last_update = '';
VACUUM;
EOF

# Start DB service
sudo systemctl start meshview-db.service
sudo systemctl start meshview-web.service

echo "Database cleanup completed on $(date)"

• Schedule running the script on a regular basis.
• In this example it runs every night at 2:00am.

Open scheduler:

sudo crontab -e

Add schedule to the bottom of the file (modify /path/to/file/ to the correct path):

0 2 * * * /path/to/file/cleanup.sh >> /path/to/file/cleanup.log 2>&1

Check the log file to see it the script run at the specific time.

---

Testing

MeshView includes a test suite using pytest. For detailed testing documentation, see README-testing.md.

Quick start:

./env/bin/pytest tests/test_api_simple.py -v

---

Technical Documentation

For more detailed technical documentation including database migrations, architecture details, and advanced topics, see the docs/ directory.