JSON Configuration¶

AIS-catcher (v0.41+) supports extensive configuration through JSON files. This guide describes the JSON structure, key settings, and common patterns.

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 loads and applies the settings from the JSON file.

Basic Structure¶

A JSON configuration file always starts with the configuration header:

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

Where:

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

This is the absolute minimal structure (just the first two keys). If no receiver is configured, AIS-catcher will use the default behaviour for selecting an input device.

To select the RTL-SDR as an input device:

{
    "config": "aiscatcher",
    "version": 1,
    "receiver": [
        {
            "input": "rtlsdr"
        }
    ]
}

Note: older configurations allowed receiver selection at the root level (e.g. input, serial). This is legacy and may disappear in a future release. Prefer defining receivers in the receiver array. ¹

Important Notes¶

JSON keys are case-sensitive and must be lowercase.
CLI setting names are not case-sensitive.
Define receivers in the receiver array (even for a single receiver).
Device sections (e.g. rtlsdr, airspy, hydrasdr) configure the device, but do not select it. Use input (and optionally serial) inside each receiver object.
active is optional in any section; if omitted, it is assumed to be true.
Outputs like udp are arrays to support multiple output channels.

Configuration Keys¶

Configuration keys are grouped below by purpose.

General Overview¶

General (mostly optional) settings define fundamental aspects of AIS-catcher's operation.

Root-level keys¶

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 array
`receiver`	array	List of receiver objects (recommended even for a single receiver) ¹	Receiver configuration
Output channels
`server`	array	Web viewer configuration	Web Viewer
`udp`	array	UDP output configuration	UDP Output
`tcp`	array	TCP output configuration (client)	TCP Output
`tcp_listener`	array	TCP output configuration (server)	TCP Output
`http`	array	HTTP output configuration	HTTP Output
`mqtt`	array	MQTT output configuration	MQTT Output

Receiver configuration (`receiver` array)¶

The root-level receiver key contains an array of receiver objects. This is the recommended structure going forward.

Receiver object keys¶

Each entry in the root-level receiver array is a receiver object. These keys live inside each receiver object:

Key	Type	Description	Documentation
`input`	string	Selects the input device type for this receiver (e.g. `rtlsdr`, `airspy`, `hydrasdr`, `spyserver`, ...)	Input Overview
`serial`	string/number	Receiver identifier (recommended; also used to target per-receiver CLI overrides in some setups)
`verbose`	boolean	Enable verbose output for this receiver	Console Output
`verbose_time`	number	Verbose update interval (seconds) for this receiver	Console Output
`screen`	number	Screen output mode (0-5) for this receiver	Console Output
`meta`	string	Metadata tags (T/D/M) for this receiver	Console Output
`own_mmsi`	number	Own MMSI of receiver station
`<device section>`	object	Device-specific configuration object matching `input` (e.g. `rtlsdr`, `airspy`, `hydrasdr`, ...). See examples in Input Device Settings.	Input Overview
`model`	object	Decoder model configuration for this receiver	Model

Multi-receiver example¶

Example with two receivers:

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

In this example, each receiver selects a device via input, is optionally named via serial, and is configured via its device section (e.g. rtlsdr, airspy, hydrasdr).

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

HydraSDR (`hydrasdr`)¶

Example

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

Full HydraSDR 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

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

Legacy configurations may use root-level input / serial to define a single receiver. This still works in some versions, but is discouraged and may be removed in a future release. Prefer putting input (and serial) inside each receiver object under receiver. ↩↩

JSON Configuration¶

Basic Structure¶

Important Notes¶

Configuration Keys¶

General Overview¶

Root-level keys¶

Receiver configuration (receiver array)¶

Receiver object keys¶

Multi-receiver example¶

Input Device Settings¶

RTL-SDR (rtlsdr)¶

Airspy (airspy)¶

HydraSDR (hydrasdr)¶

Airspy HF+ (airspyhf)¶

HackRF (hackrf)¶

SDRPlay (sdrplay)¶

SoapySDR (soapysdr)¶

Serial Port Input (serialport)¶

NMEA2000 (nmea2000)¶

File Input Settings¶

WAV File (wavfile)¶

Raw File (file)¶

Network Input Settings¶

TCP Client (rtltcp)¶

SpyServer (spyserver)¶

UDP Server (udpserver)¶

ZMQ (zmq)¶

Output Settings¶

Web Viewer (server)¶

UDP Output (udp)¶

TCP Output (Client) (tcp)¶

TCP Output (Server) (tcp_listener)¶

HTTP Output (http)¶

MQTT Output (mqtt)¶

Receiver configuration (`receiver` array)¶

RTL-SDR (`rtlsdr`)¶

Airspy (`airspy`)¶

HydraSDR (`hydrasdr`)¶

Airspy HF+ (`airspyhf`)¶

HackRF (`hackrf`)¶

SDRPlay (`sdrplay`)¶

SoapySDR (`soapysdr`)¶

Serial Port Input (`serialport`)¶

NMEA2000 (`nmea2000`)¶

WAV File (`wavfile`)¶

Raw File (`file`)¶

TCP Client (`rtltcp`)¶

SpyServer (`spyserver`)¶

UDP Server (`udpserver`)¶

ZMQ (`zmq`)¶

Web Viewer (`server`)¶

UDP Output (`udp`)¶

TCP Output (Client) (`tcp`)¶

TCP Output (Server) (`tcp_listener`)¶

HTTP Output (`http`)¶

MQTT Output (`mqtt`)¶