Waypoint recognition¶

LRAUV missions have no explicit concept of a waypoint: a position is given by a pair of separate mission arguments, one for the latitude and one for the longitude, e.g., Lat3 and Lon3. TethysDash recognizes such pairs by their names, according to a list of naming specs. The recognized pairs are the waypoints shown in the Dash UI (see Waypoints) and reported by GET /api/wp and GET /api/vehicles/{vehicle}/status.

Naming specs¶

Each spec indicates a pair of base names, plus either:

acceptsNumericSuffix: the names may be followed by a number, which gives the position of the waypoint, e.g., Lat3/Lon3 is waypoint 3; or
givenPosition: the position of the waypoint, for names without a numeric suffix.

Without a numeric suffix or a given position, the position is -1. Waypoints are ordered by position, then by the order of the specs.

An argument name matches a spec only as the exact base name (case-sensitive), plus any digits if acceptsNumericSuffix: no prefix or other text. For example, TransitLat does not match the Lat spec; it needs its own. Arguments must be in degrees.

The built-in specs:

Latitude	Longitude	Numeric suffix	Position
`Lat`	`Lon`	yes
`Latitude`	`Longitude`	yes
`LatListening`	`LonListening`	yes
`TransitLat`	`TransitLon`	yes
`CenterLatitude`	`CenterLongitude`	yes
`SamplingStartLatitude`	`SamplingStartLongitude`		0
`SamplingEndLatitude`	`SamplingEndLongitude`		2

Customizing the specs¶

The specs can be given in a waypointNaming.json file in the configuration directory (where TethysDash.conf is: /opt/tethysdash/conf in the Docker setup, that is, ${TETHYSDASH_CONFIG_DIR} on the host). Without this file, the built-in specs are used.

The file has the whole list, which replaces the built-in one. For example, with the built-in specs:

{
  "latLonPairSpecs": [
    { "latBaseName": "Lat", "lonBaseName": "Lon", "acceptsNumericSuffix": true },
    { "latBaseName": "Latitude", "lonBaseName": "Longitude", "acceptsNumericSuffix": true },
    { "latBaseName": "LatListening", "lonBaseName": "LonListening", "acceptsNumericSuffix": true },
    { "latBaseName": "TransitLat", "lonBaseName": "TransitLon", "acceptsNumericSuffix": true },
    { "latBaseName": "CenterLatitude", "lonBaseName": "CenterLongitude", "acceptsNumericSuffix": true },
    { "latBaseName": "SamplingStartLatitude", "lonBaseName": "SamplingStartLongitude", "givenPosition": 0 },
    { "latBaseName": "SamplingEndLatitude", "lonBaseName": "SamplingEndLongitude", "givenPosition": 2 }
  ]
}

Each entry in latLonPairSpecs has the following members:

Member	Type	Required	Description
`latBaseName`	string	yes	Base name of the latitude argument
`lonBaseName`	string	yes	Base name of the longitude argument
`acceptsNumericSuffix`	boolean	no (default `false`)	Whether the names may be followed by a number, which gives the waypoint position
`givenPosition`	integer, 0 or more	no	Position of the waypoint; only allowed when `acceptsNumericSuffix` is not `true`

Also:

Names consist of letters, digits, and underscores, not ending with a digit.
Each name may appear in only one spec, whether as a latitude or a longitude name.
The list must have at least one spec.
No other members are allowed, so a misspelled member name makes the file invalid.

Activation¶

Adding, changing, or removing the file takes effect without a restart: the file is checked for changes when waypoints are requested, at most every 10 seconds. The TethysDash log indicates the outcome:

loaded N specs from .../waypointNaming.json
invalid naming file: ...: the previous specs remain in effect
.../waypointNaming.json not found; using the built-in specs