Wellenvogel AvNav

• Kontakt
• GitHub

Avnav Ocharts

Hint: since 2024/02/17 there is a new (Beta) version for the o-charts support. This new version also works on android. For a documentation refer to OchartsNG.

=== not for Android ===

Inhalt

AvNav is able to handle charts in various raster formats. So far it was unable to handle any commercial charts. The  o-charts company supplies charts for various regions of the world for usage in OpenCPN.

After some agreements with o-charts, those charts can now also be used for AvNav (starting with version 20200515 with a plugin - see below). At present you can use oesenc vector-charts and beginning from version 20220225 (and the related change in the o-charts shop - see releases below) you can also use oeRNC raster charts.

To display those charts in AvNav they must be rendered into raster images. This is handled by a new plugin for AvNav(avnav-ocharts). The rendering takes place on the fly whenever tiles are to be displayed. However, major areas of the chart will be prerendered to cached tiles upon chart installation. This way those charts can be used the normal way - without worring about the rendering process.

All oeSENC charts handling is performed by the plugin - including installation (you cannot install them directly via the download page). For this purpose a dedicated GUI is offered by the plugin. You enter it from the main page via (User Apps) and  Ocharts-Provider  .

Buying and Installing the Charts

Important Hint: If you do not have 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 lose 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 consists of the following steps:

1. Create 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. Upload the fingerprint to o-charts and create a system (basically assigning a name).
3. Buy charts
4. Assign charts to the system you created
5. After a short time you will receive an email from o-charts with a download link (zip file).
6. Upload charts to AvNav (via the plugin GUI).

For updates repeat steps 4, 5 and 6 (only requesting the notification mail at step 4)

For further chart sets steps 3-6.

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

I created a video to demonstrate this process. Additionally here is a short description.

Hint: If the charts are already registered on the same system (for OpenCPN) you can directly continue at step 6. Alternatively you could also configure to access the OpenCPN chart directories at the plugin .

1. Creating the fingerprint

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

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

Choose Download to save the created file on your device.

2. Uploading the fingerprints to o-charts

Enter the  o-charts page and upload the fingerprint.

With "Choose File" you select the file 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 the desired charts from oeSENC charts.

4. Assigning to your System

At 1 you can assign charts to your system (in this screenshot this is not available anymore as the max amount of 2 systems are already assigned). At 2 you request the mail holding the download link (you would do the same for updates - in the screenshot: last version I have downloaded is 21, latest 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 plugin's GUI select "Upload Zip" to transfer the zip file downloaded in step 5 to AvNav.

There will be a progress bar during upload.

After the upload is completed the zip file will be unpacked. Some initial checks can take some time.

Unless configured otherwise, the charts will be uploaded to /home/pi/avnav/data/ocharts/charts.

After all checks have passed successfully, the dialog will ask to restart the plugin to make the charts usable.

If the newly uploaded chart contains updates to an already existing set, the existing set will be deactivated at restart. You may change this later on within the GUI. Chart sets not required anymore can be deleted.

During restart a couple of error messages will be displayed briefly but within 30s the status should be at least set to yellow (the plugin is now reading all charts).

After all charts are successfully read the status should change to green (READY).

If the status turns to "ERROR" (red) you maybe uploaded a zip that was not built 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 screenshot you see the process ("FILLING") that was started after upload. It pre-renders a major set of chart tiles to a cache file. This will help to reduce on-the-fly rendering lags that otherwise would (potentially) occur due to the limited resources of the pi. This process can be active for several hours. The provider will use one CPU (out of the 4 available) on a raspberry pi during this time. Once prefill is completed cpu usage will dramatically decrease.

In any case you may immediately start using the charts (the prefill will only use the idle time).

As already mentioned, there is a chance of lagging to occur when you are displaying a particular range/zoom of the chart for first time (you will notice this especially on the smaller/older pi's). After first usage of an area the necessary tiles will be held in the cache file and there should be no more lag.

Adapting the Look and Feel

As the o-charts are vector charts you can adjust their look and feel. However some limitations must be considered:

1. The modifications apply to the server's chart settings - so they will become effective for all displays.
2. If you change the look and feel all data in the cache have to be wiped and all chart tiles must be rendered from scratch. So this will (potentially) again induce lag on smaller/older systems. The automatic cache prefill process starts again to pre-render a lot of tiles.

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

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

By selecting "Cancel" you can revert your changes. "Defaults" will reset to the built-in defaults. Most 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 to downscale higher resolution chart tiles if no chart tile is available at the requested zoom level.	1
OverZoom	Number of zoom levels to upscale a lower resolution chart tile if is no chart tile is available with better resolution. Hint: Scale, UnderZoom and OverZoom heavily influence the cost of the rendering process as they determine the number of charts to be processed to generate a single 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	Adjust to your needs	2
Safety Depth	Adjust to your needs	3
Deep Depth	Adjust to your needs	6

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

Feature Info (Object Query)

Since version 20201219 (versions of AvNav and plugin are required) chart object information is displayed upon click.

The dialog box displays compact information about "important" objects like lights, buoys and others.

By clicking "Info" you can view the raw information from the chart.

Installation

If you are running an AvNav image you can install the new plugin as package. For the Headless Images the necessary packages are already contained in the images. Additionally they are 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.

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

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

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

Releases

You can find all releases and intermediate developer builds (daily builds) at:

• Releases
• Daily Builds

Release Versions

• 20230706 packages
• Bug fix: Make check boxes visible again in settings
• 20230702 packages
• Bug fix #41: Handling of SENC overlays
• Bug fix #47: Handling of obsolete charts (open error 3)
• Improvement: allow to set a render timeouts in the plugin settings
• Usage of OpenCPN charts should work better now
• 20220605 packages
• Bug fix #36: Problems on OpenPlotter with OpenCPN flatpak
• 20220421 packages
• Bug fix: provider not always restarted correctly
• dependency to avnav-ocharts
• 20220307 packages
• Bugfix #31: Missing checkbox for "use OpenCPN charts"
• Bugfix: wrong version was shown
• improved error handling during chart usage, show such errors in the status
• correctly limit setting for memPercent
• 20220225 packages
• New O-charts shop
  During the next days the shop at o-charts will move to a new encryption schema.
  This will require this new version of the AvNav plugin. Additionally you need to install the new avnav-ocharts package - at least 0.9.0.72 (use the avnav update plugin to handle this). The package avnav-oesenc is now obsolete and can be removed (but it can also remain on the system).
  The handling of the charts does not change and all your old charts will continue to work. But once the shop is changed you will not be able to download new charts with the old plugin.
  With the new plugin (and the new shop) AvNav will now also be able to handle oeRNC charts (like the imray charts for the Med).
• packages will now also be available for the raspberry debian bullseye OS versions (both 32 bit and 64 bit)
• the handling for "reduce details on lower zoom levels" does now work correctly
• the "under zoom" setting now works better so it's range could be extended and the default changed to 4. This avoids some white areas if no charts directly matched the required zoom level
• You can now enable the usage of OpenCPN charts on the same system directly in the AvNav plugin settings. This will only work for charts installed with the new ocharts_pi plugin in OpenCPN.
• the error handling has been improved
• 20210711 packages
• bugfix: Cache rebuild not triggered when changing parameters
• 20210328 packages
• Parameter handling in AvNav (requires AvNav >= 20210322)
• Limit for zip file size enlarged to 3GB
• restart error fixed
• 20210115 package
• shift to python3 (requires AvNav since 20210115)
• improved error handling for charts
• 20201219 package
• Display of object information (requires AvNav >= 20201219)
• 2020115 package
• Improved memory handling. The Xvfb will be restarted if it reaches 120MB
• Faster start up. The chart information will be kept in a cache file. So reading the charts is only necessary if some charts have changed.
• Removed memory leak within the used OpenCPN plugin (workaround) - so the memory usage of Xvfb will not increase that much any more.
• Hint: When installing with dpkg -i (will give an error) you need to install missing dependencies with:
  sudo apt-get install -f
• 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 Notes

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 than the licensed systems.

Access to the charts in 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.

Plugin Configuration

Some of the plugins settings can be changed on the server/status page at "plugins/system-ocharts" (AvNav >= 20210322).

Those are:

Name	Meaning	Default
port	Http port	8082
threads	Number of threads that will be used	5
debug	log level for <datadir>/ocharts/provider.log. <datadir> on a raspberry is /home/pi/avnav/data	1
cacheSize	Maximal number of chart tiles that will be cached in memory. The plugin will additionally consider the allowed memory and will potentially lower this setting.	10000
diskCacheSize	Maximal number of chart tiles (for one set) that will be cached in a file.	400000
prefillZoom	Up to which zoom level the prefill process should already render chart tiles into the cache. If you increase this value the prefill will take more time.	17
memPercent	The amount of memory (percent of the system memory) that the plugin (correctly: the provider process) will use. If this value is not set (or set to low) the provider will use an internal minimum. This potentially could be rather low - especially when using raster charts. If it is very low the provider must open and close chart files very often and this will slow down it's operation. If you have enough memory (e.g. 2GB) you can increase speed by setting the memory to 1GB .	---
useOCPNCharts (seit 20220225)	If this fla is set you can use charts that have been installed with OpenCPN on the same system within AvNav . This will only work for charts being installed with the new o-charts_pi plugin (since 2022/03/01).	aus
ocpnConfigFile (seit 20220225)	Path to the OpenCPN config file (normally $HOME/.opencpn/opencpn.conf). The plugin needs to read this file to find the installed charts.	$HOME/.opencpn/opencpn.conf

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 by an AvNav plugin.

The GUI is a reactjs app that is also provided by the executable. It 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 set some additional parameters for the AvNav plugin by editing avnav_server.xml. Normally this is not necessary at all.

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

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 sufficient disk space is available only in /home/pi/avnav/data/charts.