Raspberry Pi Installation¶

Important Disclaimer¶

AIS-Catcher is for hobby and research use only. Not for navigation or safety-critical applications.

Does not broadcast location data

Not certified for safety-critical use

Use only where legally permitted

Provided as-is without guarantees. Comply with local laws regarding AIS signal reception. Licensed under GPLv3.

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)"

The script will install all dependencies and build AIS-catcher. The required SDR libraries are installed from the official packages if they cannot be found on the system. For the RTL-SDR we build from source from the official package to guarantee support for the RTL-SDR V4 but, again, only if the package is not already installed on the system. On a fresh Raspberry Pi4 this will take less than 20 minutes.

To update AIS-catcher to the latest version, simply run the above command again. 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

Using pre-build Debian packages¶

If you want to use pre-installed Debian packages in the installation use:

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

The advantage that this avoids an compilation step which can save quite a bit of time on older Raspberry devices but it is not compatible with the first versions of the Raspberry Pi and Zero due to limnited support for floating point hardware acceleration. The pre-build packages also do not include PostgreSQL support.

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 backrgound 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).

The input configuration for AIS-catcher is quite flexible and allows for some complex configuration. This is not fully embedded in the UI in first instance. Therefore, the menus only work with our starting config JSON or any version amended by the UI. Once, the configuration files are manually edited, certain functionality will not be available.

You can still set the settings in the Advanced section of the Web UI by editing the parameters there. Also controlling the process (viewing the log and starting and stopping) is availaible.

Start First Run

Feedback¶

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