signalk-racer 0.9.12 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Signal K Racing Plugin
 
-This plugin adds sail racing-relevant data to a Signal K server. It focuses on real-time information useful during the start of a race, such as:
+This plugin adds sail racing relevant data to a Signal K server. It focuses on real-time information useful during the start of a race, such as:
  + A server side race timer that can be displayed on multiple screens and be finely adjusted
  + A mechanism to set and adjust the start line using waypoints and REST commands
  + Calculation of the distance to the line.
@@ -26,9 +26,10 @@ This plugin calculates and publishes the following Signal K paths:
 | `navigation.racing.`<br/>`timeToStart`          | Period of time until the race start                    | `s`                    | Y   |
 | `navigation.racing.`<br/>`startTime`            | The start time as an ISO timestamp                     | `rfc3339`              |     |
 
-These values can be displayed in KIP widgets, Freeboard-SK, or other Signal K clients.
+These values can be displayed in KIP widgets, Freeboard-SK, or other Signal K clients.  
+There are dedicated widgets for the start timer and line adjustment since 3.5.0 of KIP 
 
-![KIP and Freeboard Screenshot](kip-freeboard-screenshot.png)
+![KIP and Freeboard Screenshot](racer-kip.png)
 
 There is also a webapp to adjust the line and timer.
 
@@ -95,7 +96,7 @@ If `navigation.headingTrue` is not available, then `navigation.courseOverGroundT
 
 ## 🌐 API Access
 
-This plugin uses WebSocket-based PUT requests to Signal K model paths.
+This plugin uses the following WebSocket-based PUT requests to Signal K model paths.
 
 ### `navigation.racing.setStartLine`
 
@@ -133,13 +134,15 @@ Used to **start**, **sync**, **reset**, or **set a fixed start time**.
 ---
 
 ## 🧩 KIP Widgets
-KIP components for `racer-timer` and `racer-line` have been developed and will be available in a future release of KIP.
+KIP components for `racer-timer` and `racer-line` have been developed and are available from release 3.5.0 of KIP.
 
 ## 🔄 Dependencies
 
 ### Plugins
+- [KIP >= 3.5.0](https://github.com/mxtommy/Kip) for graphic widget support
+- [FreeboardSK](https://github.com/SignalK/freeboard-sk#readme) for graphic display of the start line
 - [resources-provider](https://www.npmjs.com/package/@signalk/resources-provider) plugin with waypoints enabled
-- [course-provider](https://www.npmjs.com/package/@signalk/course-provider) plugin
+- [course-provider](https://www.npmjs.com/package/@signalk/course-provider) plugin to enable the next leg calculations
 
 ### Libraries
 - `geolib`: for distance and bearing calculations.
@@ -151,7 +154,6 @@ KIP components for `racer-timer` and `racer-line` have been developed and will b
 - Add calculations for:
 - **Time to line** (using STW and heading or polar speeds)
 - **Laylines** and distance/time to them
-- Better integration with **Freeboard-SK** and **KIP** dashboards
 
 --- 
 ## 📬 Feedback

package/ReleaseNotes.md

@@ -1,3 +1,11 @@
+## 1.0.0 GA Release with KIP Widgets
+ + Fixed bias to be towards wind
+
+## 0.9.13 GA Release Candidate
+ + handle reverse routes
+ + Improve startAt date handling
+ + persist timer over plugin restart
+
 ## 0.9.12 No waypoints
  + improve no waypoint handling
  + fix create waypoint

package/index.js

@@ -105,7 +105,7 @@ module.exports = (app) => {
         ]
     });
 
-    // send multiple deltas, each in the form of { path, value, units?}
+    // send multiple deltas, each in the form of { path, value }
     function sendDeltas(updatesArray) {
         const timestamp = new Date().toISOString();
 
@@ -199,14 +199,12 @@ module.exports = (app) => {
         app.debug(`putStartLineEnd: ${end} ${JSON.stringify(position)}`);
 
         try {
-            if (!end || !position || typeof position.latitude !== 'number' || typeof position.longitude !== 'number') {
+            if (!end || !position || typeof position.latitude !== 'number' || typeof position.longitude !== 'number')
                 return complete(callback, 400, 'Failed to put start line end: !end || !position');
-            }
 
             end = end.toLowerCase();
-            if (end !== 'port' && end !== 'stb') {
+            if (end !== 'port' && end !== 'stb')
                 return complete(callback, 400, 'Failed to put start line end: unknown end');
-            }
 
             let startLine = state.startLine;
             if (startLine) {
@@ -427,9 +425,8 @@ module.exports = (app) => {
                 }
 
                 case 'sync': {
-                    if (!state.timerRunning || state.timeToStart == null) {
+                    if (!state.timerRunning || state.timeToStart == null)
                         return complete(callback, 500, 'sync timer: !running');
-                    }
 
                     const rounded = Math.round(state.timeToStart / 60) * 60;
                     state.timeToStart = rounded;
@@ -465,7 +462,7 @@ module.exports = (app) => {
                             {path: 'navigation.racing.timeToStart', value: 0},
                             {path: 'navigation.racing.startTime', value: null}
                         ]);
-                        return complete(callback, 200, 'set timer: 0K');
+                        return complete(callback, 200, 'set timer: Ignored negative start time');
                     }
 
                     state.timerRunning = true;
@@ -483,12 +480,17 @@ module.exports = (app) => {
 
                 case 'adjust': {
                     const delta = Number(args.delta);
-                    if (isNaN(delta) || state.timeToStart == null || !state.startTime) {
-                        cb(null, {state: 'FAILED', message: 'Cannot adjust: invalid state or delta'});
-                        return;
-                    }
+                    if (isNaN(delta))
+                        return complete(callback, 400, 'adjust timer: Cannot adjust invalid delta');
+
+                    if (state.timeToStart == null)
+                        return complete(callback, 400, 'adjust timer: Cannot adjust start time');
 
-                    state.timeToStart = Math.max(state.timeToStart + delta, 0);
+                    const nextTimeToStart = state.timeToStart + delta;
+                    if (nextTimeToStart <= 0)
+                        return complete(callback, 200, 'adjust timer: Ignored negative start time');
+
+                    state.timeToStart = nextTimeToStart;
 
                     if (state.timerRunning) {
                         let now = Date.now();
@@ -501,7 +503,9 @@ module.exports = (app) => {
                     if (state.timerRunning && state.startTime) {
                         deltas.push({path: 'navigation.racing.startTime', value: state.startTime });
                     }
-                    setTimer();
+                    if (delta % 60 !== 0)
+                        setTimer();
+
                     sendDeltas(deltas);
 
                     return complete(callback, 200, 'adjust timer: OK');
@@ -512,8 +516,8 @@ module.exports = (app) => {
                 }
             }
         } catch (err) {
-            app.debug('startTimerCommand:', JSON.stringify(err));
-            return complete(callback, 500, 'Failed to command timer: ' + JSON.stringify(err));
+            app.debug('startTimerCommand:', err);
+            return complete(callback, 500, 'Failed to command timer: ' + err.message);
         }
     }
 
@@ -577,6 +581,23 @@ module.exports = (app) => {
         }
     }
 
+    function isNearLineInRoute() {
+        // e.g. {
+        //   "href":"/resources/routes/a12eefe7-8fd3-49f7-81af-ce1f3440d3ff",
+        //   "name":"Course 1",
+        //   "reverse":false,
+        //   "pointIndex":1,
+        //   "pointTotal":5
+        // }
+
+        const activeRoute = state.activeRoute;
+        if (!activeRoute)
+            return true;
+        if (activeRoute.pointIndex < 2)
+            return true;
+        return activeRoute.pointIndex + 2 >= activeRoute.pointTotal;
+    }
+
     function processPosition(position) {
         if (!position) {
             position = app.getSelfPath('navigation.position');
@@ -587,7 +608,7 @@ module.exports = (app) => {
         const startLine = state.startLine;
 
         app.debug(`processPosition ${JSON.stringify(position)} to ${JSON.stringify(startLine)}`);
-        if (position && startLine && (!state.activeRoute || state.activeRoute.pointIndex < 2)) {
+        if (position && startLine && isNearLineInRoute()) {
             // handle the bow offset
             const bow = bowPosition(position);
 
@@ -636,6 +657,7 @@ module.exports = (app) => {
             state.distanceToLine = null;
             sendDeltas([
                 {path: 'navigation.racing.distanceStartline', value: null},
+                {path: 'navigation.racing.startLineBias', value: null},
             ]);
         }
     }
@@ -652,19 +674,16 @@ module.exports = (app) => {
 
         let nextTwa = null;
         const activeRoute = state.activeRoute;
-        if (activeRoute) {
-            const nextLegHeading = activeRoute.nextLegHeading;
-            if (nextLegHeading) {
-                nextTwa = (540 + toDegrees(twd) - nextLegHeading) % 360 - 180;
-                app.debug(`nextTwa: ${nextTwa}`);
-            }
+        if (activeRoute && activeRoute.nextLegHeading) {
+            nextTwa = (540 + toDegrees(twd) - activeRoute.nextLegHeading) % 360 - 180;
+            app.debug(`nextTwa: ${nextTwa}`);
         }
 
         let bias = null;
         const startLine = state.startLine;
-        if (startLine && (!activeRoute || activeRoute.pointIndex < 2)) {
+        if (startLine && isNearLineInRoute()) {
             app.debug(`processWind ${twd} to ${JSON.stringify(startLine)}`);
-            bias = startLine.length * Math.cos(toRadians(startLine.bearing) - (twd + Math.PI));
+            bias = - startLine.length * Math.cos(toRadians(startLine.bearing) - twd);
         }
 
         sendDeltas([
@@ -674,16 +693,50 @@ module.exports = (app) => {
     }
 
     function processRoute(activeRoute) {
-        if (activeRoute && (activeRoute.pointIndex + 1) < activeRoute.pointTotal) {
+        if (activeRoute) {
             // e.g. {"href":"/resources/routes/a12eefe7-8fd3-49f7-81af-ce1f3440d3ff","name":"Course 1","reverse":false,"pointIndex":1,"pointTotal":5}
+            const nextPointIndex = activeRoute.pointIndex + 1;
+            if (nextPointIndex < 0 || nextPointIndex === activeRoute.pointTotal) {
+              activeRoute.nextLegHeading = null;
+              sendDeltas([
+                {path: 'navigation.racing.nextLegHeading', value: null},
+                {path: 'navigation.racing.nextLegTrueWindAngle', value: null}
+              ]);
+              processPosition();
+              return;
+            }
+
             const routeId = activeRoute.href.split('/').pop(); //  e.g. "a12eefe7-8fd3-49f7-81af-ce1f3440d3ff"
             app.debug('processRoute:' + routeId);
             app.resourcesApi.getResource('routes', routeId).then(route => {
                 app.debug('found active route:', JSON.stringify(route));
-                // e.g. {name:"Course 1",description:"Test race course",distance:3027,feature:{type:"Feature",geometry:{type:"LineString",coordinates:[[151.2789194160523,-33.80427227074185],[151.28230238234357,-33.813458268981435],[151.2758044350174,-33.80201284252691],[151.27864400784992,-33.801915364141514],[151.27982384226053,-33.80429179893497]]},properties:{coordinatesMeta:[{href:"/resources/waypoints/bb35d9d0-c04e-4721-89f2-a1d8e697ab81"},{href:"/resources/waypoints/65082ddd-6fa6-4538-9a01-49d5d795b0bb"},{href:"/resources/waypoints/0bbce508-67c6-4f03-8de0-fb0532f88917"},{href:"/resources/waypoints/602ee562-c6dc-42c3-a775-512597063ca4"},{href:"/resources/waypoints/2e3cf194-8835-498d-abaa-a5d2104550b3"}]},id:""},timestamp:"2025-06-09T22:22:54.739Z",$source:"resources-provider"}
+                // e.g. {
+                // name:"Course 1",
+                // description:"Test race course",
+                // distance:3027,
+                // feature:{
+                //   type:"Feature",
+                //   geometry:{
+                //     type:"LineString",
+                //     coordinates:[[151.27,-33.80],[151.28,-33.81],[151.27,-33.80],[151.27,-33.80],[151.27,-33.80]]},
+                //     properties:{
+                //       coordinatesMeta:[
+                //         {href:"/resources/waypoints/bb35d9d0-c04e-4721-89f2-a1d8e697ab81"},
+                //         {href:"/resources/waypoints/65082ddd-6fa6-4538-9a01-49d5d795b0bb"},
+                //         {href:"/resources/waypoints/0bbce508-67c6-4f03-8de0-fb0532f88917"},
+                //         {href:"/resources/waypoints/602ee562-c6dc-42c3-a775-512597063ca4"},
+                //         {href:"/resources/waypoints/2e3cf194-8835-498d-abaa-a5d2104550b3"}
+                //       ]
+                //     },
+                //     id:""
+                //   },
+                //   timestamp:"2025-06-09T22:22:54.739Z",
+                //   $source:"resources-provider"}
                 const coordinates = route.feature.geometry.coordinates;
-                const [fromLongitude, fromLatitude] = coordinates[activeRoute.pointIndex];
-                const [toLongitude, toLatitude] = coordinates[activeRoute.pointIndex + 1];
+                const fromIndex = activeRoute.reverse ? activeRoute.pointTotal - activeRoute.pointIndex - 1 : activeRoute.pointIndex;
+                const toIndex = activeRoute.reverse ? activeRoute.pointTotal - nextPointIndex - 1 : nextPointIndex;
+                const [fromLongitude, fromLatitude] = coordinates[fromIndex];
+                const [toLongitude, toLatitude] = coordinates[toIndex];
                 app.debug(`from: {longitude:${fromLongitude}, latitude:${fromLatitude}}, to: {longitude:${toLongitude}, latitude:${toLatitude}}`);
                 const nextLegHeading = geolib.getRhumbLineBearing(
                     {latitude: fromLatitude, longitude: fromLongitude},
@@ -693,16 +746,20 @@ module.exports = (app) => {
                 activeRoute.nextLegHeading = nextLegHeading;
                 state.activeRoute = activeRoute;
                 sendDeltas([
-                    {path: 'navigation.racing.nextLegHeading', value: toRadians(nextLegHeading)}
+                    {path: 'navigation.racing.nextLegHeading', value: toRadians(nextLegHeading)},
+                    {path: 'navigation.racing.nextLegTrueWindAngle', value: null}
                 ]);
+                processWind();
             }).catch(err => {
                 app.error(err);
             });
         } else {
             state.activeRoute = null;
             sendDeltas([
-                {path: 'navigation.racing.nextLegHeading', value: null}
+                {path: 'navigation.racing.nextLegHeading', value: null},
+                {path: 'navigation.racing.nextLegTrueWindAngle', value: null}
             ]);
+            processPosition(null);
         }
     }
 
@@ -742,6 +799,23 @@ module.exports = (app) => {
             state.timeToStart = options.timer;
             state.startLine = getStartLine();
 
+            // Is the timer already started
+            {
+                const startTime = app.getSelfPath('navigation.racing.startTime');
+                if (startTime && startTime.value) {
+                    state.startTime = startTime.value;
+                    const now = Date.now();
+                    const startAtTime = new Date(startTime.value);
+                    if (startAtTime > now) {
+                        state.timeToStart = Math.round((new Date(state.startTime) - now) / 1000);
+                        state.timerRunning = true;
+                    } else {
+                        state.timeToStart = 0;
+                        state.timerRunning = false;
+                    }
+                }
+            }
+
             sendDeltas([{path: 'navigation.racing.timeToStart', value: state.timeToStart}]);
 
             // Subscribe to position updates.
@@ -762,7 +836,7 @@ module.exports = (app) => {
 
                 (delta) => {
                     app.debug('DELTA POSITIONS ' + JSON.stringify(delta));
-                    position = null;
+                    let position = null;
                     delta.updates.forEach((u) => {
                         u.values.forEach((v) => {
                             app.debug('DELTA POSITION ' + v.path + ' = ' + JSON.stringify(v.value));
@@ -863,8 +937,7 @@ module.exports = (app) => {
                             app.debug("DELTA ACTIVE ROUTE: " + v.path + ' = ' + JSON.stringify(route));
                         })
                     });
-                    if (route)
-                        processRoute(route);
+                    processRoute(route);
                 }
             );
 
@@ -884,23 +957,25 @@ module.exports = (app) => {
                 (delta) => {
                     app.debug('DELTAS START LINE ENDS ' + JSON.stringify(delta));
                     delta.updates.forEach((u) => {
-                        u.values.forEach((v) => {
-                            app.debug(`DELTA START LINE END from ${u.source.label}: ${v.path} = ${JSON.stringify(v.value)}`);
-                            if (u.source && u.source.label && u.source.label !== 'signalk-racer') {
-                                switch (v.path) {
-                                    case 'navigation.racing.startLinePort' :
-                                        putStartLineEnd('port', v.value, ignored => {
-                                        }, false).then(ignored => {
-                                        });
-                                        break;
-                                    case 'navigation.racing.startLineStb' :
-                                        putStartLineEnd('port', v.value, ignored => {
-                                        }, false).then(ignored => {
-                                        });
-                                        break;
+                        if (u.values) {
+                            u.values.forEach((v) => {
+                                app.debug(`DELTA START LINE END from ${u.source.label}: ${v.path} = ${JSON.stringify(v.value)}`);
+                                if (u.source && u.source.label && u.source.label !== 'signalk-racer') {
+                                    switch (v.path) {
+                                        case 'navigation.racing.startLinePort' :
+                                            putStartLineEnd('port', v.value, ignored => {
+                                            }, false).then(ignored => {
+                                            });
+                                            break;
+                                        case 'navigation.racing.startLineStb' :
+                                            putStartLineEnd('port', v.value, ignored => {
+                                            }, false).then(ignored => {
+                                            });
+                                            break;
+                                    }
                                 }
-                            }
-                        })
+                            });
+                        }
                     });
                 }
             );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-racer",
-  "version": "0.9.12",
+  "version": "1.0.0",
   "description": "Signalk plugin to calculate values of interest to sail racers: such as Time to Start, Time of Start, Distance to Line; Next leg TWA.",
   "main": "index.js",
   "repository": {

package/public/index.html

@@ -44,11 +44,9 @@
 
         .port-set    { background-color: #f88; color: black; font-size: 1em;}
         .port-move   { background-color: #a00; color: white; }
-        .port-tweak   { background-color: #f44; color: white; }
         .port-rotate { background-color: #a00; color: white; }
         .stb-set     { background-color: #8f8; color: black; font-size: 1em; }
         .stb-move    { background-color: #080; color: white;}
-        .stb-tweak    { background-color: #4c4; color: white; }
         .stb-rotate  { background-color: #080; color: white; }
 
     </style>
@@ -92,9 +90,9 @@
             }));
         };
 
-        socket.onerror = (err) => updateStatus('❌ WebSocket error: ' + err.message);
+        socket.onerror = (err) => updateStatus('WebSocket error: ' + err.message);
         socket.onclose = () => {
-            updateStatus('❌ Disconnected. Retrying in 5s...');
+            updateStatus('Disconnected. Retrying in 5s...');
             setTimeout(connectWebSocket, 5000);
         };
 
@@ -142,7 +140,7 @@
 
     function sendSetStartLine(end) {
         if (!socket || socket.readyState !== WebSocket.OPEN) {
-            updateStatus('❌ WebSocket not connected.');
+            updateStatus('WebSocket not connected.');
             return;
         }
         let message = JSON.stringify({
@@ -154,12 +152,12 @@
         });
         console.log("sendSetStartLine: " + message);
         socket.send(message);
-        updateStatus(`⏳ Sent request to set ${end}`);
+        updateStatus(`Sent request to set ${end}`);
     }
 
     function sendAdjustStartLine(end, delta, rotate) {
         if (!socket || socket.readyState !== WebSocket.OPEN) {
-            updateStatus('❌ WebSocket not connected.');
+            updateStatus('WebSocket not connected.');
             return;
         }
         const message = JSON.stringify({
@@ -171,7 +169,7 @@
         });
         console.log("sendAdjustStartLine: " + message);
         socket.send(message);
-        updateStatus(`⏳ Sent ${delta}m ${rotate}° request for ${end}`);
+        updateStatus(`Sent ${delta}m ${rotate}° request for ${end}`);
     }
 
     connectWebSocket();
@@ -184,7 +182,7 @@
 
     function adjustStartTime(deltaSeconds) {
         if (!socket || socket.readyState !== WebSocket.OPEN) {
-            updateStatus('❌ WebSocket not connected.');
+            updateStatus('WebSocket not connected.');
             return;
         }
         socket.send(JSON.stringify({
@@ -197,35 +195,45 @@
                 }
             }
         }));
-        updateStatus(`⏳ Sent delta timeToStart: ${deltaSeconds} sec`);
+        updateStatus(`Sent delta timeToStart: ${deltaSeconds} sec`);
     }
 
     function setStartTime() {
         if (!socket || socket.readyState !== WebSocket.OPEN) {
-            updateStatus('❌ WebSocket not connected.');
+            updateStatus('WebSocket not connected.');
             return;
         }
 
-        const date = startTime ? new Date(startTime) : new Date();
-        const [hours, minutes, seconds] = document.getElementById('startTime').value.split(':').map(Number);
-        date.setHours(hours, minutes, seconds, 0);
+        try {
+            const now = new Date();
+            const parts = document.getElementById('startTime').value.split(':').map(Number);
+            const hours = parts[0];
+            const minutes = parts[1];
+            const seconds = parts.length >= 3 ? parts[2] : 0;
+            const date = new Date(now);
+            date.setHours(hours, minutes, seconds, 0);
+            if (date <= now)
+                date.setDate(date.getDate() + 1);
 
-        socket.send(JSON.stringify({
-            context: 'vessels.self',
-            put: {
-                path: 'navigation.racing.setStartTime',
-                value: {
-                    command: 'set',
-                    startTime : date.toISOString(),
+            socket.send(JSON.stringify({
+                context: 'vessels.self',
+                put: {
+                    path: 'navigation.racing.setStartTime',
+                    value: {
+                        command: 'set',
+                        startTime: date.toISOString(),
+                    }
                 }
-            }
-        }));
-        updateStatus(`⏳ Sent start time: ${startTime}`);
+            }));
+            updateStatus(`Sent start time: ${startTime}`);
+        } catch (err) {
+            console.log('Could not set start at ', err);
+        }
     }
 
     function sendTimerCommand(command) {
         if (!socket || socket.readyState !== WebSocket.OPEN) {
-            updateStatus('❌ WebSocket not connected.');
+            updateStatus('WebSocket not connected.');
             return;
         }
         socket.send(JSON.stringify({
@@ -235,16 +243,8 @@
                 value: { command }
             }
         }));
-        updateStatus(`⏳ Sent timer command: ${command}`);
+        updateStatus(`Sent timer command: ${command}`);
     }
-
-    setInterval(() => {
-        if (timeToStart !== null && timeToStart > 0) {
-            timeToStart--;
-            updateTimerDisplay();
-        }
-    }, 1000);
-
 </script>
 
 <div style="display: flex; justify-content: center; align-items: center; gap: 3em; flex-wrap: wrap;">