Raspberry Pi Marine Traffic server

Warning!

This page is very out of date! A new howto for kplex and marinetraffic is currently being prepared based on some recent (Sept. 2020) investigations with marinetraffic. This should be available by October 2020

Objective

This page describes how to use a Raspberry Pi and kplex to send AIS data to Marine Traffic. The instructions here are actually valid for any POSIX-like system. At the time of writing pre-compiled kplex debian packages are only available for ARM (e.g. raspberry pi) and x86_64 although the source should compile on other versions of Linux, FreeBSD and MacOS X. See the installation instructions for full details.

Pre-requisites

You will need:

• AIS receiving equipment (See the Marine Traffic instructions for further details.
• Raspberry Pi installed with the latest Raspbian OS (or other computer running a POSIX-like OS), connected to the Internet
• kplex, installed according to the installation instructions.
• A port number which Marine Traffic will provide you with when you register with them to cover your area

Putting it together

A more complete tutorial on creation of an NMEA server is given in this tutorial which includes information on the options for connecting your AIS receiver to the pi. Briefly though, if the AIS receiver has USB output, plug this into the pi's USB port. If you have a 9 pin serial output, connect that to a serial to USB converter and plug that into the pi's USB port. If you have bare wires only, refer to the tutorial. If you only have one USB serial device plugged into the pi, this will normally be accessible through the logical device "/dev/ttyUSB0".

The connection to marine traffic is outbound from your computer, so you don't need to assign a fixed IP address to the pi. The default Raspbian installation will instruct the pi to obtain an address from a DHCP server.

Device Permissions

For simplicity, this tutorial explains how to run kplex as root. This is not the optimal configuration in an environment where security is a concern. If running kplex as a non-root user you will need to edit the kplex start script and ensure that the user kplex runs as has access to the AIS serial device as explained here.

kplex configuration file

All we need to do is customise kplex's configuration file and instruct the OS to start kplex at boot time. If we have our AIS receiver connected at 38400 baud on /dev/ttyUSB0 and we have been assigned port 5321 by marine traffic, the minimal configuration for /etc/kplex.conf looks like this:

[serial]
filename=/dev/ttyUSB0
baud=38400
direction=in
[tcp]
address=5.9.207.224
port=5321
persist=yes
direction=out

Change the "port=" line according to the port which Marine Traffic Assigns you.

Note that this establishes a TCP connection to Marine Traffic rather than a UDP connection as described in tutorials for other software. Marine Traffic supports both types of connection. TCP gives reliable data transmission over a wide area network unlike UDP, but at the expense of a greater overhead. The "persist=yes" directive tells kplex to attempt to re-establish a lost connection, for example if the marine traffic server reboots. If using kplex 1.1 (beta) or later, add the following to the [tcp] stanza to ensure that connections lost because of lost NAT mappings between you and marine traffic are restarted.

keepalive=yes

Update: Feb 2016

kplex now supports UDP unicast. To configure your connection to Marine Traffic as unicast UDP replace the [tcp] stanza above with:

[udp]
address=5.9.207.224
port=5321
direction=out
coalesce=yes

"coalesce=yes" is optional. If specified kplex attempts to send all parts of a multipart AIS message in a single UDP packet in order to reduce data transmitted.

Optimisation

kplex supports rate limiting for sentence types but does not support AIS downsampling, in other words it will not retrict the AIS information supplied from particular vessels. If your AIS receiver outputs sentences other than AIVDM/AIVDO you can tell kplex only to send AIVDM (and AIVDO if relevant) to marine traffic. To just send AIVDM sentences to marine traffic add the following to the "[tcp]" section of kplex.conf:

ofilter=+AIVDM:-all

To send only AIVDM and AIVDO:

ofilter=+AIVDM:+AIVDO:-all

Connecting to other services

kplex can send your data to multiple services and also make it available on your local network. Full configuration details are available in the kplex configuration guide. To send data to a service similar to marine traffic, simply replicate the section under "[tcp]" in the example above at the end of the file but using the address and port of the other service.

To create a tcp server which is accessible on your local area network and makes AIS data available to client applications such as OpenCPN, add the following section to the configuration file:

[tcp]
mode=server
port=10110

This makes your data available on tcp port 10110 on all network interfaces of the pi. See the discussion on the address to use to contact the pi in the NMEA server tutorial if you didn't assign a fixed IP address to the pi.

If your machine is directly connected to the Internet without a firewall be aware that there is no password or other access control on the tcp server which kplex creates.

To distribute your data via IPv4 UDP broadcast on port 10110, you can append the following declaration to kplex.conf:

[bcast]
device=eth0
port=10110
direction=out

If your pi is connected to the network via a wireless dongle, replace "eth0" with "wlan0" or other name of the device you are using.

Putting it all together, assume we want to send our data to marine traffic as above, sending only AIVDM sentences and also creating a tcp server which we can connect client applications to on our local area network:

[serial]
filename=/dev/ttyUSB0
baud=38400
direction=in
[tcp]
address=5.9.207.224
port=5321
persist=yes
direction=out
ofilter=+AIVDM:-all
[tcp]
mode=server
port=10110

Enabling kplex to start at boot

As discussed in more detail in the NMEA server tutorial, to enable kplex to start at boot, run the following command:

sudo update-rc.d kplex defaults

To start kplex without rebooting you can then run:

sudo serice kplex start