will/meshcore-usb-dashboard
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
Will Bradley
2025-10-11 17:03:31 -07:00
commit 4767b67460
25 changed files with 5098 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+339
View File
@@ -0,0 +1,339 @@
# 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.
![Dashboard Preview](https://via.placeholder.com/800x400?text=Meshtastic+Dashboard)
## 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