OpenCPN

-= GPS Odometer

Links

Purpose

The GPS Odometer is a plugin for OpenCPN version 5.8 and higher. The keyword for this GPS Odometer is simplicity. Note that, as this is a GPS/GNSS based instrument, it requires GPS/GNSS data to display any data at all. The MNEA 0183 sentences RMC and GGA or the PGN’s 129026 and PGN 129029 for Signal K or NMEA2000 is a must. See further information below.

The GPS Odometer contain these basic functions:

  • An optional Speedometer with both analog and digital readout.

  • A Total Distance log, always displayed.

  • A Trip Distance log, always displayed.

  • A checkbox for Automatic trip reset to automatically execute Trip reset as defined in the setup dialogue.

  • An optional Departure / Arrival time display with digital readout.

  • A Trip reset button that resets Trip, Departure Time and Arrival Time.

  • An optional Autoreset Trip checkbox allowing to automatically execute Trip reset as defined in the setup dialogue.

  • A log generator logging up to one month old trip log information in text, csv or html format.

Instruments

The instruments are shown in a predefined order and it is not possible to change that order. It is however possible to toggle the optional instruments on or off right-clicking on the instrument panel selecting 'Settings'. Note that the panel size is always set to default size when an instrument is added or removed, you may then manually adjust the panel size or location to fit your preferences. The trip log, with viewing options, is selected right-clicking on the instrument panel selecting 'View trip log'.

  1. Total distance, Trip distance. Trip reset button and the Automatic trip reset checkbox are always displayed and can not be toggled off. Just leave the GPS Odometer on screen and reset the trip counter once the trip is ended (and log book written?) or before the next trip starts, alternatively use the automatic trip reset option.

  2. The trip will be considered started as soon as the speed increases above 'Minimum Route Speed', preset at 2 knots (selectable in the settings menu). The departure date and the departure time will be displayed on the instrument as the upper value for 'Departure & Arrival'.

  3. The trip will be considered stopped as soon as the speed decreases below 'Minimum Route Speed' and the arrival date and time will be displayed on the instrument as the lower value for 'Departure & Arrival'.

  4. If the speed then again increases above 'Minimum Route Speed' the trip be either continued or a new trip started (new departure) depending on if the 'Trip reset' button has been clicked or not. You may even shut down OpenCPN for e.g. a lunch break, the 'Trip distance' as well as 'Departure & Arrival' times are remembered until the Trip reset button is clicked or an Automatic trip reset is executed. The Automatic trip reset will be executed if 'Autoreset Trip' is selected and the stop time exceeds the 'Minimum trip stop time' set in the settings menu.

  5. Departure and arrival times are displayed according to the ISO standard 8601 primary alternative ('YYYY-MM-DD HH:MM').

  6. 'Total distance' is simply a counter of distance travelled and is not affected by the reset button. You can edit (increase only) the 'Totaldistance' value in the OpenCPN configuration file e.g. if the GPS Odometer is replacing another log instrument. The format is '12345.6' (one decimal only) and remember to do that while OpenCPN is shut down or your change will be lost.

  7. The Leg Trip functionality is a bit different as it has higher time and distance resolution, intended for e.g. tight navigation time and distance measurements like “How far is it between X and Y?” or “How long time does it take between Y and Z?”. Start or resume the distance and time counters clicking the Start/Stop Leg button, it will count distance and time until the button is clicked again. Click the Leg Reset button to zero distance and time and begin a new count session. This counter does not use the 'Minimum Route Speed' setting nor is it saved during trip stops.

  8. Several parameters can be adjusted in the 'Settings' menu, just right-click somewhere on the instrument and select 'Settings'.

  9. The most important setting is the selection of source protocol between NMEA 0183 (default), Signal K or NMEA2000. This selection is used to avoid the same type of information coming from multiple sources but still allowing e.g. NMEA 0183 to be generated from Signal K without affecting the GPS Odometer. This is a common situation when e.g. using a NMEA 2000 GPS/GNSS unit and a VHF with NMEA 0183 input.

  10. The trip log will detect Departure (trip start), Arrival with trip distance and Resumed trip where a trip is restarted without an intermediate trip reset, manual or automatic. You may also, in the settings menu, select the shortest trip stop to be detected and logged, either all stops or stops longer than the time selected in the setings menu. To view the log, just right-click somewhere on the instrument and select 'View trip log'. This opens a menu where the viewing options are selected. Note that there must be an associated viewer available for the 'External viewer' alternative. The generated view file is located either in the users home directory (Linux) or the Documents directory (Windows). The saved files have the extension .txt, .csv or .html respectively. File type .csv will have to be converted if used in e.g Excel but there are also free csv file readers available. Please note that trip log information older than one month is automatically removed.

  11. The text style and size settings are: 'Title': Title rows and button texts 'Data': Distance and time data 'Description: Digital speed notation in speedometer 'Small': Speedometer numbering When changing text styles or sizes, the instrument area is not updated to accomodate the new style or size but you need to manually adjust to the new outlook.

  12. Please do not set 'Min Route Speed' to low or you may get false trip start/stop times due to e.g. position inaccurancies when anchored.

  13. The Odometer has a filtering that dashboard does not use, e.g. it requires a certain number of satellites (default 4) and a HDOP level of 4 (not required by dashboard). These settings can be changed in the OpenCPN configuration file, see the troubleshooting section below. Please note that HDOP and Satellites are used with SIGNAL K that names these as 'GNSS Fix', 'DGNSS fix' and 'Precise GNSS'. One of these must be present.

GPS/GNSS signal information, coming from NMEA 0183, Signal K or NMEA2000 are selected in the settings menu. If one or both of the required sentences, as mentioned above, are missing:

  1. There will be no speed or distance count nor will the GPS Odometer start displaying data until NMEA 0183 GGA or NMEA2000 is indicating a valid GPS/GNSS signal (using the 'Satellites in use' and 'HDOP' information). There is also a few seconds delay (default 15) when powered on or when switching protocol, this to allow the system to be properly settled. Many GPS/GNSS units are also somewhat inaccurate until the position is accurate enough. Note that this is a power on delay that has no effect later on. This setting, named PowerOnDelaySecs, may be updated (from 5 and up) in the OpenCPN configuration file.

  2. It is essential to use a good quality and stable GPS/GNSS receiver. Some GPS/GNSS units are quite unstable when starting (although they are indicating a valid fix) and, as all distances are added, this will add to the trip and total distances or trigger false departure times.

Multiple GPS/GNSS units

A good and reliable GPS/GNSS unit, properly mounted, is the single most important navigational tool you have onboard. It should be on top of the list. There may also be other GPS/GNSS units, like e.g. AIS or VHF radio with built-in GPS/GNSS receivers, and this may then generate multiple position and speed data. The OpenCPN priority system is message based and may, if a message is e.g. incomplete, cause a mix of messages from to different GPS/GNSS units. Messages are also processed in the order received and the last sentence of each type will be used. The order used is as shown in the NMEA Debug Window (opened via 'Options → Connections' and activating 'Show NMEA Debug Window'). Also note that the protocol (NMEA0183 / Signal K / NMEA2000) is selected in the GPS Odometer settings as all the required signals, or priority options, are currently not available for external plugins like the GPS Odometer.

A general recommendation is hence to have one, and only one, reliable good quality GPS/GNSS receiver sending navigational data (e.g. NMEA0183 RMC, GGA, GSV and GSA) to OpenCPN.

If you experience any kind of problems when having multiple GPS/GNSS units, then verify by either generating a VDR file for examination (recommended) or by opening the NMEA debug window and and check the sentences, those dropped will display in brown. You may close the settings main window and display only the debug window, this will allow you to stop/resume and copy the content if required.

If generating a VDR file, then use a standard text editor and remove everything but the lines starting with 'xxRMC' or 'xxGGA'. The letters 'xx' may be 'GP', 'EC' or something else, see the document referenced below. Group the lines and then glance through them swiftly comparing them, you will easily spot any irregularities. The trick is then to know which unit that is in error.

Now test having only one unit sending GPS/GNSS related data, preferably your dedicated GPS/GNSS receiver. All other GPS/GNSS related data should be dropped. You may efficiently do that following this procedure:

  1. Go to 'Options → Connections' and select the unit whose sentences should be dropped.

  2. In the 'Input filtering' select 'Ignore sentences'.

  3. Add the sentences RMC, GGA, GSV and GSA to be dropped.

This should not affect the functionality of any units, just make OpenCPN drop GPS/GNSS generated sentences. If this fixes the problem, then you have an error/discrepancy in the sentences received from your 'extra' GPS/GNSS units.

A good reference page for NMEA 0183 is found at: https://gpsd.gitlab.io/gpsd/NMEA.html

A note on NMEA 2000 GPS/GNSS units: OpenCPN has currently no option to prioritize units within a NMEA 2000 network so multiple GPS/GNSS units in the same NMEA 2000 network pose a large risk of getting conflicting messages unless they can be individually controlled.

General troubleshooting

The most common problem is the GPS/GNSS signal quality, often due to non-optimal GPS/GNSS unit placement. This can be easily verified examining the NMEA 0183 GGA message using OpenCPN 'Options → Connections' and activating 'Show NMEA Debug Window'. If you are using NMEA 2000 you need to generate NMEA 0183 messages either by using the TwoCan plugin or using the signalk-to-nmea0183 app activating GGA messages and reading the NMEA 0183 messages thru port 10110. Look for the GGA messages and these fields:

  1. Field 6 (following the E/W) is the Quality indicator, Should be 1 thru 5.

  2. Field 7 indicates the number of satellites, should be a minimum of 4. The required number of satellites may be adjusted setting the 'SatsRequired' parameter in the OpenCPN configuration file. The allowed range is 4 and up.

  3. Field 8 is the HDOP (Horizontal dilution of precision). This should be as low as possible with a recommended maximum of 4. The HDOP limit may be adjusted setting the 'HDOP' parameter in the OpenCPN configuration file. The allowed range is 1 thru 10. Increasing the 'HDOP' value is a last resort if nothing else helps but also an indication that there is a GPS/GNSS problem, placement or otherwise.

If any of these values becomes 'invalid' then the speed indicator will go to '0' and it will take a few seconds before the speedometer is showing any speed. This delay is introduced as the speed may, at start or straight after a valid fix, still show an erroneous value hence affecting the distance calculations. The delay, named 'PowerOnDelaySecs' defaults to 15 but may be adjusted setting the parameter in the OpenCPN configuration file. The allowed range is 5 and up. You should never see this effect apart from when the system is started if all is working as it should.

Total distance, Trip distance, Departure time and Arrival time are saved in the OpenCPN configuration file at shutdown. They are also, together with a few other parameters, saved in the GPS Odometer data directory and updated as values changes. The data log file in the GPS Odometer data directory also contains the log information. This dedicated save is done to ensure the information will survive e.g. a power outage or a system crash where OpenCPN does not shut down properly. The information in the data directory overrides the distances and times in the OpenCPN configuration file. . There is one exception for the Total distance where the highest of the two walues is used, see the description for Total distance above. . If a sudden shutdown occurs while on route, no arrival time will be given upon restart as there is no Arrival time available, it will display three dashes instead. . Starting and stopping OpenCPN, or clicking Trip reset, while on speed above 'On Route' speed may confuse the logging facility as e.g. an arrival time may be missing.

Bugs and inconveniences

The text height and length in the dialogue may not be correctly included in the size calculation. Just manually adjust the size to accomodate the texts.

Some of the parameters from the Settings menu does not update the instruments until OpenCPN is restarted, like the maximum speed setting in the speedometer.

The display on high reolution screens may not be optimal but regular screens should work just fine.

Installing

The GPS Odometer is installed using the package manager.

There is (currently?) no version available for the Android environment as I don’t have either the tools nor the knowledge to do that. Any help from the community would be appreciated.

Final comments

The name is 'GPS Odometer' as I started this before any GNSS units was available for regular boaters and changing the name is never a winning concept. GPS is also frequently used covering both GPS and GNSS systems.

I did this plugin as I wanted a simple GPS/GNSS based Odometer. The Logbook has that option but I did not need all the other stuff in there and also wanted an on-screen solution.

For 'dry-runs' I recommend using the VDR plugin playing a suitable trip.

Contact: You can PM me through OpenCPN in Cruisers Forum, look for LennartG or use Search → Advanced search → Search by user name.