AvNav OCharts

Avnav Ocharts

=== not for Android ===

Inhalt

AvNav is able to handle chart in various raster formats. Until now it was unable to handle any charts you can buy officially. There is the company o-charts that is supplying charts for various regions of the world for the usage in OpenCPN.

After some agreements with them those charts can now (starting with version 20200515 with a plugin - see below) also being usaed for AvNav. Until now you can use oesenc vector-charts.

To use those charts in AvNav they have to be rendered into raster images. This is handled by a new plugin for AvNav(avnav-ocharts). This rendering takes place on the fly whenever the charts should be displayed. This way those charts can be used the normal way - without really dealing with the rendering process.

All handling for those charts is completely done by the plugin - including the installation (you cannot install them directly via the download page). There is an own GUI at the plugin for this purpose. You can reach it from the main page via (User Apps) and  Ocharts-Provider  .


Buying and Installing the Charts

Important Hint: If you do not own a dongle from o-charts your chart license is bound to your system. So in case of any trouble do not set up a new system (by writing an image to an SD card) but instead try to repair the system. If you set up a new system you will loose your license. I will by happy to support in case of trouble - contact e.g. via email.

To be able to buy charts at o-charts you have to create an account at their site first.

Afterwards you have to register the systems you would like to buy the charts for there. AvNav is using the "Offline" process .

This process consist of the following steps:

  1. Creating a "fingerprint" for the system you would like to use the charts at. In AvNav you will create it in the GUI for the plugin and download from there.
  2. Uploading of the fingerprint to o-charts and creating a system (mainly assigning a name).
  3. Buying charts
  4. Assigning charts to your created system
  5. After a short time you will receive an email from o-charts with a download link (zip file).
  6. Uploading the charts to AvNav (via the plugin GUI).

For updates you will have to repeat steps 4,5 and 6 (only requesting the mail at step 4)

For further chart sets steps 3-6.

For steps 2,3,4 and 5 you will need a system with internet connectivity. You can e.g. use a laptop or an android device.

For this process I created a video to show the basics. Additionally here is a short description.

Hint: If the charts are already registered at the same system for OpenCPN you can directly continue at step 6. Alternatively you could also configure the OpenCPN chart directories with o-charts at the plugin .

1. Creating the fingerprint

Via -> reach the GUI of the plugin, select the tab "Charts".

Use "Get Fingerprint" to create the fingerprint file. If you are using an o-charts dongle - just use "Get Fingerprint(Dongle)".

Use the dialog to save the created file on your device.

2. Uploading the fingerprints to o-charts

Go to the  o-charts page and upload the fingerprint.

With Choose File select the file you have stored at step 2. Assign a meaningful name to the new system - this will be part of the mails you will receive later.

3. Buying the Charts

Select from oeSENC charts the ones you want to buy.

4. Assigning to your System

At 1 you can assign charts to your system (in my pictore not possible any more as I already have assigned the max amount of 2 systems). At 2 you trigger the mail with the download link (you would do the same for updates - in the picture: last version I have downloaded is 21, newest available is 23)

5. Downloading the Charts

After a short time you will receive a mail containing the download link for your charts. Download the zip file.

6. Uploading the Zip File to AvNav

In the GUI of the o-chart plugin use "Upload Zip" to transfer the zip file you have downloaded in step 5 to AvNav.

There will be a progress bar during upload.

After the upload is finished the zip file will be unpacked and there will be some initial checks on it (this can take some time).

If you did not configure anything the charts will be uploaded to /home/pi/avnav/data/ocharts/charts.

After all checks have been passed the dialog will show up asking you to restart the plugin to make the charts usable.

If the newly uploaded charts have been an update for an already existing set the existing one will be deactivated at restart. You can change this later on at the GUI. If there are chart sets that you don't need any more you can delete them here.

During the restart there will be a couple of error messages but after app. 30s the status should at least be yellow (the plugin is now reading all charts).

After successful reading of all charts the status should change to green (READY).

If the status will change to "ERROR" (red) you potentially did upload a zip that was not for your current system. You can check details in the log file at /home/pi/avnav/data/ocharts/provider.log.

Now the charts are available and can be used.
At the "Status" tab you can see some more details.

In the picture you see that after uploading a process ("Cache Prefill") started that will pre-render chart tiles. This will help to prevent lags that otherwise would (potentially) occur due to the limited resources of the pi. The cache prefill will pick a couple of tiles for the chart set and will render them into a cache file.

Anyway you can start using the charts immediately.

As already mentioned there is a chance that lags will occur when you are using a particular range/zoom of the chart for first time (you will notice this espacially on the smaller/older pi's). After the first usage of a range the necessary tiles will be in the cache and there should be no lag any more.

Adapting the Look and Feel

As the o-charts are vector charts you can adapt their look and feel. Anyway there are some limitations you have to consider:

  1. The adaption takes place at the AvNav server - so it will become effective for all displays.
  2. If you change the look and feel all the data in the cache has to be wiped and all chart tiles must be rendered newly. So this will (potentially) again introduce some lag on smaller/older systems. Anyway the automatich cache prefill process starts again to pre-render a lot of tiles.

Changing the display parameters is done in the plugin GUI(->), tab "Main Settings".

If you change a setting (1) it will be shown bold. Changes will only become effective once you click "Update Settings"(2).

Using Cancel you can revert your changes. Defaults will set to the built-in defaults. Most of the parameters are similar to the ones you find at  OpenCPN settings.

The following parameters are available.

Name Meaning Default
Show Text Show text for chart objects true
Important Text Only hide less important text false
Light Descriptions show descriptions for lights true
Extended Light Sectors show sectors for lights true
Show Depth show soundings true
Chart Information Objects show special chart object infos true
Buoy/Light Labels show labels for buoys and lights true
National text on chart show national text true
Show Lights show lights true
Reduced Detail at Small Scale reduce details at lower zoom levels true
De-Cluttered Text improve text positioning true
Display Category Base,Standard,All,User Standard All
Graphics Style Paper Chart, Simplified Paper Chart
Boundaries Plain, Symbolized Plain
Colors 4Color, 2 Color 4 Color
Text Font Size Scaling for text on charts 1 (ca. 12px)
Soundings Font Size Scaling for soundings (since oesenc-pi 4.2.x) 1 (ca. 12px)
Scale Base scaling. Higher values for more details on lower zoom levels 2
UnderZoom Number of zoom levels a higher resolution chart will be downscaled if there is no chart at the requested zoom level. 1
OverZoom Number of zoom levels a lower resolution chart is upscaled if there is no chart with better resolution.
Hint: Scale,UnderZoom and OverZoom heavily influence the cost of the rendering process as they determine how many charts have to be considered when generating one chart tile. Lower values normally mean less charts (i.e. being faster) - but there could be white areas between chart tiles. The defaults should be a good compromise.
4
Depth Unit for soundings(Meters, Feet, Fathoms) Meters
Shallow Depth Adapt to your needs 2
Safety Depth Adapt to your needs 3
Deep Depth Adapt to your needs 6

At the tab "Detail Settings" you can switch on/off particular chart features.

Installation

You can install the new plugin as packages on AvNav images. For the Headless Images the packages are already available in the repository. You need to install

  • avnav-ocharts-plugin
  • avnav-oesenc

For avnav-ocharts-provider you need at least version 20200606. The package avnav-oesenc is the oesenc-pi plugin - repackaged to install into /usr/lib/avnav/plugins/ocharts to avoid conflicts with a parallel OpenCPN installation.

sudo apt-get update
sudo apt-get install avnav-ocharts-plugin avnav-oesenc
sudo systemctl restart avnav

If you are working on other images you should add the repository from free-x:

deb https://www.free-x.de/debian buster main contrib non-free

You can also see the packages in the release list below. To use one of those packages (if it is not in the repo yet or if you need an older one) - just download and install the package (replace the version by the one you want):

cd /home/pi/avnav
wget -O avnav-ocharts-plugin_20200606-raspbian-buster_armhf.deb https://www.wellenvogel.net/software/avnav/downloads/release-ochartsplugin/20200606/avnav-ocharts-plugin_20200606-raspbian-buster_armhf.deb
sudo dpkg -i /home/pi/avnav/avnav-ocharts-plugin_20200606-raspbian-buster_armhf.deb
sudo systemctl restart avnav

You can also download on a PC, scp/WinScp to the pi and install then.

Releases

  • 20200710 package
    • You can now set the directory for the charts - see details
    • When uploading charts it is checked if those charts can be read. Otherwise the upload is rejected.
    • No errors in GUI any more when restarting the provider
    • correctly work on a vfat partition (as used by avnav touch)
  • 20200705 package
    • correct a problem in the OpenCPN plugin that could potentially stop it from decoding charts after running for a long time.
  • 20200606 package
    • first version

License Hints

Using the charts in AvNav with the oesenc-pi plugin has been agreed with o-charts and therefore is inline with their license conditions.
You have to agree to the license conditions of o-charts. Especially it is not allowed to copy the charts or use them on other systems then the ones you have licensed them for.

Access to the charts inside AvNav is only possible from within the local net. You can connect at most 5 devices (Clients) at the same time.

For software licenses see the Readme.

Technical Details

The charts are provided by an executable on the raspberry pi that normally serves at port 8082. This executable loads the oesenc-pi OpenCPN plugin.
Communication with AvNav is handled via an AvNav plugin.

The GUI is a reactjs app that is also provided by the executable. and is integrated into AvNav as a User App.

You will find the complete code at GitHub.

You install into /usr/lib/avnav/plugins/ocharts. The data directory is /home/pi/avnav/data/ocharts. You can configure the AvNav plugin within avnav_server.xml. Normally this is not necessary at all. If you need to configure anyway this has to be done below the Plugin-Manager.

<AVNPluginHandler>
...
<system-ocharts port="8082".../>
</AVNPluginHandler>

For a list of available options refer to the description in the plugin source code.

If you e.g. want to use charts that you already installed for OpenCPN you can just configure the OpenCPN chart directories with o-charts like:

<AVNPluginHandler>
...
<system-ocharts chartdir="/my/chartdir1,/my/chartdir2"/>
</AVNPluginHandler>

Normally the recommendation is anyway to upload the zip files like described at  charts .

Since version 20200709 you can separately set the directory for uploading the charts:

<AVNPluginHandler>
...
<system-ocharts uploadDir="$DATADIR/charts/ocharts"/>
</AVNPluginHandler>

In this example the directory is set to /home/pi/avnav/data/charts/ocharts (normally it is located at /home/pi/avnav/data/ocharts/charts). This could be helpful on the  touch image as only in /home/pi/avnav/data/charts there is sufficient disk space.