signalk-race-control 0.11.1 → 0.12.0

package/README.md

@@ -170,7 +170,27 @@ and a live projected finishing order — during and after the race.
   waypoint/route resources for any chart plotter (e.g. freeboard-sk) that reads the
   standard resources API — both directions (reading existing waypoints for the
   autocomplete, and publishing the saved course) only do anything if your server has a
-  resources provider installed; they're a no-op otherwise, never a failure.
+  resources provider installed; they're a no-op otherwise, never a failure. Once a race
+  has started, the moment this vessel's own position actually crosses the start line
+  (a real crossing between two GPS fixes, not just getting close to it), the course is
+  also activated as this vessel's SignalK navigation route — so a chart plotter reading
+  the standard Course API starts showing/guiding to the next mark automatically, without
+  anyone having to find and select the route by hand right as the race gets underway.
+  Requires both a resources provider and a server new enough to have the Course API;
+  a no-op otherwise. Whenever this vessel's own true wind direction and a moving SOG
+  are available from SignalK, the chart also draws a pair of 10-minute laylines from its
+  live position — where a further 10 minutes on each close-hauled tack would put it,
+  using a generic ~40° tack angle rather than this boat's own polar data. Absent
+  whenever that wind/speed data isn't, same as everything else on this chart that
+  depends on live SignalK data. A **Wind shift** instrument sits above the chart
+  alongside it, once there's enough live wind history (30s or more) to call a trend
+  from: it tracks a rolling ~3-minute average true wind direction as a baseline and
+  compares the current reading against it, reporting **Lift** or **Header** (with the
+  shift in degrees) or **Steady** below a small deadband — tack-aware, since the same
+  shift is a lift on one tack and a header on the other, using this vessel's own
+  heading to tell which. It's a wind-trend read, not a mark-aware tactical simulator —
+  no probability-of-gain number, just whether the breeze has moved for or against
+  whichever tack you're currently on.
 - **Estimated finish time & live rank** — while a boat is still racing, if it has a
   live AIS position and speed and the race has a finish line, the plugin projects a
   finish time and corrected time from its remaining distance and speed, and ranks it

package/index.js

@@ -305,6 +305,7 @@ function ensureRaceShape(race) {
   if (race.stopTime === undefined) race.stopTime = null;
   if (race.scheduledCallOff === undefined) race.scheduledCallOff = null;
   if (race.multiDay === undefined) race.multiDay = false;
+  if (race.courseActivated === undefined) race.courseActivated = false;
   if (!race.classes) race.classes = [];
   race.classes.forEach((c) => {
     if (c.startTime === undefined) c.startTime = null;
@@ -364,6 +365,22 @@ function midpoint(a, b) {
   return { lat: (a.lat + b.lat) / 2, lon: (a.lon + b.lon) / 2 };
 }
 
+// True if segment p1-p2 crosses segment p3-p4 — the standard orientation
+// (cross-product sign) test. Treats lat/lon as a flat plane, fine at the
+// scale of a start line (tens to low hundreds of meters). Used to detect a
+// boat crossing the start line between two consecutive position samples;
+// doesn't distinguish direction (inbound vs outbound) or handle the
+// collinear/touching edge case — a crossing landing exactly on that is
+// astronomically unlikely, and would just be caught on the next sample.
+function segmentsIntersect(p1, p2, p3, p4) {
+  const cross = (o, a, b) => (a.lon - o.lon) * (b.lat - o.lat) - (a.lat - o.lat) * (b.lon - o.lon);
+  const d1 = cross(p3, p4, p1);
+  const d2 = cross(p3, p4, p2);
+  const d3 = cross(p1, p2, p3);
+  const d4 = cross(p1, p2, p4);
+  return ((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0));
+}
+
 function validateCoordPoint(p) {
   if (!p || typeof p.lat !== 'number' || typeof p.lon !== 'number' || !isFinite(p.lat) || !isFinite(p.lon)) {
     return null;
@@ -1600,6 +1617,7 @@ module.exports = function (app) {
   let dataFile = null;
   const scheduleTimers = new Map(); // raceId -> Timeout, for scheduledStart
   const callOffTimers = new Map(); // raceId -> Timeout, for scheduledCallOff
+  let lastSelfPos = null; // {lat, lon} as of the previous checkStartLineCrossings tick
 
   // setTimeout's delay is a 32-bit signed int internally — anything past
   // ~24.8 days silently wraps and fires almost immediately instead of
@@ -1988,6 +2006,48 @@ module.exports = function (app) {
     if (changed) saveState();
   }
 
+  // Once a race has started and this vessel (this SignalK server's own
+  // position, not any boat in the fleet) actually crosses its start line,
+  // activate that race's course as the vessel's current SignalK navigation
+  // route — so a chart plotter (freeboard-sk etc.) reading the standard
+  // Course API immediately starts showing/guiding to the next mark,
+  // without anyone having to find and select the route by hand right as
+  // the race gets underway. Detected as a genuine line crossing between
+  // two consecutive position samples (not just proximity), same 15s
+  // cadence as recordTrackSample. Best-effort and silently skipped if this
+  // server has no Course API (older signalk-server) or no resourcesApi —
+  // core race-control features never depend on this succeeding.
+  async function checkStartLineCrossings() {
+    let selfPos = null;
+    try {
+      const leaf = app.getSelfPath('navigation.position');
+      const v = leaf && leaf.value;
+      if (v && typeof v.latitude === 'number' && typeof v.longitude === 'number') {
+        selfPos = { lat: v.latitude, lon: v.longitude };
+      }
+    } catch (e) {
+      // no self position available yet
+    }
+    const prevPos = lastSelfPos;
+    lastSelfPos = selfPos;
+    if (!selfPos || !prevPos || typeof app.activateRoute !== 'function') return;
+    for (const race of Object.values(state.races)) {
+      if (!race.startTime || race.stopTime || race.courseActivated) continue;
+      const line = race.course && race.course.startLine;
+      if (!line) continue;
+      if (!segmentsIntersect(prevPos, selfPos, line[0], line[1])) continue;
+      try {
+        await publishCourseResources(race);
+        await app.activateRoute({ href: `/resources/routes/${deterministicUuid(`race-${race.id}-course`)}`, pointIndex: 0 });
+        race.courseActivated = true;
+        saveState();
+        app.debug(`race-control: activated course for race "${race.name}" after crossing the start line`);
+      } catch (e) {
+        app.debug('race-control: could not activate course in SignalK: ' + e.message);
+      }
+    }
+  }
+
   function disarmSchedule(raceId) {
     const t = scheduleTimers.get(raceId);
     if (t) {
@@ -2002,6 +2062,7 @@ module.exports = function (app) {
     race.startTime = atTime;
     race.scheduledStart = null;
     race.stopTime = null;
+    race.courseActivated = false;
     Object.values(race.boats).forEach((b) => {
       b.finishTime = null;
       b.startTime = null;
@@ -2151,7 +2212,10 @@ module.exports = function (app) {
       armSchedule(race);
       armCallOffSchedule(race);
     });
-    trackTimer = setInterval(recordTrackSample, 15000);
+    trackTimer = setInterval(() => {
+      recordTrackSample();
+      checkStartLineCrossings().catch((e) => app.debug('race-control: checkStartLineCrossings failed: ' + e.message));
+    }, 15000);
     app.setPluginStatus('Race control ready');
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-race-control",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "SignalK plugin and webapp for tracking elapsed and handicap-corrected (Time-on-Time) race time, with a per-boat editable TCF and boat names pulled from AIS when available.",
   "main": "index.js",
   "author": "Joachim Bakke <github@heiamoss.com>",

package/public/app.js

@@ -125,6 +125,10 @@
   const startEtaValue = document.getElementById('startEtaValue');
   const startBurnValue = document.getElementById('startBurnValue');
   const startTimerNote = document.getElementById('startTimerNote');
+  const windShiftBar = document.getElementById('windShiftBar');
+  const windShiftValue = document.getElementById('windShiftValue');
+  const windShiftTack = document.getElementById('windShiftTack');
+  const windShiftTwd = document.getElementById('windShiftTwd');
   const raceImportSection = document.getElementById('raceImportSection');
   const raceImportToggleBtn = document.getElementById('raceImportToggleBtn');
   const raceImportBody = document.getElementById('raceImportBody');
@@ -1179,18 +1183,43 @@
   // start-line transit timer app shows, computed from this vessel's own
   // live position/speed (not any other boat's).
 
-  let selfNav = null; // {lat, lon, sogMs} | null, refreshed on its own poll — see below
+  let selfNav = null; // {lat, lon, sogMs, windDirTrueRad, headingRad} | null, refreshed on its own poll — see below
+
+  function normalizeRad(a) {
+    const twoPi = Math.PI * 2;
+    return ((a % twoPi) + twoPi) % twoPi;
+  }
 
   async function fetchSelfNav() {
     try {
-      const [posLeaf, sogLeaf] = await Promise.all([
+      const [posLeaf, sogLeaf, headingLeaf, cogLeaf, windDirLeaf, windAngleGroundLeaf, windAngleWaterLeaf] = await Promise.all([
         fetchJSON(`${SK_API}/vessels/self/navigation/position`).catch(() => null),
-        fetchJSON(`${SK_API}/vessels/self/navigation/speedOverGround`).catch(() => null)
+        fetchJSON(`${SK_API}/vessels/self/navigation/speedOverGround`).catch(() => null),
+        fetchJSON(`${SK_API}/vessels/self/navigation/headingTrue`).catch(() => null),
+        fetchJSON(`${SK_API}/vessels/self/navigation/courseOverGroundTrue`).catch(() => null),
+        fetchJSON(`${SK_API}/vessels/self/environment/wind/directionTrue`).catch(() => null),
+        fetchJSON(`${SK_API}/vessels/self/environment/wind/angleTrueGround`).catch(() => null),
+        fetchJSON(`${SK_API}/vessels/self/environment/wind/angleTrueWater`).catch(() => null)
       ]);
       const v = posLeaf && posLeaf.value;
       if (!v || typeof v.latitude !== 'number' || typeof v.longitude !== 'number') return null;
       const sogMs = sogLeaf && typeof sogLeaf.value === 'number' ? sogLeaf.value : null;
-      return { lat: v.latitude, lon: v.longitude, sogMs };
+      // True wind direction, absolute (radians, 0 = north) — prefer a
+      // sensor/instrument that already computed it; otherwise derive it
+      // from a true wind ANGLE (relative to the bow) plus heading (or, if
+      // no compass, course over ground as a rough stand-in). null — not
+      // just a missing layline — if none of these are available, per
+      // SignalK's own "best-effort, never a failure" convention elsewhere
+      // in this app.
+      let windDirTrueRad = null;
+      const heading = headingLeaf && typeof headingLeaf.value === 'number' ? headingLeaf.value : cogLeaf && typeof cogLeaf.value === 'number' ? cogLeaf.value : null;
+      if (windDirLeaf && typeof windDirLeaf.value === 'number') {
+        windDirTrueRad = normalizeRad(windDirLeaf.value);
+      } else if (heading != null) {
+        const angle = windAngleGroundLeaf && typeof windAngleGroundLeaf.value === 'number' ? windAngleGroundLeaf.value : windAngleWaterLeaf && typeof windAngleWaterLeaf.value === 'number' ? windAngleWaterLeaf.value : null;
+        if (angle != null) windDirTrueRad = normalizeRad(heading + angle);
+      }
+      return { lat: v.latitude, lon: v.longitude, sogMs, windDirTrueRad, headingRad: heading };
     } catch (e) {
       return null;
     }
@@ -1200,6 +1229,95 @@
   function toRad(deg) {
     return (deg * Math.PI) / 180;
   }
+  function toDeg(rad) {
+    return (rad * 180) / Math.PI;
+  }
+
+  const EARTH_RADIUS_M = 6371000;
+  // Destination point a given bearing/distance from a start point (great-
+  // circle "direct" geodesic problem) — used to draw laylines a fixed
+  // sailing distance out from the boat's own position, same spherical
+  // approximation as everywhere else on this chart.
+  function destinationPoint(pt, bearingRad, distanceM) {
+    const delta = distanceM / EARTH_RADIUS_M;
+    const phi1 = toRad(pt.lat);
+    const lambda1 = toRad(pt.lon);
+    const phi2 = Math.asin(Math.sin(phi1) * Math.cos(delta) + Math.cos(phi1) * Math.sin(delta) * Math.cos(bearingRad));
+    const lambda2 = lambda1 + Math.atan2(Math.sin(bearingRad) * Math.sin(delta) * Math.cos(phi1), Math.cos(delta) - Math.sin(phi1) * Math.sin(phi2));
+    return { lat: toDeg(phi2), lon: toDeg(lambda2) };
+  }
+
+  // ---- Wind shift / tack-or-hold --------------------------------------
+  // A lift/header indicator: is the current true wind direction shifted
+  // toward this vessel's advantage on whichever tack it's on right now
+  // (favors holding), or away from it (favors tacking onto the shift)?
+  // Tracks a short rolling average of true wind direction as the
+  // "baseline" — the same live SignalK feed the laylines use — since a
+  // helm sailing closehauled keeps adjusting course to hold a steady angle
+  // to the wind, so watching the boat's own heading wouldn't show a shift
+  // that's already been steered around; watching the wind's own bearing
+  // trend does.
+  const WIND_HISTORY_WINDOW_MS = 3 * 60 * 1000; // rolling baseline span
+  const WIND_HISTORY_MIN_SPAN_MS = 30 * 1000; // need at least this much history before calling a shift
+  const WIND_SHIFT_DEADBAND_DEG = 4; // smaller than this reads as "steady", not a real shift
+  let windHistory = []; // [{t, rad}], trimmed to WIND_HISTORY_WINDOW_MS
+
+  function normalizeSignedRad(a) {
+    const twoPi = Math.PI * 2;
+    let r = a % twoPi;
+    if (r > Math.PI) r -= twoPi;
+    if (r < -Math.PI) r += twoPi;
+    return r;
+  }
+
+  // Angles wrap, so a plain arithmetic mean is wrong near the wrap point —
+  // average the unit vectors instead (standard circular mean).
+  function circularMeanRad(radians) {
+    let sumSin = 0;
+    let sumCos = 0;
+    radians.forEach((r) => {
+      sumSin += Math.sin(r);
+      sumCos += Math.cos(r);
+    });
+    return Math.atan2(sumSin, sumCos);
+  }
+
+  // null until there's a moving self position, a true wind direction, a
+  // heading to determine tack from, and enough rolling history to call a
+  // baseline — same "if available, silently not otherwise" spirit as the
+  // laylines above.
+  function computeWindShift() {
+    if (!selfNav || selfNav.windDirTrueRad == null || selfNav.headingRad == null) return null;
+    if (!windHistory.length) return null;
+    const span = windHistory[windHistory.length - 1].t - windHistory[0].t;
+    if (span < WIND_HISTORY_MIN_SPAN_MS) return null;
+    const baselineRad = circularMeanRad(windHistory.map((s) => s.rad));
+    const shiftRad = normalizeSignedRad(selfNav.windDirTrueRad - baselineRad);
+    const shiftDeg = toDeg(shiftRad);
+    // Wind source to the right of the bow (positive) = starboard tack.
+    const tack = normalizeSignedRad(selfNav.windDirTrueRad - selfNav.headingRad) > 0 ? 'starboard' : 'port';
+    let verdict = 'steady';
+    if (Math.abs(shiftDeg) >= WIND_SHIFT_DEADBAND_DEG) {
+      const isLift = tack === 'starboard' ? shiftDeg > 0 : shiftDeg < 0;
+      verdict = isLift ? 'lift' : 'header';
+    }
+    return { tack, verdict, shiftDeg, twdDeg: (toDeg(selfNav.windDirTrueRad) + 360) % 360 };
+  }
+
+  function renderWindShift() {
+    const result = computeWindShift();
+    windShiftBar.hidden = !result;
+    if (!result) return;
+    windShiftTack.textContent = result.tack === 'starboard' ? 'Starboard' : 'Port';
+    windShiftTwd.textContent = `${Math.round(result.twdDeg)}°`;
+    windShiftValue.className = 'start-timer-value';
+    if (result.verdict === 'steady') {
+      windShiftValue.textContent = 'Steady';
+    } else {
+      windShiftValue.textContent = `${result.verdict === 'lift' ? 'Lift' : 'Header'} ${result.shiftDeg >= 0 ? '+' : ''}${Math.round(result.shiftDeg)}°`;
+      windShiftValue.classList.add(result.verdict);
+    }
+  }
 
   // Perpendicular distance from a point to the start-line segment (or to
   // its nearest end, if the point doesn't fall between the two ends) — a
@@ -2225,6 +2343,27 @@
         .addTo(chartLayerGroup);
     });
 
+    // Laylines for this vessel — where a further 10 minutes on each
+    // close-hauled tack would put it, from wherever it is right now. Shown
+    // only when there's actually a true wind direction and a moving SOG to
+    // draw them from (not just a position); silently absent otherwise,
+    // same "if available" spirit as the rest of this app's SignalK-fed
+    // instruments. LAYLINE_TACK_ANGLE_DEG is a generic close-hauled
+    // assumption, not this boat's own polar data — good enough for a rough
+    // visual, not a precise VMG angle.
+    const LAYLINE_TACK_ANGLE_DEG = 40;
+    const LAYLINE_DURATION_S = 10 * 60;
+    if (selfNav && selfNav.windDirTrueRad != null && selfNav.sogMs != null && selfNav.sogMs >= 0.25) {
+      const distanceM = selfNav.sogMs * LAYLINE_DURATION_S;
+      const tackAngleRad = toRad(LAYLINE_TACK_ANGLE_DEG);
+      [selfNav.windDirTrueRad + tackAngleRad, selfNav.windDirTrueRad - tackAngleRad].forEach((bearingRad) => {
+        const end = destinationPoint(selfNav, normalizeRad(bearingRad), distanceM);
+        L.polyline([ll(selfNav), ll(end)], { color: 'var(--accent)', weight: 1.5, dashArray: '2,6' })
+          .bindTooltip('<span style="color:var(--accent)">10min layline</span>', { sticky: true, className: 'mark-label' })
+          .addTo(chartLayerGroup);
+      });
+    }
+
     let minT = Infinity;
     let maxT = -Infinity;
     boatsWithTrack.forEach((b) => {
@@ -2811,6 +2950,7 @@
     classSection.hidden = !raceState;
     raceImportSection.hidden = !raceState || !raceImportEnabled;
     renderStartTimer();
+    renderWindShift();
 
     if (!raceState) {
       emptyMsg.hidden = true;
@@ -3112,6 +3252,7 @@
     courseToggleBtn.textContent = (courseBody.hidden ? '▸' : '▾') + ' Course & chart';
     if (!courseBody.hidden) {
       renderChart();
+      renderWindShift();
       // The map may have been created (or last sized) while its container
       // was hidden or a different size — Leaflet doesn't pick that up on
       // its own.
@@ -3220,7 +3361,13 @@
 
   async function refreshSelfNav() {
     selfNav = await fetchSelfNav();
+    if (selfNav && selfNav.windDirTrueRad != null) {
+      const now = Date.now();
+      windHistory.push({ t: now, rad: selfNav.windDirTrueRad });
+      while (windHistory.length && now - windHistory[0].t > WIND_HISTORY_WINDOW_MS) windHistory.shift();
+    }
     renderStartTimer();
+    renderWindShift();
   }
 
   async function init() {

package/public/index.html

@@ -159,6 +159,20 @@
             <span id="courseStatusText" class="status"></span>
           </div>
         </div>
+        <div id="windShiftBar" class="start-timer-grid wind-shift-grid" hidden>
+          <div class="start-timer-tile">
+            <div class="start-timer-label">Wind shift</div>
+            <div id="windShiftValue" class="start-timer-value">--</div>
+          </div>
+          <div class="start-timer-tile">
+            <div class="start-timer-label">Tack</div>
+            <div id="windShiftTack" class="start-timer-value">--</div>
+          </div>
+          <div class="start-timer-tile">
+            <div class="start-timer-label">True wind</div>
+            <div id="windShiftTwd" class="start-timer-value">--</div>
+          </div>
+        </div>
         <div class="chart-wrap">
           <div id="courseChart" class="chart-map"></div>
           <p id="chartEmptyMsg" class="empty chart-empty-msg" hidden>Add a course, then start the race, to see the chart here</p>

package/public/style.css

@@ -276,6 +276,18 @@ main {
   color: var(--muted);
 }
 
+.wind-shift-grid {
+  margin-bottom: 1rem;
+}
+
+.start-timer-value.lift {
+  color: var(--good);
+}
+
+.start-timer-value.header {
+  color: var(--bad);
+}
+
 .course-grid {
   margin-top: 0.75rem;
   display: flex;