signalk-racer 0.9.0 → 0.9.2

package/README.MD

@@ -10,17 +10,17 @@ GitHub repository: [https://github.com/gregw/signalk-racer](https://github.com/g
 
 This plugin calculates and publishes the following Signal K paths:
 
-| Path                                        | Description                                            | Units   | Standard |
-|---------------------------------------------|--------------------------------------------------------|---------|----------|
-| `navigation.racing.distanceStartline`       | Signed minimum distance from the bow to the start line | `m`     | Y        |
-| `navigation.racing.startLineLength`         | Total length of the start line                         | `m`     |          |
-| `navigation.racing.stbLineBias`             | Bias of the start line toward the starboard end        | `m`     |          |
-| `navigation.racing.startLinePort.latitude`  | Latitude of the port (pin) end of the start line       | `deg`   | Y        |
-| `navigation.racing.startLinePort.longitude` | Longitude of the port end                              | `deg`   | Y        |
-| `navigation.racing.startLineStb.latitude`   | Latitude of the starboard (boat) end of the start line | `deg`   | Y        |
-| `navigation.racing.startLineStb.longitude`  | Longitude of the starboard end                         | `deg`   | Y        |
-| `navigation.racing.nextLegHeading`          | True heading for the next leg of the course            | `deg`   |          |
-| `navigation.racing.nextLegTWA`              | True Wind Angle for the next leg of the course         | `deg`   |          |
+| Path                                        | Description                                             | Units   | Schema |
+|---------------------------------------------|---------------------------------------------------------|---------|--------|
+| `navigation.racing.`<br/>`distanceStartline`       | Signed minimum distance from the bow to the start line  | `m`     | Y      |
+| `navigation.racing.`<br/>`startLineLength`         | Total length of the start line                          | `m`     |        |
+| `navigation.racing.`<br/>`stbLineBias`             | Bias of the start line toward the starboard end         | `m`     |        |
+| `navigation.racing.`<br/>`startLinePort.latitude`  | Latitude of the port (pin) end of the start line        | `deg`   | Y      |
+| `navigation.racing.`<br/>`startLinePort.longitude` | Longitude of the port (pin) end of the start line       | `deg`   | Y      |
+| `navigation.racing.`<br/>`startLineStb.latitude`   | Latitude of the starboard (boat) end of the start line  | `deg`   | Y      |
+| `navigation.racing.`<br/>`startLineStb.longitude`  | Longitude of the starboard (boat) end of the start line | `deg`   | Y      |
+| `navigation.racing.`<br/>`nextLegHeading`          | True heading for the next leg of the course             | `deg`   |        |
+| `navigation.racing.`<br/>`nextLegTWA`              | True Wind Angle for the next leg of the course          | `deg`   |        |
 
 These values can be displayed in KIP, Freeboard-SK, or other Signal K clients.
 
@@ -28,6 +28,7 @@ These values can be displayed in KIP, Freeboard-SK, or other Signal K clients.
 
 ---
 
+
 ## ⚙️ Configuration
 
 You can configure the plugin via the Signal K web interface or by editing `settings.json` manually.
@@ -44,16 +45,15 @@ You can configure the plugin via the Signal K web interface or by editing `setti
 
 ## 🧠 Algorithm Descriptions
 
-### 🔹 Waypoint selection (`navigation.racing.startLinePort` and `navigation.racing.startLineStb`)
+### Waypoint selection (`navigation.racing.startLinePort` and `navigation.racing.startLineStb`)
 
-The `startLineStb` and `startLinePort` configurations are used to search resources for matching waypoints.  
-These waypoints can be modified in real time (e.g. moving or setting in Freeboard SK) and the algorithm with update to the new line.
+The `startLineStb` and `startLinePort` configurations are used to search resources for matching waypoints. These waypoints can be modified in real time (e.g. moving or setting in Freeboard SK) and the algorithm with update to the new line.
 
-### 🔹 Bow position
+### Bow position
 
 If `navigation.headingTrue` is not available, then `navigation.courseOverGroundTrue` is used when determining the position of the bow relative to the GPS position.
 
-### 🔹 Distance to Start Line (`navigation.racing.distanceStartline`)
+### Distance to Start Line (`navigation.racing.distanceStartline`)
 
 - Computes the **signed minimum distance** from the **bow** of the boat to the configured start line.
 - Uses `sensors.gps.fromBow` and `sensors.gps.fromCenter` offsets to calculate the actual bow position.
@@ -63,26 +63,42 @@ If `navigation.headingTrue` is not available, then `navigation.courseOverGroundT
     - **Negative** when the bow is **over the line (OCS)**
     - **Positive** when the bow is **behind the line**
 
-### 🔹 Start Line Bias (`navigation.racing.stbLineBias`)
+### Start Line Bias (`navigation.racing.stbLineBias`)
 
 - Measures how far ahead (downwind) the **pin** end is relative to the **boat** end.
 - The `environment.wind.directionTrue` is used as well as the calculated line length and bearing.
 - A **positive value** means the **pin end is more downwind**, implying the **starboard (boat) end is favored** for upwind starts.
 
-### 🔹 Line Coordinates & Length
+### Line Coordinates & Length
 
 - The plugin reads Signal K `waypoints` resources for the names you configure.
 - If both endpoints are found, it calculates:
 - Line length (using `geolib.getPreciseDistance`)
 - Line bearing (rhumb line from starboard to port)
 
-###🔹Next Leg
+### Next Leg
 - If a course is active then the true bearing for the next leg is calculated as `navigation.racing.nextLegHeading`
 - If the `environment.wind.directionTrue` is available, then the True Wind Angle for the next leg is also calculated as `navigation.racing.nextLegHeading`
 - If the next mark of the active route is beyond the first mark, then the start line calculations are suspended.
 
 ---
 
+## 🌐 Start Line REST API
+
+The plugin provides a REST API that allows external clients (e.g. KIP dashboards, mobile apps, or scripts) to **set or query the start line ends**. This can be used to "ping" the boat or pin end by calling a simple HTTP POST with or without a position.
+
+The plugin supports **partial line configuration**: you can set just one end (port or starboard), and it will store and emit that end's position immediately. Once both ends are defined, the full line geometry (length, bearing, bias) will be calculated.
+
+### 📮 API Endpoints
+
+| Method | Endpoint                                 | Description                                                                                          |
+|--------|------------------------------------------|------------------------------------------------------------------------------------------------------|
+| `GET`  | `/plugins/signalk-racer/startline/port`  | Get the last known **port (pin)** end position                                                       |
+| `PUT`  | `/plugins/signalk-racer/startline/port`  | Set the **port (pin)** end of the start line to the current position of the boat plus the bow offset |
+| `GET`  | `/plugins/signalk-racer/startline/stb`   | Get the last known **starboard (boat)** end position                                                 |
+| `PUT`  | `/plugins/signalk-racer/startline/stb`   | Set the **starboard (boat)** end of the line to the current position of the boat plus the bow offset |
+
+
 ## 🔄 Dependencies
 
 - [geolib](https://github.com/manuelbieh/geolib): Used for all geospatial math, including distances, bearings, and projections.

package/ReleaseNotes.md

@@ -0,0 +1,7 @@
+## 0.9.0 Initial Release
++ working DTL, Line Length, next TWA
+## 0.9.1 Format Release
++ formating for the README.TXT
+## 0.9.2 Set Start Line
++ Added API to set the start line
++ Added webapp to call start line API

package/index.js

@@ -178,6 +178,85 @@ module.exports = (app) => {
                 return bow;
             }
 
+            plugin.setStartLineEnd = async (req, res) => {
+                try {
+                    const end = req.params.end;  // "port" or "stb"
+                    if (end !== 'port' && end !== 'stb') {
+                        res.status(400).send({error: 'End must be "port" or "stb"'});
+                        return;
+                    }
+
+                    let position = app.getSelfPath('navigation.position');
+                    if (position)
+                        position = position.value;
+                    else {
+                        res.status(500).send({error: 'No valid position available'});
+                        return;
+                    }
+                    const bow = bowPosition(position);
+                    const startLine = state.startLine;
+                    const waypointName = options[`startLine${end.charAt(0).toUpperCase() + end.slice(1)}`];
+
+                    let waypointId = startLine ? startLine[end + 'Id'] : null;
+                    if (!waypointId) {
+                        // Get the ID of the last existing waypoint with the given name.
+                        const waypoints = await app.resourcesApi.listResources('waypoints', {});
+                        for (const [id, resource] of Object.entries(waypoints)) {
+                            if (resource.name === waypointName) {
+                                waypointId = id;
+                                // don't break here as we want the last waypoint with the given name
+                            }
+                        }
+                    }
+
+                    app.debug(`POSITION to set ${end}(${waypointName}/${waypointId}): ${JSON.stringify(bow)}`);
+
+                    const waypoint = {
+                        name: waypointName,
+                        feature: {
+                            type: 'Feature',
+                            geometry: {
+                                type: 'Point',
+                                coordinates: [bow.longitude, bow.latitude]
+                            },
+                            properties: {}
+                        }
+                    }
+
+                    app.debug(`waypoint: ${waypointId} -> ${end}/${waypointName} : ${JSON.stringify(waypoint)}`);
+
+                    if (waypointId)
+                        await app.resourcesApi.setResource('waypoints', waypointId, waypoint);
+                    else
+                        await app.resourcesApi.createResource('waypoints', waypoint);
+
+                    res.json({
+                        message: 'OK'
+                    });
+
+                    if (startLine)
+                    {
+                        const newStartLine = { ...state.startLine };
+                        newStartLine[end + 'Id'] = waypointId;
+                        newStartLine[end] = bow;
+                        startLine.length = geolib.getPreciseDistance(newStartLine.port, newStartLine.stb, 0.1);
+                        startLine.bearing = geolib.getRhumbLineBearing(newStartLine.stb, newStartLine.port);
+                        state.startLine = newStartLine;
+                        sendDeltas([
+                            { path: `navigation.racing.startLine${end.charAt(0).toUpperCase() + end.slice(1)}`, value: bow },
+                            { path: 'navigation.racing.startLineLength', value: newStartLine.length },
+                        ]);
+
+                        processPosition(position);
+                    } else {
+                        findLineAndThenProcess(position, true);
+                    }
+                } catch (err) {
+                    app.error('Failed to set start line end:', err);
+                    res.status(500).json({ error: 'Failed to set start line end' });
+                }
+            }
+
             function findLineAndThenProcess(position, alwaysFindLine = false) {
                 if (!state.startLine || alwaysFindLine) {
                     app.resourcesApi.listResources(
@@ -196,15 +275,20 @@ module.exports = (app) => {
                             app.debug(`WAYPOINT: ${key}, Value:`, JSON.stringify(value));
                             if (value.name === options.startLinePort) {
                                 let pos = waypointToPosition(value);
-                                if (pos)
+                                if (pos) {
+                                    startLine.portId = key;
                                     startLine.port = pos;
+                                }
                             }
                             if (value.name === options.startLineStb) {
                                 let pos = waypointToPosition(value);
-                                if (pos)
+                                if (pos) {
+                                    startLine.stbId = key;
                                     startLine.stb = pos;
+                                }
                             }
                         }
+
                         if (startLine.port && startLine.stb) {
                             startLine.length = geolib.getPreciseDistance(startLine.port, startLine.stb, 0.1);
                             startLine.bearing = geolib.getRhumbLineBearing(startLine.stb, startLine.port);
@@ -494,7 +578,15 @@ module.exports = (app) => {
             unsubscribes.length = 0;
         },
 
-        schema: () => racerSchema
+        schema: () => racerSchema,
+
+        registerWithRouter: (router) => {
+            router.get('/startline/port', (req, res) => res.json(state.startLine ? state.startLine.port : null));
+            router.get('/startline/stb', (req, res) => res.json(state.startLine ? state.startLine.stb : null));
+            router.put('/startline/:end', plugin.setStartLineEnd);
+        },
+
+        getOpenApi: () => require('./openapi.json'),
     };
 
     return plugin;

package/openapi.json

@@ -0,0 +1,31 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "version": "0.0.1",
+    "title": "Signal K Demo/Test Plugin OpenApi",
+    "license": {
+      "name": "Apache 2.0",
+      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+    }
+  },
+
+  "paths": {
+    "/startline/port": {
+      "get": {
+        "summary": "Set the port end of the start line",
+        "responses": {
+          "200": { "description": "Port end set" }
+        }
+      }
+    },
+    "/startline/stb": {
+      "put": {
+        "summary": "Set the starboard end of the start line",
+        "description": "Set the starboard end of the start line to the boats position plus the bow offset.",
+        "responses": {
+          "200": { "description": "Starboard end set" }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-racer",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Signalk plugin to calculate values of interest to sail racers: such as Distance to Line; Next leg TWA.",
   "main": "index.js",
   "scripts": {
@@ -12,7 +12,8 @@
   },
   "keywords": [
     "signalk-node-server-plugin",
-    "signalk-category-utility"
+    "signalk-category-utility",
+    "signalk-webapp"
   ],
   "signalk-plugin-enabled-by-default": false,
   "signalk": {

package/public/index.html

@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>SignalK Racer</title>
+    <style>
+        body {
+            font-family: sans-serif;
+            max-width: 600px;
+            margin: 3em auto;
+            text-align: center;
+        }
+        button {
+            padding: 1em 2em;
+            margin: 1em;
+            font-size: 1.2em;
+            cursor: pointer;
+        }
+        #status {
+            margin-top: 2em;
+            font-size: 1em;
+            color: green;
+        }
+    </style>
+</head>
+<body>
+<h1>Set Start Line Ends</h1>
+<button onclick="setEnd('port')">Set Port End (Pin)</button>
+<button onclick="setEnd('stb')">Set Starboard End (Boat)</button>
+<div id="status"></div>
+
+<script>
+    async function setEnd(end) {
+        const url = `/plugins/signalk-racer/startline/${end}`;
+        document.getElementById('status').textContent = `Sending request to ${url}...`;
+
+        try {
+            const res = await fetch(url, { method: 'PUT' });
+            if (res.ok) {
+                const data = await res.json();
+                document.getElementById('status').textContent = `✅ ${end.toUpperCase()} set at bow position.`;
+            } else {
+                const err = await res.text();
+                throw new Error(`Error ${res.status}: ${err}`);
+            }
+        } catch (e) {
+            document.getElementById('status').textContent = `❌ Failed: ${e.message}`;
+        }
+    }
+</script>
+</body>
+</html>