AvNav Config File

AvNav Server Configuration

== not for Android ==

Introduction

On start up the AvNav server reads its configuration from an xml file - avnav_server.xml.
This file normally is located at /home/pi/avnav/data on the raspberry, otherwise at $HOME/avnav - see installation.

If this file still does not exist on start up it will be created from a template - fitting either the raspberry set up or other systems.

This template will be /etc/avnav_server.xml (from 20230426) on a raspberry pi (with the package avnav-raspi installed). If this one does not exist, AvNav falls back to a template installed with the package.
If you start AvNav from the command line using "avnav" you can define the template to be used with the -t parameter.
On package updates of AvNav this file normally will not be changed. Potentially it could be necessary to add some entries to enable new functions. In this case you will find some hints in the release notes.

With every successful start AvNav (from version 20200325) creates a copy of this file with the extension .ok. If during the next start up parsing of the config file fails, AvNav will fall back to this .ok file. With this fallback handling it will be ensured that AvNav can start up, even if a change of the original config file (what AvNav is doing in some situations) leaves the file in a defect state. If you don't want this fallback (for testing) add the -e command line switch.

If AvNav completely fails to start, you can try to remove the avnav_server.xml completely. This way AvNav will start up with a clean template.

Starting from 20210322 it should not be necessary anymore to modify the config file "by hand". Instead use AvNav itself (Server/Status page) to edit most parts of the configuration. This also eliminates the need of a manual restart when changing parameters.
In the following descriptions the column "online" will give you a hint whether this value can be changed directly at the server/status page.

If you need to change sections not editable there, you still can use the avnav-update-plugin to edit it directly from within your browser.
So the following text simply serves as reference.

If you change the avnav_server.xml you need to restart AvNav. If it is running as a system service you can do this with the command

sudo systemctl restart avnav

I recommend to do a start up of AvNav from the command line whenever you changed the config file to watch for serious errors. The commands would be:

sudo systemctl stop avnav
avnav -e
^C
sudo systemctl start avnav

Option -e, since version 20200325. It prevents the fallback to avnav_server.xml.ok (what would hide your errors). ^C interrupts the running AvNav.

Content

Within avnav_server.xml there are entries for the various parts of AvNav. You will find a lot of commented examples in the templates.

Basically there are 3 categories of AvNav parts:

  1. parts that have to occur exactly once.
    example: AVNConfig, AVNHttpServer,...
  2. parts that normally don't need to be part of avnav_server.xml. You only insert them if you want to change some of the defaults.
    example: AVNAlarmHandler, AVNChartHandler,...
  3. parts that can be contained once or multiple times. This includes all the input and output channels. If no entry is present the functionality will not be available.

Some properties will be available at various parts - as described here:

Name Description Example
enabled Many handlers can be switched on or off with this parameter at the server/status page. on
name name of an input or output channel. This name will be shown at the status page and it can be used in a blackList to avoid output of data from this channel. There is always an internal default for the name. nmea0183tosignalk
filter Filtering of NMEA date. You can provide filters separated by comma. Only matching NMEA data will pass this filter. To make them independent of talker ids, the 2 characters following a $ will not be considered. To e.g. only pass $GPRMC sentences (and any other $xxRMC) the filter would be: $RMC.
If you prefix the filter with a ^ it will be negated, i.e. ^$RMC means. No $xxRMC records. For AIS data you can use "!" or "!AIVDM" .
$RMC,^$RMB,!AIVDM
readFilter If the channel is a combined reader/writer this is the filter for the input path
blackList List of channel names (separated by comma). Data originating from those channels will not be sent out. Consider the camel case - i.e. capital L. nmea0183tosignalk
priority
(since 20220421)
All NMEA input channels have a priority field. This controls which value will win if the same item will be decoded from multiple channels. The default priority is 50 you can adapt upwards and downwards. The SignalK integration has priority 40 by default. 50


The following tables list the main parts together with their parameters. If some properties in a template are not listed here, just leave them as they are.

AVNConfig

Base configuration and system time handling, category 1 (1x, mandatory)

Name online Description default/template
settimecmd
command to set the system time.
It will receive the time to be set as UTC timestamp like to be used for date -u
only set with the avnav-raspi package
settime
(from 20220421)
X if set setting the system time is enabled (requires settimecmd to be set additionally) on
maxtimeback X maximal time (in seconds)  the system time will be set backwards before all internal data will be cleared. 5
systimediff X maximum delta (in seconds) between system time and gps time before the system time is set. 5
settimeperiod
min time in seconds between 2 attempts to set the system time 3600
ntphost
(from 20220421)
X NTP server to be queried if there is no valid GPS time pool.ntp.org
switchtime
(from 20220421)
X time (in s) after setting the time before it is changed between valid GPS time and ntp time (and back). This time will also be used to wait for a valid GPS time when starting up (before NTP is used) 60
ownMMSI X MMSI of own vessel, will be filtered from the received AIS data
expiryTime X time (in s) that received NMEA data will remain valid 30
aisExpiryTime X time (in s) that received AIS data will remain valid 1200

AVNFeeder

The internal NMEA list and decoder unit. category 2 (once, optional since version 20200325).

This part has no parameters anymore. In previous versions you could configure gpsd here, so potentially there still will be some parameters in your configuration. When you previously had an old version installed this entity will be named AVNGpsdFeeder.

AVNHttpServer

The internal HTTP server. category 1 (once, mandatory).

Apart from parameters for the AVNHttpServer there are some child entries that could be repeated multiple times. Normally there is no need for any change at those entries (Directory,MimeType).

Beside the httpPort you would normally not change anything.

Parameters for AVNHttpServer

Name Description default/template
httpPort listener port for the HTTP server 8080
navurl REST interface, no change /viewer/avnav_navi.php
index start page, no change /viewer/avnav_viewer.html
httpHost bind address for the server 0.0.0.0
numThreads number of threads being used by the HTTP server 5

Parameters for Directory

Normally those values will be replaced by the -u command line parameter. You should not change them.

Name Description default/template
urlpath the URL (without /)
path real path on the system

Parameters for MimeType

You may configure (additional) mime types for the server. Potentially your own application requires some extension here if you have special files.

Name Description default/template
extension extension(e.g. .avt)
type mime type (e.g. text/plain)


AVNBlueToothReader

Reading of bluetooth devices that have a serial profile. category 3 (once, optional)
Only possible if your server has a bluetooth device.

Name online Description default/template
maxDevices X max number of concurrently connected bluetooth devices 5
deviceList X Comma separated list of bluetooth device ids. If provided only those devices will be connected.
filter X filter for NMEA data
name X

priority X

enabled X

AVNSerialReader

Reading of serial devices. category 3 (multiple times, optional).
This reader only should be configured for devices that are directly connected to a built in UART. For USB devices use the AVNUsbSerialReader.

Name online Description default/template
name X channel name intern gebildeter Name
port X device name, e.g. /dev/ttyAMA0
baud X Baudrate. If minBaud is also set baudRate is the maximal baud rate for automatic baud rate detection. 4800
minbaud X Minimal baud rate for auto detection. If not set or 0 - no automatic detection.
timeout X Timeout in s, if no data received within this time the device will be closed and reopened. 1
bytesize X serial byte size 8
parity X parity N
stopbits X number of stopbits 1
xoxoff X xon/xoff protocol (0: off) 0
rtscts X RTS/CTS protocol (0: off) 0
numerrors X After that number of errors the device will be closed and re opened. 20
autobaudtime X Time in seconds to recognize a newline during automatic baud rate detection. 5
filter X NMEA filter - see filter
enabled X

priority X

AVNSerialWriter

Output via a serial device. Could also read from this device. category 3 (optional)
Only use this for direct serial devices, for USB devices use AVNUsbSerialReader

Name online Description default/template
name X channel name
combined X if "true", also read from this channel false
readFilter X filter for the input path
blackList X blackList, comma separated list of channel names from which no data should be written
....
all parameters from AVNSerialReader

AVNUsbSerialReader

Handles serial devices connected via USB. category 3 (once, optional).
This worker process scans all connected USB devices. It tries to open those with a serial profile, detect their baud rate and read NMEA data. This way AvNav normally auto detects all such devices.
You can define separate rules for individual devices. As device identification we use the USB port id where the device is plugged into. To find out this id simply watch the status page when you connect the device.

The parameters consist of 2 parts:

  • Attributes for the entry itself
  • Child entries of type UsbDevice

Example

<AVNUsbSerialReader maxDevices="5" allowUnknown="true" baud="38400" minbaud="4800"> <UsbDevice usbid="1-1.2.1:1.0" baud="38400" minbaud="4800" filter="$RMC"/>
</AVNUsbSerialReader>

Parameters for AVNUsbSerialReader

Name online Description default/template
maxDevices X maximal number of simultaneously connected USB devices 5
allowUnknown X only if this attribute is true, unknown devices (i.e. lacking an UsbDevice entry) will be handled true
...
all parameters from AVNSerialReader except port. Those parameters will be used for unknown devices.

Parameters for UsbDevice

Name online Description default/template
usbid X USB Port identification e.g.. "1-1.2.1:1.0", mandatory
type X type of the device reader, writer, combined, ignore, use ignore if you don't want the device to be used reader
...
all parameters from AVNSerialReader if  type = "reader"  (except port, this will be set internally)
...
all parameters from AVNSerialWriter if the type is combined or writer  (except port, this will be set internally)

AVNUdpReader

Opens a UDP port and reads data from it. category 3(optional, multiple times).

Name online Description default/template
name X channel name for blackList and for display
port X UDP port
host X Bind address 0.0.0.0
minTime X if set: time in s before the next record is read 0
filter X filter for NMEA data
enabled X

priority X

stripLeading X Remove anything before $ or ! in received lines. off

AVNUdpWriter

Sends out NMEA Daten via UDP. category 3 (optional, multiple times)

Name online Description default/template
name X channel name
port X UDP destination port
host X UDP destination address
filter X filter NMEA data
broadcast X set to true if you want to send broadcast false
blackList X blackList for channel names
enabled X

AVNSocketWriter

Output that opens a listener port, waits for connections and sends out NMEA data (TCP server). category 3 (multiple times, optional).

Name online Description default/template
name X channel name
port X listener port
address X if set - bind to this address 0.0.0.0
filter X filter for NMEA data
read X if true, data is also read from connections false
priority X only if read is enabled
readFilter X if read is true: NMEA filter for input direction
blackList X blackList comma separated list of channel names (no data sent out coming from this channels)
minTime X minimal time in s between 2 consecutive NMEA messages 0
avahiEnabled X if activated the server will announce this service via MDNS (Bonjour/Avahi). The service tpye is _nmea-0183._tcp false
avahiName X the name that this service will be visible with in MDNS avnav-server

AVNSocketReader

Input. Connects to TCP server reading data from it (TCP client). category 3 (multiple times, optional)

Name online Description default/template
name X channel name
port X TCP destination port
host X TCP destination address (ip or hostname)
timeout X connect timeout in seconds 10
minTime X min time between 2 received messages 0
filter X filter for NMEA data
writeOut X send out NMEA data on this connection false
writeFilter X filter for the sent NMEA data empty
blackList X , separated list of source names that will not be sent out empty
enabled X

priority X

stripLeading X Remove anything before $ or ! in received lines. false

AVNNmea0183ServiceReader

This reader is very similar to the AVNSocketReader. But instead of configuring host and port you will configure the serviceName. AvNav will search for services of type _nmea-0183._tcp and will provide you a list of available services. Using this reader will give you connectivity even if the network topology potentially will change.

Name online Description default/template
serviceName X The name of the service (AvNav will provide a list of found services) --
timeout X connect timeout in seconds 10
minTime X min time between 2 received messages 0
filter X filter for NMEA data empty
writeOut X send out NMEA data on this connection false
writeFilter X filter for the sent NMEA data empty
blackList X , separated list of source names that will not be sent out empty
name X

enabled X

priority X


AVNBME280Reader

Reader for BME280 via I2C. category 3 (optional)
Writes MDA and XDR records.
Will only be available if python3-smbus is installed

Name online Description default/template
name X channel name
addr X I2C address of the sensor 0x77
interval X time between 2 NMEA records in s 5
writeXdr X write XDR if true true
writeMda X write MDA if true true
namePress X XDR transducer name for pressure Barometer
nameHumid X XDR transducer name for humidity Humidity
nameTemp X XDR transducer name for temperature TempAir
enabled X

priority X

AVNBMB180Reader

Reader for BMP180 via I2C. category 3 (optional)
Writes MDA and XDR records.
Only available if python3-smbus is installed.

Name online
Description default/template
name X
channel name
addr X
I2C address of the sensor 0x77
interval X
time between 2 NMEA records in s 5
writeXdr X
write XDR if true true
writeMda X
write MDA if true true
namePress X XDR transducer name for pressure Barometer
nameTemp X XDR transducer name for temperature TempAir
enabled X

priority X

AVNSenseHatReader

Reader for SenseHat I2C. category 3 (optional)
Writes MDA and XDR records.
Requires python3-sense-hat to be installed

Name online Description default/template
name X channel name
interval X time between 2 NMEA records in s 5
writeXdr X write XDR if true true
writeMda X write MDA if true true
namePress X XDR transducer name for pressure Barometer
nameTemp X XDR transducer name for temperature TempAir
nameHumid X XDR transducer name for humidity Humidity
nameRoll
(from 20220421)
X XDR transducer name for roll Roll
namePitch
(from 20220421)
X XDR transducer name for pitch Pitch
enabled X

priority X

AVNTrackWriter

Writes tracks in gpx format and in a simple ASCII format. category 3 (once, optional)

Name online Description default/template
interval X minimal time between 2 track points (seconds) before written 10
mindistance X minimal distance between 2 track points (meters) 50
trackdir X track directory <datadir>/tracks
cleanup X maximum age (in hours) for track data sent to the WebApp. Still files are stored to hold older data but these are not available to the WebApp. 25
writeFile X Write to file. If off, only have the track in memory. on

AVNRouter

Handling of routing data (waypoints, routes, anchor alarm). Computing of RMB, APB. category 1 (once, mandatory).

Name online Description default/template
name X channel name (for generated records)
routesdir
directory for routes <datadir>/routes
interval X time (in s) between RMB/APB records 5
computeRMB X compute RMB if a waypoint is active true
computeAPB X compute APB if a waypoint is active false
useRhumbLine
(since 20220819)
X use the rhumb line mode for routes false
nextWpMode
(since 20220819)
X select the  switching mode for the next waypoint in a route (late, 90, early) late
nextWpTime
(since 20220819)
X The time to wait after the waypoint alarm (in seconds) before switching to the next waypoint (only nextWpMode = early). 10

AVNNmeaLogger

Writes NMEA logs into the track directory. category 3 (once, optional).

Name online Description default/template
maxfiles X number of files (1 per day) that are kept. 100
filter X filter for NMEA data "$RMC,$DBT,$DBP"
interval X minimal time (in seconds) before a next record of the same type is written 5
enabled X

AVNImporter

Import Charts that still need conversion. category 2 (once, optional)

Name online Description default/template
importDir
directory to read charts for import <datadir>/import
workDir
working directory for the converter <datadir>/work
waittime X converter waittime in seconds to start conversion after a new/changed file has been detected 30
knownExtensions X list of extensions the WebApp offers to upload to the importer. kap,map,geo
keepInfoTime
time in seconds an information on import is kept 30
enabled X

AVNWpaHandler

Configuration for external wifi connections. category3 (once, optional)

Name Description default/template
wpaSocket the control connection to wpa_supplicant /var/run/wpa_supplicant/wlan-av1
ownSsid own SSIDs - those will be filtered from the list avnav,avnav1,avnav2
firewallCommand if configured, you can enable access to the pi from the connected wifi network sudo -n $BASEDIR/../raspberry/iptables-ext.sh wlan-av1

AVNCommandHandler

Execute commands (e.g. for alarms). category2 (once, optional).

AVNCommandHandler itself has no parameters. There can be child configurations for various commands. The default configuration is:

<AVNCommandHandler> <Command name="sound" command="mpg123 -q" repeat="1"/> </AVNCommandHandler>

Parameters for Command

Name Description default/template
name name for the command
command system command to be executed
repeat number of repetitions 1

AVNAlarmHandler

Management of Alarms. category 2 (once, optional).

Changed from 20220421.

The default configuration:

<AVNAlarmHandler> <Alarm name="waypoint" category="info" repeat="1"/>
<Alarm name="connectionLost" category="info" repeat="1"/> <Alarm name="anchor" category="critical" repeat="20000"/> <Alarm name="gps" category="critical" repeat="20000"/> <Alarm name="mob" category="critical" repeat="2"/>
</AVNAlarmHandler>

Since version 20220421 you should remove existing alarm entries from your avnav_server.xml if you do not have special needs.
When using the defaults you can choose the sound directly at the server status page and you can e.g. use an own sound file that has been uploaded to the user directory.

If you would like to trigger special commands you need to configure this in avnav_server.xml .

<AVNAlarmHandler>
<!-- legacy way of configuring alarms - still supported but not recommended, use category at least and optionally parameter --> <Alarm name="gps" category="critical" command="gpsAlarm" parameter="$BASEDIR/../sounds/anchorAlarm.mp3" repeat="20000"/>
<!-- with the next line we configuer a special command that will be called when we receive a "sinking" notification from SignalK
the sound is determined by the category - and this is also the parameter that the command will receive --> <Alarm name="sk:sinking" command="sinkingAlarm" category="critical" repeat="2"/>
</AVNAlarmHandler>

Parameter for Alarm

Name Description default
name Name of the alarm (mandatory) empty
category Categorie (info,critical) empty
command Command to be executed (must be configured at AVNCommandHandler). If not configured the default command will be used. empty
autoclean Switch off the alarm when the command has finished. off
sound The name of a sound file. If provided this will be used for the sound in the browser and as parameter for the command. Relative pathes are based on the internal sound dir or on the user dir.
If not set the sound will be dtermined by the category - or as last resort by 'parameter'.
empty
repeat Number of command and sound repetitions 1
parameter If provided this is the parameter for the command. If neither sound nor category are set this is treated as the path to a sound file and alos used for the browser.


Parameter for AlarmHandler

Name online Description default/template
infoSound X Name of a mp3 file for the sound in category info.
Can be selected form a list of sound files from the user dir (upload your sounds via the Download page) or from the internal sound dir.
waypointAlarm.mp3
criticalSound X Name of a mp3 file for the sound in category critical.
Can be selected form a list of sound files from the user dir (upload your sounds via the Download page) or from the internal sound dir.
anchorAlarm.mp3
defaultCommand X Command for alarms without an own command definition.
This command has to be configured at AVNCommandHandler.
sound
stopAlarmPin X Only on Raspberry Pi. If set (board numbering), a low at this pin will switch off all currently active alarms. leer


AVNPluginHandler

Management of plugins. category 2 (once, optional).
AVNPluginHandler is handling plugins. They can be installed in different directories:

  • builtin: /usr/lib/avnav/server/plugins
  • system: /user/lib/avnav/plugins
  • user: /home/pi/avnav/data/plugins

Beside the parameters for the plugin handler itself, each plugin could expect parameters. The name of the plugin consists of the category and the plugin directory name. Example:

<AVNPluginHandler> <builtin-signalk enabled="true"/> <builtin-canboat enabled="true" allowKeyOverwrite="true" autoSendRMC="30" sourceName="canboatgen"/> </AVNPluginHandler>

Parameters for AVNPluginHandler

Name Description default/template
builtinDir directory for built in plugins, no change /usr/lib/avnav/server/plugins
systemDir directory for plugins installed with packages /usr/lib/avnav/plugins
userDir directory for user plugins /home/pi/avnav/data/plugins

Parameters for builtin-canboat

Name online Description default/template
enabled X only if true the plugin will become active false
allowKeyOverride X set to true to allow the plugin to set date and time in the internal store false
port X canboat json port 2598
host X host for n2kd localhost
autoSendRMC X if no RMC record is seen in the NMEA data within this period (in seconds) but valid position and date/time data were received from n2k - generate a RMC record (important to have date and time on NMEA0183) 30
sourceName X channel name for RMC plugin-Name
timeInterval X minimal time (in seconds) before we read a new time value from NMEA2000 0.5
timePGNs X PGNs for setting the time 126992,129029

AVNChartHandler

Management of charts. category 2 (once, optional)

Name Description default/template
period time between 2 reads of the chart directory 30
upzoom number of zoom levels above the highest available 2

AVNUserHandler

Management of the user files. category 2 (once, optional)

Name Description default/template
interval time (in s) between 2 reads of the directory 5

AVNImagesHandler

Management of user images. category 2 (once, optional)

Name Description default/template
interval time (in s) between 2 reads of the directory 5

AVNUserAppHandler

Management of configured User Apps. category 2 (once, optional)

This is somehow a special handler. Normally initially there should be no configuration. Within the App you can configure the user apps. Manual change of the configuration is not recommended.

AVNAvahiHandler

Controls how AvNav registers at Avahi(MDNS).

Name online Description default/template
serviceName X The name that will be visible in tools that are able to browse MDNS information.
This is not the host name that you would use in e.g. avnav.local!
avnav
maxRetries X How many retries AvNav would make if the name is already used by someone else. Retries would add a "-nn" suffix to the name. 20
timout X timeout when connecting to the avahi daemon (s) 10
enabled X

AVNSignalKHandler

New with 20220421.
For a description refer to the SignalK Documentation.