Troubleshooting

For trouble shooting and lower level nitty gritty details, the command line, configuration files and debuggers are your friends.

OpenCPN command line interface (CLI)

    $ ./opencpn --help
    Usage:
      opencpn -h | --help
      opencpn [-p] [-f] [-G] [-g] [-P] [-l <str>] [-u <num>] [-U] [-s] [GPX file ...]
      opencpn --remote [-R] | -q] | -e] |-o <str>]

    Options for starting opencpn

      -c, --configdir=<dirpath>     Use alternative configuration directory.
      -p, --portable                Run in portable mode.
      -f, --fullscreen              Switch to full screen mode on start.
      -G, --no_opengl               Disable OpenGL video acceleration. This setting will
                                    be remembered.
      -g, --rebuild_gl_raster_cache Rebuild OpenGL raster cache on start.
      -D, --rebuild_chart_db        Rescan chart directories and rebuild the chart database
      -P, --parse_all_enc           Convert all S-57 charts to OpenCPN's internal format on start.
      -l, --loglevel=<str>          Amount of logging: error, warning, message, info, debug or trace
      -u, --unit_test_1=<num>       Display a slideshow of <num> charts and then exit.
                                    Zero or negative <num> specifies no limit.
      -U, --unit_test_2
      -s, --safe_mode               Run without plugins, opengl and other "dangerous" stuff
      -W, --config_wizard           Start with initial configuration wizard

    Options manipulating already started opencpn
      -r, --remote                  Execute commands on already running instance
      -R, --raise                   Make running OpenCPN visible if hidden
      -q, --quit                    Terminate already running opencpn
      -e, --get_rest_endpoint       Print rest server endpoint and exit.
      -o, --open=<GPX file>         Open file in running opencpn

    Arguments:
      GPX  file                     GPX-formatted file with waypoints or routes.

-l, --loglevel=<str>

Set the amount of logged information. The source code contains wxLogInfo(), wxLogDebug() and wxLogTrace() statements. Setting the loglevel to info, the default, only prints wxLogInfo() messages in the log. Setting it to debug makes the wxLogDebug() messages appear, and likewise for trace and wxLogTrace()

-u, --unit_test_1

Test cycles through all possible charts in the currently loaded chart database, adjusting the viewport to show the loaded chart automatically. The value of this test is clear: it provides an unattended stress test of OpenCPN. It is most fun to watch in quilt mode.

The test runs until all charts in the database have been visited once. Let’s think of this as a Beta test tool.

A side-effect of this switch is that it can be used to process a set of ENC charts into SENC files. The first, time consuming processing of ENC charts, can this way be done unattended.

-p

The portable option is explained in. https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:advanced_features:portable_opencpn_v2/ Basically, it allows OpenCPN to run just using local data directories for example on a USB stick or in an IDE.

-no_opengl

A total switch-off of OpenGL, in a more thorough way than in "Options".

Debugging Output Settings for Logfile

The config or ini file contains a lot of settings that are saved between sessions. Debug statements can be added to produce a lot of output when problems arises in certain areas. The following statement are recognized and can be added to the config file before a session starts.

[Settings] ...
DebugNMEA=500   Writes 500 NMEA sentences to the log file\\
DebugCM93=1     Writes volumes of debug info relating to CM93 to the logfile.\\
DebugS57        Add logfile debug output for S57\\
DebugGDAL       Add logfile debug output for GDAL\\

Using a FIFO for ais debugging.

See the code in ais.cpp:

A special test for a user defined FIFO
To use this method, do the following:
a.  Create a fifo            $mkfifo /tmp/aisfifo
b.  netcat into the fifo     $nc $ip $port> /tmp/aisfifo
                sample ip port could be  nc 82.182.117.51 6401 > /tmp/aisfifo
c.  hand edit opencpn.conf and make AIS data source like this:
     [Settings/AISPort]
     Port=Serial:/tmp/aisfifo

This also works if you have an ascii ais log
for which you can simply $cat ais.log> /tmp/aisfifo

You may see that if the port name contains the string "fifo", then the requirement for the port to be a TTY is relaxed.

wxWidgets

OpenCPN uses wxWidgets, currently version 3.2.x on Linux packages, and 3.2.5 for other platforms. See wxWidgets Reference Manuals

wxWidgets uses a tick-tock release schedule where even-numbered versions are stable including a stable ABI. Odd-numbered version are unstable, development versions.

On Linux platforms OpenCPN normally uses the current stable version, at the time of writing 3.2. This is partly a practical issue since conservative distributions like Debian don’t package unstable, odd versions.

One other platforms unstable, odd versions are occasionally used.

Changing wxWidgets version leads to a ABI break for plugins, which must be re-compiled against the new version. However, wxWidgets has strong ABI compatiblity promise for minor updates, so for example updating from 3.2.3 to 3.2.4 should not affect plugins as long as nothing which only exists in 3.2.4 is used.

This PDF wxWidgets History document might help with wxWidgets issues.