This package will add the AIS-catcher command - a dual channel AIS receiver for RTL-SDR dongles and the Airspy HF+. Output is send in the form of NMEA messages to either screen or broadcasted over UDP. The program provides the option to read and decode the raw discriminator output of a VHF receiver as well.
AIS-catcher is created for research and educational purposes under the MIT license. It is a hobby project from an unqualified amateur and not tested and designed for reliability and correctness. You can play with the software but it is the user's responsibility to use it prudently. So, in summary, DO NOT rely upon this software in any way including for navigation and/or safety of life or property purposes.
Release version 0.17: Upgrade challenger model to default model (max-min to max-avg)
Release version 0.14: Support for sampling rates of 2304KHz and 1920KHz. Default remains 1536K samples/second.
The aim of AIS-catcher is to provide a platform to facilitate continuous improvement of receiver models. Any suggestions, observation or sharing of recordings for setups where the current models are struggling is highly appreciated! The algorithm behind the default receiver model was created in this way by investigating signals and trying different ways to get a coherent model running whilst keeping it simple at the same time. If I have some more free time I will try to expand the documentation and implement some improvement ideas.
use: AIS-catcher [options]
[-h display this message and terminate (default: false)]
[-s xxx sample rate in Hz (default: based on SDR device)]
[-v [option: xx] enable verbose mode, optional to provide update frequency in seconds (default: false)]
[-q surpress NMEA messages to screen (default: false)]
[-u address port - UDP address and port (default: off)]
[-r filename - read IQ data from raw 'unsigned char' file]
[-r cu8 filename - read IQ data from raw 'unsigned char' file]
[-r cs16 filename - read IQ data from raw 'signed 16 bit integer' file]
[-r cf32 filename - read IQ data from WAV file in 'float' format]
[-w filename - read IQ data from WAV file in 'float' format]
[-l list available devices and terminate (default: off)]
[-d:x select device based on index (default: 0)]
[-d xxxx select device based on serial number]
[-p xx frequency correction for RTL SDR]
[-m xx run specific decoding model (default: 2)]
[ 0: Standard (non-coherent), 1: Base (non-coherent), 2: Default, 3: FM discrimator output]
[-b benchmark demodulation models - for development purposes (default: off)]
To test a proper installation and/or compilation (see below), we can first try to run the program on a RAW audio file as in this tutorial:
wget "https://github.com/freerange/ais-on-sdr/wiki/example-data/helsinki-210-messages.raw"
AIS-catcher -m 3 -v -s 48000 -r cs16 helsinki-210-messages.rawAIS-catcher on this file should extract roughly 360 AIVDM lines. Notice that with switch -m 3 on the command line AIS-catcher runs a decoding model that assumes the input is the output of an FM discriminator. In this case the program is similar to the following usage of GNUAIS:
gnuais -l helsinki-210-messages.rawwhich produces:
INFO: A: Received correctly: 153 packets, wrong CRC: 49 packets, wrong size: 4 packets
INFO: B: Received correctly: 52 packets, wrong CRC: 65 packets, wrong size: 10 packetsTo list the devices available for AIS reception:
AIS-catcher -lThe output depends on the available devices but will look something like:
Found 1 device(s):
0: Realtek, RTL2838UHIDIR, SN: 00000001A specific device can be selected with the d-switch like -d:0 or -d 00000001.
To start AIS demodulation, print some occasional statistics (every 10 seconds) and broadcast AIS messages via UDP, we can use the following command:
AIS-catcher -v 10 -u 127.0.0.1 12345If succesful, NMEA messages will start to come in, appear on the screen and send as UDP messages to 127.0.0.1 port 12345. These console messages can be surpressed with the option -q.
The following commands record a signal with rtl_sdr at a sampling rate of 288K Hz and then subsequently decodes the input with AIS-catcher:
rtl_sdr -s 288K -f 162M test_288.raw
AIS-catcher -r test_288.raw -s 288000 -vThe command line provides the -m option which allows for the selection of the specific receiver models. In the current version 4 different receiver models are embedded:
- Default model (
-m 2): the default demodulation engine - Base model (non-coherent) (
-m 1): similar to RTL-AIS (and GNUAIS/Aisdecoder) with some modifications to PLL and main receiver filter (taken from here and here ). - Standard model (non-coherent) (
-m 0): as the base model with brute force timing recovery, described here. - FM discriminator model: (
-m 3) as the 'standard' model but assumes input is output of a FM discriminator, hence no FM demodulation takes place which allowsAIS-catcherto be used as GNUAIS and AISdecoder.
The default model is the most time and memory consuming but experiments suggest it to be the most effective. In my home station it improves message count by a factor 2 - 3. The reception quality of the standard model over the base model is more modest at the expense of roughly a 20% increase in computation time. Advice is to start with the default model, which should run fine on most modern hardware including a Raspberry 4B and then scale down to -m 0or even -m 1, if needed.
Notice that you can execute multiple models in one run for benchmarking purposes but only the messages from the first model specified are displayed and forwarded. To benchmark different models specify -b for timing and/or -v to compare message count, e.g.
AIS-catcher -s 1536000 -r posterholt_1536_2.raw -m 2 -m 0 -m 1 -q -b -v
The program will run and summarize the performance (count and timing) of three decoding models:
[AIS engine v0.13+] : 38 msgs at 43 msg/s
[Standard (non-coherent)] : 4 msgs at 4.6 msg/s
[Base (non-coherent)] : 3 msgs at 3.4 msg/s
[AIS engine v0.13+] : 3.5e+02 ms
[Standard (non-coherent)] : 2.2e+02 ms
[Base (non-coherent)] : 2e+02 ms
In this example the default model performs quite well in contrast to the standard non-coherent engine with 38 messages identified versus 4 for the standard engine. This is typical when there are few messages with poor quality. However, it doubles the decoding time and has a higher memory usage so needs more powerful hardware. Please note that the improvements seen for this particular file are an exception.
To get a sense of the performance of the different models, I have run a simple test in two different setups whereby AIS-catcher ran the main two models in parallel for 2 minutes and we counted the number of detected messages.
Location: The Hague residential area with RTL-SDR v3 dongle and Shakespeare antenna with quite some (perhaps fair to say a lot of) blockage from surrounding buildings and antenna placed within a window, we have the following message count for various models and sample rates (over 2 minute run):
| Model | Settings | Run 1 | Run 2 |
|---|---|---|---|
| AIS-catcher v0.13 Default @ 1536K | 191 | 194 | |
| AIS-catcher Standard (non-coherent) @ 1536K | -m 0 |
64 | 72 |
| AISRec 2.2 (trial) | Sampling: very high, super fast | 161 | 119 |
| rtl-ais v0.3 @ 1600K | -n |
33 | 30 |
For completeness I performed seperate runs with AISRec and RTL-AIS as well. Results for a dAISy HAT are not listed but in this setup I received roughly ~85 messages over a two minute run.
A release in binary format for Windows 32 bit (including required libraries) can be occasionally found with the latest release but if not, please reach out and I will make it available. Note that you will have to install drivers using Zadig (https://www.rtl-sdr.com/tag/zadig/). After that, simply unpack the ZIP file in one directory and start the executable. For Linux systems, compilation instructions are below.
Make sure you have the following dependencies:
- librtlsdr and/or libairspyhf
The steps to compile AIS-catcher for RTL-SDR dongles are fairly straightforward on a Raspberry Pi 4B and Ubuntu systems. First ensure you have the necessary dependencies installed. If not, the following commands can be used:
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install git make gcc g++ -y
sudo apt-get install librtlsdr-dev -y
Next step is to download AIS-catcher source and install the program:
git clone https://github.com/jvde-github/AIS-catcher.git
cd AIS-catcher
make rtl-only
sudo make installIf you want to include Airspy HF+ functionality, ensure you install the required libraries as descibed on https://github.com/airspy/airspyhf. If not installed yet, you might first want to try:
sudo apt-get install libairspy-devThe process to install AIS-catcher then becomes:
make
sudo make installPre-built container images containing AIS-catcher are available from the GitHub Container Registry. Available container tags are documented on the package's page, with latest (the latest release) and edge (the bleeding edge of the main branch) being the two main ones.
The following docker run command provides an example of the usage of this container image, running the latest release of AIS-catcher interactively:
docker run --rm -it --pull always --device /dev/bus/usb ghcr.io/jvde-github/ais-catcher:latest <ais-catcher command line options>Alternatively, the following docker-compose.yml configuration provides a good starting point should you wish to use Docker Compose:
services:
ais-catcher:
command: <ais-catcher command line options>
container_name: ais-catcher
devices:
- "/dev/bus/usb:/dev/bus/usb"
image: ghcr.io/jvde-github/ais-catcher:latest
restart: alwaysNote that the container images only support RTL-SDR at this time, and do not yet support Airspy HF+.
AIS-catcher tunes in on a frequency of 162 MHz. However, due to deviations in the internal oscillator of RTL-SDR devices, the actual frequency can be slightly off which will result in no or poor reception of AIS signals. It is therefore important to provide the program with the necessary correction in parts-per-million (ppm) to offset this deviation where needed. For most of our testing we have used the RTL-SDR v3 dongle where in principle no frequency correction is needed as deviations are guaranteed to be small. For optimal reception though ensure you determine the necessary correction, e.g. see and provide as input via the -p switch on the command line.
On some laptops we observed that Windows was struggling with high volume of data transferred from the RTL SDR dongle to the PC. I am not sure why (likely some driver issue as Ubuntu on the same machine worked fine) but it is wortwhile to check if your system supports transferring from the dongle at a sampling rate of 1.536 MHz with the following command which is part of the osmocom rtl-sdr package:
rtl_test -s 1536000In case you observe a high number of lost data, the advice is to run AIS-catcher at a lower sampling rate for RTL SDR dongles:
AIS-catcher -s 288000If your system allows for it you might opt to run AIS-catcher at a sample rate of 2304000.
- Access to SDR hardware specific functionality, e.g. gain control
- Documenting and finetuning the default decoding model
- Ongoing: further improvements to reception and testing (e.g. improve coherent demodulation, filters, etc)
- Performance improvements
- More testing: in particular in an area with high message density
- Windows GUI
- ....
- ....