Wellenvogel AvNav

• Kontakt
• GitHub

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.
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.

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.

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

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:

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

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, category 1 (1x, mandatory)

Name	Description	default/template
loglevel	Level log writing  (ERROR, INFO, DEBUG,...)	INFO
logfile	Name of the log file	<datadir>/log/avnav.log
maxtimeback	maximal time (in seconds)  the system time will be set backwards before all internal data will be cleared.	5
systimediff	maximum delta (in seconds) between system time and gps time before the system time is set.	5
settimecmd	command to set the system time	/usr/lib/avnav/raspberry/settime.sh
settimeperiod	min time in seconds between 2 attempts to set the system time	3600
ownMMSI	MMSI of own vessel, will be filtered from the received AIS data

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	Description	default/template
maxDevices	max number of concurrently connected bluetooth devices	5
deviceList	Comma separated list of bluetooth device ids. If provided only those devices will be connected.
filter	filter for NMEA data

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

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	Description	default/template
name	channel name
combined	if "true", also read from this channel	false
readFilter	filter for the input path
blackList	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

Parameters for AVNUsbSerialReader

Name	Description	default/template
maxDevices	maximal number of simultaneously connected USB devices	5
allowUnknown	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	Description	default/template
usbid	USB Port identification e.g.. "1-1.2.1:1.0", mandatory
type	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	Description	default/template
name	channel name for blackList and for display
port	UDP port
host	Bind address	0.0.0.0
minTime	if set: time in s before the next record is read	0
filter	filter for NMEA data

AVNUdpWriter

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

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

AVNSocketWriter

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

Name	Description	default/template
name	channel name
port	listener port
address	if set - bind to this address	0.0.0.0
filter	filter for NMEA data
read	if true, data is also read from connections	false
readFilter	if read is true: NMEA filter for input direction
blackList	blackList comma separated list of channel names (no data sent out coming from this channels)
minTime	minimal time in s between 2 consecutive NMEA messages	0
avahiEnabled	if activated the server will announce this service via MDNS (Bonjour/Avahi). The service tpye is _nmea-0183._tcp	false
avahiName	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	Description	default/template
name	channel name
port	TCP destination port
host	TCP destination address (ip or hostname)
timeout	connect timeout in seconds	10
minTime	min time between 2 received messages	0
filter	filter for NMEA data
writeOut	send out NMEA data on this connection	false
writeFilter	filter for the sent NMEA data	empty
blackList	, separated list of source names that will not be sent out	empty

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

AVNBME280Reader

Reader for BME280 via I2C. category 3 (optional)
Writes MDA and XDR records.

Name	Description	default/template
name	channel name
addr	I2C address of the sensor	0x77
interval	time between 2 NMEA records in s	5
writeXdr	write XDR if true	true
writeMda	write MDA if true	true

AVNBMB180Reader

Reader for BMP180 via I2C. category 3 (optional)
Writes MDA and XDR records.

Name	Description	default/template
name	channel name
addr	I2C address of the sensor	0x77
interval	time between 2 NMEA records in s	5
writeXdr	write XDR if true	true
writeMda	write MDA if true	true

AVNSenseHatReader

Reader for SenseHat I2C. category 3 (optional)
Writes MDA and XDR records.

Name	Description	default/template
name	channel name
interval	time between 2 NMEA records in s	5
writeXdr	write XDR if true	true
writeMda	write MDA if true	true

AVNTrackWriter

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

Name	Description	default/template
interval	minimal time between 2 track points (seconds) before written	10
mindistance	minimal distance between 2 track points (meters)	50
trackdir	track directory	<datadir>/tracks
cleanup	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

AVNRouter

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

Name	Description	default/template
name	channel name (for generated records)
routesdir	directory for routes	<datadir>/routes
interval	time (in s) between RMB/APB records	5
computeRMB	compute RMB if a waypoint is active	true
computeAPB	compute APB if a waypoint is active	false

AVNNmeaLogger

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

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

AVNImporter

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

Name	Description	default/template
importDir	directory to read charts for import	<datadir>/import
workDir	working directory for the converter	<datadir>/work
waittime	converter waittime in seconds to start conversion after a new/changed file has been detected	30
knownExtensions	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

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:

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).

The default configuration is:

AVNAlarmHandler has one parameter: stopAlarmPin. If this is set (pin number - i.e. mode board, only Raspberry) you can stop an alarm by using an "L" potential at this pin (e.g. with a simple button).
The parameters set at the alarms will also be used for the sound in the WebApp.

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:

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-signalk

Name	Description	default/template
enabled	only if true the plugin will become active	false
port	port for the signalk API	3000
period	interval in seconds for querying the signalk API	1000

Parameters for builtin-canboat

Name	Description	default/template
enabled	only if true the plugin will become active	false
allowKeyOverride	set to true to allow the plugin to set date and time in the internal store	false
port	canboat json port	2598
host	host for n2kd	localhost
autoSendRMC	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	channel name for RMC	plugin-Name
timeInterval	minimal time (in seconds) before we read a new time value from NMEA2000	0.5
timePGNs	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	Description	default/template
serviceName	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	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	timeout when connecting to the avahi daemon (s)	10