Configuration Keys¶
The keys the managed hub edits, generated from its editor schema. They live in the config.json that
-C reads and managed mode (-E) keeps; JSON Configuration shows the
structure with examples, and the command line accepts more than is listed here: see the settings page
linked from each section. "Only with" marks a key that applies for one choice of another key in the
same object.
Main section¶
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
config |
string | – | "aiscatcher" |
Identifies the file; required |
version |
number | – | 1 |
Format version; required |
receiver |
object[] | – | One object per receiver, see Receiver | |
udp |
object[] | – | UDP outputs, see UDP | |
http |
object[] | – | HTTP outputs, see HTTP | |
mqtt |
object[] | – | MQTT outputs, see MQTT | |
tcp |
object[] | – | TCP Client outputs, see TCP Client | |
tcp_listener |
object[] | – | TCP Server outputs, see TCP Server | |
db |
object[] | – | Database outputs, see Database | |
server |
object[] | – | Viewer outputs, see Viewer | |
engine |
string | "off" |
on · off |
Managed mode: whether the receivers run; the Start and Stop buttons write it |
control |
object | – | Managed mode, see Managed mode | |
sharing |
boolean | false |
Share messages with the community map | |
sharing_key |
string | – | Leave empty to share anonymously | |
sharing_zone |
string[] | [] |
No zones — receives from all inputs | |
timeout |
false or number | false (60 when set) |
1 – 3600 | Stop the receiver after this many seconds |
timeout_only_when_idle |
boolean | false |
Watchdog: counts only while input is idle | |
screen |
string | "0" |
0 Off · 1 NMEA · 2 NMEA + details · 3 JSON with NMEA · 4 JSON (compact) · 5 JSON (full) |
Messages written to standard output: the journal under systemd, the container log under Docker |
verbose_time |
number | 3 |
1 – 3600 | How often a receiver with Verbose on logs its message counts; one interval for all receivers |
Receiver¶
Each entry of receiver is one object. input selects the device and the device section of the same
name inside the object configures it.
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
input |
string | – | RTLSDR · AIRSPY · AIRSPYHF · HACKRF · HYDRASDR HydraSDR · SERIALPORT SERIAL · UDPSERVER UDP Server · RTLTCP TCP Client · SPYSERVER · NMEA2000 |
Device Type |
channel |
string | "AB" |
AB · CD |
AB is standard, CD the long-range pair. Only with input = RTLSDR or AIRSPY or AIRSPYHF or HACKRF or HYDRASDR |
nmea_channel |
string | – | AB |
Channel letters in the NMEA output; AB for software that only knows A and B. Only with channel = CD |
serial |
string | – | Pick a device by serial number. Only with input = RTLSDR or AIRSPY or AIRSPYHF or HYDRASDR or HACKRF |
|
active |
boolean | true |
Active | |
verbose |
boolean | false |
Log message counts at the interval set under Output › Screen | |
zone |
string[] | [] |
Routes this receiver to outputs sharing a zone |
Engines¶
A second engine compares decoders and doubles CPU. engines is an optional array; each entry has a type, an optional zone
(string[]) of its own and an optional settings object.
| Key | Type | Values | Description |
|---|---|---|---|
type |
string | auto Auto · v1_base AIS Engine v1 Base · v1_high AIS Engine v1 High · v2_base AIS Engine v2 Base (experimental) |
Decoder |
zone |
string[] | Routes this engine to outputs sharing a zone | |
settings.fp_ds |
boolean | v1_base · v1_high · v2_base |
Integer downsampling of 1536K input: less CPU on low-end hardware |
Device sections¶
rtlsdr¶
With input = RTLSDR. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
tuner |
"auto" or number | "auto" |
0 – 50 | Gain in dB, or auto for AGC |
bandwidth |
integer | 0 |
e.g. 0, 192000; 0 – 1000000 |
Tuner filter bandwidth; Off uses the device default |
sample_rate |
integer | 1536000 |
e.g. 288000, 1536000; 96000 – 3200000 |
1536000 Hz (1536K) is recommended; 288K reduces CPU load on small devices |
freqoffset |
number | 0 |
-150 – 150 | Correct the dongle frequency error in ppm |
biastee |
boolean | false |
Powers an external LNA over the cable | |
rtlagc |
boolean | true |
RTL2832U internal AGC |
airspyhf¶
With input = AIRSPYHF. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
sample_rate |
integer | 192000 |
e.g. 192000, 256000, 384000, 768000; 192000 – 768000 |
Sample Rate (Hz) |
threshold |
string | "low" |
low Low · high High |
Automatic gain control threshold |
preamp |
boolean | false |
Enable the built-in preamplifier |
airspy¶
With input = AIRSPY. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
gain_mode |
string | "linearity" |
free Free · linearity Linearity · sensitivity Sensitivity |
Free sets LNA, mixer and VGA individually |
vga |
number | 10 |
0 – 14 | VGA. Only with gain_mode = free |
mixer |
"auto" or integer | "auto" |
0 – 14 | Mixer. Only with gain_mode = free |
lna |
"auto" or integer | "auto" |
0 – 14 | LNA. Only with gain_mode = free |
linearity |
number | 17 |
0 – 21 | Linearity. Only with gain_mode = linearity |
sensitivity |
number | 17 |
0 – 21 | Sensitivity. Only with gain_mode = sensitivity |
biastee |
boolean | false |
Powers an external LNA over the cable |
hydrasdr¶
With input = HYDRASDR. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
gain_mode |
string | "linearity" |
free Free · linearity Linearity · sensitivity Sensitivity |
Free sets LNA, mixer and VGA individually |
vga |
number | 10 |
0 – 14 | VGA. Only with gain_mode = free |
mixer |
"auto" or integer | "auto" |
0 – 14 | Mixer. Only with gain_mode = free |
lna |
"auto" or integer | "auto" |
0 – 14 | LNA. Only with gain_mode = free |
linearity |
number | 17 |
0 – 21 | Linearity. Only with gain_mode = linearity |
sensitivity |
number | 17 |
0 – 21 | Sensitivity. Only with gain_mode = sensitivity |
biastee |
boolean | false |
Powers an external LNA over the cable |
rtltcp¶
With input = RTLTCP. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
protocol |
string | "rtltcp" |
txt NMEA · none Raw · rtltcp RTLTCP · ws WS · wss WSS · wsmqtt WSMQTT · mqtt MQTT · gpsd GPSD · beast BEAST · basestation BASESTATION · raw1090 RAW1090 |
How the remote server is reached and what it sends |
host |
string | – | Host. Only with protocol = txt or none or rtltcp or wsmqtt or mqtt or gpsd or beast or basestation or raw1090 |
|
port |
number | – | Port. Only with protocol = txt or none or rtltcp or wsmqtt or mqtt or gpsd or beast or basestation or raw1090 |
|
url |
string | – | Port 443 (wss) or 80 (ws) unless given; user:password@ sends HTTP Basic, token@ a Bearer token. Only with protocol = ws or wss |
|
ssl_verify |
boolean | true |
Verify Certificate. Only with protocol = wss |
|
sample_rate |
number | 288000 |
0 – 20000000 | Sample Rate (Hz). Only with protocol = rtltcp |
bandwidth |
number | 0 |
0 – 1000000 | Bandwidth (Hz). Only with protocol = rtltcp |
freqoffset |
number | 0 |
-150 – 150 | Frequency Offset (PPM). Only with protocol = rtltcp |
tuner |
"auto" or number | "auto" |
0 – 50 | Gain in dB, or auto for AGC. Only with protocol = rtltcp |
rtlagc |
boolean | false |
RTL AGC. Only with protocol = rtltcp |
|
protocols |
string | – | Protocols. Only with protocol = ws or wss |
|
binary |
boolean | false |
Binary Mode. Only with protocol = ws or wss |
|
origin |
string | – | Origin. Only with protocol = ws or wss or wsmqtt |
|
topic |
string | "ais/data" |
Topic. Only with protocol = mqtt or wsmqtt |
|
client_id |
string | – | Client ID. Only with protocol = mqtt or wsmqtt |
|
username |
string | – | Username. Only with protocol = mqtt or wsmqtt or ws or wss |
|
password |
string | – | Password. Only with protocol = mqtt or wsmqtt or ws or wss |
|
qos |
string | "0" |
0 · 1 · 2 |
QoS Level. Only with protocol = mqtt or wsmqtt |
serialport¶
With input = SERIALPORT. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
port |
string | – | Port | |
baudrate |
string | "38400" |
9600 · 19200 · 38400 · 57600 · 115200 |
38400 is standard for AIS equipment |
init_seq |
string | – | Commands sent to the device on open | |
dump_file |
string | – | Append raw bytes to this file (also enables dump) |
udpserver¶
With input = UDPSERVER. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
server |
string | – | Local address the UDP server listens on | |
port |
number | – | Port |
hackrf¶
With input = HACKRF. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
lna |
number | 8 |
0 – 40 | LNA Gain |
vga |
number | 20 |
0 – 62 | VGA Gain |
preamp |
boolean | false |
Enable the built-in preamplifier |
spyserver¶
With input = SPYSERVER. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
gain |
number | 0 |
0 – 50 | Tuner Gain |
host |
string | "localhost" |
Host | |
port |
number | "1234" |
Port |
nmea2000¶
With input = NMEA2000. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
interface |
string | "can0" |
socketCAN interface, Linux only |
Outputs¶
UDP¶
udp is an array, one object per output. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
description |
string | – | Description | |
link |
string | – | Link | |
host |
string | "127.0.0.1" |
Host | |
port |
number | 10110 |
Port | |
active |
boolean | true |
Pause without removing | |
broadcast |
boolean | false |
Allow sending to broadcast addresses | |
msgformat |
string | "NMEA" |
NMEA · NMEA_TAG NMEA + TAG · JSON_NMEA JSON with NMEA · JSON_SPARSE JSON (compact) · JSON_FULL JSON (full) · JSON_ANNOTATED JSON (annotated) · BINARY_NMEA Binary |
Format of forwarded messages |
unique |
boolean | false |
Drops a message identical to one seen in the last 3 seconds | |
position_interval |
false or integer | false (60 when set) |
0 – 3600 | Off forwards every position; on keeps at most one per vessel within the seconds set (0-3600) |
zone |
string[] | [] |
No zones — receives from all inputs |
HTTP¶
http is an array, one object per output. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
description |
string | – | Description | |
link |
string | – | Link | |
url |
string | – | URL | |
interval |
number | 60 |
1 – 86400 | How often messages are posted |
active |
boolean | true |
Pause without removing | |
id |
string | – | Station identifier in the feed | |
userpwd |
string | – | Sent as user:password | |
gzip |
boolean | false |
Compress posted data | |
response |
boolean | true |
Log the server response | |
protocol |
string | "AISCATCHER" |
AISCATCHER · MINIMAL · APRS · LIST · AIRFRAMES · NMEA |
Submission format expected by the server |
unique |
boolean | false |
Drops a message identical to one seen in the last 3 seconds | |
position_interval |
false or integer | false (60 when set) |
0 – 3600 | Off forwards every position; on keeps at most one per vessel within the seconds set (0-3600) |
zone |
string[] | [] |
No zones — receives from all inputs |
MQTT¶
mqtt is an array, one object per output. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
description |
string | – | Description | |
link |
string | – | Link | |
url |
string | – | URL | |
active |
boolean | true |
Pause without removing | |
topic |
string | "ais/data" |
Supports %mmsi%, %type% and %channel% placeholders | |
client_id |
string | – | Client ID | |
qos |
string | "0" |
0 0 - At most once · 1 1 - At least once · 2 2 - Exactly once |
QoS |
msgformat |
string | "JSON_FULL" |
NMEA · NMEA_TAG NMEA + TAG · JSON_NMEA JSON with NMEA · JSON_SPARSE JSON (compact) · JSON_FULL JSON (full) · JSON_ANNOTATED JSON (annotated) · BINARY_NMEA Binary |
Format of forwarded messages |
unique |
boolean | false |
Drops a message identical to one seen in the last 3 seconds | |
position_interval |
false or integer | false (60 when set) |
0 – 3600 | Off forwards every position; on keeps at most one per vessel within the seconds set (0-3600) |
zone |
string[] | [] |
No zones — receives from all inputs |
TCP Client¶
tcp is an array, one object per output. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
description |
string | – | Description | |
link |
string | – | Link | |
host |
string | "127.0.0.1" |
Host | |
port |
number | 10110 |
Port | |
active |
boolean | true |
Pause without removing | |
persist |
boolean | true |
Reconnect automatically after failures | |
keep_alive |
boolean | false |
Enable TCP keep-alive probes | |
msgformat |
string | "NMEA" |
NMEA · NMEA_TAG NMEA + TAG · JSON_NMEA JSON with NMEA · JSON_SPARSE JSON (compact) · JSON_FULL JSON (full) · JSON_ANNOTATED JSON (annotated) · BINARY_NMEA Binary |
Format of forwarded messages |
unique |
boolean | false |
Drops a message identical to one seen in the last 3 seconds | |
position_interval |
false or integer | false (60 when set) |
0 – 3600 | Off forwards every position; on keeps at most one per vessel within the seconds set (0-3600) |
zone |
string[] | [] |
No zones — receives from all inputs |
TCP Server¶
tcp_listener is an array, one object per output. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
description |
string | – | Description | |
link |
string | – | Link | |
port |
number | 5010 |
Port clients connect to, max 64 | |
active |
boolean | true |
Pause without removing | |
msgformat |
string | "NMEA" |
NMEA · NMEA_TAG NMEA + TAG · JSON_NMEA JSON with NMEA · JSON_SPARSE JSON (compact) · JSON_FULL JSON (full) · JSON_ANNOTATED JSON (annotated) · BINARY_NMEA Binary |
Format of forwarded messages |
unique |
boolean | false |
Drops a message identical to one seen in the last 3 seconds | |
position_interval |
false or integer | false (60 when set) |
0 – 3600 | Off forwards every position; on keeps at most one per vessel within the seconds set (0-3600) |
zone |
string[] | [] |
No zones — receives from all inputs |
Database¶
db is an array, one object per output. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
description |
string | – | Description | |
link |
string | – | Link | |
type |
string | "sqlite" |
sqlite SQLite (local file) · postgres PostgreSQL · csv CSV files |
Database |
conn_str |
string | – | File for SQLite, libpq connection string for PostgreSQL, directory for CSV | |
retention |
number | 0 |
0 – … | Days of history kept, pruned daily; 0 keeps everything |
capacity |
number | 8192 |
64 – 1000000 | CSV only: how many targets the state file keeps before the least recently heard is dropped. Only with type = csv |
station_id |
number | – | 0 – … | Stamped on every row so several feeders can share one database |
active |
boolean | true |
Pause without removing | |
state |
boolean | true |
Latest values per MMSI, one row per vessel | |
stats |
boolean | true |
Hourly reception statistics, one row per hour | |
position |
boolean | false |
Log every position report; grows with traffic | |
static |
boolean | false |
Log static and voyage reports; grows with traffic | |
nmea |
boolean | false |
Store the raw sentences with each message | |
interval |
number | 60 |
5 – 1800 | Write Interval (seconds) |
unique |
boolean | false |
Drops a message identical to one seen in the last 3 seconds | |
position_interval |
false or integer | false (60 when set) |
0 – 3600 | Off forwards every position; on keeps at most one per vessel within the seconds set (0-3600) |
zone |
string[] | [] |
No zones — receives from all inputs |
Viewer¶
server is an array, one object per output. Documentation
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
port |
number | 8100 |
1 – 65535 | Port the viewer is served on |
station |
string | "My Station" |
Station name shown in the web viewer | |
station_link |
string | – | External website linked from the station name | |
lat |
number | 0 |
-90 – 90 | Station latitude in decimal degrees |
lon |
number | 0 |
-180 – 180 | Station longitude in decimal degrees |
places |
string | – | Directory containing saved port, berth, anchorage, and custom area definitions | |
plugin_dir |
string | – | Directory with .pjs/.pss plugins injected into the viewer | |
mbtiles |
string[] | – | Base map, one file per line | |
mboverlay |
string[] | – | Overlay, one file per line | |
fstiles |
string[] | – | Base map, one directory per line | |
fsoverlay |
string[] | – | Overlay, one directory per line | |
webcontrol_http |
string | – | URL of this Web Control, linked from the viewer menu | |
file |
string | – | Keeps statistics across restarts, empty to disable | |
backup |
number | 10 |
0 – 2880 | Minutes between backups: 0 disables periodic writes; otherwise at least 5. The file is still saved on shutdown. |
history |
number | 1800 |
5 – 43200 | Hides ships with no messages for this long |
track_memory |
number | 1024 |
16 – 262144 | More memory keeps longer track history |
replay |
boolean | true |
Visitors can animate tracks | |
split |
boolean | true |
Visitors can pick one receiver | |
track_time |
number | 3600 |
0 – 604800 | How far back tracks and replay reach, 0 for no limit |
context |
string | "settings" |
Browser storage key; separates viewers | |
active |
boolean | true |
Serve the viewer on this port | |
share_loc |
boolean | false |
Show station location and range on the map | |
use_gps |
boolean | true |
Let GPS update the station location | |
expire |
boolean | false |
Clear data not reconfirmed by new messages | |
realtime |
boolean | false |
Stream live NMEA to the viewer | |
msg |
boolean | false |
Keep recent NMEA per ship for the ship card | |
geojson |
boolean | false |
Enable GeoJSON endpoints | |
prome |
boolean | false |
Metrics served at /metrics | |
log |
boolean | false |
Show the log tab in the viewer | |
decoder |
boolean | false |
Enable the NMEA decoder tab | |
zone |
string[] | [] |
No zones — receives from all inputs |
Managed mode¶
Managed mode (-E) reads the same file. The server beside the control panel, on the panel's port plus one, is the entry of
services marked "main": true: it takes a server's keys (api, mcp, system, geojson, kml, metrics, keys, public, view) and the
Viewer options (realtime, replay, msg, decoder, log, station, station_link, webcontrol_http,
mbtiles, plugin_dir, …), never a port; the map is always on it. How ships are kept is tracking (file, backup,
history, track_time, track_memory, expire, max_ships, cutoff, places), and the default station is station 0
of stations. control.wizard (boolean) shows the setup wizard on the next visit; the hub stores its password under
control itself; leave those keys alone. A file from before, with the viewer under control.viewer, is read as it is and
brought to this layout by the panel when it saves.