Description avNav

Navigation in the Browser

AvNav is a free of charge, open source navigation software for recreational boaters. Like similar applications in this area, AvNav displays nautical charts and marks the boat's position using GPS devices attached to the system. Markers, waypoints, routes, tracks, AIS, external sensors and many more features are supported. The server concept is one of it's key features: AvNav installs on any Raspberry Pi, Windows or Android device acting as 'navigation server'. It collects relevant data from various sources and administers nautical charts. Server access and graphical represention can be realised on any device running a modern web browser, irrespective of it's operating system. AvNav is consequently optimised to be used on touchscreens. Different layouts can be defined to adapt the user interface e.g. to meet special user requirements or to fit specific screen dimensions.

Charts

Any raster charts (RNC), not encrypted by their author, can be used. Vector charts of type oeSENC can also be used. They are, however, not free of charge and need to be acquired at the o-charts shop.

Variants

There is more than AvNav's server variant: as an alternative a stand alone version is offered for Rapberri Pi (AvNav Touch) as well as an Android app. On top of that: 'AvNav for OpenPlotter' integrates seamlessly into the OpenPlotter 2 image with all necessary connections to SignalK server configured out of the box.
All software is available for download under an open source license.

Quickstart


15.12.2020

Important Note:

In no case I promise or can be held responsible for correct function of AvNav - especially using it for navigation is at your own risk. Before using it I recommend to carefully test the precision of the display and the used charts.

Overview

avnav-raspi-2020
The whole solution consists of different parts:

  • A Raspberry Pi with the server software reading the connected devices (e.g. NMEA via serial-USB converter – like PL 2303), Bluetooth GPS, multiplexing and storing the data and providing them via WLAN

  • A variant of this software for the desktop (Windows/OSx/Linux) to convert and prepare the charts

The raspberry pi creates an access point and various devices can access it's data:

  • Variant 1: the client (lie laptop or iPad) runs some (other) navigation software (tested: InavX, OpenCPN), those access the NMEA data via TCP or UDP.

  • Variant 2: the client device just runs a browser. All the navigation is handled by the AvNav WebApp provided by the raspi. There is no need for any other installed software on the device, only a current HTML5 browser (tested: Chrome Windows, OSX, Safari, Android starting 4.4 – Chrome/Stock/Boat Browser, IOS, Blackberry stockBrowser, WebBrowser mini).

The server part is written in python and can be configured via an xml file. The normal set up is ready to go - i.e. there is no need for any configuration to get started. Beside the software itself there are images you can download to get started - see installation.

The java script app provides all basic navigation functions on raster charts (gemf, mbtiles) or oeSENC vector charts  including AIS display, waypoint navigation, routes, tracks,... The charts to be used by the web app must be installed on the raspberry.

oeSENC charts can be bought in the o-charts shop.

Chart formats that cannot be handled directly in the app must be converted to gemf using AvNav at the desktop (or directly on the pi within the App). The converter can process the following formats:

  • All chart sources that can be read by GDAL software (especially BSB)

  • Charts downloaded with Mobile Atlas Creator

Beside the described set up there is also an  Android-App providing similar functions.The server part is implemented natively in Java, the display part is identical.

The following chapters describe the parts a bit more in detail.

The Server Software (avnav_server.py)

The pi holds a normal Debian image (app. 2GB). A couple of additional packages get installed together with AvNav (see list below).

Structure of the server software:

The server tries to detect all devices connected via USB-serial and via bluetooth-serial. You have to take care that your USB-serial device is correctly handled by the pi - like e.g. this one. The server scans connected devices (via dbus) and discovers the device nodes. It then tries to do some auto-bauding (i.e. determine the baudrate for the device) between 4800 and 34000 baud and tries to recognise NMEA data. If no data is detected it starts over again by closing and reopening the devices. This way it can cope with disconnecting and reconnecting devices. I have connected a AIS VHF receiving GPS data from the pi and sending AIS data to it. If bluetooth serial devices are detected AvNav will also try to read from them.

You can also configure devices to output the data and this way have a NMEA multiplexer.

All NMEA data internally are stored in a queue and made available for output. By default a TCP socket is open where you can connect to (default port: 34567).

Additionally you can configure more outputs (TCP,UDP,serial).

Internally the data (including AIS) are forwarded to a decoder storing them in the server  ("NMEA decoded data"). Those data  are available as JSON for the webapp's HTTP - API requests. Additionally the server writes track data, computes routing information, handles anchor watch and alarms.

To control an auto pilot the server computes RMB data and sends them to the internal queue so that it can be received by any connected device.

If there is a valid time information in the GPS data it sets the system time of the raspberry.

For automated start up there is a (systemd) service so you can control start and stop via systemctl.

Most of the server functions you can configure via an xml file (avnav_server.xml). In the installed template there are examples for many use cases. Additionally (if a bluetooth device has been detected) AvNav tries to connect to bluetooth serial devices and receive NMEA data from them.

Normally there is no need for additional configuration.

You can find the software on github. For installation instructions see the installation description.

Software on the raspberry

On the  raspberry the following directories are used;

Directory

Content

/usr/lib/avnav software

/home/pi/avnav/data/

base data directory

.../data/charts

charts - see  converting charts.

.../dava/log

logfiles

.../data/tracks

trackfiles (gpx), one file per day, nmea logs

.../data/routes routes - xxx.gpx and the current segment (leg) currentLeg.json
.../data/import input directory for the converter: charts stored here will be converted to 'gemf'
.../data/user/viewer location of user files (user.js, user.css,...)
.../data/user/images location for user image files
.../data/layout location if user layout files

Apart from the systemd scripts (and some command scripts) the software is running as user pi (on the raspberry). You can also start the software from the command line using the command "avnav". On a desktop system you may run this as any user.

The Web App

The app is a single page app built with ReactJs.
It communicates with the server using Ajax (javascript). The app entry point is http://avnav.avnav.de/viewer/avnav_viewer.html. It is optimized for mobile devices - especially tablets starting at 7". But you can use it also on desktop systems or larger displays. Meaningful usage starts at around 900x540 pixel.

URL Parameters

The WebApp support a couple of URL Parameters that you can add to control some functions.

parameter description
defaultLayout The name of an existing layout that will be used as the initial layout.
defaultSettings The name of an existing settings file (regex supported) that will be used as default settings when AvNav is started for the first time in the Browser with this URL.
Example: defaultSettings=.*localFirefox
fullscreen You can provide a parameter in the form of "server:<command>". Command must be an existing command that has been configured at the AVNCommandHandler. This will be executed when the Fullscreen Button is pressed (instead of using the browser fullscreen feature)
Example: fullscreen=server:fullCommand
dimm You can provide a parameter in the form of "server:<command>". Command must be an existing command that has been configured at the AVNCommandHandler. This will be executed when the dimm Button is pressed (instead of using a dimm function that is available in the Browser - like AvNav on Android)
Example: dimm=server:dimmCommand
noCloseDialog Prevent the Dialog that will warn you if you are going to leave the AvNav page.
Example: noCloseDialog=true
splitMode Start AvNav directly in split mode.
Example: splitMode=yes
preventAlarms Do not show any Alarms.
Example: preventAlarms=true


For a user documentation of the web app refer to this description.