Create a Receive-ONLY APRS iGate on a Raspberry Pi

This document was first created on Feb 9, 2021.  It was last updated from my own experience building an iGate on Feb 16, 2021, but was updated again on Jan 16, 2024, based on the kind input of several readers.  Linux is pretty stable and these steps should not vary much for several years, but obviously, there's no guarantee of that.  I'm assuming the audience for this will include people with no Linux experience so please don't take the overly detailed steps and explanations in some sections as condescension on my part.  Much credit and gratitude goes to the various resources I found online creating this.  Anyway, I don't tend to write how-to documents often but I feel there's a need for this one so here goes.  ~Reg Natarajan VA7ZEB

APRS is a useful system, especially in emergencies in which the cellular system fails or when you're out of range of cellular service (or if you lose/break your phone for that matter).  In such cases, APRS lets you send out emails, SMS texts and direct messages using ham radios.  APRS also provides a location-reporting service that shows your position on some excellent web-based map front-ends like aprs.fi and aprsdirect.com.  This could save your rear-end in an emergency where rescue people need to be sent to your exact location.

The challenge we have with APRS is that, for it to work, there need to be iGates everywhere and there aren't right now.  In this document, I'm hoping to show people how to easily build and configure a cheap iGate that will contribute to the APRS system's infrastructure.  If even a tiny percentage of ham radio operators did this, APRS would have remarkable coverage just about everywhere.

Being frugal, we're going to make this happen using an inexpensive Raspberry Pi, an inexpensive SDR, an inexpensive antenna and a bunch of free software.  We're going to build a Pi, install Raspbian (now called Raspberry Pi OS), then install Direwolf and the Linux drivers for the RTL-SDR.  We're not going to use any other software at all.  We're going to configure Direwolf to relay APRS beacons and messages to APRS-IS and to beacon the iGate itself at regular intervals.  We're going to configure the iGate to be accessed from your home computer via VNC so that, after you hide it wherever you're going to hide it, you can still get to it and control it from your main PC.  We're going to set it up so that it survives reboots and resumes operation without requiring any human action.  We're going to set it up to update itself nightly with any new software upgrades and/or security patches and to reboot itself nightly to keep itself fresh. We'll even do a bit of hacker-proofing. It should take about an hour or two to do all of this (including the build of the Pi).

These are the parts I purchased and used for this project in Feb of 2021. You can substitute equivalents for any or all of them.  Please note that my links are to Amazon Canada because, obviously, I'm in Canada.  All of these parts are easy to purchase in most countries.  

You'll also need a reasonably fast Micro SD card and reader which most of us have lying around so I haven't bothered listing them below.  You will obviously also need a monitor, keyboard and mouse, but you can just temporarily steal those from your home computer while working on this project.  You won't need them for long.

Note that you don't need to do this on a Pi.  While I haven't tried it, I see no reason this approach wouldn't work on any Debian-based Linux including Ubuntu or Mint.  If you have an old computer lying around, use it.  Keep in mind it probably won't hide as well as a Pi.

I'm not going to cover this part other than to say if it takes you more than 10 minutes, you're doing it wrong.  Using the parts I listed above, I unscrewed the case (four screws), plopped the Raspberry Pi motherboard in, re-screwed the case, connected the fan and that was it.  If you're not sure how to connect the fan, there's a good image here.  If you have issues, YouTube is your friend.

Let's assume you've got yourself an assembled (but not booted) Raspberry Pi.  Make sure your SDR dongle is plugged in to a USB slot on the Pi and your antenna is connected to the SMA female connector on the SDR dongle.

Don't skip this part.  I know it's tempting to but you'll regret it.  The whole idea of a tiny little iGate is that you can hide it somewhere and let it run headless (no monitor, keyboard or mouse).  Well, if it ever needs attention (which it will, computers being what they are), it'll be much easier to fix whatever went wrong if you can just do it from your home PC rather than digging the Pi out of wherever you've hidden it, connecting a monitor, keyboard and mouse, only to click "ok" on whatever error is on the screen.

Now it's time to put your Pi in its permanent home.  Don't skip this as VNC will look funny if you leave your monitor connected (the monitor's native resolution will override whatever you set in the step above).  You also need to be sure your Pi won't have issues running headless. We'll do the rest of the steps in this document from your home PC using the VNC you just configured.  In your terminal window, type shutdown -h now and hit enter.  Wait a minute and your Pi will shut down.  Now, unplug the USB power from your Pi.  With the power unplugged, now unplug the monitor, keyboard and mouse, and then move the Pi to wherever you plan to keep it permanently.  Finally, plug only the USB power back in.  At this point, your Pi is operating "headless", without a keyboard, mouse or monitor.

At this point, things will be easiest if you load this document in the web browser on your home PC as you will be copying/pasting a lot.  Always use ctrl-shift-v to paste instead of just ctrl-v because the shift lets you paste into terminal windows.

Load up another terminal and copy/paste the following lines one at a time.  Yes, it's tedious to do this one line at a time.  Just do it that way or it might fail.  Pasting in multiple lines at a time is always hit and miss.

sudo apt update

sudo apt upgrade -y

sudo apt install cmake build-essential libusb-1.0-0-dev libasound2-dev libudev-dev -y

cd /usr/src

sudo git clone https://www.github.com/wb2osz/direwolf

cd direwolf

sudo mkdir build && cd build

sudo cmake -DUNITTEST=1 ..

sudo make -j4

sudo make test

sudo make install

cd /usr/src

sudo git clone https://git.osmocom.org/rtl-sdr.git

cd rtl-sdr

sudo mkdir build && cd build

sudo cmake ../ -DINSTALL_UDEV_RULES=ON -DDETACH_KERNEL_DRIVER=ON

sudo make

sudo make install

sudo ldconfig

sudo rtl_test

You should see your SDR dongle listed as follows.

Don't worry if you see a few lost bytes when you first run it.  It should stabilize quickly and not show any more lost bytes.  If you keep seeing significant numbers of lost bytes pop up on your screen after the first few seconds, you may have bad hardware.  Once you're satisfied, type ctrl-c to terminate the program.

Copy/Paste the following command into a terminal window.

nano ~/igate.conf

Copy/Paste the following brown text into the Nano editor.  Note that lines starting with # are just comments that don't affect anything.  You can paste them safely.  They won't harm anything.

IMPORTANT: Change YOURCALLSIGN to your actual call sign. Change YOURPASSCODE to your actual passcode.  If you don't have a passcode, get one here.  Change your latitude and longitude to your actual coordinates (just right click on any point in Google Maps and it'll tell you the lat/long).  If you're not in North America, change the IGSERVER to one of the alternatives listed below.

# Set the sound card to null

ADEVICE null null

CHANNEL 0

# Put your callsign here.  It is common to add "-10" to the end.

MYCALL YOURCALLSIGN-10

# Enter your callsign (no "-10" this time) and your passcode.

# If you don't have one, get your passcode at http://apps.magicbug.co.uk/passcode/

IGLOGIN YOURCALLSIGN YOURPASSCODE

# The IGSERVER defaults to North America.  

# If you prefer a different server, use one of these:

#      noam.aprs2.net - North America

#      soam.aprs2.net - South America

#      euro.aprs2.net - Europe and Africa

#      asia.aprs2.net - Asia

#      aunz.aprs2.net - Oceania

IGSERVER noam.aprs2.net

# Set your iGate up to beacon itself every 60 minutes.

# IMPORTANT: Change your latitude/longitude to your own coordinates.

PBEACON sendto=IG delay=0:30 every=60:00 symbol="igate" overlay=R lat=42^37.14N long=071^20.83W

When you're done with your changes, type ctrl-x to exit and then y to save.  Hit enter when it asks you to confirm the file name.

Copy/Paste the following command into a terminal window.

nano ~/igate.sh

Copy/Paste the following brown text into the Nano editor.

IMPORTANT: If you are in Europe, change 144.39 to 144.80.  Obviously if you wish to use APRS on any other frequency, there's nothing to stop you from doing that but I encourage you to stay within the conventions of your area.  You'll also need to change USERNAME to your user name.

#!/bin/bash

export DISPLAY=":0"

DWCMD="direwolf -c /home/USERNAME/igate.conf -r 24000 -D 1 -T \"Timestamp: %F %T\""

LXCMD="bash -c 'rtl_fm -f 144.39M - | $DWCMD -'"

sleep 30

/usr/bin/lxterminal -t "iGate" -e "$LXCMD"

Type ctrl-x to exit and then y to save.  Hit enter when it asks you to confirm the file name.

You also need to make the file executable.  Copy/Paste the following command into your terminal.

chmod +x ~/igate.sh

Now, finally, you get to run your iGate!  Copy/Paste the following command into your terminal.

sudo ~/igate.sh

There are different ways to do this.  To be frank, I find most of the common ones (such as throwing a dw-start.sh into a cron) to be overly complicated and prone to failure.  I'm just going to use the Raspberry Pi desktop to autostart the iGate 30 seconds after it loads.

IMPORTANT: Update Jan 2024: Some readers have told me they have had issues with the method below on newer versions of Raspberry Pi OS.  If the method below fails, please investigate alternative methods such as making the igate.sh script a service.  Here is a how-to on that.

Copy/Paste the following lines into a terminal window.

mkdir ~/.config/autostart

nano ~/.config/autostart/igate.desktop

Copy/Paste the following brown text into the Nano editor.  Be sure to change USERNAME to your user name.

[Desktop Entry]

Type=Application

Name=iGate

Exec=sh -c "sudo /home/USERNAME/igate.sh"

Type ctrl-x to exit and then y to save.  Hit enter when it asks you to confirm the file name.

Test it.  Reboot your Pi by typing reboot into your terminal window.  VNC will disconnect, of course, but it should reconnect automatically as your Pi boots and your iGate should run automatically after 30 seconds. 

Automatic updates should not be a controversial idea.  They'll keep your Pi up to date with the latest security patches, bug fixes and so on.  Some people worry about the risk that an update in the future may break the stack of software programs and configurations that make up your iGate.  To me, the risk of old and stagnant software being compromised is far greater than the risk of an upgrade making your stack fail.  It's worth setting your Pi up to auto-update itself.

Copy/Paste the following commands one at a time into a terminal window.  It may not work if you try to paste both lines at once.

sudo apt install -y unattended-upgrades apt-listchanges

sudo dpkg-reconfigure -plow unattended-upgrades

Every few weeks (or months), you should try to remember to log in to your Pi and just do a sudo apt update && sudo apt upgrade to see that it's working.  There should be (almost) no updates found if automatic updates are working correctly.

Nightly reboots are something each sysadmin has to decide on (and you're now a sysadmin, even if it's for just one system).  If your software stack hangs and you don't happen to notice, a nightly reboot will keep your downtime to less than a day.  I choose to do automatic nightly reboots but you'll have to decide for yourself.  If you want to proceed, do the following.

Copy/Paste the following command into a terminal window.

sudo crontab -e

Choose 1 for Nano and copy/paste the following brown text into a new line at the bottom of the file.  Note, this will reboot your Pi every night at 4 am. The first number is minutes, the second is hours.  If you want a different time, just change those two numbers.

0   4   *   *   *    /sbin/shutdown -r now

Type ctrl-x to exit and then y to save.  It should say "crontab: installing new crontab".

Fail2ban is a well known and well regarded hacker-protection program that just bans IP addresses temporarily if they try to log in with the wrong user/pw too often or too fast.  I always install it.  You can decide for yourself.  If you want to proceed, do the following.

Copy/Paste the following commands one at a time into a terminal window.  It may not work if you try to paste both lines at once.

sudo apt install fail2ban -y

sudo systemctl enable fail2ban

That's it.

You've done it.  You've built, configured and tested your APRS receive-only iGate.  Your final product should look something like this.

Put it somewhere safe with as much exposure for the antenna as you can manage, test that VNC still works, and boast to all your ham friends about how cool you are, because you really are.  APRS only works if people like you deploy iGates and you've done your bit for the community today.  

Link your ham friends to your iGate on aprs.fi and I bet they'll be jealous of you.  If they do happen to be jealous, please consider sharing this document with them.  Let's get as many iGates out there as we can.  I'd prefer that you link to my site because I intend (ok, hope) to keep this document updated here as much as possible, but I release everything I post here to the Public Domain so use it as you see fit.

I first wrote this document in February of 2021 based on my own experience building an iGate, and then updated it in January of 2024 based on the kind input of several readers.  If you follow this how-to and find things that need updating, please contact me.  That sort of feedback is always greatly appreciated.

I belong to some of the large APRS and BC/Canada ham groups on Facebook. Those groups are great places to get individual advice and support from the community.  You can find my FB profile here. 

I hope this has helped you. 

73,

Reg Natarajan

VA7ZEB