Raspberry Pi Installation¶

License & Important Disclaimer¶

AIS-catcher is provided for research and educational purposes. It has not been designed, tested, or certified for reliability, accuracy, or safety. Do not rely on AIS-catcher for navigation or any safety-critical applications. Users bear full responsibility for ensuring compliance with local laws and regulations regarding the reception, decoding, and use of AIS signals. AIS-catcher is provided “as is,” without warranty of any kind, and must not be used for illegal or unauthorized activities. Operate AIS-catcher only where such use is permitted by local authorities.

Copyright (C) 2021–2025 jvde.github at gmail.com. Licensed under the GNU General Public License v3.0

Installation¶

This guide provides instructions for installing AIS-catcher on Debian-based systems (like Raspberry Pi) and setting it up to run as a background service. The background service provides the option for AIS-catcher to automatically start when the machine is booted.

Basic Installation via the below script is required as a first step if you want to install the Web GUI package.

Basic Installation¶

To install AIS-catcher via a script, open a terminal or log in via SSH, then run the following command:

sudo bash -c "$(wget -qO- https://raw.githubusercontent.com/jvde-github/AIS-catcher/main/scripts/aiscatcher-install) _ -p"

The script will install all dependencies and install AIS-catcher. The required SDR libraries are installed from the official packages, if they cannot be found on the system. This script will install AIS-catcher from the latest available Debian package on Github. To guarantee support for the RTL-SDR V4 the latest version of the Osmocom library is statically linked into the AIS-catcher executable.

This script is not compatible with the first versions of the Raspberry Pi and Zero due to their limited support for floating point hardware acceleration. The pre-build packages also do not include PostgreSQL support. If this is required, please build from source.

To additionally install the Web GUI, see below. The Web GUI allows you to control the AIS-catcher process (start and stop) and set the configuration remotely via a convenient Web GUI.

Start First Run Install Web GUI

Update AIS-catcher to latest version¶

After you have installed with the above script, to update AIS-catcher to the latest version, simply run the above command again. It will not overwrite any configuration files when there are available on the system.

Install From Source¶

If you want to install from source, you can run the script as follows:

sudo bash -c "$(wget -qO- https://raw.githubusercontent.com/jvde-github/AIS-catcher/main/scripts/aiscatcher-install)"

The advantage of building from source is that the executable is optimized for the hardware specifics but can take a significant amount of time (20 minutes on a Raspberry Pi 4).

Testing the installation¶

Once the program is installed it can be run on the command line and checked for the features that are included in the build:

AIS-catcher -L

More information to get started is available. The installation script also sets up the infrastructure to run AIS-catcher as a systemd background service automatically on start up.

Configuration Files for background service¶

For running AIS-catcher as a background service we can use two configuration files:

/etc/AIS-catcher/config.json (JSON configuration)
/etc/AIS-catcher/config.cmd (command line parameters)

The simplest approach is to edit the configuration file /etc/AIS-catcher/config.cmd to capture your settings which are detailed below. Lines starting with # are considered comments and ignored. The default file contains comments for popular options, which can be modified using a text editor, for example:

sudo nano /etc/AIS-catcher/config.cmd

Please note that config.json takes precedence over config.cmd.

Running AIS-catcher as a Background Service¶

To start AIS-catcher as a background service use the following command:

sudo systemctl start ais-catcher.service

To view the status of the service copy the following command:

sudo systemctl status ais-catcher.service

To ensure AIS-catcher starts automatically at boot time, enable the service with:

sudo systemctl enable ais-catcher.service

Installation with Web GUI¶

AIS-catcher provides a web-based graphical user interface for easy configuration. Ensure you have installed the basic package first. It needs to be installed as a separate service by entering in the terminal:

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/jvde-github/AIS-catcher-control/main/install_ais_catcher_control.sh)"

To access it, open your web browser and navigate to your Raspberry Pi's IP address on port 8110 (for example, http://zerowh:8110).

Please note that once you manually edit the AIS-catcher configuration files, certain simplified Web UI features (such as one-click or wizard-like configuration menus) will no longer be available. However, you can still configure advanced settings via the Web UI and manage AIS-catcher by viewing logs or starting and stopping the service.

Start First Run

Feedback¶

This is fairly new script and under development so any feedback is appreciated.