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.1 — December 2025

🌐 Multi-Language Support (i18n)

• New /api/lang endpoint for serving translations
• Section-based translation loading (e.g., ?section=firehose)
• Default language controlled via config file language section
• JSON-based translation files for easy expansion
• Core pages updated to support data-translate-lang attributes

🛠 Improvements

• Updated UI elements across multiple templates for localization readiness
• General cleanup to support future language additions

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://canadaverse.org (Canadaverse)
• https://meshview.meshtastic.es (Spain)
• https://view.mtnme.sh (North Georgia / East Tennessee)
• https://meshview.lsinfra.de (Hessen - Germany)
• https://meshview.pvmesh.org (Pioneer Valley, Massachusetts)
• https://meshview.louisianamesh.org (Louisiana)
• https://www.swlamesh.com/map (Southwest Louisiana)
• https://meshview.meshcolombia.co/ (Colombia)
• https://meshview-salzburg.jmt.gr/ (Salzburg / Austria)

---

Updating from 2.x to 3.x

We are adding the use of Alembic. If using GitHub Update your codebase by running the pull command

cd meshview
git pull origin master

Install Alembic in your environment

./env/bin/pip install alembic

Start your scripts or services. This process will update your database with the latest schema.

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 =

# Select language (this represents the name of the json file in the /lang directory)
language = es

# 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.