Routes and waypoints

When someone on the chartplotter selects a waypoint and presses GoTo, or activates a saved route, the plotter starts broadcasting where the boat is being taken: which waypoint is next, how far away it is, what bearing to steer, and how far off the intended track the boat currently is.

muxen-nmea2000 collects that and publishes it as one message, so a MUXEN screen can show the same route the plotter is following — the active leg, the cross-track error, the full list of waypoints — without being the plotter.

The daemon is a reader here. It never activates a route, never changes a waypoint and never sends anything to the plotter.

The three modes

Everything on this topic hangs off one field, mode:

mode	Meaning
route	a saved route is active; there is a waypoint list
goto	the plotter is steering to a single waypoint, with no route
idle	nothing is active

goto is the common case in practice — picking a mark and pressing GoTo is what most people do — and it is why the waypoint list can legitimately be absent while navigation data is present.

What gets published

Enable it with --report-route, or ReportRoute in the deploy configuration.

• Topic nmea/route
• Rate 1 Hz in route and goto, every 60 s in idle
• QoS 0, retained
• expireAfterSec 30 when active, 70 when idle

The idle behaviour is the interesting one: rather than going silent, the topic keeps republishing mode: "idle" once a minute with a longer expiry. A consumer can therefore always distinguish "no route" from "the daemon has stopped", which a silent topic cannot.

data
├── mode
├── activeNavigation
├── route
└── waypoints[]
metadata

activeNavigation is the live steering picture:

Field	Meaning
xteNm	cross-track error in nautical miles, signed
xteMode	how it was computed
distanceToWpNm	distance to the destination waypoint
bearingReference	true or magnetic
bearingOriginDestDeg	bearing along the leg, origin to destination
bearingPosDestDeg	bearing from the boat to the destination
originWaypoint, destWaypoint	waypoint identifiers
destLatitude, destLongitude	destination position
closingVelocityKnots	speed made good toward the destination
perpendicularCrossed	the boat has passed abeam of the waypoint
arrivalCircleEntered	the boat is inside the arrival circle
calculationType	greatCircle or rhumbLine
etaDate, etaTime	estimated time of arrival

originWaypoint is omitted on a GoTo, because there is no origin.

route describes the route itself: routeId, databaseId, routeName, databaseName, status (inactive, active or reverse) and isCircular.

waypoints[] lists the waypoints in the order they will be visited, each with wpId, rps (its position in the route), name, latitude, longitude, xteLimitNm and navigationMethod.

metadata carries rxDate, rxTimestamp, expireAfterSec and waypointCount.

Reverse routes

status: "reverse" means the plotter is running the route backwards. The waypoint list is published in the order the boat will actually visit them, so a consumer draws the legs in sequence without having to know about the reversal. route.status is still reported, because a display may well want to say so.

How it ages

Two different clocks, because the two kinds of data behave differently:

Data	Expiry	Why
cross-track error, navigation data	5 s	live steering; stale is dangerous
route metadata, waypoint list	5 min	a route does not change while you sail it

The waypoint list is also broadcast only on demand — a plotter sends the waypoints when the route is activated or changed, not continuously — so a short expiry there would blank the route between updates.

When the plotter reports the route as inactive, the daemon clears its route state immediately rather than waiting out either timer, and publishes mode: "idle".

Partial data is normal

A route arrives across several message types, and the daemon publishes what it has rather than waiting for a complete set. Expect to see:

• activeNavigation present with an empty waypoints[], seconds after a route is activated and before the waypoint messages arrive;
• a waypoint with a position but no name, because names arrive in a separate message from positions;
• a waypoint with no xteLimitNm, because the cross-track limit is keyed by route position and is discarded if it arrives before the waypoint it belongs to. The plotter resends it.

--route-max-waypoints N (or RouteMaxWaypoints) bounds the list. Default 500.

One plotter at a time

The daemon locks onto the first device that sends route data and ignores route data from any other. Two chartplotters both broadcasting their own active route would otherwise interleave into one incoherent route.

The consequence: on a boat with two plotters, the one that spoke first after the daemon started is the one on the screens. Restart the daemon to change that.

Which PGNs feed it

PGN	Name
129283	Cross Track Error
129284	Navigation Data
129285	Route/WP Information
130064	Route and WP Service — Database List
130065	Route and WP Service — Route List
130066	Route and WP Service — Route/WP-List Attributes
130067	Route and WP Service — Route, WP Name & Position
130068	Route and WP Service — Route, WP Name
130069	Route and WP Service — XTE Limit & Navigation Method
130074	Route and WP Service — WP List, WP Name & Position

129283 is single-frame; the rest are Fast Packet.

Diagnostics

mosquitto_sub -h 127.0.0.1 -t 'nmea/route' -v

--verbose-route logs route activation, deactivation, waypoint insertion and expiry, prefixed Route:.

If the topic reads idle while the plotter is clearly navigating, the plotter is either not transmitting route data at all — some models need it enabled in their own settings — or a different plotter got the lock first.