Setup and user guide

This guide covers Akashlipi 2.5.2 on Linux. In this version the app is still called ADS-B Logger in your menu and window title, and its terminal command is adsb-logger. Both keep working after the new name arrives in an update.

What you need

• A Linux computer. A 64-bit PC or laptop, or a Raspberry Pi with a 64-bit OS. Ubuntu 20.04, Debian 11, Fedora, RHEL 9 or anything newer.
• An RTL-SDR dongle and an antenna for 1090 MHz. Any RTL2832U dongle works. The RTL-SDR Blog V4 needs its own driver, and Akashlipi brings it with it.
• A second dongle for aircraft messages (optional). Messages arrive on VHF, around 130–137 MHz, so this dongle needs its own antenna: a dipole about 110 cm overall, two arms of about 55 cm.
• A GPS receiver (optional). For logging on the move, through gpsd.

Put the antenna as high and as clear of buildings as you can. Range on 1090 MHz is line of sight, and a window sill on the right side of the house can double what you hear.

Install

Download the package for your Linux, then install it:

Everything is installed in /opt/adsb-logger. If you already run your own readsb, Akashlipi uses it instead of the one it brings.

First run: the six setup steps

Open ADS-B Logger from your app menu. The first time, it walks you through six steps with buttons. Each step says what it found and what it will do, and asks before changing anything.

1. System parts. Installs the background services, the USB rule that lets your account use the dongles, and a rule that stops the TV-tuner driver from grabbing them. Asks for your password once.
2. Dongles. Lists the dongles plugged in and gives each one a job: ADS-B or messages.
3. Location. Where your antenna is, for distances and the radar.
4. ADS-B decoder. Sets up readsb on the ADS-B dongle.
5. Messages (optional). Sets up the message decoders on the second dongle.
6. Check. Confirms that everything works and aircraft are being received.

You can run the same steps in a terminal with adsb-logger setup. Run it again any time: steps that are already fine are skipped. adsb-logger setup --check only reports what is and isn’t set up.

Using the app

• Overview. The live radar, aircraft in range, charts and every logged pass. Click an aircraft for its details: owner, lessor, flight number, route, weather and its messages.
• Messages. Every message aircraft send, decoded into plain English. Click one to open it beside the list, with the text as received one click away. Move with ↑/↓ or j/k, close with Esc.
• Manage (the gear icon). Health, Signal, Data (save or clear the log), Dongles and Settings (location, messages, app window, handheld buttons).

Akashlipi receives while the app is open. Closing the window keeps it running in the tray; Quit stops it, and nothing starts at boot. To log around the clock, choose Settings › App window › keep logging, or run adsb-logger enable. On a Raspberry Pi without a screen, adsb-logger start runs it without the app.

Dongles and their jobs

New dongles usually leave the factory with the same serial number, 00000001, so two of them can’t be told apart. When Akashlipi finds a dongle with the factory serial or a duplicate, it saves a copy of the dongle’s memory, gives it its own number from 00000100 up, and asks you to unplug it and plug it back in.

The first dongle gets the ADS-B job and the second gets messages. To change that:

adsb-logger dongles                                # what's plugged in
adsb-logger dongles --set-role 00000101 messages   # use this one for messages
adsb-logger dongles --restore 00000101             # put its original memory back
adsb-logger dongles --auto off                     # stop numbering new dongles

The same controls are in Manage › Dongles.

Aircraft messages (ACARS and VDL2)

Aircraft send short text messages to their airline and to air traffic control over VHF: position reports, gate times, weather requests, clearances, maintenance reports and free text. With a dongle on the Messages job, Akashlipi decodes them into plain English and links each one to the logged pass of the aircraft that sent it.

Which frequencies are busy depends on where you are. Run the frequency survey once after setting up, from Manage › Dongles or in a terminal:

adsb-logger messages --survey         # listens across the band for 3 minutes and saves the busiest
adsb-logger messages -f               # watch messages as they arrive
adsb-logger messages --aircraft VT-IJK

Sharing what you receive with airframes.io is off unless you turn it on: adsb-logger messages --share airframes.

The watchdog

If the sky goes quiet, the watchdog restarts the decoder, resets the dongle’s USB connection if needed, and alerts you if it can’t fix things itself. It watches every receiver, including the messages dongle. adsb-logger watchdog shows its status and can send a test alert.

Handheld layout

On screens of 800×480 or smaller, such as the 640×480 Waveshare PocketTerm35, the app switches to a handheld layout with Radar, Nearby, Msgs, Stats and Status tabs, driven by the arrow keys and game buttons. The first time, it asks you to press each button once.

If the buttons get mixed up: Settings › Handheld buttons, Status › Controls, hold Esc for 3 seconds, or run adsb-logger buttons --reset. adsb-logger app --compact --kiosk forces the handheld layout full screen.

Commands

adsb-logger help lists every command, and adsb-logger help COMMAND gives details and examples. man adsb-logger has the same.

Where things are kept

What it looks up online

Most data is kept on your computer: the tar1090-db aircraft database, VRS standing data for routes, OurAirports, and India’s DGCA register of civil aircraft and list of non-scheduled operators (from their public PDFs, refreshed every 30 days). Map tiles are cached for offline use.

The internet is used only to fill gaps: adsbdb.com and hexdb.io for aircraft and routes it doesn’t know, aviationweather.gov for METAR weather, OpenSky when you ask for it, and OpenStreetMap for map tiles. Fuel and CO₂ estimates are calculated on your computer with OpenAP. MLAT and message sharing are off unless you turn them on.

When something isn’t working

• Start with adsb-logger doctor, or Manage › Health in the app. Each problem it finds has a Fix button, and Repair everything puts back any missing system part (adsb-logger setup --repair in a terminal).
• No aircraft. Check the dongle is plugged in (adsb-logger dongles) and has the ADS-B job, and that the antenna is connected and has a view of the sky. Manage › Signal shows what the receiver hears.
• Another program needs the dongle, such as SDR++: run adsb-logger stop --release-dongle. adsb-logger start takes it back.
• No messages. Check the second dongle has the Messages job and its own VHF antenna, then run the frequency survey again.
• The app window doesn’t open. It falls back to a browser window; adsb-logger app --browser opens it in your browser directly.
• Logs. adsb-logger logs -f follows the services’ logs.

Upgrading and removing

Install a new version over the old one with the same command you installed it with. Your log in ~/adsb-log and your location are kept, and the log is backed up first.

sudo apt remove adsb-logger      # .deb
sudo dnf remove adsb-logger      # .rpm
adsb-logger setup --remove-system && rm adsb-logger-*.AppImage    # AppImage

Removing the program never removes your logs in ~/adsb-log.