airdash
airdash copied to clipboard
A standalone, alternative ADS-B (readsb) web frontend
AirDash
A new/experimental web frontend for showing realtime ADS-B (airplane) and AIS (ship) data.
- Screenshots
-
Quickstart
- Run directly from source
- Run from Docker (using official builds)
- Build and run from Docker
-
Configuration
- Environment variables
-
Project Status & Goals
- Goals
-
Supported Data Sources
-
readsb-proto://
(ADS-B data) -
ais-tcp://
(AIS data from a TCP stream) -
ais-serial://
(AIS data from a serial port)
-
-
The AirDash Server
- Server responsibilities
-
Server API
- Authentication
-
GET /api/entities
-
GET /api/data-sources
-
POST /api/data-sources
-
Developer instructions
- Prerequisites
-
Using the
devserver
- Directory structure
- Contributing
- Changelog
- License
Screenshots
Planes | Ships |
---|---|
![]() |
![]() |
Quickstart
Here's how you can give AirDash a spin.
Run directly from source
$ cd airdash/
$ yarn
$ export DATA_SOURCES=readsb-proto://localhost:8080,ais-tcp://localhost:10111
$ yarn devserver
Run from Docker (using official builds)
Pre-built Docker images are available for x86 and ARM (Raspberry Pi):
$ docker run --rm -i -t -p 8888:8000 -e DATA_SOURCES=ais-tcp://localhost:10111 mik3y/airdash
When run as above, the container will expose a web service on http://localhost:8888
.
Build and run from Docker
You can build and run from Docker locally, too:
$ docker build -t airdash .
$ docker run --rm -i -t -p 8888:8000 -e DATA_SOURCES=ais-tcp://localhost:10111 airdash
Configuration
Environment variables
-
DATA_SOURCES
: A comma-delimited list of data sources to connect to. See Supported Data Sources for configuration details. -
DEBUG
: Controls extra debugging logging from the server. UseDEBUG='airdash:*'
for maximum verbosity.
Project Status & Goals
Status: Alpha. Things are in rapid development and may be broken. Bug reports and feature requests are welcome, please file them here.
Goals
This project is meant to be a standalone webapp for locally visualizing and exploring ADS-B and AIS telemetry data. Why another frontend? I have a few goals (besides the main goal: have fun).
-
Support ADS-B and AIS. The ADS-B community has better frontends than the similar ship-tracking world. But the needs are so similar. I wanted to try to fix this.
-
Fresh take. The leading frontends from ADS-B are tried and true. They also make design choices that, for whatever subjective reasons, I just wasn't as attracted to. I specifically wanted to build something leveraging React.
-
Developer-friendly. It's a goal that this project is straightforward to extend and improve, and that development is decoupled from development of the underlying data sources.
Supported Data Sources
The app currently supports:
readsb-proto://
(ADS-B data)
ADS-B (aircraft) data is supported through readsb-proto. You should be running readsb-proto
somewhere on your network.
Example:
# Read from readsb-proto which is runnning locally on port 8080.
DATA_SOURCES=readsb-proto://localhost:8080
ais-tcp://
(AIS data from a TCP stream)
AIS (boat) data can be read from a TCP stream that exposes in NMEA format.
Example:
# Read AIS data from a server offering it locally on port 10111.
DATA_SOURCES=ais-tcp://localhost:10111
ais-serial://
(AIS data from a serial port)
AIS (boat) data can be read from a serial port that exposes in in NMEA format.
Example:
# Read AIS data from the local serial port
DATA_SOURCES=ais-serial:///dev/ttyS0
(Yes the three slashes in ais-serial:///
are correct; two are part of ais-serial://
, and the rest is the absolute file path /dev/ttyS0
).
Optionally, you can specify the serial port baud rate with ?baud=<rate>
.
DATA_SOURCES=ais-serial:///dev/ttyS0?baud=57600
If unspecified, baud rate will be unchanged.
Note: When running AirDash under Docker, you may need to supply the flag --device=/dev/ttyS0
to expose your serial device to Docker.
The AirDash Server
AirDash is mostly a rich, client-side web application (sometimes called a single-page application or SPA). However, it also includes a service that runs with it.
Server responsibilities
This simple server has two responsibilities:
- Run a basic HTTP server to serve up the AirDash javascript/app at the root url (e.g.
http://localhost:8000/
). - Connect and listen to (or poll) data sources, aggregating their updates and making it available to the web app, through a built-in API.
Server API
This section lists the API supported by the AirDash server.
Authentication
There is no authentication on the API. AirDash should only be used in trusted/isolated envrionments.
GET /api/entities
Get all tracked entities. The frontend polls this endpoint to keep the map view up-to-date.
Returns a map, keyed by unique entity id, with the entity data. Each entity is an object consisting of:
-
id
: The unique entitiy ID. While this value shouldn't be interpreted or relied on for other purposes, it will generally be theICAO
code (ADS-B) orMMSI
(AIS). -
type
: One of"AIS"
,"ADSB"
. -
lat
: The last seen latititude. -
lon
: The last seen longitude. -
lastUpdatedMillis
: The timestamp data from this entity was last recorded. -
adsbData
: If (and only if)type == "ADSB"
, an object containing the detailed, aggregated ADS-B data. -
aisData
: If (and only if)type == "AIS"
, an object containing the detailed, aggregated AIS data.
GET /api/data-sources
Lists all configured data sources.
Returns: A list of data source, each an object with fields:
-
id
: An opaque and unique string identifying the data source. -
type
: One of"AIS"
,"ADSB"
.
POST /api/data-sources
Dynamically add a new data source.
Request fields
-
url
: The URL of the new data source.
Response codes
-
400
: Invalid URL or data source already exists.
Response body
-
status
: The valueok
when sucessful.
Developer instructions
These notes are for folks interested in modifying or extending airdash.
Prerequisites
You'll need a recent version of nodejs, and the tool yarn. Once you have node installed, install yarn:
npm install -g yarn
Using the devserver
When you run the server using yarn devserver
instead of yarn start
, the server runs in development mode. This enables two features:
- Frontend code changes (code in
src/
) are automatically built and hot reloaded in your browser. - Backend code changes (code in
server/
) cause the devserver to reload.
Directory structure
Here is how the code is structured.
-
server/
: All code implementing the backend server. This small server application uses the Koa web framework. -
webapp/
: All code implementing the frontend. This is a React JS single page web application. -
proto/
: Data structure definitions, in Protocol Buffer format.
Both the server and the webapp depend on proto
files. However, no other code is currently shared between these applications.
Contributing
Pull requests, ideas, and improvements are welcome. Please open an issue in the issue tracker to get in touch!
Changelog
See CHANGELOG.md
.
License
All code is offered under the MIT license, unless otherwise noted. Please
see LICENSE.txt
for the full license.