Will Bradley
340 lines
9.4 KiB
Markdown
340 lines
9.4 KiB
Markdown
# 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:**
|
|
|
|
```bash
|
|
cd meshtastic-mqtt-dashboard
|
|
```
|
|
|
|
2. **Install dependencies:**
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **Configure environment variables:**
|
|
|
|
Copy the example environment file and edit it:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` with your settings:
|
|
|
|
```env
|
|
# 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:**
|
|
|
|
```bash
|
|
npm run create-user
|
|
```
|
|
|
|
Follow the prompts to create a username and password.
|
|
|
|
5. **Start the application:**
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
For development with auto-reload:
|
|
|
|
```bash
|
|
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. Select the channel (0-7)
|
|
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
|
|
|
|
### 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
|
|
|
|
## 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
|