Screenshots and readme

README.md

@@ -1,133 +1,100 @@
 # Meshstream
 
-A Go application that monitors the Meshtastic MQTT server and logs packets to the terminal.
+Meshstream is a bridge between Meshtastic MQTT networks and web clients, enabling real-time monitoring and visualization of mesh network activity. The server component connects to Meshtastic MQTT servers, decodes mesh packets, and streams this data to web clients using Server Sent Events (SSE). The client-side application then aggregates and visualizes this raw data stream in various interactive views.
 
-## Setup
+Meshstream caches recent network packets on the server side, but does not persist pemanently. Client will receive some historical data upon connection. This provides immediate context and visualization even before new real-time data starts flowing.
 
-1. Clone this repository
-2. Install dependencies:
+![Meshstream Dashboard](./screenshots/dashboard.png)
 
-```
-go mod tidy
-```
+## Features
 
-## Running
+- **MQTT to SSE Bridge**: Connects Meshtastic MQTT networks to web clients using Server Sent Events
+- **Real-time Map**: Interactive map showing node locations
+- **Message Streaming**: Live view of all packets flowing reported on the MQTT topic
+- **Telemetry Monitoring**: Track device metrics like battery levels, temperatures, and signal strength
+- **Encrypted Channel Support**: Ability to decrypt private channels using pre-shared keys
+- **Node Details**: In-depth information about each node in your network
+- **Chat Activity**: View channels and text messages
 
-### Using Go directly
+![Network Map](./screenshots/map.png)
 
-```
-go run main.go
-```
+## Quick Start
 
-### Using Make
+### Using Docker (Recommended)
 
-```
-make run
-```
+The easiest way to get started:
 
-### Using Docker
+```bash
+# Clone the repository
+git clone https://github.com/your-username/meshstream.git
+cd meshstream
 
-The application can be built and run in Docker using the provided Dockerfile:
+# Configure environment variables
+cp .env.example .env
 
-```
-# Build the Docker image
-make docker-build
-
-# Run the Docker container
-make docker-run
-```
-
-Or using Docker Compose:
-
-```
+# Build and run with Docker Compose
 docker-compose up
 ```
 
-#### Docker Environment Variables and Secrets
+Then visit http://localhost:8080 in your browser.
 
-The application supports two types of environment variables:
+### Manual Setup
 
-1. **Build-time variables** - Used during the web application build (via Docker build args)
-2. **Runtime variables** - Used when the application is running
+Prerequisites:
+- Go 1.24 or later
+- Node.js 20 or later
+- pnpm (for web UI development)
 
-You can set these variables in two ways:
-
-1. **Using a `.env` file** (recommended for development and secrets):
-
-   ```
-   # Copy the sample file
-   cp .env.example .env
-   
-   # Edit with your values, especially for secrets like Google Maps API key
-   nano .env
-   
-   # Build and run with variables from .env
-   docker-compose up --build
-   ```
-
-2. **Passing variables directly** (useful for CI/CD or one-off runs):
-
-   ```
-   # Example with custom settings
-   docker run -p 8080:8080 \
-     -e MESHSTREAM_MQTT_BROKER=your-mqtt-broker.com \
-     -e MESHSTREAM_MQTT_TOPIC_PREFIX=msh/YOUR/REGION \
-     -e MESHSTREAM_SERVER_HOST=0.0.0.0 \
-     -e MESHSTREAM_STATIC_DIR=/app/static \
-     meshstream
-   ```
-
-For build-time variables (like the Google Maps API key), use Docker build arguments with the MESHSTREAM_ prefix:
-
-```
-docker build \
-  --build-arg MESHSTREAM_GOOGLE_MAPS_API_KEY=your_api_key_here \
-  --build-arg MESHSTREAM_GOOGLE_MAPS_ID=your_maps_id_here \
-  -t meshstream .
-```
-
-**Important Notes:**
-- All environment variables use the `MESHSTREAM_` prefix. 
-- The Dockerfile internally transforms build-time variables like `MESHSTREAM_GOOGLE_MAPS_API_KEY` to `VITE_GOOGLE_MAPS_API_KEY` for the web application build process.
-- Web application configuration (site title, Google Maps API key, etc.) must be set at build time. These values are compiled into the static files and cannot be changed at runtime.
-- To update web application configuration, you must rebuild the Docker image.
-
-## Decoding Meshtastic Packets
-
-This project includes the Meshtastic protocol buffer definitions in the `proto/` directory and a decoder for parsing MQTT packets. The application will automatically decode JSON messages and extract key information from binary messages.
-
-### Protocol Buffer Compilation
-
-To regenerate the protocol buffer Go code:
-
-```
+```bash
+# Install dependencies and generate protobuf code
+go mod tidy
 make gen-proto
+
+# Run the server
+make run
+
+# Run the client
+make web-run
 ```
 
-This will:
-1. Install the required protoc-gen-go compiler plugin in a local bin/ directory
-2. Generate Go code from the protocol buffer definitions
-3. Place the generated code in the proto/generated/ directory
+## Configuration
 
-### Packet Decoding
+Meshstream can be configured through environment variables, command-line flags, or a `.env` file. All configuration options use the `MESHSTREAM_` prefix.
 
-The application currently decodes packets in these formats:
+### Core Configuration
 
-1. JSON messages (from topics containing '/json/')
-   - Extracts common fields like sender, receiver, and payload
-   - Pretty-prints the JSON content
+| Environment Variable | Default | Description |
+|----------------------|---------|-------------|
+| `MESHSTREAM_MQTT_BROKER` | mqtt.bayme.sh | MQTT broker address |
+| `MESHSTREAM_MQTT_USERNAME` | meshdev | MQTT username |
+| `MESHSTREAM_MQTT_PASSWORD` | large4cats | MQTT password |
+| `MESHSTREAM_MQTT_TOPIC_PREFIX` | msh/US/bayarea | MQTT topic prefix for Meshtastic |
+| `MESHSTREAM_SERVER_HOST` | localhost | Host to bind the web server |
+| `MESHSTREAM_SERVER_PORT` | 8080 | Port for the web server |
+| `MESHSTREAM_CACHE_SIZE` | 1000 | Number of packets to cache for new client connections |
+| `MESHSTREAM_STATS_INTERVAL` | 30s | Interval for statistics reporting |
+| `MESHSTREAM_CHANNEL_KEYS` | LongFast:DefaultKey,... | Comma-separated list of channel:key pairs for decrypting private channels |
 
-2. Binary messages (from topics containing '/binary/')
-   - Shows basic topic information and a hex dump of the binary data
+> [!NOTE] 
+> Meshstream can be configured with pre-shared keys to decrypt private encrypted channels. This should only be done when channel participants have explicitly consented to having their messages monitored or when Meshstream is deployed behind an authentication gateway. Remember that decrypting private channels without consent may violate privacy expectations and potentially laws depending on your jurisdiction.
 
-3. Text messages (from topics containing '/text/')
-   - Displays the plain text content
+### Web UI Configuration (Build-time)
 
-The decoder is implemented in the `decoder` package.
+These must be set at build time (via Docker build args):
 
-## MQTT Configuration
+| Build Variable | Description |
+|----------------|-------------|
+| `MESHSTREAM_GOOGLE_MAPS_API_KEY` | Google Maps API key for map visualization |
+| `MESHSTREAM_GOOGLE_MAPS_ID` | Google Maps map ID |
+| `MESHSTREAM_SITE_TITLE` | Custom site title |
+| `MESHSTREAM_SITE_DESCRIPTION` | Custom site description |
 
-- Broker: mqtt.bayme.sh
-- Username: meshdev
-- Password: large4cats
-- Topic prefix: msh/US/CA/Motherlode
+For complete configuration options, see the Dockerfile and docker-compose.yml.
+
+![Message Stream](./screenshots/stream.png)
+
+![Node Details](./screenshots/node-details.png)
+
+## License
+
+[MIT License](./LICENSE)