Aisdispatcher.pl Submit your AIS data to aggregation services

Do you roam in areas where MarineTraffic and ShipFinder have no coverage? Do you have an AIS transponder/receiver on board and access to internet? Then you could become an AIS station and cover the area around your ship. I wrote a Perl script to make that happen, in this article you will find the information you need.

Why participate?

Why would you submit your AIS data to AIS aggregators like MarineTraffic or ShipFinder?

• Friends and relatives often consult MarineTraffic or ShipFinder to find out where you are. This works usually fine if you are in a well developed densely populated area, but when you are roaming in tropical waters there is usually no coverage and this is when your aunt starts inquiring why you are no longer on MarineTraffic. If you don't want to be found, fine, but then you'd better switch off your AIS regardless because governments trace your AIS signals with satellites and don't rely on MarineTraffic. But if you like to be "on the map" and make your aunt happy, you can make that happen. As a bonus, you will make the other boats within range of your AIS visible on the map as well.

• As a reward, MarineTraffic and other aggregation organisations will give you some benefits, like a free premium membership or a free map with a track to include on your blog. Consult their respective websites for more information about this.

• It helps with troubleshooting. You will get some idea how well your AIS is functioning by comparing your coverage to that of other boats. It happens often that your once very well working AIS became somewhat deaf over time, due to corroding antenna connectors or whatever. With the help of AIS aggregators the problem is easy to spot, because they show your coverage on the map, and if it starts shrinking over time, you know you have a problem. Your coverage may also be asymmetric, due to interference with nearby objects (like the mast). In area's where they already have coverage you can easily see what you should be seeing and what you are actually seeing. Again, if you fail to register quite a lot of boats, you know you have a problem.

• It is fun. When we were on the Cape Verdes, we used our long range WiFi system to connect to a hotel where we had previously ordered a cup of thee and obtained the WiFi password "to look on WhatsApp" while sipping our thee. Back on the boat, we connected again and our system was feeding our AIS data to MarineTraffic. Just at that moment the ARC (Atlantic Rally) came around the corner, a few dozen boats where visible on our AIS and thus on MarineTraffic. I flipped the switch, and they disappeared from MarineTraffic. And I flipped it again, and there they were again. Probably a lot of people where watching the progress of "their team" on MarineTraffic and we were feeding it to them with our "stolen" WiFi connection from the hotel miles away. It is somehow funny to have this influence over the "rest of the world" while you are in a solitude anchorage, drinking a beer while watching the screen.

How to participate?

You probably already have most of the ingredients to make it happen:

• An AIS transponder/receiver. Anyone works. They all feed their received information to the chartplotter with an NMEA output, and this output is what you need.
• A computer to run the software. You can use your laptop, your computer that runs OpenCPN, or a Raspberry Pi which only consumes 100mA of current but can do a lot of interesting things for your boat. An AISdispatcher has low memory and CPU demands and just runs in the background, so any computer will do just fine.
• An internet connection. AIS data is extremely low bandwidth, so it won't cost you much data and a slow and intermittent connection is sufficient. A typical AIS class-B message is about 50 bytes and sent only once per 3 minutes when the boat is not moving. This is 1kB per boat per hour. You need to receive 40 boats continuously to accumulate it to 1MB per day.
• A free subscription with one or more AIS aggregators. After you fill in your details, they will send you an email with the IP and PORT number for you to use.
• The software to capture the AIS data and forward it to the aggregation service. There is a program called "AISdispatcher" that can be downloaded for free. I wrote a Perl script with an almost similar name "AISdispatcher.pl", and I think it is more suitable for cruisers and easier to use.

AIS aggregators

MT screenshot. AIS Source: 4792 ZwerfCat

While writing this article I had some interesting and sometimes frustrating experiences with the aggregation services I tried to submit my data to. The overview below is not a full review but only covers the suitability to submit AIS data by the sailing community.

MarineTraffic

MarineTraffic is the most well known AIS aggregator, and as it turned out, for a reason. They have well written instructions on their website. After entering all our information, within a few days our boat and the boats we were receiving on our AIS where correctly depicted on their map, and it is a nice gesture that for each boat they reveal the AIS source. I was happy to discover that I could enlist my AIS station as a roaming station, by simply entering our MMSI. Now when we are sailing to another spot, the "AIS station" on the map moves along. The only shortcoming of MarineTraffic is that it is the only aggregator in this list who doesn't understand NMEA tagging, which is used for the AISdispatcher.pl --sid option.

MyShipTracking

MyShipTracking has an easy to use website. Interestingly, they were already receiving our data before we were even supplying it to them, so they clearly got it forwarded from one of the other aggregators we were already feeding. They already had a picture of our boat (with a MarineTraffic copyright mark on it). Instructions were easy to find. Just like MarineTraffic, they understand the concept of a roaming AIS station. As a bonus, they can relay your information to one other configurable aggregator so it can save you on bandwidth. They have an easy to use interface and provide lots of statistical information about your AIS performance.

FleetMon

FleetMon is a heavy website with lots of animations and high resolution graphics, sometimes even starting unsollicited movie playbacks. It might look pretty but is not ideal for the cruisers who have a limited data plan and are notoriously low on bandwidth. FleetMon also offers instructions about setting up a station, but after creating an account (for which I even had to change some settings in the browser "for security reasons"!) I was unable to complete setting up the station. After e-mail consultation they set it up for me, and they put my "antenna" on a random place on the map. On the "station status" page we got a whooping AIS reception range of 1200nm, but I guess that had something to do with our random antenna location. Although FleetMon is clearly using our data, I find it hard to find the relevant data and on one page they put a crude oil tanker named "Wu Yi San" - for this occasion sailing under Dutch flag - on our position on the map.

VesselFinder

VesselFinder also has a welcoming page with instructions to add an AIS station. After I did this, I could see on their Station Status page that they were receiving our data... however, they still had ZwerfCat positioned in Amsterdam while we left there almost three years ago, and kept ignoring our questions about this. After almost a week we received an e-mail in which they made clear that they are not interested in the help of the growing community of internet equipped sailing boats to put remote areas like the South Pacific islands on their map.

AISHub

VesselFinder shows our latest position in Durgerdam (NL) on the 4th of October 2020! That's hilarious; we've left the Netherlands in September 2018 and at October the 4th 2020 we were in Tikehau (oops VesselFinder, that's on the other side of the world!)

AISHub has an interface quite similar to VesselFinder and clear instructions and after we submitted our data they confirmed that they were receiving our feed and upgraded our account. They also noted that they were forwarding our feed to VesselFinder. Alas, it seems they have the same problem as their apparent partner: they are receiving our data but it doesn't result in any of "our" boats appearing on their map.

ShipFinder

ShipFinder is a clean site, easy to navigate with no commercial options. You can't make an account but you don't need an account. The instructions were easy to find and after submitting our feed to their advertised ip:port we were on their map. Simple, clean and fast. The only drawback for not having an account for me as a feed supplier is that they don't know who is sending which data, hence there is no station status page and they can's show who is responsible for the boats you are seeing. So you won't know whether they are actually using your data, unless of course, like in our situation, you happen to be the only AIS source in the whole area. In AISdispatcher.pl I implemented an option to add a "Source ID" to the AIS data, if they would listen to it they would know who is supplying which data without the need for an account.

AISdispatcher.pl

Many people successfully use a program called AISdispatcher, but I had problems go get it working (something with an incompatible 'glibc' version), so I wrote my own program and tailored it more to what we liveaboards need.

Highlights

• Open source. There are no secrets here, AISdispatcher.pl is not abusing its connection privilege to silently submit your financial information to some obscure Chinese IP-address. Everybody who understands programming can see what it is doing and probably even improve the code.
• Platform independent and unobtrusive. It is a simple Perl script, just one file, with no other dependencies than that you must have the Perl interpreter installed. It doesn't mess up your system: If you don't like it anymore, no risky uninstall procedure needed, just delete that single file. The required Perl interpreter is by default installed on Linux and Mac computers, and many people have it unknowingly on their Windows computers as well, and otherwise it is free to download and easy to install.
• Low data usage. AISdispatcher.pl filters and downsamples your NMEA stream and only forwards the absolute minimum to paint you on the map. It has a smart data saver, it only throttles down MMSI's which are sending updates too frequently. See also Technical notes.
• Transparency. It shows exactly what it is receiving, and it shows exactly what it is sending after filtering and downsampling.
• Privacy. Although it goes against the idea of AIS broadcasts, if you feel that you should only forward AIS data about your own ship, you can tell AISdispatcher.pl not to reveal anyone else's positions.
• Lightweight and simple. It assumes you already have the AIS transponder somehow connected to a computer, so it has no low level connection capabilities by itself and is AIS brand and type independent.
• Source ID tagging. AISdispatcher.pl is able to add a "signature" to its outgoing data, which can be used by aggregators to determine who is sending which data.

Input sources

AISdispatcher is written with the assumption that you are not building a dedicated system to capture AIS data and submitting it to aggregation services, but that you already have a working AIS infrastructure and simply want to extend it with an AIS forwarder. Usually, you can use one of the following methods, in order of preference:

UDP

NMEA data can be streamed over WiFi. Usually this is done by UDP over port 10110. If you don't stream your NMEA data over WiFi, I strongly recommend you to start doing so. The benefits are that any computer logged on to your private WiFi network has access to your NMEA data, which includes your position, wind and depth data, AIS data, etc. This means that you can run OpenCPN on any laptop or even Android phones, without a physical connection to your boat devices. There are several hardware devices that can do this, I use one from ShipModul.

If you have NMEA data broadcasted on your own network, use 0.0.0.0 as IP address and add the port number, which is usually 10110. The input source is thus specified as "0.0.0.0:10110", like this:

perl aisdispatcher.pl 0.0.0.0:10110

OpenCPN

You probably have OpenCPN, and otherwise this is just another marvel of software I strongly recommend. Assuming that you have setup OpenCPN to have access to your AIS data, you can easily forward it from OpenCPN to AISdispatcher.pl. Go to the connections tab, and add an UDP output connection.

Make sure the connection looks exactly like this!

In this case, the AISdispatcher.pl input source is specified as "127.0.0.1:10110", like this:

perl aisdispatcher.pl 127.0.0.1:10110

Note that 127.0.0.1 is not an arbitrary value but means "localhost" which you can read as "this computer". You can also use OpenCPN to forward the data to another computer but this is beyond the scope of this manual.

GPSD

GPSD is often used as an intermediate between your physical GPS/AIS hardware device and software clients on Linux, Android systems, driverless cars, aircraft, etc. Assuming that you run AISdispatcher.pl on the computer running GPSD, you use the input source "--gpsd 127.0.0.1:2947", like this:

perl aisdispatcher.pl --gpsd 127.0.0.1:2947

The "--gpsd" option is used to let AISdispatcher.pl know that the input is coming from GPSD. The GPSD connection is by TCP, so the --gpsd option automatically includes the --tcp option as well.

Using AISdispatcher.pl

On Linux systems (skip this if you use Windows), set the executable flag with:

chmod a+x aisdispatcher.pl

First you should verify that AISdispatcher.pl successfully connects to the input source and that it is receiving data. Run AISdispatcher in the terminal with the input source applicable to your system, but no outputs, like this:

perl aisdispatcher.pl 0.0.0.0:10110

If everything is working as intended, you should see a steady stream of NMEA data on the screen. End the program with Ctrl-C once you get bored.

Now it is time to test run without actually sending out any data, by using the --test option. You can specify the output to the aggregation services to make the test more realistic. You should have received a specific IP address and PORT number to forward the data to. Add these to the command line, like this:

perl aisdispatcher.pl --test 0.0.0.0:10110 1.2.3.4:555

You can enter multiple aggregation addresses. The output on the screen should be different now, with only the filtered relevant NMEA messages. Depending on the amount of boats you are reporting, it can take up to three minutes before at least your own boat is reported. The AIS message should start with "!AIVDM".

The first number on the line is the MMSI number of the boat sending the AIS message. The MMSI of ZwerfCat is 244090716. We just started receiving position updates from a boat with MMSI 367516290, and just a few moments later it broadcasted a static data report which contains the encoded boat name.

If you run the program with the default interval set, you will see that AISdispatcher.pl maintains a table with records for each individual MMSI number. New MMSI numbers will be added when they present themselves, and if they send too many position updates, some of them will be rejected. Again, once you get bored, it is time for the next step.

Run the program again but this time without the --test option. You should wait some minutes and then go to your "station page" on the respective aggregation site(s). They should report receiving data from you! Note that your boat won't be immediately visible on their public map or mobile phone app. Apparently, your data is first scrutinized to see if it correlates with other sources before it is made public, which can take a few days.

If all is working as intended, you can now make the installation final. The following command should be somewhere on your system so that it will run automatically when you start the computer. The option --daemon is used to specify that it should run as a service in the background.

perl aisdispatcher.pl --daemon 0.0.0.0:10110 1.2.3.4:555

Note that in daemon mode you won't get any screen output while it is running. If you want to have a peek about what is going on, you can run AISdispatcher.pl again with the --test mode while the daemon is still running in the background.

Command line options

Usage: perl aisdispatcher.pl [OPTIONS] <SOURCE IP:PORT> [<UDP TARGET IP:PORT> ...]

--help

This option displays a small help screen

--tcp

This specifies that the input source is TCP. If you can choose between UDP (the default) and TCP, always try to use UDP. In most cases TCP is better, but in this specific case UDP is the way to go. For the output channels, UDP is always used because this is what all the aggregation services use.

--gpsd

This specifies that the input source is GPSD. It includes the --tcp option because GPSD always uses TCP.

--ownship

Most AIS receivers have a special NMEA message to indicate the position of your own ship. If you have an AIS transceiver, its own broadcasted AIS signal is already included in the standard messages, so the ownship messages are filtered out. I'm not sure however how AIS receiving only devices handle this (but you should not use them on a ship anyway) but if your stream shows other boats but not your own, you can use the option --ownship to specifically include the own position messages.

--justme

If you only care about your own boat position on the map, or are worried about the privacy of your fellow boaters, or want to cut down even more on your data consumption, you can use the --justme option. In that case only information about your own boat will be revealed.

--interval=<SECONDS>

By default AIS position updates from individual MMSI's are not sent more frequently than 25 seconds apart. You can change this value to anything you like. Anything less than 4 seconds disables the position update throttling (and saves some CPU and memory usage). Try to avoid values that are a multitude of 30, as this interferes with the AIS favored 30 seconds or minute intervals. For more information about this see the Technical notes

--sid=<SOURCE ID>

With this option you can add a marking to your outgoing data so the aggregator can identify you as the source. SOURCE ID is an alphanumeric string of maximal 15 characters, for ships I would suggest to enter your MMSI number in this field. All aggregators understand --sid, except for MarineTraffic. If you feed to MarineTraffic together with other aggregators, specify the MarineTraffic HOST:IP first, then specify the --sid option, and then the other aggregators. For more information and possible uses of this option see the Technical notes

--test

If this option is used, AISdispatcher.pl will work in normal mode, except that it does not actually send out any data. With this option you can run AISdispatcher.pl while another instance is running in daemon mode.

--daemon

If this option is used, the program terminates but leaves a service running in the background. Note that in this case you can not run a second instance of AISdispatcher.pl from the command line (except with the use of option --test), because otherwise you would be feeding all information to the aggregation services twice.

Technical notes

Filtering

In contrast to some other AISdispatcher software, AISdispatcher.pl actually decodes the AIS messages and applies some smart filtering.

1. All non AIS-related NMEA messages are filtered away.

2. The remaining AIS-related messages are filtered. Only the following AIS messages types remain:

   • 1,2,3: Standard class-A position report
   • 5: Static and voyage related data
   • 9: Standard SAR aircraft position report
   • 18: Standard class-B position report
   • 19: Extended class-B position report
   • 24: Static data report

3. The frequency of AIS update reports is depending on the situation. For a class-B station at anchor, it drops down to one message per 3 minutes. However, for a fast or turning class-A station, the updates will be broadcasted only 2 seconds apart! This might be great for navigational purposes, however it is not in the interest of the typical MarineTraffic user to get so many updates and it is just a waste of your data. To alleviate this, AISdispatcher.pl maintains a list of all MMSI stations and times of their most recent updates. If MMSI stations are sending position update reports (message type 1,2,3 or 18) more frequently than the interval value (default 25 seconds) it will downsample only those position updates of these specific MMSI numbers.

Note that the smart filtering requires a bit more CPU and memory, so if you run AISdispatcher.pl on a memory or CPU constrained system, you might switch it off with "--interval=0" at the expense of a bit more data consumption in high traffic areas.

Interval

A bit more information about sensible values for the --interval option. By default, a class-B AIS transponder broadcasts a position update every 30 seconds when the boat is sailing. To avoid recurring broadcast collisions with nearby other boats this interval is intentionally slightly variable. If you would instruct AISdispatcher.pl to only allow position updates once in every 30 seconds, then when the transponder is giving one update slightly faster it will be rejected because it is "too soon", and during the next interval when the transponder might use a slightly longer interval it will be accepted. This causes the update frequency on the output of AISdispatcher.pl to look somewhat erratic with half of the time a rejected position update. With an interval which is set somewhat lower than the transponder interval, you won't have this problem, and that is why the default is set at 25 seconds. Consequently, if you wish to allow only a position update once per minute, specify an interval of 55. Don't set the interval too long, because at some point the aggregation service will see the updates as "glitches" rather than a steady stream of position updates, and they might flag your station as "low/poor coverage". I think that an update frequency of 3 minutes (use --interval=170) would still be acceptable, but note that due to the nature of AIS you might sometimes miss a transponder update, so in reality the updates could become longer apart.

Relaying

If you are feeding multiple aggregation services, your data consumption goes up with each additional target aggregation service. One way to overcome this is to setup a shore bound relay. There are two ways to achieve this:

1. Assuming you have access to a computer running somewhere ashore, with a fixed IP address, you could setup AISdispatcher.pl on your boat to forward your AIS data only to the IP:PORT of your shore station (as if it is an aggregation service). If you need to use option --sid, do this not on your boat but on the shore computer. On the shore station you run AISdispatcher.pl with its input listening to your boat output, and with the multiple final aggregation targets as its own outputs. On the shore station use --interval=0 and no further options (except for --daemon and/or --sid), because the filtering is already done on your boat. Of course the output HOST:IP of your boat should match the input HOST:IP of your shore station, and you will have to setup the router of your shore station to forward the relevant port to the computer running AISdispatcher.pl, and if you have a firewall installed you have to configure it as well.

2. You can use a relay on our ZwerfCat server for a small fee. Ask us for more information if you are interested.

Source ID (--sid)

With this option you can add a marking to the outgoing data. It uses the NMEA 4.0 tag block. The following is prepended to the NMEA sentence:

\s:<SID>*<NMEA CHECKSUM>\

According to the NMEA 4.0 specs, this should be accepted by NMEA interpreters, and indeed, almost all AIS aggregators do, with the notable exception of MarineTraffic.

The Source ID feature can be used as extra safety, if the AIS aggregator uses it for authentication, it becomes harder to submit bogus AIS data in someone else's feed data port.

Also, it can be used in cases where just one UDP port accepts data from anyone. With the Source ID feature it is still possible to distinguish between different AIS stations.