Vessel states¶

	Garmin WatchApp	Wear OS WatchApp	Apple Watch	Server	Mobile
Status	✅	✅	⏳	✅	⏳
Code	`source/VesselState.mc`, `source/VesselStateMenu.mc`, `source/Theme.mc`	`core/…/VesselState.kt` (`VesselState`, `Palette`)	—	`app/services/sailever/vessel_states.rb`, `app/services/track_file.rb` (`STATES`), `app/assets/stylesheets/tokens.css`	`docs/companion_app/*.html` (click dummies)

Verified against code: 2026-10-13

Purpose¶

The vessel state says how the boat moves right now. The skipper sets it on the watch. It splits every track into sailed, motored, motorsailed and stationary time and distance, colours the instruments and the map, and marks where the boat spent the night.

The eight states¶

The id is the number on the wire: the SLTB state byte (track-sync.md) and the FIT developer field 6 (watchapp/recording.md). Ids never change. They are not in menu order and not in the order of the codes in the server's track file, so every decoder maps by this table.

Id	State	Menu label	`-ing` label	Category	Watch accent	Counts as
0	Engine	`ENGINE`	`Motoring`	propulsion	`0xFF5555` red	engine time / motored distance
1	Motorsail	`MOTORSAIL`	`Motorsailing`	propulsion	`0xFFAA00` orange	engine time; motorsailed distance on the watch
2	Sail	`SAIL`	`Sailing`	propulsion	`0x00AAFF` blue	sailing time / sailed distance
3	Anchor	`ANCHOR`	`Anchoring`	stationary	`0xAAAAAA` grey	stationary time
4	Buoy	`BUOY`	`Buoy`	stationary	`0xAAAAAA` grey	stationary time
5	Mooring	`MOORING`	`Mooring`	stationary	`0xAAAAAA` grey	stationary time
6	Shoreline	`SHORELINE`	`Shoreline`	stationary	`0xAAAAAA` grey	stationary time
7	Adrift	`ADRIFT`	`Drifting`	stationary	`0xAAAAAA` grey	stationary time

Propulsion states are ids 0–2 (id <= 2). All others are stationary.
Mooring is a berth in a marina or on a quay (lazy line). Buoy is a mooring buoy. Shoreline is tied to the shore with lines. Adrift is floating free with no propulsion and no mooring.
The states carry no icons on the watch.
Server names (track file and SLTB decoder): engine, motorsail, sail, anchor, buoy, mooring, shoreline, adrift.

The vessel state picker lists the states in this order, propulsion first:

ENGINE → MOTORSAIL → SAIL → MOORING → ANCHOR → BUOY → SHORELINE → ADRIFT

A Garmin Boating trip leaves out MOTORSAIL and SAIL (watchapp/lifecycle.md).

The picker itself (title, look per platform, preselection, what happens after a pick): watchapp/menus.md.

Defaults¶

Which state is preselected when a track starts, and which state a resumed track uses, is WatchApp behaviour: watchapp/menus.md and watchapp/lifecycle.md. The watch remembers the last state per trip (watchapp/recording.md).

Where the state shows¶

Product	Where	How
WatchApp	Dashboard header, line 1	`-ing` label (watchapp/dashboard.md)
WatchApp	Dashboard header, line 2	state period values (propulsion) or duration (stationary) (watchapp/recording.md)
WatchApp	Speed chart	each slot drawn in the accent colour of the state at that time
WatchApp	Track plot	track line in the accent colour of the current state (watchapp/track-view.md)
WatchApp, Garmin	Action menu item `Vessel State`	sub-label = menu label (e.g. `SAIL`)
WatchApp	Stats summary	rows in the Engine, Sail and Motorsail accents (watchapp/stats.md)
Server	Map polyline	red under engine (engine or motorsail), blue otherwise
Server	Map markers	one marker per vessel state change (stationary states with their own icon; sail as the SailEver sail in blue, engine as the engine icon on red, motorsail as the sail on orange), and storm warnings; engine on / off events get no marker (../server/trip.md)
Server	Trip page "nights"	anchor, buoy, mooring ("in port"), shoreline
Server	Track editor, Sail and engine	sail, engine and motorsail each in its own colour (map, timeline, readout); the skipper can change them, stationary states stay (../server/track-editor.md)
Mobile	Same tokens as the server web	⏳

Server colours¶

From tokens.css (light / dark):

Token	Light	Dark	Used for
`--sail`	`#0284C7`	`#38B6F5`	sailed track lines and bars
`--engine`	`#E23B3B`	`#FF5A52`	motored track lines and bars (engine and motorsail)
`--motorsail`	`#E08A00`	`#F5A524`	defined; the map draws motorsail in the engine colour
`--rest`	`#6F7F95`	`#94A3B8`	stationary states (nights, chips)

Map details (markers, popups, bridge lines): ../server/trip.md.

Mapping to sailing and engine time¶

Engine time is time in Engine or Motorsail.
Sailing time is time in Sail.
Stationary states count as neither.
The exact rules on the watch and on the server (speed threshold, gaps, scaling) are in calculations.md.

The legacy FIT fields are derived from the state: engine_on = 1 for Engine and Motorsail; sail_main = 1 for Sail and Motorsail (see watchapp/recording.md).

States and edge cases¶

An unknown wire value (> 7) or a FIT file without field 6 is read as sail on the server.
Changing the state resets the state period (watchapp/recording.md) and writes a STATE event into the SLTB stream from the next sample on.
The server logs every change as a vessel_state_change event. A change into a stationary state gets a place name. A change into or out of Engine / Motorsail also logs an engine_on / engine_off event.

Known deviations¶

Server: anything that is not Engine or Motorsail lands in the sailing bucket, including stationary states. See calculations.md.
Server map: the marker for mooring is titled "Mooring Buoy" (mini_map_controller.js), which mixes up Mooring and Buoy.