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 you to collect and process your own data (as illustrated in the pipeline below). Doing so lets you 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 connectivity

Raspberry Pi (Image source: https://www.raspberrypi.com/products/raspberry-pi-3-model-b/)

• 162MHz receiver, such as the Wegmatt dAISy 2 Channel Receiver
• An antenna in the VHF frequency band (30MHz - 300MHz), e.g., Shakespeare QC-4 VHF Antenna
• Optionally, you may want

  • Antenna mount
  • A filtered preamp, such as this one sold by Uputronics, to improve signal range and quality

Another option is free AIS receivers from MarineTraffic. 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 as 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

Below is the antenna hardware setup MERIDIAN uses.

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

Software Setup

AISdb's receiver is a Rust component exposed to Python as aisdb.start_receiver(). It listens for AIS traffic on a UDP or TCP socket, parses the NMEA sentences, and writes the decoded positions and static reports straight into an SQLite or PostgreSQL database. It does not read a serial port directly, so a USB receiver such as the dAISy needs a small bridge program in front of it to forward the serial bytes onto a local network port. mproxy-client, the same crate the AISdb receiver links against internally, does that job.

Install AISdb

On the Raspberry Pi (or whatever Linux box the receiver is plugged into), install Python 3.10 or newer and pull AISdb from PyPI.

pip install aisdb

pip install aisdb ships prebuilt wheels for the common platforms, so a Rust toolchain is not required just to run the receiver. You only need Rust if you are building AISdb from source.

Bridge the serial port to a network socket

1

Connect the receiver

Attach the dAISy (or equivalent) to the Pi over USB, log in, and update the system with sudo apt-get update.

2

Install the Rust toolchain

Needed to build mproxy-client. Run curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh, then log out and back in so cargo is on the path.

3

Install mproxy-client

Install it from crates.io by running cargo install mproxy-client.

4

Create a systemd service

Keeps the bridge running and restarts it if the receiver is unplugged and replugged. Create ./mproxy_client.service, replacing User=ais and /home/ais with the username and home directory on your Pi.

mproxy_client.service

[Unit]
Description="AISdb serial-to-UDP bridge"
After=network-online.target

[Service]
Type=simple
User=ais
ExecStart=/home/ais/.cargo/bin/mproxy-client --path /dev/ttyACM0 --server-addr '127.0.0.1:9921'
Restart=always
RestartSec=30

[Install]
WantedBy=default.target

This forwards whatever the dAISy writes to /dev/ttyACM0 onto UDP port 9921 on the same machine, where the AISdb receiver will be listening. Run mproxy-client --help for the full set of forwarding options if you want to relay to a different host instead.

5

Link and enable the service

Starts the bridge at boot.

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

Run the AISdb receiver

With the bridge forwarding raw NMEA onto 127.0.0.1:9921, point aisdb.start_receiver() at that port. Save this as ./run_receiver.py.

./run_receiver.py

import aisdb

aisdb.start_receiver(
    udp_listen_addr="127.0.0.1:9921",
    sqlite_dbpath="/home/ais/ais_rx.db",
    connect_addr=None,
)

sqlite_dbpath can be swapped for postgres_connection_string if you would rather write straight into PostgreSQL. connect_addr defaults to aisviz.cs.dal.ca:9920, MERIDIAN's public aggregator. Leaving it at the default also merges MERIDIAN's live feed into your own stream, which is convenient if you want a fuller picture of traffic than your antenna alone can see, but set it to None (as above) if you only want the messages your own receiver decodes.

Wrap the script in its own systemd service the same way as the bridge, pointing ExecStart at your Python interpreter and run_receiver.py, and enable it so both services come up together on boot.

💡 Common Issues

For some Raspberry Pi hardware (the Raspberry Pi 4 Model B is a common example), the device file Linux assigns to the receiver is not always /dev/ttyACM0 as used in the systemd unit above.

Check which device file is actually in use.

ls -l /dev

On some boards serial0 is linked to ttyS0 rather than a ttyACM* device.

Simply changing /dev/ttyACM0 to /dev/ttyS0 in the service file may produce garbled AIS sentences, because the default baud rate on that port does not match what the receiver expects. Set the baud rate explicitly.

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