AvNav Server Configuration
== not for Android ==
Introduction
The AvNav server is reading its configuration from an xml file -
avnav_server.xml on start up.
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 up AvNav (from version 20200325) will write a copy of this file with the extension .ok. If during the next start up the parsing of the config file is failing it 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 any more to change the config file "by hand". Instead use AvNav itself (Server/Status page) to edit most parts of the configuration. This also avoids the need of a restart when changing parameters.
If you would have to change parts not being editable there you still can
use the avnav-update-plugin
to edit it directly from within your browser.
So the following part is here just for 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:
avnav -e
^C
sudo systemctl start avnav
Option -e only starting with 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:
- parts that have to occur exactly once.
example: AVNConfig, AVNHttpServer,... - parts that normally don't need to be part of avnav_server.xml. You
only need them there if you would like to change some of the defaults.
example: AVNAlarmHandler, AVNChartHandler,... - 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 there.
Some property will be available at multiple parts - a description form them:
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 ,.
Only matching NMEA data will pass this filter. To make them
independent of talker ids the 2 characters after 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 you this will be the filter for the input path | |
blackList | List of channel names (separated by ,). Data coming from those channels will not be sent out. Consider the camel case - i.e. capital L. | nmea0183tosignalk |
The following list contains the main parts together with their parameters. If there are some properties in a template that 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 | maximal difference (in seconds) between system time and gps time before the system time is set. | 5 |
settimecmd | command for setting 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 |
AVNGpsdFeeder
The internal NMEA lsit and decoder. category 2 (1x, not mandatory since version 20200325).
This part now has no parameters any more. In previous versions you could configure gpsd here so potentially there still will be some parameters in your configuration. In newer versions ensure that you include useGpsd="false".
AVNHttpServer
The internal HTTP server. category 1 (once, mandatory).
Besode the 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 fro 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 configure (additional) mime types for the server. Potentially your own application would need 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 re opened. | 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 many 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 scans all USB connected devices and for all of them with a
serail profile it tries to open them, detect the serial baud rate and read
NMEA data from them. Thsi way AvNav normally auto detects all such
devices.
You can define separate rules for dedicated devices, As a device
identification we use an ID that is related to the USB port that the
device is plugged in. To find out this Id simple watch the status
page when you connect the device.
The parameters are separated into 2 pieces:
- Attributes for the entry itself
- Child entries of type UsbDevice
Example
</AVNUsbSerialReader>
Parameters for AVNUsbSerialReader
Name | Description | default/template |
maxDevices | maximal number of simultaneously connected USB devices | 5 |
allowUnknown | only if this attribute is true onknonw devices (i.e. without any UsbDevice entry) will be handled | true |
... | all parameters from AVNSerialReader except port. Those parameters will be used for devices without an UsbDevice entry. |
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 received | 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 |
AVNSocketReader
Input. Connects with a TCP server and reads 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 | |
timeout | connect timeout in seconds | 10 |
minTime | min time between 2 received messages | 0 |
filter | filter for NMEA data |
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 | maximal length (in hours) for the track data that is sent to the WebApp. Still files are there for older data but not for the app. | 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 is 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
Imports 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 | time in seconds that the importer waits after an new/changed file has been detected before the conversion starts. | 30 |
knownExtensions | list of extensions that the WebApp will offer to upload to the importer. | kap,map,geo |
keepInfoTime | time in seconds an information for an input is kept after removal | 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 defualt 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>
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 additionally be used for the sound
in the WebApp.
AVNPluginHandler
Management of plugins. category 2 (once, optional).
AVNPluginHandler is handling plugins that can
be installed into 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 data 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 for this time (in seconds) but we received valid data/time from n2k and valid position data in the NMEA - generate an 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 |