Firefly

A real-time web-based chat application for Meshtastic mesh networks. Features node discovery, profile management, and persistent message storage with an intuitive web interface.

Features

Real-time Chat: Send and receive messages instantly across the Meshtastic network
Meshtastic Integration: Connect to Meshtastic mesh networks via UDP multicast
Node Discovery: Automatically discover and track nodes on the mesh network
User Profiles: Create, edit, and manage multiple Meshtastic profiles
Database Storage: Persistent storage of seen nodes and message history per profile
Web Interface: Clean, responsive web interface built with Bootstrap
Real-time Updates: WebSocket integration for instant message and node discovery
Detailed Node Information: View hardware details, roles, and connection statistics

Requirements

Native Installation

Python 3.7+
Modern web browser with WebSocket support
Local network access

Docker Installation (Recommended)

Docker and Docker Compose
Modern web browser with WebSocket support
Local network access

Installation

Option 1: Docker (Recommended)

The easiest way to run Firefly is using Docker:

Clone the repository

git clone https://github.com/pdxlocations/firefly.git
cd firefly

Optional: Configure environment

cp .env.example .env
# Edit .env file if you want to customize settings

Build and run with Docker Compose
```
docker-compose up --build
```
Access the application
- In the default Docker bridge setup, open http://localhost:5011
- If you switch Compose to Linux host networking, use http://YOUR_IP:5011
- The application will be ready to use!

Option 2: Native Python Installation

Clone or download this project

git clone https://github.com/pdxlocations/firefly.git
cd firefly

Create a virtual environment (recommended)

python3 -m venv .venv
source .venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies
```
pip install -r requirements.txt
```

Usage

Starting the Application

Docker Method (Recommended)

Start the application
```
docker-compose up
```
Use docker-compose up -d to run in the background.
Open your web browser
- Navigate to http://localhost:5011
- Or access from other devices on the network using your computer's IP address: http://YOUR_IP:5011

Native Python Method

Run the application

Option A: With automatic virtual environment handling
```
python start_with_venv.py
```
This script validates the active interpreter and starts the application.

Option B: Manual start
```
python start.py
```
You can also run app.py directly for testing, but start.py is the recommended entry point.
Open your web browser
- Navigate to http://localhost:5011
- Or access from other devices on the network using your computer's IP address: http://YOUR_IP:5011

Using the Application

Create a Meshtastic Profile
- Go to the "Profiles" page
- Click "Create New Profile"
- Fill in your Meshtastic node details:
  - Node ID: Your Meshtastic node ID (e.g., !deadbeef)
  - Long Name: Full display name for your node
  - Short Name: Short identifier (4 chars max)
  - Channel: Meshtastic channel name
  - Key: Encryption key for the channel
- Click "Create Profile"
Select Your Profile
- Return to the "Chat" page
- Select your profile from the dropdown
- Click "Set Profile"
Start Using the Network
- Chat: Type messages to communicate with other nodes
- View Nodes: Check the "Nodes" page to see discovered mesh nodes
- Monitor Activity: Watch real-time updates as nodes join and send messages

Multiple Instances

To chat with others on your network:

Each person should run the application on their device
Everyone should be connected to the same local network
Each person needs to create their own profile
Messages will be automatically shared between all running instances

Pages and Features

Chat Page

Real-time messaging with other Meshtastic nodes
Profile selection and management
Connection status monitoring
Channel, DM, and node inbox views in one interface

Nodes Page

Comprehensive list of all discovered mesh nodes
Detailed node information including:
- Hardware model and role
- First/last seen timestamps
- Packet counts and signal information
- MAC addresses and public keys
Interactive node details modal
Statistics overview

Profiles Page

Create, edit, and delete Meshtastic profiles
Configure node ID, names, channel, and encryption key
Switch between different profiles

Configuration

Docker Configuration

Configure Firefly using environment variables in .env file:

FIREFLY_HOST: Bind address for the Flask server inside the container (default: 0.0.0.0)
FIREFLY_PORT: Application port inside the container (default: 5011)
FIREFLY_WEB_PORT: Published host port in docker-compose.yml (default: 5011)
FIREFLY_UDP_PORT: UDP multicast port (default: 4403)
FIREFLY_DATABASE_FILE: SQLite database path (Docker default: /app/data/mudpchat.db)
FIREFLY_SECRET_KEY: Flask secret key (change in production!)
FIREFLY_DEBUG: Enable debug mode (default: false)
NETWORK_MODE: Set by docker-compose.yml to match bridge vs host networking for startup messages

Native Installation Configuration

Native runs use the same application defaults without Docker:

FIREFLY_HOST: Flask bind address (default: 0.0.0.0)
FIREFLY_PORT: Web interface port (default: 5011)
FIREFLY_DATABASE_FILE: SQLite database path (default: firefly.db)
FIREFLY_UDP_PORT: UDP multicast port (default: 4403)
FIREFLY_MCAST_GRP: Multicast group address (default: 224.0.0.69)

Network Requirements

Connection to a Meshtastic network via UDP multicast
UDP multicast port 4403 must be available and not blocked by firewalls
For best results, ensure your network allows UDP multicast traffic
Compatible with MUDP (Meshtastic UDP) protocol implementations

File Structure

firefly/
├── .env.example       # Example Docker environment overrides
├── DOCKER.md          # Docker-specific setup and troubleshooting
├── Dockerfile         # Container image definition
├── app.py              # Main Flask application
├── database.py         # Database models and operations
├── docker-compose.yml  # Local Docker orchestration
├── encryption.py       # Meshtastic encryption/decryption
├── requirements.txt    # Python dependencies
├── start.py            # Primary startup entry point
├── start_with_venv.py  # Interpreter validation helper
├── templates/
│   ├── auth.html      # Login and account creation
│   ├── base.html      # Shared layout and mobile navigation
│   └── index.html     # Single-page app for chat, nodes, map, and profiles
└── static/
    ├── css/
    │   └── style.css  # Custom styles
    └── images/
        ├── firefly-logo-dark.png   # Logo for dark theme
        └── firefly-logo-light.png  # Logo for light theme

Docker Management

Useful Docker Commands

# View logs
docker-compose logs -f

# Restart the application
docker-compose restart

# Stop the application
docker-compose down

# Update and rebuild
docker-compose up --build

# Access container shell
docker-compose exec firefly /bin/bash

Data Persistence (Docker)

Application data is stored in Docker volume firefly_data
Database and profiles persist between container restarts

To backup data:

docker run --rm -v firefly_data:/data -v $(pwd):/backup alpine tar czf /backup/firefly-backup.tar.gz -C /data .

Troubleshooting

Docker Issues

Container Won't Start

Check logs: docker-compose logs firefly
Verify port availability: netstat -tulpn | grep :5011
Check disk space: df -h

UDP Communication Issues (Docker)

Verify UDP port 4403 is not blocked by firewall
Test UDP connectivity: nc -u localhost 4403
Check Meshtastic device configuration
Ensure Docker container can access host network for UDP multicast

General Issues

Port Already in Use

If you get a "port already in use" error:

Docker: Change FIREFLY_WEB_PORT in .env file
Native: Change the MCAST_PORT in app.py to a different number
Restart the application
Make sure all users use the same port number

No Messages Received

Check that all devices are on the same network
Verify that UDP port 4403 is not blocked by firewall
Try disabling firewall temporarily for testing
Check that the application is running on all devices
Docker: Ensure container networking allows UDP multicast

Firefly

Install / Use

README

Firefly

Features

Requirements

Native Installation

Docker Installation (Recommended)

Installation

Option 1: Docker (Recommended)

Option 2: Native Python Installation

Usage

Starting the Application

Docker Method (Recommended)

Native Python Method

Using the Application

Multiple Instances

Pages and Features

Chat Page

Nodes Page

Profiles Page

Configuration

Docker Configuration

Native Installation Configuration

Network Requirements

File Structure

Docker Management

Useful Docker Commands

Data Persistence (Docker)

Troubleshooting

Docker Issues

Container Won't Start

UDP Communication Issues (Docker)

General Issues

Port Already in Use

No Messages Received

Web Interfa