AirBear Setup

Last updated on 
AirBear Setup

Set Up Your AirBear Receiver

AirBear shows the aircraft and APRS stations that your own receiver hears: a Raspberry Pi with one or two small USB radios. Setting one up takes a single command, and removing it takes one more.

What you need

  • A Raspberry Pi 3, 4, 5 or Zero 2 W. Their built-in Bluetooth lets AirBear connect to the receiver without a network.
  • A microSD card, 8 GB or larger.
  • An RTL-SDR USB dongle with a 1090 MHz antenna, for aircraft.
  • Optionally, a second RTL-SDR dongle with a 2-meter (144 MHz) antenna, for APRS stations.
  • Optionally, a USB GPS, so the receiver knows where it is. It's handy when the receiver travels with you.

1. Install Raspberry Pi OS

  1. Install Raspberry Pi Imager on your computer.
  2. Choose your Raspberry Pi, then Raspberry Pi OS Lite (64-bit), under Raspberry Pi OS (other). The desktop version works too; it needs to be the 64-bit one.
  3. In Imager's customization settings, set a hostname (airbear, say), a username and password, and your Wi-Fi, and turn on SSH.
  4. Write the card, put it in the Pi, and switch it on. Give it a couple of minutes to start the first time.

2. Install AirBear

Plug the dongles (and the GPS, if you have one) into the Pi. Then connect to the Pi from your computer's terminal, using the hostname and username you chose:

ssh [email protected]

and run:

curl -fsSL https://acgao.com/content/files/airbear/dist/install.sh | sudo sh

This downloads AirBear and the radio software it needs from Raspberry Pi OS, and starts the receiver. Then it asks three things:

  • Which dongle is which. AirBear listens for aircraft on each dongle for 20 seconds and suggests which one is for aircraft. Press Return to agree.
  • Your APRS frequency. Pick your region: 144.39 MHz in North America, 144.8 MHz in Europe and Africa, and so on.
  • Where the receiver is. With a GPS, AirBear knows already. Without one, you can type a rough latitude and longitude, or skip it.

It finishes by showing how the receiver is doing.

3. Connect the app

In AirBear, tap Sources, then Add Receiver.

  • On your network: your receiver appears under On Your Network. Choose it, then tap Add.
  • By Bluetooth: choose Bluetooth, then Device. Your receiver appears as AirBear Receiver. Bluetooth reaches about 30 feet.

Aircraft and stations appear on the map as the receiver hears them.

Checking on it

airbear status

shows each feed, which dongle it uses, the GPS fix and Bluetooth:

AirBear receiver 1.0.0 on airbear (192.168.1.20)

  ● ADS-B      active      port 30003, 1 client  dongle 00000001 (detected)
  ● APRS       active      port 8001  dongle 00000002 (detected)
  ● GPS        active      port 10110  /dev/ttyUSB0 at 4800 baud, fix 34.47132, -84.32118, 27 satellites
  ● Bluetooth  active      advertising as "AirBear Receiver"

airbear logs shows what the receiver is doing as it happens.

Changing settings

  • Run sudo airbear setup again to change which dongle does what, the APRS frequency or the location.
  • Everything else is in /etc/airbear/airbear.conf: the Bluetooth name, whether the app may switch the receiver off, which GPS to use, and so on. After editing it, run sudo airbear restart.

Updating

Run the install command again. Your settings stay as they are.

Uninstalling

sudo apt purge airbear-receiver
sudo apt autoremove

The first command removes AirBear: its services, settings and files, and the user it runs as. The second removes the radio software it installed, unless something else on the Pi uses it.

What it installs

  • One package, airbear-receiver, plus the radio software it needs from Raspberry Pi OS (rtl-sdr and Direwolf). It changes nothing else on the Pi, except to switch off another ADS-B decoder (readsb or dump1090) if one is running, since it would hold the same dongle. Uninstalling AirBear switches that decoder back on.
  • Services for aircraft, APRS, GPS and Bluetooth, which run as their own airbear user, never as root.
  • Network ports with read-only feeds: aircraft on 30003 (SBS), APRS on 8001 (KISS) and GPS on 10110 (NMEA), plus raw (30002) and Beast (30005) aircraft data for other ADS-B tools. Nothing sent to these ports can change the
    receiver.
  • Bluetooth as AirBear Receiver. Over Bluetooth, the app can read those feeds and, unless you set ALLOW_SHUTDOWN=no in /etc/airbear/airbear.conf, switch the receiver off.

If something's not right

  • "waiting for a dongle" — check that it's plugged in. lsusb lists what the Pi sees.
  • No aircraft — check that the 1090 MHz antenna is on the aircraft dongle. sudo airbear setup listens on each dongle and tells you which one hears aircraft. If that's not the one you expected, the antennas may be on the
    wrong dongles.
  • Few APRS stations — that's normal away from cities and highways. Some places hear one every few minutes, others one an hour.
  • "this needs the 64-bit Raspberry Pi OS" — write the card again with the 64-bit version.
  • The app doesn't find it by Bluetooth — move closer, and check that airbear status says it's advertising.

Open source

The receiver includes readsb, the ADS-B decoder, which is licensed under the
GPL 3. Its source code is at acgao.com/content/files/airbear/dist/readsb-3.16.17.tar.gz.

Support

If you have questions about AirBear, contact us at [email protected].

OG

The original, old instructions are included below for historical purposes. You can stop reading at this point.

Overview

AirBear is an app for Mac, iPad and iPhone. AirBear integrates with 3rd party software to track and map APRS, ADS-B and NMEA (GPS) data sources. AIS should be available soon as well. AirBear works fully offline, using built-in mapping data. AirBear requires no internet access.

AirBear receives data via TCP and BLE (Bluetooth Low Energy). The mechanism you choose is based on your requirements. If you have a wired or wireless network connecting your macOS or iOS device with the data source, you should use TCP. If you will be on-the-go without a network, BLE is the best option.

A typical setup includes a Raspberry Pi with one or more RTL receivers.

These instructions are preliminary. More detailed instructions will be available in the future.

APRS (People & Vehicles)

APRS is a protocol used to broadcast locations and text messages from handheld radios, mobile radios and tracking devices. It is perhaps most frequently used in vehicles.

AirBear is designed to work with the output from Dump1090. Dump1090 will create a TCP listener which AirBear can be configured to connect to on port 8001.

dump1090-mutability --quiet --fix --lon "-80.123" --lat "30.456" --modeac --phase-enhance --aggressive --net

ADS-B (Planes)

ADS-B is the protocol used by airplane transponders to broadcast basic flight information for air traffic control and other planes. ADS-B messages can include a flight number, heading, altitude, location and other information.

AirBear is designed to work with the output from Dire Wolf. Dire Wolf will create a TCP listener which AirBear can be configured to connect to on port 30003.

rtl_fm -f 144.39M - | direwolf -c ~/direwolf.conf -r 24000 -D 1 -

AIS (Boats)

AIS is the protocol used by boats; not unlike an ADS-B airplane transponder. AIS support in AirBear is still forthcoming. Stay tuned, so to speak.

NMEA (GPS)

I'll skip the explanation of what GPS is. AirBear will work with the NMEA-0183 output from a USB GPS or with CoreLocation on your macOS or iOS device.

AirBear is designed to work with the output from ser2net. Determine the baud rate of your GPS and adjust the following /etc/ser2net.yaml configuration accordingly. ser2net will create a TCP listener which AirBear can be configured to connect to no port 10110.

connection: &airbear_gps_nmea
    accepter: tcp,0.0.0.0,10110
    enable: on
    options:
      max-connections: 10
      no-acc-to-con: true
    connector: serialdev,
              /dev/ttyUSB0,
              4800n81,local

TCP

The easiest way to connect AirBear to one of your APRS, ADS-B, NMEA or AIS data sources is via TCP. However, if you are mobile, that may not be an option. In that case, see the BLE instructions, below.

Configure connections in AirBear using the Connection Settings screen, which is accessible from the navigation buttons on the right side of the map. A TCP connection just requires the hostname. Each connection is pre-configured with the default port number.

BLE

Instructions will be available shortly.