|  |  | Real-time logging

## Real-time logging

At present there are two variants of the implementation, that will probably be merged in the future. Any receiver sending data in the NMEA 0183 v2.0 standard format can be used with GPSMan and can use any of the two variants. This also applies to Garmin and Lowrance receivers. For the time being there is no support for real-time logging if the receiver is declared to be a Magellan.

Users of Lowrance receivers will want to use the variant for Lowrance. Users of Garmin-defined protocols, be it the serial or USB Garmin protocols , or the Simple Text Output Protocol, should use the variant for Garmin.

Both variants implement some sort of simulator that can be helpful for tests and in getting acquainted with the interface before going to real-time usage.

GPSMan will work with the variant corresponding to the receiver brand selected in the options menu. After changing this option the program must be restarted because different code has to be loaded.

### Variant for the Lowrance

This variant was designed and implemented by Brian Baulch (baulchb`_at_`hotkey.net.au) who has prepared a description of it.

The file `exerciser.tcl` used for simulation by this variant can be found in the `util` directory. It must be edited for configuration before use.

### Variant for the Garmin

This variant implements:

- Garmin and NMEA 0183 protocols,
- recording of logging data that can be saved to file (at a certain moment, or continuously) and converted to a track,
- real-time animation in the map window (moving map),
- a travel/navigation interface, and
- a driving simulator and a random generator that produce fake logging data, to be used in training/testing.

Protocols supported by this variant are the following:

- Garmin PVT (position, velocity and time) Data Protocol, which is a part of the Garmin (`GRMN/GRMN` or `Garmin`) protocol,
- Garmin Simple Text Output Protocol (`Text Out`), and
- part of NMEA 0183 v2.0.

Some receivers must be configured to use one of these protocols: this is done in some receivers in a `Interface` display under `Setup`. Not all Garmin receivers support the first two, in which case NMEA 0183 should be selected and the variant for the Lowrance may also be used. If the selected protocol is not supported, either GPSMan knows about that and issues a warning, or there will be no information captured by GPSMan.

Facts that may help in choosing among the available protocols:

- Garmin PVT can be used along the rest of the Garmin (serial or USB) protocol, meaning that getting and putting other information from/into the receiver can be done while real time logging is on; the receiver will temporarily stop sending logging information while these operation take place -- this may be DANGEROUS if the logging information is crucially needed for navigation; it is the user's responsability not to initiate such operations in these conditions;
- both Simple Text and the implemented part of NMEA 0183 are one way protocols: information is only sent from the receiver to GPSMan; this means that it is not possible for GPSMan to check the connection with the receiver: GPSMan will be passively waiting for information to appear on the serial port;
- Simple Text carries less information than Garmin PVT (neither EPE, expected position error, nor EPV, expected position vertical error), while NMEA 0183 may carry more information than Garmin PVT; it is difficult to say more than this because there is no complete information on which NMEA sentences (commands) are sent by receivers.

Selecting the protocol in GPSMan is done in the GPSMan's receiver window using the `Protocol` menu, or the entry with this name of the `GPS Receiver` menu. Note that there is an option that defines the default protocol to be used.

If GPSMan was invoked by using the `start travel` command the protocol will be either the default in the preferences file or the protocol given by the `-prot` command option.

Two other entries in these menus start simulators of logging data that will be helpful in getting acquainted with the interface before real-time usage:

- `simulator` generates random (and somewhat inconsistent) data;
- `driving simulator` provides an interface for the user to "drive" (starting from a waypoint) and in this way generate logging data.

A simulator will be switched off only when a different protocol is selected.

Controlling the real-time logging is done with the three buttons `Get Log` (or `Stop`), `Record` and `Animation` in the receiver window, or the corresponding entries of the receiver menu under `Real-time track log`. The first starts and stops the input of logging information, the second launches a window that records that information, and the third starts the animation on the map. These buttons/entries can be actuated independently of each other, but it is obvious that the recording or the animation cannot start or go on if the input has not started or has been stopped. In this way the user may select when to record or when to have the animation. The recording window or the animation control window must be used to stop recording or the animation, respectively.

If GPSMan was invoked by using the `start travel` command the animation is started unless the connection to the receiver could not be established.

The control buttons in the recording window and in the animation control window affect only the recording and the animation, respectively, except in what concerns the logging time interval which is the same for the recording and the animation. The minimum value for the time interval depends on the rate at which the receiver sends information. The initial value for it is 2 seconds. The recording window and the animation control window will appear only after the first valid logging information is received, and this means at least 2 seconds from the clicking on the buttons/entries.

If GPSMan is invoked by using the `start travel` command the time interval can be given as the last argument to the command.

The recording window shows several columns with the logging information. These are, from left to right:

- number of the fix,
- local date and time,
- the latitude and the longitude (datum: "WGS 84"),
- altitude in metres (the existing option on user unit for altitude is not considered),
- quality of the position fix,
- EPE (estimated position error), EPH (expected position horizontal error), EPV (expected position vertical error) in metres,
- the 3 coordinates of the velocity vector in metres/second,
- TRK, the true track or bearing (CMG, course made good, track made good), true North.

Columns for which there is no information for the very first fix will be hidden automatically. The title of a column is a button that hides the column. This will be wanted for columns that are not being used or needed. The information in a hidden column is not lost and is updated. At any time a hidden column can be shown again by selecting its name from the `Show` menu.

The `Restart` button will destroy all the recorded information and restart recording.

The entries in the `Save` menu save as text the contents of the columns either in a one-shot fashion (`Existing log`), or writing the current contents and writing each new information when it comes up (`continuously`). In the latter case, the file will be closed when this menu entry is deselected or when real-time logging is stopped.

The text obtained with this menu cannot be re-loaded by GPSMan. To save the information in a format readable by GPSMan the `Make TR` button should be clicked to create a track, which can then be saved and loaded in the normal way.

The moving map works as the animation for a track described above. The main difference is in the scale that instead of setting the animation speed sets the logging interval.

For the time being there is no automatic loading of background images, a feature present in the variant for the Lowrance.

The travel/navigation interface provides

- two alternative displays, configurable by the user, to show real-time logging data and navigation information,
- navigation information (including warnings) to
  - record the current position and return to it (MOB, man over board),
  - create a waypoint whose coordinates are those of the last point in the real-time log; this fails if the waypoint edit window already exists,
  - go to a selected waypoint,
  - follow a selected route, track or polyline,
  - go back, following in reverse the real-time track since travelling was started;
- a `Change` menu (referred to as the menu in the remainder of this subsection) to control travelling/navigation and giving access to the receiver menu.

WARNING! use of this interface is at the sole risk of the user. In particular, the use of a laptop computer while driving alone is extremely dangerous. The user may also want to read the safety alert from the United States Coast Guard regarding the use of GPS equipment in boats.

A distinction is made here between travelling and navigating in the sense that the latter implies that there is a destination (when going to a waypoint or following a route) while the former does not. Starting a travel changes the map window top replacing the buttons by the travel/navigation displays. Stopping travelling restores the map window and will suspend (but not forget) current navigation objectives which will be resumed if travelling is again selected.

If GPSMan was invoked by using the `start travel` command travelling is started unless the connection to the receiver could not be established.

The following information from the real-time log can be shown when travelling:

- local time,
- position (latitude and longitude, "WGS 84" datum),
- altitude in metres (the existing option on user unit for altitude is not considered),
- `TRK`, true track, current bearing (COG, course over ground, CMG, course made good, track made good), true North,
- quality of the position fix,
- speed in user units,
- vertical speed in metres/second and up/down arrow indicators,
- type of receiver fix.

Other information only available when navigating:

- `CTS`, course to steer,
- `TRK`/`CTS` indicator, with an external compass ring (current track pointing up) and a CTS arrow,
- `TRN`, turn (difference between course to steer and true track),
- `TRN` arrow indicator,
- `To`, current destination (when following a route or track, next point in it),
- `From`, previous point in route or track,
- distance to current destination,
- `ETA`, expected time of arrival at current destination,
- `ETE`, expected time in route to current destination,
- `VMG`, velocity made good (velocity along the line from starting/previous point to current destination), in user units,
- `XTK`, cross-track error (distance from current position to line from starting/previous point to current destination), in user units.

Navigation is started from the menu by selecting an objective which can be forgotten (navigation stops), suspended (navigation displays are frozen) and resumed.

Navigation to a point is made along a line of constant bearing with no drift (wind or stream effects) taken into account. This means that the transport velocity is assumed to be null and that CTS (the course to steer) is taken to be the bearing to the point. Computations use the so-called plane-sailing formulas that are commonly accepted as valid for distances up to 600 nautical miles [Gardner and Creelman, 1965], [Moore, 1964], [Macfarlane, 1963]. A point is arrived at when the distance to it is less than a user defined arrival distance.

Navigation along a route, track or polyline can be configured to be made:

- either exactly, meaning that each point must be arrived at before the next is selected as current goal; or approximately, in the sense that the current goal is abandoned in favour of the next when a certain criterion is met even if the point is not yet arrived at (see below);
- either starting from one end of the route or track, or from its nearest point (relative to the current position);
- either in the normal direction, or in reverse.

At any moment the user can force a change to the next goal from the travel menu.

Following a route, track or polyline in an approximate way is implemented by considering only the current position and the next two points (the current destination and the point after it if there is one) because of efficiency issues. This means that navigation will be blind to all other points in the route, track or polyline even when the current position is closer to any of them than to the next two points. The criterion for changing the goal has a looseness parameter that can be changed from the menu. When a change to the next goal is about to be made a second CTS arrow (in a different colour) will be shown in the `TRK`/`CTS` indicator giving the bearing to it.

Tracks and polylines will be simplified to a certain number of points before being followed in an approximate way. In this case, numbers identifying track points will be preceded by an asterisk ("`*`") indicating that the numbers are different from those in the track.

Going back is implemented as following exactly the travelling log in reverse. This log is started when travelling begins and cleared only when restarting travelling, upon user confirmation. As a copy of it is used in going back, such a navigation will not be affected by clearing it.

Warnings will be issued as messages at the left upper corner of the map. Different colours are used for different priorities. User warnings can also be issued after configuration from the menu, and warnings (except those standing for danger) can be disabled without loosing the configuration. In case a warning is issued when another one is still being displayed it will either replace the previous one or be discarded depending on their relative priorities. There are the following classes of priority, in decreasing order:

|  | owner |  | usage
`important` |  | GPSMan |  | possibly dangerous situations
`high` |  | user |  |
`medium` |  | user |  |
`normal` |  | GPSMan |  | arrivals, errors
`low` |  | user |  |
`info` |  | GPSMan |  | other information

User warnings may be any of:

|  | when |  | needs
proximity to WP |  | approaching |  | WP, distance (user units)
|  | leaving (anchor) |  | WP, distance (user units)
speed |  | in excess |  | limit (user units)
vertical speed |  | out of range |  | minimun (may be <0), maximum (m/s)
turn |  | in excess |  | limit (degrees in -180 to 180)
cross-track error |  | in excess |  | limit (user units)

The configuration of the travel/navigation displays, warnings, arrival distance, and parameters for changing goal are kept on the saved state.

|  |  | Real-time logging