Skip to content

Running

Jump to bottom
charlie-foxtrot edited this page Feb 7, 2024 · 2 revisions

Privileges

If using the Broadcom VideoCore GPU on a Raspberry Pi you need to run RTLSDR-Airband as root, otherwise it won't be able to access the GPU hardware.

Otherwise you can run the program with user privileges. The only prerequisite is to have access rights to USB devices. Check /dev/bus/usb directory for permissions of device nodes - most probably they are writable by a group usb or plugdev or similar. Just add yourself to that group and RTLSDR-Airband should run fine.

Running in Foreground

By default RTLSDR-Airband runs as a daemon (background process). If you have just finished preparing a new config file, it is a good idea to launch it in foreground first, to find out if all the configured items have been properly recognized and the noise levels and signal levels are good. To do this, use the -f command line option:

/usr/local/bin/rtl_airband -f

As mentioned above, if using the GPU this command needs to be run as root or via sudo:

sudo /usr/local/bin/rtl_airband -f

RTLSDR-Airband attempts to read the configuration from the default path, which is /usr/local/etc/rtl_airband.conf. If your configuration file is located elsewhere, add the -c option and its path:

/usr/local/bin/rtl_airband -f -c /home/pi/new_config.conf

First, the configuration will be checked for correctness. Syntax errors or invalid settings will cause the program to exit with an error message describing the problem. Read it, fix the config and try again.

RTLSDR-Airband will then attempt to open and configure all devices specified in the configuration. If it succeeds, you should see something like this:

User interface screenshot

These are simple text waterfalls, one per each configured channel. This is an example for three devices running in multichannel mode. The meaning of the fields is as follows:

  • The number at the top of each waterfall is the channel frequency. When running in scan mode, this will be the first one from the list of frequencies to scan.
  • The number before the forward slash is the current signal level expressed in dBFS (decibels related to the full scale of the analog-to-digital converter, ie. 0 dBFS is full scale and everything else is lower than that).
  • The number after the forward slash is the current noise level estimate (in dBFS).
  • If there is an asterisk * after the second number, it means the squelch is currently open.
  • I there is a tilde ~ after the second number, it means that the channel has a signal that is being suppressed because it is outside of the band of the channel filter.
  • If there is a > or < character after the second number, it means AFC has been configured and is currently correcting the frequency in the respective direction.

If the device is running in scan mode, only one waterfall is displayed for it. Additionally, current scan frequency is then printed in each row.

Note: the fact that your devices are running and the squelch opens from time to time does not mean you will hear a sound from locally connected speakers or headphones! RTLSDR-Airband does not play any audio via local soundcard by default. You have to configure PulseAudio outputs for your channels if you want local playback.

To stop the program, just press Ctrl+c.

Running in Background

If you omit the -f option, RTLSDR-Airband will put itself into background after the configuration file has been successfully read. It will write its process ID into /run/rtl_airband.pid file (provided that it has write privileges to this directory). To stop the program when running in background, do:

killall rtl_airband

(remember to add "sudo" on a Raspberry Pi).

Note: Avoid killing RTLSDR-Airband with SIGKILL (kill -9), especially on a Raspberry Pi. The program would not properly free the GPU memory then, leading to memory exhaustion after a few subsequent runs. Eventually RTLSDR-Airband will not be able to start due to insufficient GPU memory available and you will have to reboot the Pi to cure this.

Note: The PID file path can be modified by pidfile global config option. Example:

pidfile = "/tmp/rtl_airband.pid";

Logging

Any errors related to configuration parsing are printed to standard error (ie. to the terminal). After the configuration file has been parsed successfully, all subsequent diagnostic messages are logged to system logger (syslog) by default - both in foreground and in background mode. Location of the log files depends on the syslog configuration - RTLSDR-Airband uses log facility "daemon", which most often lands in /var/log/daemon.log, /var/log/messages or /var/log/syslog file. After starting RTLSDR-Airband, check out the contents of /var/log directory for recently modified files. Once you find the correct file, you can, for example, follow it for any new messages with this command:

tail -f /var/log/daemon.log

If you are a Linux beginner, take your time to explore your log files and find out what is logged and where. In case of any problems with RTLSDR-Airband, this is your primary source of information during troubleshooting.

Here is an example of how a successful run of RTLSDR-Airband might look like in the logfile:

Jan 18 17:48:41 mypi rtl_airband[12407]: RTLSDR-Airband version v2.4.0-58-g3b716b0-dirty starting
Jan 18 17:48:41 mypi rtl_airband[12407]: pulse: <default_server>: connecting...
Jan 18 17:48:41 mypi rtl_airband[12407]: pulse: <default_server>: connecting...
Jan 18 17:48:41 mypi rtl_airband[12407]: SoapySDR: device 'driver=airspy,device_id=0': sample rate set to 3000000 sps
Jan 18 17:48:41 mypi rtl_airband[12407]: SoapySDR: device 'driver=airspy,device_id=0': gain set to 15.0 dB
Jan 18 17:48:41 mypi rtl_airband[12407]: SoapySDR: device 'driver=airspy,device_id=0' initialized
Jan 18 17:48:41 mypi rtl_airband[12407]: SoapySDR: device 'driver=airspy,device_id=0' started
Jan 18 17:48:41 mypi rtl_airband[12407]: pulse: <default_server>: connected
Jan 18 17:48:41 mypi rtl_airband[12407]: pulse: <default_server>: stream "VOLMET" connected
Jan 18 17:48:41 mypi rtl_airband[12407]: pulse: <default_server>: connected
Jan 18 17:48:41 mypi rtl_airband[12407]: pulse: <default_server>: stream "APP" connected
Jan 18 17:48:45 mypi rtl_airband[12407]: Appending from pos 680000 to /home/pi/recordings/APP_20180118_17.mp3
Jan 18 17:48:53 mypi rtl_airband[12407]: Got signal 2, exiting
Jan 18 17:48:53 mypi rtl_airband[12407]: Cleaning up
Jan 18 17:48:53 mypi rtl_airband[12407]: Input threads closed

There is an information about the SDR device (Airspy) and how it has been configured by RTLSDR-Airband. There are two pulse outputs configured and both have been connected successfully. Then there is a file output defined and RTLSDR-Airband continues to write to a file created during previous run. Then the program has been interrupted with ctrl+c and exited cleanly.

If you wish, you can disable syslog logging. To do this, add the -e command line option. This will cause the logs to be sent to standard error. When running in foreground, they will be printed to the terminal screen. In background mode there is no terminal available, so the logs will be lost and in case of any problem you will have no way of figuring out what's wrong.

Starting at Boot

If you wish to start the program automatically at boot, you can use example startup scripts from init.d subdirectory in the source tree. These scripts assume default installation paths (ie. the program in /usr/local/bin/rtl_airband and the config in /usr/local/etc/rtl_airband.conf).

Debian / Raspbian Jessie or newer

(or any other distribution based on systemd):

sudo cp init.d/rtl_airband.service /etc/systemd/system
sudo chown root.root /etc/systemd/system/rtl_airband.service
sudo systemctl daemon-reload
sudo systemctl enable rtl_airband

You can then start, stop and restart RTLSDR-Airband manually, using systemctl commands:

sudo systemctl start rtl_airband
sudo systemctl stop rtl_airband
sudo systemctl restart rtl_airband

Logs are written to the system journal then, meaning you can browse them using journalctl command:

journalctl -u rtl_airband

Expert note: When running rtl_airband under systemd, it's best to use a service type "simple" and start the program with -F -e options. The first one causes it to run in foreground, but disables textual waterfalls. The second one causes logs to be written to standard error instead of syslog. systemd is then responsible for keeping the program in the background and for redirecting its logs to the system journal. This is how the example unit file is set up.

Debian / Raspbian Wheezy or older (sysvinit-based)

sudo cp init.d/rtl_airband-debian.sh /etc/init.d/rtl_airband
sudo chown root.root /etc/init.d/rtl_airband
sudo chmod 755 /etc/init.d/rtl_airband
sudo update-rc.d rtl_airband defaults

You can then start RTLSDR-Airband manually, using the startup script:

/etc/init.d/rtl_airband start       # or "stop" or "restart"

There are example startup scripts for Gentoo Linux and FreeBSD as well. If you are using one of these, I'm sure you know what to do :-)

Docker

The docker container is setup to run the following command:

/app/rtl_airband -F -e -c /app/rtl_airband.conf

The docker container will need access to the USB bus, a config file mounted to /app/rtl_airband.conf, and optionally network access (for outgoing audio streams) and/or cross mounted directories for recordings. The following example command if run from the repo's root directly will run a rtl_airband with a sample config that will use the first rtl-sdr device to record the seven (NOAA Weather Radio Stations)[https://www.weather.gov/nwr/] to directory new local directory recordings/.

docker run -it --rm --device=/dev/bus/usb --network=host -v ./config/noaa.conf:/app/rtl_airband.conf -v ./recordings/:/recordings/ ghcr.io/charlie-foxtrot/rtlsdr-airband:latest
Clone this wiki locally