Web Viewer

AIS-catcher -N port [setting value] ...

AIS-catcher includes a simple web interface. A live demo is available for East Boston, US. The web interface gratefully uses the following libraries: chart.js, chart.js annotation plugin, leaflet, Material Design Icons, tabulator, marked and flag-icons.

Make sure you use the latest version and start the web viewer as follows:

AIS-catcher -N 8100

where 8100 is the port number. If your machine network name is raspberrypi, e.g., then enter raspberrypi:8100 in your browser. On the web page, you will find several sections with information related to the station and received messages.

For users wishing to include a station name and a link to an external website in the Statistics section:

AIS-catcher -N STATION Southwood STATION_LINK http://example.com

This could be a useful option if you want to offer the interface externally. To display the reception range and distances from your station, provide the program with the station coordinates and permission to share the location with the web viewer:

AIS-catcher -N LAT 50 LON 3.141592 SHARE_LOC on

The last option share_loc (default is off) will allow the web viewer to access and display the location.

The user can make a page in markdown format. The content will be shown in the About tab of the web viewer:

AIS-catcher -N 8100 ABOUT about.md

All these options can be captured in the configuration file (in a section with name server), see below.

Menu structure

The main menu behind the hamburger icon in the top left corner navigates between different functional areas. Context-sensitive menus, accessible through right-click, long press on iOS, or the vertical dot icon on the map, offer more functionalities. Here you can set options like activating the "dark mode" theme, displaying the station range on the map, locking/unlocking the map center, toggling text-only ship labels, decluttering ship labels, and viewing details of the last message received from a vessel, amongst others.

Visualization

When AIS-catcher receives data containing a vessel's dimensions but can not determine the direction it is pointing (heading), it will display a circle that accommodates the ship's dimensions regardless of heading. Missing heading information is common for Class B ships. If there's a decent approximation available for the heading, such as course-over-ground above certain speeds, it will be used. Shapes plotted using this approximation will have a dashed border, indicating incomplete information. An example is the USS Constitution docked in Boston.

In the map section, clicking on a vessel will open a ship card with details of the vessel. For smaller screens it can be minimized in the top bar (via the ^ symbol or by clicking on the header bar). The ship card will open minimized on mobile devices. In its maximized form, users can choose which rows will be visible in the minimized state. Additional options, such as looking up the vessel on aggregator sites, are available by clicking the three-dot icon on the ship card header.

Validation

The web-interface shows a "validation" indication at the left border of the ship card header.

AIS-catcher analyzes an enormous stream of bits per day for both AIS channels (2 to the power 33 to be precise). To avoid erroneous messages, the AIS system employs a 16-bit CRC and matching of other bit patterns. Unfortunately, purely statistically this cannot prevent that there will be an occasional technically correct but nonsense message. These are typically easy to recognize (e.g. looking at the signal level, and location on the map) and aggregator sites like MarineTraffic will filter these out.

To reliably measure the reception range for the station in the web interface, AIS-catcher has implemented a "validation function" that checks the location of the vessel for consistency between messages and flags if there is an inconsistency. Practically speaking, if we receive a position from an MMSI that is relatively close to the last received position, the "validation" indicator will be green and the distance to the station will be included to determine the station range. Please note that messages within 50 NMi from the receiving station will always be included for range setting. The validation indicator will be grey if validation for the location cannot be performed and red if it is not successful.

Plots

The Plot section contains several visualizations to assess the performance of the receiver:

Restarting AIS-catcher typically erases history in the graphs. To retain plot "state" and backup the information to a file use the following:

AIS-catcher -N 8100 FILE stat.bin BACKUP 10

This will back up the plots when the program closes and every 10 minutes in a file stat.bin. The minimum backup interval is 5 minutes.

Custom plugins and styles...

To give the user the option to tweak the look-and-feel and functionality of the web viewer and/or modify for example the color scheme or regional preferences, the program provides the option to inject custom plugins (JavaScript) and CSS into the website, with a command like:

AIS-catcher -N 8100 PLUGIN plugin1.js PLUGIN plugin2.js STYLE mystyle.css

You can also include all plugin files from a specific directory using the command:

AIS-catcher -N 8100 PLUGIN_DIR /usr/share/aiscatcher/plugins

Files need to have the extension .pjs and .pss for respectively JavaScript and CSS style plugins. The repository includes a few example plugins that demonstrate how to add additional maps or cater to regional preferences. Examples of plugins can be found in another GitHub repository.

Offline web viewer

There is an option to run the web viewer without relying on online libraries. This facilitates using the web interface whilst traveling without an internet connection. The steps are simple. First, go to your home directory (say /home/jasper) and clone the necessary offline web assets:

git clone https://github.com/jvde-github/webassets.git

This will create a directory webassets that we need to share with AIS-catcher as an alternative location for online web content with the CDN argument followed by the location of the web assets directory:

AIS-catcher -N 8100 CDN /home/jasper/webassets

Offline maps can also be included in mbtiles format:

AIS-catcher  -N 8100 MBTILES filename

or as an overlay

AIS-catcher  -N 8100 MBOVERLAY filename

Sending data to Prometheus for use in Grafana dashboards

You can add the option PROME on to the web configuration command to start rendering Prometheus-compatible statistics at /metrics. For example:

AIS-catcher -N 8100 PROME on

For more information on how to configure Prometheus and Grafana to get an initial dashboard, see README-grafana.md.

Summary Settings

Server Options:

Key	Type	Default	Description
PORT	integer	-	Single port for web server
PORT_MIN	integer	-	Minimum port in binding range
PORT_MAX	integer	-	Maximum port in binding range
IP_BIND	string	-	Server binding IP address
REUSE_PORT	boolean	false	Enable port reuse
ZLIB	boolean	true	Enable response compression
Location Settings
LAT	float	-	Station latitude
LON	float	-	Station longitude
SHARE_LOC	boolean	false	Share station location
USE_GPS	boolean	false	Use GPS data
OWN_MMSI	integer	-	Own vessel MMSI
Data Management
HISTORY	integer	-	History retention (5-43200 sec)
CUTOFF	integer	-	Data retention threshold (0-10000)
BACKUP	integer	-1	Backup interval (5-2880 min)
FILE	string	-	Statistics file path
REALTIME	boolean	false	Enable real-time updates
Output Formats
KML	boolean	false	Enable KML output
GEOJSON	boolean	false	Enable GeoJSON output
PROME	boolean	false	Enable Prometheus metrics
MESSAGE	boolean	false	Enable message saving
UI Customization
STATION	string	-	Station display name
STATION_LINK	string	-	Station info URL
CDN	string	-	Local CDN resources path
MBTILES	string	-	Offline map in mbtiles format
MBOVERLAY	string	-	Offline overlay in mbtiles format
PLUGIN	string	-	JavaScript plugin path
STYLE	string	-	CSS style path
PLUGIN_DIR	string	-	Plugins directory
ABOUT	string	-	About page path