JSON Configuration

AIS-catcher (v0.41+) supports extensive configuration through JSON files, enabling users to tailor the application to their specific needs. This guide provides an in-depth look at the JSON configuration structure, key settings, and best practices to help you effectively set up and manage AIS-catcher.

To start AIS-catcher with a JSON configuration file, use the -C option followed by the path to your config.json file:

AIS-catcher -C config.json

This command instructs AIS-catcher to load and apply the settings defined in config.json.

Basic Structure

A minimal JSON configuration file for AIS-catcher requires the following structure:

{
    "config": "aiscatcher",
    "version": 1
}

• config: Identifies the configuration type. Must be "aiscatcher".
• version: Specifies the configuration version. Currently, only version 1 is supported.

Configuration Keys

Configuration keys are organized into several categories to manage different aspects of AIS-catcher's functionality. Each key has a specific purpose and should be used as per the documentation.

Core Settings

Core but optional settings define fundamental aspects of AIS-catcher's operation.

Key	Type	Description	Documentation
General
config	string	"aiscatcher"
version	number	1
sharing	boolean	Enable community feed sharing	Community Feed
sharing_key	string	Community feed key	Community Feed
Receiver
input	string	Primary input device selection	rtlsdr/hackrf/etc
serial	string	Device serial number
verbose	boolean	Enable verbose output	Console Output
verbose_time	number	Verbose update interval (seconds)	Console Output
screen	number	Screen output mode (0-5)	Console Output
meta	string	Metadata tags (T/D/M)	Console Output
own_mmsi	number	Own MMSI of receiver station
model	object	Decoder model configuration	Model

• config: Must always be set to "aiscatcher" to identify the configuration type.

• version: Defines the configuration file version. Ensure it is set to 1 as this is the currently supported version.

• sharing: Enables sharing of AIS data with the AIS-catcher community feed, allowing others to access your AIS data and vice versa.

• sharing_key: A unique key obtained from aiscatcher.org to easily share your AIS data with the community.

• input: Specifies the primary input device for AIS data (e.g., "rtlsdr", "airspy", etc).

• serial: Defines the serial number of the device to be used. Useful when multiple devices are connected.

• verbose: When set to true, AIS-catcher provides detailed logs and output for debugging purposes.

• screen: Controls the verbosity and format of the console output. Values range from 0 (no output) to 5 (full JSON decoding).

• meta: Metadata tags to include in output. Use "T" for NMEA timestamp, "D" for decoder data (signal power, ppm), "M" for MMSI country info. Can be combined (e.g., "TD", "TDM").

• own_mmsi: Sets the MMSI number of the receiving station. Used for NMEA2000 output and web viewer location sharing.

• model: Configuration object for decoder model settings. See model documentation for available options.

Important Notes

JSON is case-sensitive; all keys must be lowercase. Device-specific sections only configure the device but don't select it - use input or serial for device selection. The active boolean in any section enables/disables that configuration and if ommited it is assumed to be active.

Outputs are often captured in a JSON-array, like for example for udp, to support multiple output channels.

Input Device Settings

AIS-catcher supports various input devices. Each device type has specific configuration options. Below are the supported devices and their respective settings. The documentation of the relevant keys can be found in the Configuration sections. Below we provide a few examples.

RTL-SDR (rtlsdr)

Example

{
    "rtlsdr": {
        "active": true,
        "rtlagc": true,
        "tuner": "auto",
        "bandwidth": "192K",
        "sample_rate": "1536K",
        "biastee": false
    }
}

Full RTL-SDR Documentation

Airspy (airspy)

Example

{
    "airspy": {
        "sample_rate": "3000K",
        "linearity": 17,
        "biastee": false
    }
}

Full Airspy Documentation

Airspy HF+ (airspyhf)

Example

{
    "airspyhf": {
        "sample_rate": "192k",
        "threshold": "low",
        "preamp": false
    }
}

[Full Airspy HF+ Documentation](../configuration/input/airspyhf.md)

HackRF (hackrf)

Example

{
    "hackrf": {
        "sample_rate": "6144k",
        "lna": 8,
        "vga": 20,
        "preamp": false
    }
}

Full HackRF Documentation

SDRPlay (sdrplay)

Example

{
    "sdrplay": {
        "sample_rate": "2304K",
        "agc": true,
        "lnastate": 5,
        "grdb": 40
    }
}

Full SDRPlay Documentation

SoapySDR (soapysdr)

Example

{
    "soapysdr": {
        "active": true,
        "device": "driver=rtlsdr",
        "sample_rate": "1536K"
    }
}

Full SoapySDR Documentation

Serial Port Input (serialport)

Example

{
    "serialport": {
        "baudrate": 38400,
        "port": "/dev/tty0"
    }
}

Full Serial Port Documentation

NMEA2000 (nmea2000)

Example

{
    "nmea2000": {
        "active": true,
        "port": "can0"
    }
}

Full NMEA2000 Documentation

File Input Settings

WAV File (wavfile)

Example

{
    "wavfile": {
        "active": true,
        "filename": "recording.wav"
    }
}

Full WAV File Documentation

Raw File (file)

Example

{
    "file": {
        "active": true,
        "filename": "data.raw"
    }
}

Full File Documentation

Network Input Settings

TCP Client (rtltcp)

Example

{
    "rtltcp": {
        "host": "192.168.1.100",
        "port": 12345
    }
}

Full TCP Documentation

SpyServer (spyserver)

Example

{
    "spyserver": {
        "host": "server.example.com",
        "port": 5555
    }
}

Full SpyServer Documentation

UDP Server (udpserver)

Example

{
    "udpserver": {
        "active": true,
        "port": 10110
    }
}

Full UDP Documentation

ZMQ (zmq)

Example

{
    "zmq": {
        "active": true,
        "endpoint": "tcp://localhost:5555"
    }
}

Full ZMQ Documentation

Multi-Receiver Configuration

For multiple receivers, you can move the relevant above settings to a receiver array as in this example starting two receivers:

{
    "config": "aiscatcher",
    "version": 1,
    "receiver": [
        {
            "input": "airspy",
            "airspy": {
                "sample_rate": "3000K"
            }
        },
        {
            "input": "rtlsdr",
            "serial": "ais",
            "rtlsdr": {
                "bandwidth": "192k"
            }
        }
    ]
}

Output Settings

AIS-catcher supports various output channels. Each output channel has specific configuration options. The documentation of the relevant keys can be found in the Configuration sections with some JSON examples below.

Web Viewer (server)

Example

{
    "server": [
        {
            "active": true,
            "port": 8100,
            "station": "My Station",
            "share_loc": true,
            "lat": 52,
            "lon": 4.3
        }
    ]
}

Full Web Server Documentation

UDP Output (udp)

Example

{
    "udp": [
        {
            "active": true,
            "host": "192.168.1.235",
            "port": 4002,
            "filter": false,
            "allow_type": "1,2,3,5,18,19,24"
        }
    ]
}

Full UDP Documentation

TCP Output (Client) (tcp)

Example

{
    "tcp": [
        {
            "active": true,
            "host": "5.9.207.224",
            "port": 12,
            "keep_alive": false
        }
    ]
}

Full TCP Documentation

TCP Output (Server) (tcp_listener)

Example

{
    "tcp_listener": [
        {
            "active": true,
            "port": 5012
        }
    ]
}

Full TCP Documentation

HTTP Output (http)

Example

{
    "http": [
        {
            "active": true,
            "url": "http://example.com/ais",
            "interval": 10,
            "response": "json"
        }
    ]
}

Full HTTP Documentation

MQTT Output (mqtt)

Example

{
    "mqtt": [
        {
            "active": true,
            "host": "mqtt.example.com",
            "port": 1883,
            "topic": "ais/messages",
            "username": "user",
            "password": "pass"
        }
    ]
}

Full MQTT Documentation