root
cb387e8d12
- Add VERSION = "1.1.0" to server.py; print at startup, expose via public GET /api/config, and show it in the admin header (so deployed == released is verifiable at a glance). - Ignore config.json in .gitignore — it holds the admin password hash and session secret; fresh installs use config.json.example. - README/CLAUDE.md: document the in-app pixel editor (now with shape tools, select/move, reference overlay, custom/recent palettes), the receiver health dashboard, 9 sprite types, and the asset cache-busting convention. - Bump admin asset cache-bust to ?v=20260609d. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
167 lines
4.6 KiB
Markdown
167 lines
4.6 KiB
Markdown
# ADS-Bit
|
|
|
|
A retro SNES-style side-view flight tracker that displays ADS-B aircraft data with custom pixel art sprites.
|
|
|
|
|
|
|
|
## 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
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://gitea.chops.one/allen/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](https://docs.docker.com/get-docker/) with Compose V2, **or** [Podman](https://podman.io/) with `podman-compose`
|
|
|
|
### First Run
|
|
|
|
```bash
|
|
# Create a config file (the setup wizard runs if you skip this)
|
|
cp config.json.example config.json
|
|
|
|
# Build and start
|
|
docker compose up -d
|
|
```
|
|
|
|
The web UI is available at http://localhost:2001.
|
|
|
|
### Useful Commands
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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 |
|
|
|------|----------|
|
|
| `config.json` | Server configuration and credentials |
|
|
| `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.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.8+
|
|
- 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:
|
|
|
|
```json
|
|
{
|
|
"receivers": "AUTO",
|
|
"receiver_port": 30003,
|
|
"location": {
|
|
"name": "My Location",
|
|
"lat": 36.2788,
|
|
"lon": -115.2283
|
|
},
|
|
"web_port": 2001,
|
|
"theme": "desert"
|
|
}
|
|
```
|
|
|
|
**Important:** Set your `location.lat` and `location.lon` for accurate weather and sun/moon positioning.
|
|
|
|
See [CONFIG.md](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](CONFIG.md) for image specifications and tips.
|
|
|
|
## Running as a Service
|
|
|
|
To auto-start on boot, see the systemd service instructions in [CONFIG.md](CONFIG.md#running-as-a-service-auto-start).
|
|
|
|
## 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](LICENSE) for details.
|
|
|
|
## Credits
|
|
|
|
- Aircraft and environment sprites generated with AI assistance
|
|
- Weather data from [Open-Meteo](https://open-meteo.com/) (free, no API key required)
|