allen/ADS-Bit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Merge pull request 'Package for public GitHub release' (#10) from chore/github-packaging into main

Browse Source
This commit is contained in:
allen
2026-06-10 10:13:54 -07:00
parent f047f82e86 bf71ba1b50
commit f081af36d8
11 changed files with 313 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/bug_report.md
+29
View File
@@ -0,0 +1,29 @@
---
name: Bug report
about: Report something that isn't working
title: "[Bug] "
labels: bug
---
**Describe the bug**
A clear description of what's wrong.
**To reproduce**
Steps to reproduce the behavior:
1. …
2. …
**Expected behavior**
What you expected to happen.
**Screenshots / logs**
If applicable, add screenshots or server log output.
**Environment**
- ADS-Bit version (admin header or `GET /api/config`):
- Install method: [ ] bare metal [ ] Docker [ ] Podman
- OS / Python version:
- Receiver / feed (e.g. dump1090, readsb) and how it's reached:
**Additional context**
Anything else that might help.
.github/ISSUE_TEMPLATE/feature_request.md
+18
View File
@@ -0,0 +1,18 @@
---
name: Feature request
about: Suggest an idea or improvement
title: "[Feature] "
labels: enhancement
---
**What problem does this solve?**
A clear description of the need or pain point.
**Proposed solution**
What you'd like to happen.
**Alternatives considered**
Any other approaches you thought about.
**Additional context**
Mockups, examples, or references.
.github/PULL_REQUEST_TEMPLATE.md
+19
View File
@@ -0,0 +1,19 @@
## Summary
<!-- What does this PR change, and why? -->
## Related issues
<!-- e.g. Closes #123 -->
## How was this tested?
<!-- Commands run, manual steps, screenshots. For Docker changes, note that
`docker build` succeeds. -->
## Checklist
- [ ] Server starts and the change works locally (`python3 server.py`)
- [ ] If admin assets changed, bumped the `?v=` cache-bust token in `admin/admin.html`
- [ ] If behavior/version changed, updated `VERSION` and `CHANGELOG.md`
- [ ] No secrets or local config committed (`config.json` stays ignored)
.github/workflows/ci.yml
+30
View File
@@ -0,0 +1,30 @@
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
python:
name: Python checks
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install dependencies
run: pip install -r requirements.txt
- name: Byte-compile server
run: python -m compileall -q server.py
- name: Validate example config is valid JSON
run: python -c "import json; json.load(open('config.json.example'))"
docker:
name: Docker build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build image
run: docker build -t ads-bit:ci .
.github/workflows/release.yml
+52
View File
@@ -0,0 +1,52 @@
name: Release
# Build and publish a multi-arch image to GitHub Container Registry (GHCR)
# whenever a version tag is pushed (e.g. v1.1.2). Lets users run a prebuilt
# image — including on Raspberry Pi (arm64) — without building locally.
on:
push:
tags: ["v*"]
permissions:
contents: read
packages: write
jobs:
image:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Compute lowercase image name
id: img
run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
- uses: docker/setup-qemu-action@v3
- uses: docker/setup-buildx-action@v3
- name: Log in to GHCR
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Docker metadata (tags & labels)
id: meta
uses: docker/metadata-action@v5
with:
images: ${{ steps.img.outputs.name }}
tags: |
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=raw,value=latest
- name: Build and push
uses: docker/build-push-action@v6
with:
context: .
platforms: linux/amd64,linux/arm64
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
.gitignore
+1
View File
@@ -15,6 +15,7 @@ __pycache__/
# Claude Code
.claude/
CLAUDE.md
# Gitea token
.gitea-token
CHANGELOG.md
+48
View File
@@ -0,0 +1,48 @@
# Changelog
All notable changes to this project are documented here. The format is based
on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
[Semantic Versioning](https://semver.org/).
## [1.1.1] - 2026-06-10
### Added
- `/health` endpoint (status, version, receiver/flight counts) plus a Docker
`HEALTHCHECK`.
- `ADSBIT_CONFIG` environment variable to override the config file path.
### Changed
- Docker first-run now works with no manual steps: `config.json` is auto-seeded
from `config.json.example` by `docker-entrypoint.sh` and persisted on a
`./data` directory mount (removing the single-file bind-mount footgun).
- Network auto-scan skips subnets larger than `/20` (e.g. a Docker bridge
`172.17.0.0/16`) so discovery no longer stalls startup on Docker hosts.
- `SIGTERM`/`SIGINT` (`docker stop`, `systemctl stop`) shut down cleanly
without a stack trace.
## [1.1.0] - 2026-06-09
### Added
- In-app pixel editor for sprites (admin → Sprites → EDIT): pencil, eraser,
color picker, fill bucket, line/rectangle/ellipse shapes, rectangular
select with move/cut/copy/paste, reference-image overlay, brush size &
opacity, custom + recent palettes, zoom/pan, grid, undo/redo.
- Receiver health dashboard: live per-receiver status (receiving / no data /
unreachable), connection testing, a select → save → apply flow, selectable
scan results, and a per-interface scan selector.
- Version surfaced at startup, via `GET /api/config`, and in the admin header.
### Fixed
- Server crash when restarting receiver connections: cancelled receiver tasks
no longer tear down the main event loop.
## [1.0] - 2026-01
### Added
- Initial release: retro SNES-style side-view ADS-B flight tracker with custom
pixel-art sprites, directional backgrounds, weather, sun/moon, admin panel,
first-run setup wizard, and Docker/Podman support.
[1.1.1]: https://github.com/OWNER/ADS-Bit/releases/tag/v1.1.1
[1.1.0]: https://github.com/OWNER/ADS-Bit/releases/tag/v1.1.0
[1.0]: https://github.com/OWNER/ADS-Bit/releases/tag/v1.0
CLAUDE.md
-159
View File
@@ -1,159 +0,0 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
ADS-Bit is a retro SNES-style side-view flight tracker that displays ADS-B aircraft data with custom pixel art sprites.
## Running the Server
```bash
# Start the server (port configured in config.json, default 2001)
python3 server.py
# Or use the startup script
./start.sh
```
Access at http://localhost:{web_port} (configured in config.json)
### Deployment / fielding notes
- **Config path** is overridable via the `ADSBIT_CONFIG` env var (defaults to `config.json` beside `server.py`). Docker uses `/app/data/config.json` on a mounted volume.
- **`/health`** (no auth) returns status/version/receiver/flight counts — used by the Docker `HEALTHCHECK` and any external monitoring.
- **`VERSION`** constant in `server.py` is the single source of truth; surfaced at startup, via `GET /api/config`, and in the admin header. Bump it for releases.
- **Auto-scan** (`scan_for_receivers`) skips subnets larger than `MIN_SCAN_PREFIX` (/20) so a docker `/16` doesn't stall startup; the manual scan endpoint enforces the same limit.
- **`docker-entrypoint.sh`** seeds `config.json` from `config.json.example` on first run, so a fresh `docker compose up` needs no manual steps. SIGTERM/SIGINT shut down cleanly (no traceback).
## Architecture
### Components
- **server.py** - Python WebSocket server using aiohttp
- Reads configuration from config.json
- Auto-scans for ADS-B receivers or connects to configured IPs
- Parses SBS/BaseStation format messages from receivers (port 30003)
- Polls dump1090 JSON API (`/dump1090/data/aircraft.json`) every 5s for ADS-B emitter categories
- Broadcasts flight data (including emitter category) to WebSocket clients every 1 second
- Cleans up flights not seen in 60 seconds
- Serves static files, admin panel, setup wizard, and APIs
- Authentication via bcrypt password hashing and session cookies
- **config.json** - Configuration file for receiver and location settings
- See CONFIG.md for full documentation
- **ads-bit.js** - JavaScript rendering engine (Canvas-based)
- Handles WebSocket connection and flight data updates
- Renders 10 FPS retro-style canvas animation
- Layer order (bottom to top): sky gradient → clouds → sun → moon → directional background → grid → aircraft → labels
- Directional backgrounds include horizon, so low sun/moon is realistically occluded
- Aircraft sprites flip horizontally when heading west (track 90°-270°)
- View direction rotates between N/E/S/W (arrow keys or A/D), changing the background
- **index.html** - Main HTML interface with embedded styles
- **admin/** - Admin panel (login + tabbed settings UI)
- Theme management: rename display names, upload per-direction background PNGs, create new themes
- Display names stored in `config.json` `theme_names` map (folder name -> display name)
- Receivers tab: live per-receiver health (via `GET /api/admin/receiver-status` and `POST /api/admin/test-receivers`), a select → SAVE & APPLY → auto-test flow, selectable scan results, and a per-interface scan selector
- Version (from `server.py` `VERSION`) is surfaced via public `GET /api/config` and shown in the admin header
- **pixel-editor.js** - In-app Canvas2D pixel editor (Sprites tab "EDIT" button)
- Edits sprites at native 500x333; tools: pencil, eraser, color picker, fill bucket, pan, line, rectangle, ellipse (outline/filled), rectangular select
- Select & move: marquee + floating layer, drag/arrow-nudge, Ctrl+C/X/V clipboard, Delete, Enter/Esc commit
- Zoom/pan, undo/redo (snapshot-per-stroke), grid overlay, brush size & opacity, retro + custom (localStorage) + recent palettes, adjustable reference-image overlay
- Exports a 500x333 PNG via `srcCanvas.toBlob` and POSTs to the existing `/api/admin/sprites/{type}` upload endpoint (no new server route)
- Keyboard: B/E/I/F/L/R/O/M tools, Space=pan, +/-/0 zoom, Ctrl+Z/Y undo/redo, Ctrl+C/X/V, arrows nudge, G grid, Esc close
- **Asset cache-busting:** `admin.html` references `admin.css`/`admin.js`/`pixel-editor.js` with a `?v=YYYYMMDD[x]` query — bump it whenever those files change so browsers reload them
- **setup/** - First-run setup wizard (multi-step configuration)
### Sprite Assets
All PNG sprites face right (eastward) and are flipped in-canvas for westbound aircraft:
- 9 aircraft types: smallProp, regionalJet, narrowBody, wideBody, heavy, helicopter, balloon, glider, uav
- Directional backgrounds: north.png, south.png, east.png, west.png (1536x1024, shown based on view direction)
- Celestial: sun.png, moon_6_phases.png (2x3 sprite sheet)
- Weather: happycloud.png (clear), raincloud.png (rain/snow)
### Aircraft Type Detection Logic
Two-tier system: real ADS-B emitter categories when available, heuristic fallback otherwise.
#### Tier 1: ADS-B Emitter Category (from dump1090 JSON API)
The server polls `http://{receiver_ip}/dump1090/data/aircraft.json` every 5 seconds. The SBS/BaseStation protocol (port 30003) does **not** include emitter category, but the dump1090/readsb JSON API exposes the raw ADS-B transponder category field. When available, this is authoritative and always preferred over heuristics.
Mapping from DO-260B emitter categories to sprite types:
| ADS-B Category | Description | Sprite |
|---|---|---|
| A1 | Light (< 15,500 lbs) | smallProp |
| A2 | Small (15,500 - 75,000 lbs) | regionalJet |
| A3 | Large (75,000 - 300,000 lbs) | narrowBody |
| A4 | High vortex large (B757) | narrowBody |
| A5 | Heavy (> 300,000 lbs) | wideBody or heavy (by altitude/speed) |
| A6 | High performance (> 5g, > 400 kts) | narrowBody |
| A7 | Rotorcraft | helicopter |
| B1 | Glider / sailplane | glider |
| B2 | Lighter-than-air | balloon |
| B4 | Skydiver drop plane | smallProp |
| B6 | UAV | uav |
Once an emitter category is received for an aircraft, it is locked in and heuristic re-evaluation is skipped.
#### Tier 2: Heuristic Fallback (when no emitter category available)
Priority order when ADS-B category is not available (some transponders don't broadcast it):
1. **Helicopter callsigns**: known operator prefixes (LFE, MED, CHP, PHI, ERA, BHS) or keywords (LIFE, MERCY, COPTER, etc.)
2. **Heavy/Wide body callsigns**: major airline ICAO prefixes (CPA, UAE, ETH, QTR, SIA, AAL, DAL, UAL, FDX, UPS, etc.) + altitude/speed thresholds
3. **Altitude/speed extremes**: altitude > 42000 ft or speed > 550 kts = heavy; > 40000 ft or > 500 kts = wideBody
4. **N-number (US GA registration)**: pattern `N` + digit + 2-4 alphanumerics = smallProp (or narrowBody if above 25000 ft)
5. **Regional airline callsigns**: SKW, RPA, ASH, PDT, CHQ, ENY, JIA, CPZ
6. **Speed/altitude heuristics**: speed < 60 + alt < 5000 = helicopter; alt < 18000 + speed < 300 = smallProp or regionalJet
7. **Altitude-only**: < 10000 ft = smallProp, < 25000 ft = regionalJet, higher = narrowBody
8. **Default**: narrowBody (re-evaluated when better data arrives)
Important: `speed=0` or `altitude=0` means data not yet received, not actual zero. The system re-categorizes when better data arrives (speed > 0 and callsign present).
### View Direction Controls
The viewer can rotate between cardinal directions (N/E/S/W), showing aircraft in a 90° field of view:
- **Keyboard**: Left/Right arrow keys or A/D keys
- **UI**: Arrow buttons on the interface
- Each direction displays a unique background image (north.png, east.png, south.png, west.png)
- Sun and moon positions are calculated based on actual azimuth and only appear when in the current field of view
### External APIs
- **Open-Meteo**: Weather and sunrise/sunset data (updates every 10 minutes)
- **ADS-B Receivers**: SBS/BaseStation protocol on port 30003 (flight data)
- **dump1090 JSON API**: `http://{receiver}/dump1090/data/aircraft.json` on port 80 (emitter categories, polled every 5s)
## Dependencies
Python packages required:
- aiohttp (web server and WebSocket)
- netifaces (network interface scanning)
- bcrypt (password hashing)
No package.json - frontend is vanilla JavaScript with no build step.
## Key Code Patterns
- Canvas version parameter on assets (`?v=36`) for cache busting
- Aircraft direction: `const isFacingLeft = flight.track > 90 && flight.track < 270`
- Moon phases use sprite sheet cropping with 2x3 grid (3 columns, 2 rows)
- Flight data stored in global `flights` dict keyed by ICAO hex code
## Debugging
```bash
# Check for running server instances
ps aux | grep server.py
# Kill all instances
pkill -9 -f server.py
# Test receiver connectivity (replace with your receiver IP)
nc -zv <receiver_ip> 30003
```
CONTRIBUTING.md
+59
View File
@@ -0,0 +1,59 @@
# Contributing to ADS-Bit
Thanks for your interest in improving ADS-Bit! Contributions of all kinds —
bug reports, features, sprites, themes, docs — are welcome.
## Development setup
ADS-Bit is a Python (aiohttp) backend with a vanilla-JavaScript frontend.
There is **no build step** for the frontend.
```bash
git clone <your-fork-url>
cd ADS-Bit
pip install -r requirements.txt # Python 3.9–3.11 recommended (see note below)
cp config.json.example config.json # optional; the setup wizard runs otherwise
python3 server.py # serves on http://localhost:2001
```
Or with Docker (no local Python needed):
```bash
docker compose up -d
```
> **Python version note:** the `netifaces` dependency can be hard to build on
> Python 3.12+. Use Python 3.9–3.11, or just use the Docker image (Python 3.11).
## Project layout
- `server.py` — aiohttp server: receiver connections, flight state, APIs, auth.
- `ads-bit.js` / `index.html` — Canvas-based retro viewer.
- `admin/` — admin panel, including the in-browser `pixel-editor.js`.
- `setup/` — first-run setup wizard.
- `images/`, `backgrounds/` — sprite and theme assets.
## Conventions
- **Frontend assets are cache-busted** via a `?v=YYYYMMDD[x]` query in
`admin/admin.html`. If you change `admin.css`, `admin.js`, or
`pixel-editor.js`, bump that token so browsers reload them.
- The `VERSION` constant in `server.py` is the single source of truth; bump it
for releases and add a `CHANGELOG.md` entry.
- Keep the retro aesthetic (Press Start 2P, blue/gold palette) for UI work.
- Match the style of surrounding code; no frontend framework or build tooling.
## Submitting changes
1. Fork and create a topic branch (`feature/…`, `fix/…`, `chore/…`).
2. Make focused commits with clear messages.
3. Verify locally: the server starts, the page loads, and your change works.
For Docker changes, confirm `docker build` succeeds.
4. Open a pull request describing what changed and how you tested it.
CI will byte-compile the server, validate `config.json.example`, and build the
Docker image on every PR.
## Reporting bugs / requesting features
Use the issue templates. For security issues, see [SECURITY.md](SECURITY.md).
README.md
+22 -2
View File
@@ -1,5 +1,11 @@
# ADS-Bit
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Release](https://img.shields.io/github/v/release/OWNER/ADS-Bit)](https://github.com/OWNER/ADS-Bit/releases)
[![CI](https://github.com/OWNER/ADS-Bit/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/ADS-Bit/actions/workflows/ci.yml)
> **Setup note:** replace `OWNER` with your GitHub username/org throughout this README (badges and image names) after creating the repository.
A retro SNES-style side-view flight tracker that displays ADS-B aircraft data with custom pixel art sprites.
![ADS-Bit Screenshot](screenshots/screenshot.png)
@@ -41,7 +47,21 @@ On first run, visit http://localhost:2001 and the setup wizard will guide you th
- [Docker](https://docs.docker.com/get-docker/) with Compose V2, **or** [Podman](https://podman.io/) with `podman-compose`
### First Run
### 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:
```bash
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/OWNER/ads-bit:latest
```
Then open http://localhost:2001 and complete the setup wizard.
### Build from source
```bash
# Build and start — no config step needed
@@ -92,7 +112,7 @@ Host networking (`network_mode: host`) is used so the server can auto-scan your
## Requirements
- Python 3.8+
- 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
SECURITY.md
+35
View File
@@ -0,0 +1,35 @@
# Security Policy
## Supported Versions
| Version | Supported |
|---------|-----------|
| 1.1.x | ✅ |
| < 1.1 | ❌ |
## Reporting a Vulnerability
Please **do not** open a public issue for security vulnerabilities.
Instead, use GitHub's private vulnerability reporting:
**Security → Report a vulnerability** on the repository.
Include as much detail as you can:
- Affected version (see the version in the admin header or `GET /api/config`)
- Steps to reproduce / proof of concept
- Impact and any suggested remediation
You can expect an acknowledgement within a few days. Please allow reasonable
time for a fix before any public disclosure.
## Security Notes for Operators
ADS-Bit is intended for trusted LANs, not direct exposure to the public
internet. If you must expose it:
- Set a strong admin password (changed from the setup default).
- Put it behind HTTPS via a reverse proxy or tunnel (e.g. Caddy, nginx,
Tailscale). The built-in server speaks plain HTTP.
- Never commit your `config.json` — it contains the admin password hash and
session secret. It is git-ignored by default; fresh installs start from
`config.json.example`.