ADS-Bit/README.md

ADS-Bit

A retro SNES-style side-view flight tracker that displays ADS-B aircraft data with custom pixel art sprites.

Screenshots

Live viewer

Real-time ADS-B traffic rendered as pixel-art sprites over a directional background — here the East view, with the Las Vegas skyline on the horizon. Aircraft are labelled with callsign, altitude, and distance, and listed in the sidebar sorted by range.

In-app pixel editor

Draw and edit aircraft sprites directly in the browser: pencil, eraser, line/rectangle/ellipse shapes, fill bucket, select & move, zoom/pan, undo/redo, custom palettes, and an adjustable reference overlay. Saving uploads the sprite back to the running tracker — no external tools needed.

Features

• Real-time aircraft tracking via ADS-B receivers
• Custom pixel art sprites for 9 aircraft types (small prop, regional jet, narrow body, wide body, heavy, helicopter, balloon, glider, UAV)
• Animated sun and moon with accurate astronomical positions
• Dynamic sky colors based on time of day
• Weather visualization with cloud sprites
• Directional view (N/E/S/W) with themed backgrounds
• Auto-discovery of ADS-B receivers on your network, with per-interface scanning
• Canvas-based 10 FPS retro rendering
• Admin panel with password authentication
• In-app pixel editor — draw and edit sprites in the browser (pencil, shapes, fill, select & move, reference overlay, custom palettes)
• Receiver health dashboard — live per-receiver status (receiving / no data / unreachable), connection testing, and select → save → apply flow
• First-run setup wizard

Quick Start

# Clone the repository
git clone https://github.com/AllenNPIT/ADS-Bit.git
cd ADS-Bit

# Install dependencies
pip install -r requirements.txt

# Start the server
python3 server.py

On first run, visit http://localhost:2001 and the setup wizard will guide you through configuration.

Docker / Podman

Prerequisites

• Docker with Compose V2, or Podman with podman-compose

Run the prebuilt image (no clone needed)

Once a release is published, a multi-arch image (amd64 + arm64, e.g. Raspberry Pi) is available from GitHub Container Registry:

docker run -d --name ads-bit --network host --restart unless-stopped \
  -e ADSBIT_CONFIG=/app/data/config.json \
  -v "$PWD/data:/app/data" \
  ghcr.io/allennpit/ads-bit:latest

Then open http://localhost:2001 and complete the setup wizard.

Build from source

# Build and start — no config step needed
docker compose up -d

A config file is created automatically in data/ on first run, then the browser setup wizard walks you through receiver, location, and password setup. The web UI is available at http://localhost:2001.

A /health endpoint (used by the container healthcheck) reports status, version, and receiver/flight counts: curl http://localhost:2001/health.

Useful Commands

# View logs
docker compose logs -f

# Stop
docker compose down

# Rebuild after a git pull
docker compose build && docker compose up -d

Podman

The same docker-compose.yml works with Podman:

podman-compose up -d

On SELinux systems (Fedora, RHEL), add :Z to each volume mount in docker-compose.yml so containers can access the bind-mounted files.

Data Persistence

The following paths are bind-mounted from the repo directory and persist across container recreation:

Path	Contents
data/	Server configuration and credentials (config.json, auto-seeded)
images/	Aircraft and UI sprites (including uploads)
backgrounds/	Theme background images (including custom themes)

Host networking (network_mode: host) is used so the server can auto-scan your LAN for ADS-B receivers. Auto-scan skips oversized subnets (larger than /20, e.g. a Docker bridge 172.17.0.0/16); if your receiver lives on such a network, set it explicitly via the admin Receivers tab.

Requirements

• Python 3.9–3.11 (3.12+ may require build tools for netifaces; the Docker image uses 3.11)
• ADS-B receiver providing SBS/BaseStation format on port 30003 (dump1090, readsb, etc.)
• Modern web browser with Canvas support

Configuration

ADS-Bit uses a first-run setup wizard to configure your installation. You can also edit config.json directly:

{
  "receivers": "AUTO",
  "receiver_port": 30003,
  "location": {
    "name": "My Location",
    "lat": 0.0,
    "lon": 0.0
  },
  "web_port": 2001,
  "theme": "desert"
}

Important: Set your location.lat and location.lon for accurate weather and sun/moon positioning.

See CONFIG.md for full configuration options including custom backgrounds and running as a service.

Controls

• Arrow Keys / A/D: Rotate view direction
• View cycles through North, East, South, West
• Click aircraft in sidebar to highlight

Aircraft Types

Type	Detection
Helicopter	Low altitude + slow speed
Heavy (747/A380)	High altitude or specific callsigns
Wide Body	Very high altitude/speed
Narrow Body	Default commercial
Regional Jet	Regional carrier callsigns or lower altitude
Small Prop	N-prefix callsigns or very low/slow

Custom Backgrounds

Create backgrounds for your location:

1. Add 4 directional images to backgrounds/custom/ (north.png, east.png, south.png, west.png)
2. Set "theme": "custom" in config.json
3. Restart the server

See CONFIG.md for image specifications and tips.

Running as a Service

To auto-start on boot, see the systemd service instructions in CONFIG.md.

Compatible Receivers

Works with any receiver providing SBS/BaseStation format on port 30003:

• dump1090 / dump1090-fa / dump1090-mutability
• readsb
• ADS-B Exchange feeders
• FlightAware PiAware
• Any SBS1 compatible receiver

License

MIT License - see LICENSE for details.

Credits

• Aircraft and environment sprites generated with AI assistance
• Weather data from Open-Meteo (free, no API key required)