Page cover image

πŸ“‘AIS Hardware

How to deploy your own Automatic Identification System (AIS) receiver.

In addition to utilizing AIS data provided by Spire for the Canadian coasts, you can install AIS receiver hardware to capture AIS data directly. The received data can be processed and stored in databases, which can then be used with AISdb. This approach offers additional data sources and allows users to collect and process their data (as illustrated in the pipeline below). Doing so allows you to customize your data collection efforts to meet specific needs and seamlessly integrate the data with AISdb for enhanced analysis and application. At the same time, you can share the data you collect with others.

Pipeline for capturing and sharing your own AIS data with a VHF Antenna and AISdb.

Requirements

  • Raspberry Pi or other computers with internet working capability

An additional option includes free AIS receivers from MarrineTraffic. This option may require you to share the data with the organization to help expand its AIS-receiving network.

Hardware Setup

  • When setting up your antenna, place it as high as possible and far away from obstructions and other equipment as is practical.

  • Connect the antenna to the receiver. If using a preamp filter, connect it between the antenna and the receiver.

  • Connect the receiver to your Linux device via a USB cable. If using a preamp filter, power it with a USB cable.

  • Validate the hardware configuration

    • When connected via USB, the AIS receiver is typically found under /dev/ with a name beginning with ttyACM, for example /dev/ttyACM0. Ensure the device is listed in this directory.

    • To test the receiver, use the command sudo cat /dev/ttyACM0 to display its output. If all works as intended, you will see streams of bytes appearing on the screen.

    $ sudo cat /dev/ttyACM0
    !AIVDM,1,1,,A,B4eIh>@0<voAFw6HKAi7swf1lH@s,0*61
    !AIVDM,1,1,,A,14eH4HwvP0sLsMFISQQ@09Vr2<0f,0*7B
    !AIVDM,1,1,,A,14eGGT0301sM630IS2hUUavt2HAI,0*4A
    !AIVDM,1,1,,B,14eGdb0001sM5sjIS3C5:qpt0L0G,0*0C
    !AIVDM,1,1,,A,14eI3ihP14sM1PHIS0a<d?vt2L0R,0*4D
    !AIVDM,1,1,,B,14eI@F@000sLtgjISe<W9S4p0D0f,0*24
    !AIVDM,1,1,,B,B4eHt=@0:voCah6HRP1;?wg5oP06,0*7B
    !AIVDM,1,1,,A,B4eHWD009>oAeDVHIfm87wh7kP06,0*20

A visual example of the antenna hardware setup that MERIDIAN has available is as follows:

MERIDIAN AIS hardware setup working at Sandy Cove in Halifax, NS - Canada.

Software Setup

Quick Start

Connect the receiver to the Raspberry Pi via a USB port, and then run the configure_rpi.sh script. This will install the Rust toolchain, AISdb dispatcher, and AISdb system service (described below), allowing the receiver to start at boot.

curl --proto '=https' --tlsv1.2 https://git-dev.cs.dal.ca/meridian/aisdb/-/raw/master/configure_rpi.sh | bash

Custom Install

  1. Install Raspberry Pi OS with SSH enabled: Visit https://www.raspberrypi.com/software/ to download and install the Raspberry Pi OS. If using the RPi imager, please ensure you run it as an administrator.

  2. Connect the receiver: Attach the receiver to the Raspberry Pi using a USB cable. Then log in to the Raspberry Pi and update the system with the following command: sudo apt-get update

  3. Install the Rust toolchain: Install the Rust toolchain on the Raspberry Pi using the following command: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh Afterward, log out and log back in to add Rust and Cargo to the system path.

  4. Install the network client and dispatcher: (a) From crates.io, using cargo install mproxy-client(b) To install from the source, use the local path instead, e.g. cargo install --path ./dispatcher/client

  5. Install systemd services: Set up new systemd services to run the AIS receiver and dispatcher. First, create a new text file ./ais_rcv.service with contents in the block below, replace User=ais and /home/ais with the username and home directory chosen in step 1.

./ais_rcv.service
[Unit]
Description="AISDB Receiver"
After=network-online.target
Documentation=https://aisdb.meridian.cs.dal.ca/doc/receiver.html

[Service]
Type=simple
User=ais # Replace with your username
ExecStart=/home/ais/.cargo/bin/mproxy-client --path /dev/ttyACM0 --server-addr 'aisdb.meridian.cs.dal.ca:9921' # Replace home directory
Restart=always
RestartSec=30

[Install]
WantedBy=default.target

This service will broadcast receiver input downstream to aisdb.meridian.cs.dal.ca via UDP. You can add additional endpoints at this stage; for more information, see mproxy-client --help. Additional AIS networking tools, such as mproxy-forward, mproxy-server, and mproxy-reverse, are available in the ./dispatcher source directory.

Next, link and enable the service on the Raspberry Pi to ensure the receiver starts at boot:

sudo systemctl enable systemd-networkd-wait-online.service
sudo systemctl link ./ais_rcv.service
sudo systemctl daemon-reload
sudo systemctl enable ais_rcv
sudo systemctl start ais_rcv

See more examples in docker-compose.yml

πŸ’‘ Common Issues

For some Raspberry hardware (such as the author's Raspberry Pi 4 Model B Rev 1.5), when connecting dAISy AIS Receivers, the device file in Linux used to represent a serial communication interface is not always "/dev/ttyACM0", as used in our ./ais_rcv.service.

You can check the actual device file in use by running:

ls -l /dev

For example, the author found that serial0 was linked to ttyS0 (i.e., ttyS0).

Simply changing /dev/ttyACM0 to /dev/ttyS0 may result in receiving garbled AIS signals. This is because the default baud rate settings are different. You can modify the default baud rate for ttyS0 using the following command:

stty -F /dev/ttyS0 38400 cs8 -cstopb -parenb

Last updated