# Setup and user guide

> How to set up Akashlipi: the hardware you need, installing it, the six-step first-run setup, dongle jobs, aircraft messages, the handheld layout, every command, where files live, and fixing problems.

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](https://akashlipi.com/download/) the package for your Linux, then install it:

| Your Linux | Command |
|---|---|
| Debian, Ubuntu, Mint, Raspberry Pi OS, Kali | `sudo apt install ./adsb-logger_2.5.2_amd64.deb` (or `_arm64.deb`) |
| Fedora, RHEL, AlmaLinux, Rocky 9+, openSUSE | `sudo dnf install ./adsb-logger-2.5.2-1.x86_64.rpm` (or `.aarch64.rpm`) |
| Anything else | `chmod +x adsb-logger-2.5.2-x86_64.AppImage`, then open it and click **Set up** |

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:

```sh
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:

```sh
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.

| Button | Does |
|---|---|
| L / R | previous / next tab |
| Arrows | move; on the radar, ◀▶ picks an aircraft and ▲▼ zooms |
| A | open or select |
| B | back (hold it to return to the Radar) |
| X / Y | the tab’s actions, shown at the bottom of each tab |
| Start / Select | quick menu / button guide |

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.

| Command | What it does |
|---|---|
| `app` / `launch` | Open the app window (what the menu entry runs) |
| `setup [--check \| --repair \| --remove-system]` | The setup steps in a terminal |
| `dongles` | Dongles, serial numbers and jobs |
| `messages [-f] [--aircraft X] [--survey] [--share airframes\|off]` | Aircraft messages |
| `buttons [--reset \| --calibrate \| --test]` | Handheld buttons |
| `start` / `stop [--release-dongle]` / `restart` / `status` / `logs -f` | Control the services |
| `enable` / `disable` | Keep logging with the app closed, or only while it’s open |
| `live [-w]`, `recent [N]`, `stats`, `trips` | Your log in the terminal |
| `lookup VT-IJK`, `history VT-IJK`, `metar VOHS` | Everything known about an aircraft, where it has flown recently (OpenSky), an airport’s weather |
| `watchdog`, `mlat`, `gps` | The watchdog, opt-in MLAT, and mobile mode with a GPS |
| `export`, `sync`, `update`, `config` | Save the log as CSV or GeoJSON, copy it elsewhere on a schedule, refresh the offline data, settings |
| `doctor` | Check everything and say what’s wrong |

## Where things are kept

| What | Where |
|---|---|
| Program and bundled tools | `/opt/adsb-logger` |
| Settings | `/etc/adsb-logger/config.ini`, and per user `~/.config/adsb-logger/config.ini` |
| Your log and data | `~/adsb-log/`: `flights.db`, `flights.csv`, `messages.jsonl`, `ref/dgca.db`, `tiles/`, `dongles/`, `backups/` |
| Dongle numbers, jobs and button mapping | `~/.config/adsb-logger/dongles.json`, `buttons.json` |
| System parts | systemd services, `60-adsb-logger-rtlsdr.rules` (udev), `adsb-logger-blacklist.conf` (modprobe), `/etc/polkit-1/rules.d/50-adsb-logger.rules` |

## 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.

```sh
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`.