balena ads b
v1.2.0
ADS-B Flight Tracker running on balena with support for FlightAware, Flightradar24, Plane Finder, OpenSky Network, AirNav RadarBox, ADSB Exchange, Wingbits, adsb.fi, ADSB.lol, ADS-B One, airplanes.live, Planespotters.net, TheAirTraffic, AvDelphi, HP Radar, RadarPlane and Fly Italy ADSB.
Contribute to the flight tracking community! Feed your local ADS-B data from an RTL-SDR USB dongle (or various other radio types) and a supported device (see below) running balenaOS to the tracking services FlightAware, Flightradar24, Plane Finder, OpenSky Network, AirNav RadarBox, ADSB Exchange, Wingbits, adsb.fi, ADSB.lol, ADS-B One airplanes.live, Planespotters.net, TheAirTraffic, AvDelphi, HP Radar, RadarPlane and Fly Italy ADSB. In return, you can receive complimentary premium accounts (or cryptocurrency tokens) worth several hundred dollars annually!
? Subscribe to our newsletter ?? to stay updated on the latest development of balena ADS-B Flight Tracker.
Ask a question in our discussion board
✏️ Create a post in our balena forum thread
Raise an issue on GitHub
Watch the videos from the balena IoT Happy Hour in March 2021 and from balena Hackathon in October 2021
? Reach out directly
? Read past newsletters
| Device | |
|---|---|
| Intel NUC | |
| Nvidia Jetson Nano SD-CARD | |
| Orange Pi Zero | |
| Raspberry Pi 3 Model B+ | |
| Raspberry Pi 3 (using 64bit OS) | |
| Raspberry Pi 4 (using 64bit OS) | |
| Raspberry Pi 400 | |
| Raspberry Pi 5 |
Please let us know if you are successfully running balena-ads-b on a hardware platform not listed here!
This software defaults to using an RTL-SDR radio device. However, it is also compatible with Mode-S Beast, bladeRF, HackRF, LimeSDR, and SoapySDR. Below, you can find more information on configuring these device types in the Using different radio device types section.
The balena-ads-b project was created by Ketil Moland Olsen. It is now maintained as a team effort by Ketil, Aaron Shaw (shawaj), and Teko012.
The project was inspired by and has borrowed code from the following repos and forum threads:
Thanks to compujuckel, Glenn Stewart, wercsy, mikenye, abcd567a and marcelstoer for sharing!
Thanks to garethhowell for implementing the initial ADSB Exchange support and to wiedehopf for improving it.
Thanks to rmorillo24 for verifying balenaFin compatibility, to adaptive for confirming Raspberry Pi 400 compatibility, and to eagleDiego for confirming Orange Pi Zero compability.
Thanks to schubydoo for assistance in keeping the repository up to date.
Thanks to Teko012 for modernising the repo, keeping it up to date, and suggesting several improvements.
Thanks to schubydoo, JPGMC, and alanb128 for beta testing the UAT support.
And thanks to Aaron Shaw (shawaj) for implementing Wingbits and Mode-S Beast support, fixing bugs, and improving the code.
You are all stars! ?
Software packages downloaded, installed, and configured by the balena-ads-b script are disclosed in CREDITS.md.
We'll build the receiver using the parts that are outlined on the Flightradar24, FlightAware, and RadarBox websites:
These sites suggest the Raspberry Pi 3 Model B+ as the preferred device. Still, this project runs on all the devices mentioned above. Suppose you are buying a new appliance specifically for this project. In that case, we suggest the Raspberry Pi 4 Model B with as much memory as possible. It's excellent value for money.
In addition to the device, you will need an RTL-SDR-compatible USB dongle. The dongles are based on a digital television tuner, and numerous types will work – both generic TV sticks and specialized ADS-B sticks (produced by FlightAware). Although both options work, the ADS-B sticks seem to perform a little better.
If you live in the US, and want to track UAT traffic in addition to ADS-B traffic, you can use two dongles in parallell. Please note that the blue FlightAware USB devices should only be used for ADS-B traffic, as they have an integrated filter optimized explicitly for the 1090 MHz frequencies. The orange FlightAware USB devices work well for tracking UAT traffic. See Part 10 – Configure UAT (Optional and US only) for more details.
or
wifi-connect container will create a network with a captive portal to connect to a local WiFi network. The SSID for the created hotspot is balenaWiFi, and the password isbalenaWiFi. When connected, visit http://192.168.42.1:8181/ in your web browser to set up the connection.LAT (Receiver Latitude), e.g. with a value such as 60.12345 and LON (Receiver Longitude), e.g. with a value such as 4.12345.ALT. If you need to find the altitude, you can find it using one of several online services. Remember to add the approximate number of corresponding meters if your antenna is mounted above ground level.balena login. Then follow the instructions on the screen.git clone [email protected]:ketilmo/balena-ads-b.git. If you want to make changes to the repo, you can also fork it.cd balena-ads-b.balena push YOUR–FLEET–NAME–HERE.\ \ >/7 _.-(6' (=___._/` ) | / / | / > / j < _ _.-' : ``. r=._ `. <`\_ .`-. r-7 `-. ._ ' . ` `, `-.`7 7) ) / | ' / `-._ || .' \ ( > > ,.-' >.' <.'_.'' <'
If you have previously set up a standalone FlightAware receiver and want to port it to balena, you only have to do the following steps:
FLIGHTAWARE_FEEDER_ID, then paste your Unique Identifier key, e.g. 134cdg7d-7533-5gd4-d31d-r31r52g63v12. The ID can be found on the FlightAware website's My ADS-B section.If you have not previously set up a FlightAware receiver that you want to reuse, do the following steps:
/getid.sh (including the leading slash), then press return.FLIGHTAWARE_FEEDER_ID and paste the value from the previous step, e.g. 134cdg7d-7533-5gd4-d31d-r31r52g63v12.FLIGHTAWARE_FEEDER_ID.)ALT variable in part 1.If you have previously set up a Flightradar24 receiver and want to port it to balena, you only have to do the following steps:
FR24_KEY and paste the value of your existing Flightradar24 key, e.g. dv4rrt2g122g7233. The key is located in the Flightradar24 config file, usually found here: /etc/fr24feed.ini. (If you cannot locate your old key, retrieve or create a new one by following the steps in alternative B.)If you have not previously set up a Flightradar24 receiver that you want to reuse, do the following steps:
fr24feed --signup.yes at the next prompt. If you have restricted bandwidth, consider leaving it off by typing no.LAT variable in part 1.LON variable in part 1.ALT variable in part 1 by 3.28.yes to continue.4 for ModeS Beast.1 for network connection.dump1090-fa.30005.no to disable the RAW data feed on port 30334.no to disable the BaseStation data feed on port 30003.0 to disable log file writing.cat /etc/fr24feed.ini. Your Flightradar24 settings will be displayed.fr24key=, and copy the string between the quotes. It will look something like this: dv4rrt2g122g7233.FR24_KEY and paste the value from the previous step, e.g. dv4rrt2g122g7233.If you have previously set up a Plane Finder receiver and want to port it to balena, you only have to do the following steps:
PLANEFINDER_SHARECODE and paste the value of your existing Plane Finder key, e.g. 7e3q8n45wq369. You can find your key at Plane Finder's Your Receivers page.If you have not previously set up a Plane Finder receiver that you want to reuse, do the following steps:
pfclient, then press return.192.168.2.35 - if there is more than one IP address, any of them should work. Click the button next to the IP address to copy it to the clipboard.LAT variable in part 2. For Receiver Lon, use the value from the LON variable. Lastly, click the Create new sharecode button. A sharecode should appear in a few seconds. It should look similar to 6g34asr1gvvx7. Copy it to your clipboard. Disregard the rest of the form – you don't have to fill this out.PLANEFINDER_SHARECODE and paste the value of the Plane Finder key you just created, e.g. 7e3q8n45wq369.If you have previously set up an OpenSky Network receiver and want to port it to balena, you only have to do the following steps:
OPENSKY_USERNAME and paste your OpenSky Network username, e.g. JohnDoe123. You can find your username on your OpenSky Network Dashboard page.OPENSKY_SERIAL and paste the value of your existing OpenSky Network serial number, e.g. 1663421823. You can find your serial on your OpenSky Network Dashboard page.If you have not previously set up an OpenSky Network receiver that you want to reuse, do the following steps:
OPENSKY_USERNAME and populate it with your newly created OpenSky Username, e.g. JohnDoe123./getserial.sh (including the leading slash), then press return.OPENSKY_SERIAL and paste the value from the previous step, e.g. 1267385439.If you have previously set up a RadarBox receiver and want to port it to Balena, you only have to do the following steps:
RADARBOX_KEY and paste the value of your existing RadarBox key, e.g. 546b69e69b4671a742b82b10c674cdc1. To get your key, issue the following command at your current RadarBox device: sudo rbfeeder --showkey --no-start.If you have not previously set up a RadarBox receiver that you want to reuse, do the following steps:
/showkey.sh. Your RadarBox key will be displayed and look similar to this: 546b69e69b4671a742b82b10c674cdc1.RADARBOX_KEY and paste the value from step 5, e.g. 546b69e69b4671a742b82b10c674cdc1.546b69e69b4671a742b82b10c674cdc1.LAT and LON variables. When asked for the antenna's altitude, specify it in meters (or feet) above the ground – NOT above sea level, as done previously. If you are not asked to enter this information, you can do it manually by clicking the Edit link under your receiver's ID on the left-hand side of the screen./usr/local/share/adsbexchange-stats/create-uuid.sh followed by return. Your ADSB-Exchange UUID is displayed. Note it down./create-sitename.sh followed by return. Enter a friendly name for your feeder as per the instructions on the screen (e.g. your location). Hit return and note down the result.ADSB_EXCHANGE_UUID with the value from step 2.ADSB_EXCHANGE_SITENAME with the value from step 3.This project supports a number of ADSB Exchange clones that arose after the sale of ADSB Exchange. Currently there is support for adsb.fi, ADSB.lol, ADS-B One, airplanes.live, Planespotters.net, TheAirTraffic, AvDelphi, HP Radar, RadarPlane and Fly Italy ADSB. If you would like any new services adding, please create a PR adding the new service or if you do not know how then please open an issue with your request.
For these services, you currently do not need any login or API credentials so there is no need to make an account with them (although some of them do offer this) and no credentials to add in balenaCloud. However, you do have to selectively enable each service (or you can enable all of them, or all but ADSB Exchange).
To enable all services, or all services apart from ADSB Exchange, you can use one of the following Device Variables:
ADSB_EXCHANGE_ENABLE_ALL=trueADSB_EXCHANGE_ENABLE_ALL_BUT_ADSBX=trueNote that you can use true, enable, enabled, 1, y, yes or on for the value, and capitalisation does not matter. If you use ADSB_EXCHANGE_ENABLE_ALL this will enable ADSB Exchange and you will then need to add the ADSB_EXCHANGE_UUID and ADSB_EXCHANGE_SITENAME as described in the section above.
To enable a single service, you would need to add a Device Variable with one of the following value (or several if you want to enable multiple services):
ADSB_EXCHANGE_ENABLE=true (you also need to add the ADSB_EXCHANGE_UUID and ADSB_EXCHANGE_SITENAME as described in the section above.ADSB_FI_ENABLE=trueADSB_LOL_ENABLE=trueADSB_ONE_ENABLE=trueAIRPLANES_LIVE_ENABLE=truePLANESPOTTERS_ENABLE=trueTHE_AIR_TRAFFIC_ENABLE=trueAV_DELPHI_ENABLE=trueHPRADAR_ENABLE=trueRADARPLANE_ENABLE=trueFLY_ITALY_ADSB_ENABLE=trueLastly, these services all require a UUID to be passed to identify devices in their system. If you have set an ADSB_EXCHANGE_UUID the same UUID will be used for all services. If you do not have ADSB Exchange enabled and the ADSB_EXCHANGE_UUID variable set, the system will automatically generate one for you. However, if you would like, you can also set a UUID manually using the Device Variable with name UUID and with a UUID as a value (e.g. 2ddf6698-ea34-4c39-bbce-a8c3ddaf9bbd). You can use an online UUID generator to generate one should you want to.
If you have previously set up a Wingbits receiver and want to port it to Balena, you only have to do the following steps:
WINGBITS_DEVICE_ID and paste the value of your existing Wingbits ID, e.g. small-coral-spider. To get your ID, visit the Wingbits Dashboard, make sure you are on the Antennas tab and look in the ID column.If you have not previously set up a Wingbits receiver that you want to reuse, do the following steps:
small-coral-spider.WINGBITS_DEVICE_ID and paste the value from step 4, e.g. small-coral-spider.Online with a green background. If you hover over this with your mouse you should see a tooltip text pop-up that says the last time data was receive e.g. Last message: 22/11/2023, 03:17:40.Please note: The following instructions involve making low-level changes to RTL-SDR USB sticks, such as changing the serial numbers. Proceed with caution, and only if you are comfortable with the steps involved. All changes made are at your own risk.
In the United States, aircraft can use either the ADS-B standard, which transmits at a frequency of 1090 MHz or the UAT protocol, which transmits at 978 MHz. If you live in the US and have an extra RTL-SDR dongle, you can track the UAT and ADS-B traffic. Please note that the blue FlightAware USB devices should only be used for ADS-B traffic, as they have an integrated filter optimized explicitly for the 1090 MHz frequencies. The orange FlightAware USB devices work well for tracking UAT traffic.
DISABLED_SERVICES and populate it with the values dump1090-fa,dump978-fa./add-serial-1090.sh, then press return.YES, followed by return, to change your dongle's serial number. Verify that the process completes successfully.DUMP1090_DEVICE and set its value to 00001090./add-serial-978.sh, then press return.YES, followed by return, to change your dongle's serial number. Verify that the process completes successfully.DUMP978_DEVICE and set its value to 00000978.DISABLED_SERVICES variable.UAT_ENABLED and assign it the value true.balena also produces a project that can be easily configured to display a webpage in kiosk mode on a digital display called balenaDash. By dropping that project into this one, we can automatically display a feeder page directly from the Pi. We can then set a LAUNCH_URL device variable configured to connect to http://{{YOURIP or YOURSERVICENAME}}:YOURSERVICEPORT (where the service/port is one of the frontends above, like http://planefinder:30053) and that will automatically be displayed on the attached display. The balenaDash service can be configured locally by accessing the webserver on port 8081.
If the setup goes well, you should feed flight traffic data to several online services. You will receive access to the providers' premium services in return for your efforts. But in addition to this, you can explore the data straight from your device, raw and unedited. And that's part of the magic, right?
When you have local network access to your receiver, you can explore the data straight from the source. Start by opening your device page in the balena console and locate the IP ADDRESS field, e.g. 10.0.0.10. Then, add the desired port numbers specified further below.
Away from your local network but still eager to know what planes are cruising over your home? Here, balena's built-in Public Device URL comes in handy. Open your device page in the balena console, locate the PUBLIC DEVICE URL header, and flip the switch below to enable it. Finally, click on the arrow icon next to the button, add the desired URL postfix specified below and voila – you should see what's going on in your area.
Dump1090's Radar View
This view visualizes everything that your receiver sees, including multilaterated plane positions. When you are in your local network, head to YOURIP:8080 to check it out. When remote, open balena's Public Device URL and add /skyaware/ to the tail end of the URL, e.g. https://6g31f15653bwt4y251b18c1daf4qw164.balena-devices.com/skyaware/
Plane Finder's Radar View
It's similar to Dump1090, but Plane Finder adds 3D visualization and other excellent viewing options. Head to YOURIP:30053 to check it out. When remote, open balena's Public Device URL and add /planefinder/ to the tail end of the URL, e.g. https://6g31f15653bwt4y251b18c1daf4qw164.balena-devices.com/planefinder/
Flightradar24 Status Page
Less visual than the two other options, Flightradar24's status page gives you high-level statistics and metrics about your feeder's performance. Head to YOURIP:8754 to check it out. When remote, open balena's Public Device URL and add /fr24feed/ to the tail end of the URL, e.g. https://6g31f15653bwt4y251b18c1daf4qw164.balena-devices.com/fr24feed/
Dump978's Radar View (Optional and US only)
If you live in the US and have configuered UAT feeding, you can explore the data using this view. When you are in your local network, head to YOURIP:8978 to check it out. When remote, open balena's Public Device URL and add /skyaware978/ to the tail end of the URL, e.g. https://6g31f15653bwt4y251b18c1daf4qw164.balena-devices.com/skyaware978/. However, keep in mind that UAT traffic is scarce. It might take several days before you see any traffic, depending on where in the US you are situated.
You can disable any of the balena-ads-b services by creating a Device Variable named DISABLED_SERVICES with the services you want to disable as comma-separated values. For example, if you want to disable the dump1090fa service, you set the DISABLED_SERVICES variable to dump1090fa. If you want to disable the dump1090fa and piaware services, you set the DISABLED_SERVICES variable to dump1090fa, piaware.
With balena-ads-b you are able to use a variety of SDRs (software defined radios) and other devices such as the FPGA based Mode-S Beast. The default operating mode is to use an RTL-SDR over USB and no additional configuration is needed for this setup.
If you are using a Mode-S Beast, bladeRF, HackRF, LimeSDR or SoapySDR then you will need to configure this for the device to work as intended.
In order to configure the particular device type you are using, you need to create a Device Variable named RADIO_DEVICE_TYPE. The possible values are below:
For example if you have a Mode-S Beast, you set the RADIO_DEVICE_TYPE variable to modesbeast. Remember to save the device variable settings after you have updated them. Your device should restart automatically once you configure this and the radio should now work.
The dump1090-fa service can be configured to adapt the tuner gain to changing conditions automatically. You can read more about how this works at FlightAware's website.
From FlightAware's documentation: The dynamic range adaptive gain mode attempts to set the receiver gain to maintain a given dynamic range - that is, it tries to set the gain so that general noise is at or below a given level.
This mode is enabled by default. If you specify the antenna gain manually (see below), it will be deactivated. You can manually disable this mode by setting a Device Variable named DUMP1090_ADAPTIVE_DYNAMIC_RANGE with the value false.
From FlightAware's documentation: The "burst" adaptive gain mode listens for loud bursts of signal that were not successfully decoded as ADS-B messages, but which have approximately the right timing to be possible messages that were lost due to receiver overloading. When enough overly-loud signals are heard in a short period of time, dump1090 will reduce the receiver gain to try to allow them to be received.
This mode is disabled by default. You can enable it by setting a Device Variable named DUMP1090_ADAPTIVE_BURST with the value true.
For this mode to work optimally, you should adjust loud and quiet ranges. You do this by creating two Device Variables named DUMP1090_ADAPTIVE_BURST_LOUD_RATE and DUMP1090_ADAPTIVE_BURST_QUIET_RATE, with the desired loud- and quiet targets as their values.
From FlightAware's documentation: If you know in advance approximately what the gain setting should be, so you want to allow adaptive gain to change the gain only within a certain range, you can set minimum and maximum gain settings in dB. Adaptive gain will only adjust the gain within this range.
You can specify the target maximum and minimum gain by creating two Device Variables named DUMP1090_ADAPTIVE_MIN_GAIN and DUMP1090_ADAPTIVE_MAX_GAIN, with the desired maximum- and minimum gain as their values.
From FlightAware's documentation: The measurements needed to adjust gain have a CPU cost, and on slower devices it may be useful to reduce the amount of work that adaptive gain does. This can be done by adjusting the adaptive gain duty cycle. This is a percentage that controls what fraction of incoming data adaptive gain inspects. 100% means that every sample is inspected. Lower values reduce CPU use, with a tradeoff that adaptive gain has a less accurate picture of the RF environment. The default duty cycle is 50% on "fast" CPUs and 10% on "slow" CPUs (where currently "slow" means "armv6 architecture", for example the Pi Zero or Pi 1).
You can reduce the duty cycle further by creating a Device Variable named DUMP1090_SLOW_CPU, with the desired duty cycle percentage as the value (1-100).
By default, dump1090 will run with adaptive gain in dynamic range mode. You can override this by setting a Device Variable named DUMP1090_GAIN with a value of your liking. You can read more about manual gain optimization at the adsb-wiki.
dump978 and dump1090 can restart the device if it hits an error. You can enable this feature by setting a Device Variable named REBOOT_DEVICE_ON_SERVICE_EXIT with the value of true.
Automatically keep your balenaOS host release up-to-date. To enable this service, create a Device Variables named ENABLED_SERVICES with the value of autohupr.
HUP_CHECK_INTERVAL: Interval between checking for available updates. Default is 1d.HUP_TARGET_VERSION: The OS version you want balenaHUP to automatically update your device to. This is a required variable to be specified, otherwise, an update won't be performed by default. Set the variable to 'latest'/'recommended' for your device to always update to the latest OS version or set it to a specific version (e.g '2.107.10').Updating to the latest version is trivial. If you installed balena-ads-b using the blue Deploy with balena-button, you can click it again and overwrite your current application. Choose the "Deploy to existing fleet" option, then select the fleet you want to update. All settings will be preserved. For convenience, the button is right here:
If you used the manual balena push method, pull the changes from the master branch and push the update to your application with the balena CLI. For complete instructions, look at Part 2 – Setup balena and configure the device.
Enjoy!
