meshcore-usb-dashboard/README.md

Meshtastic MQTT Dashboard

A complete, self-contained Node.js web application for monitoring and managing Meshtastic networks via MQTT. Features real-time message tracking, GPS location mapping, node management, and automatic data retention with secure authentication.

Features

• Real-time MQTT Integration - Automatically connects to Meshtastic MQTT broker and stores all messages
• Interactive Map View - View GPS locations of all nodes on an interactive Leaflet map
• Message Management - View message history and send messages to the mesh network
• Node Monitoring - Track all nodes with detailed metadata including battery levels, signal strength, and telemetry
• Secure Authentication - Username/password login with session management
• Automatic Data Purging - Configurable cron job to automatically clean old data
• Modern UI - Responsive, modern web interface with dark theme support
• SQLite Database - All data stored locally in a SQLite database
• Comprehensive Logging - Winston-based logging for debugging and monitoring

Architecture

meshtastic-mqtt-dashboard/
├── src/
│   ├── auth/           # Authentication and authorization
│   ├── config/         # Application configuration
│   ├── database/       # SQLite database setup and queries
│   ├── mqtt/           # MQTT client and message handlers
│   ├── routes/         # Express API routes
│   ├── scripts/        # Utility scripts (user creation, etc.)
│   ├── services/       # Background services (cron jobs)
│   ├── utils/          # Utilities (logging, etc.)
│   └── server.js       # Main application entry point
├── public/
│   ├── css/            # Stylesheets
│   ├── js/             # Frontend JavaScript
│   └── index.html      # Main HTML file
├── data/               # SQLite database (auto-created)
├── logs/               # Application logs (auto-created)
├── .env                # Environment configuration
└── package.json        # Dependencies

Prerequisites

• Node.js 16.x or higher
• npm or yarn
• Access to a Meshtastic MQTT broker (default: mqtt.meshtastic.org)

Installation

1. Clone or navigate to the project directory:

cd meshtastic-mqtt-dashboard

2. Install dependencies:

npm install

3. Configure environment variables:

Copy the example environment file and edit it:

cp .env.example .env

Edit .env with your settings:

# Server Configuration
PORT=3000
NODE_ENV=production

# Session Secret (CHANGE THIS!)
SESSION_SECRET=your-random-secret-string-here

# MQTT Configuration
MQTT_BROKER=mqtt://mqtt.meshtastic.org
MQTT_PORT=1883
MQTT_USERNAME=meshdev
MQTT_PASSWORD=large4cats
MQTT_TOPIC=msh/US/#

# Data Retention (in days)
DATA_RETENTION_DAYS=30

# Cron schedule for automatic data purging (daily at 2 AM)
PURGE_CRON_SCHEDULE=0 2 * * *

# Logging
LOG_LEVEL=info

4. Create your first user:

npm run create-user

Follow the prompts to create a username and password.

5. Start the application:

npm start

For development with auto-reload:

npm run dev

6. Access the dashboard:

Open your browser and navigate to:

http://localhost:3000

Login with the username and password you created.

Configuration

MQTT Settings

The application connects to the Meshtastic MQTT broker to receive messages. Configure these settings in .env:

• MQTT_BROKER: The MQTT broker URL (default: mqtt://mqtt.meshtastic.org)
• MQTT_USERNAME: MQTT username (default: meshdev)
• MQTT_PASSWORD: MQTT password (default: large4cats)
• MQTT_TOPIC: MQTT topic to subscribe to (default: msh/US/# for all US channels)

To monitor a specific region, change the topic:

• msh/US/# - All US channels
• msh/EU/# - All EU channels
• msh/US/2/json/# - Specific channel

Data Retention

Configure automatic data purging:

• DATA_RETENTION_DAYS: Number of days to keep data (default: 30)
• PURGE_CRON_SCHEDULE: Cron schedule for purging (default: 0 2 * * * = daily at 2 AM)

You can also manually purge data from the Settings tab in the web interface.

Security

IMPORTANT: Change the SESSION_SECRET in your .env file to a random string for production use.

Usage

Dashboard Overview

The dashboard provides several tabs:

1. Overview - Statistics and recent messages at a glance
2. Map - Interactive map showing GPS locations of all nodes
3. Messages - Send and view message history
4. Nodes - View all discovered nodes and their metadata
5. Settings - Data management and application settings

Sending Messages

1. Navigate to the Messages tab
2. Type your message in the text field
3. Choose a device to send From
4. Click Send

Messages will be broadcast to the mesh network via MQTT.

Viewing Node Details

1. Navigate to the Nodes tab
2. Click on any node card to view detailed information
3. Modal will display:
   • Node ID and names
   • Hardware model and firmware version
   • Battery level and voltage
   • Signal metrics
   • Last heard timestamp

Map View

The Map tab displays GPS locations of all nodes:

• Click on markers to see node details
• Map automatically fits to show all nodes
• Click Refresh Map to update positions

Data Management

From the Settings tab:

1. Select retention period (7, 14, 30, 60, or 90 days)
2. Click Purge Old Data
3. Confirm the action

This will delete messages, positions, and telemetry older than the selected period.

API Endpoints

The application provides a REST API for programmatic access:

Authentication

• POST /api/login - Login with username/password
• POST /api/logout - Logout current session
• GET /api/auth/status - Check authentication status

Data Access

• GET /api/nodes - Get all nodes
• GET /api/nodes/:nodeId - Get specific node details
• GET /api/positions - Get latest positions for all nodes
• GET /api/positions/:nodeId - Get position history for a node
• GET /api/messages - Get recent messages
• GET /api/messages/node/:nodeId - Get messages for a specific node
• GET /api/telemetry/:nodeId - Get telemetry history for a node
• GET /api/stats - Get dashboard statistics

Actions

• POST /api/messages/send - Send a message to the mesh
• POST /api/purge - Purge old data

Status

• GET /api/mqtt/status - Get MQTT connection status

All endpoints (except login) require authentication.

Database Schema

The application uses SQLite with the following tables:

• users - User accounts for authentication
• nodes - Meshtastic node information
• positions - GPS position updates
• messages - Text messages
• telemetry - Device telemetry data
• activity_log - User activity logging

Database file location: data/meshtastic.db

Logging

Logs are stored in the logs/ directory:

• combined.log - All log messages
• error.log - Error messages only

Log level can be configured with LOG_LEVEL in .env (debug, info, warn, error).

Troubleshooting

Cannot connect to MQTT broker

1. Check your internet connection
2. Verify MQTT broker URL in .env
3. Check username/password if using a private broker
4. Review logs in logs/error.log

No data appearing

1. Verify MQTT connection (check status indicator in header)
2. Ensure MQTT topic is correct for your region
3. Check that there is active mesh traffic on the topic
4. Review logs for any error messages

Messages sent over MQTT aren't sent over the radio

1. Ensure the sending radio (node) has a channel called "mqtt"
2. Ensure the node has Uplink and Downlink enabled on both the default channel (LongFast, etc) and the mqtt channel
3. Ensure the node's setting under LoRa is "Ok to MQTT"

Database errors

1. Ensure the data/ directory is writable
2. Check disk space
3. Try deleting data/meshtastic.db and restarting (this will delete all data)

Login issues

1. Verify user was created successfully with npm run create-user
2. Check SESSION_SECRET is set in .env
3. Clear browser cookies and try again

T-Deck

• It's touch screen, which is often easier than using the trackball.
• To pair over Bluetooth, power on the T-Deck and LONG PRESS (about 2 seconds) the Meshtastic logo.
• To set the timezone properly, it should be PST8PDT,M3.2.0,M11.1.0 for PST
• To get map tiles: https://www.jeffgeerling.com/blog/2025/adding-gps-and-grid-maps-my-meshtastic-t-deck

Development

Project Structure

• Backend: Express.js server with REST API
• Frontend: Vanilla JavaScript (no frameworks)
• Database: SQLite with better-sqlite3
• MQTT: mqtt.js client
• Map: Leaflet.js for interactive maps
• Logging: Winston for structured logging
• Security: bcrypt for password hashing, express-session for sessions

Adding Features

1. New API endpoint: Add route to src/routes/api.js
2. New database table: Modify src/database/db.js and src/database/queries.js
3. MQTT message handler: Update src/mqtt/client.js
4. Frontend UI: Modify public/index.html, public/css/style.css, and public/js/app.js

Contributing

Contributions are welcome! Please ensure:

1. Code follows existing style conventions
2. All features are properly documented
3. Security best practices are followed
4. No sensitive data in commits

Security Considerations

• Change default SESSION_SECRET in production
• Use HTTPS in production (configure reverse proxy)
• Regularly update dependencies
• Review and limit access to MQTT credentials
• Use strong passwords for user accounts
• Enable firewall rules to restrict access

License

MIT License

Support

For issues and feature requests, please open an issue on the project repository.

Acknowledgments

• Meshtastic project for the excellent mesh networking platform
• OpenStreetMap for map tiles
• All contributors and testers

---

Version: 1.0.0 Author: Meshtastic Community Last Updated: 2025