signalk-racer 0.9.9 → 0.9.11

package/README.md

@@ -1,6 +1,10 @@
 # Signal K Racing Plugin
 
-This PROTOTYPE plugin adds sail racing-relevant data calculations to a Signal K server. It focuses on real-time information useful during the start of a race, such as distance to the line, start line bias, and geographic position of the line ends.
+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.
+ + Calculation of the TWA for the next leg of the course.
 
 GitHub repository: [https://github.com/gregw/signalk-racer](https://github.com/gregw/signalk-racer)
 
@@ -10,24 +14,26 @@ 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 | Std |
-|----------------------------------------------------|---------------------------------------------------------|-------|-----|
-| `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` |     |
-| `navigation.racing.`<br/>`timeToStart`             | Period of time until the race start                     | `s`   | Y   |
-| `navigation.racing.`<br/>`startTime`               | The start time as an ISO timestamp                      | `iso` |     |
-
-These values can be displayed in KIP, Freeboard-SK, or other Signal K clients.
+| Path                                            | Description                                            | Units                  | Std |
+|-------------------------------------------------|--------------------------------------------------------|------------------------|-----|
+| `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`        | Location of the port (pin) end of the start line       | `{latitude,longitude}` | Y   |
+| `navigation.racing.`<br/>`startLineStb`         | Location of the starboard (boat) end of the start line | `{latitude,longitude}` | Y   |
+| `navigation.racing.`<br/>`nextLegHeading`       | True heading for the next leg of the course            | `rad`                  |     |
+| `navigation.racing.`<br/>`nextLegTrueWindAngle` | True Wind Angle for the next leg of the course         | `rad`                  |     |
+| `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.
 
 ![KIP and Freeboard Screenshot](kip-freeboard-screenshot.png)
 
+There is also a webapp to adjust the line and timer.
+
+![Signalk Racer Webapp](racer-webapp.png)
+
 ---
 
 ## ⚙️ Configuration
@@ -36,11 +42,14 @@ You can configure the plugin via the Signal K web interface or by editing `setti
 
 ### Parameters:
 
-| Parameter       | Description                                                              | Default       |
-|----------------|--------------------------------------------------------------------------|---------------|
-| `startLineStb`  | Name of the waypoint for the starboard (committee boat) end of the line | `"startBoat"` |
-| `startLinePort` | Name of the waypoint for the port (pin) end of the line                 | `"startPin"`  |
-| `period`        | How often to update values (in milliseconds)                            | `1000`        |
+| Parameter                 | Description                                                             | Default       |
+|---------------------------|-------------------------------------------------------------------------|---------------|
+| `startLineStb`            | Name of the waypoint for the starboard (committee boat) end of the line | `"startBoat"` |
+| `startLinePort`           | Name of the waypoint for the port (pin) end of the line                 | `"startPin"`  |
+| `timer`                   | Initial time for the race timer (in seconds)                            | `300`         |
+| `period`                  | How often to update values (in milliseconds)                            | `1000`        |
+| `updateStartLineWaypoint` | Should the waypoints be updated if the line is set/adjusted             | `true`        |
+| `createStartLineWaypoint` | Should the waypoints be created if the line is set                      | `true`        |
 
 ---
 
@@ -79,7 +88,7 @@ If `navigation.headingTrue` is not available, then `navigation.courseOverGroundT
 
 ### 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 `environment.wind.directionTrue` is available, then the True Wind Angle for the next leg is also calculated as `navigation.racing.nextLegTrueWindAngle`
 - If the next mark of the active route is beyond the first mark, then the start line calculations are suspended.
 
 ---
@@ -123,8 +132,16 @@ 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.
+
 ## 🔄 Dependencies
 
+### Plugins
+- [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
+
+### Libraries
 - `geolib`: for distance and bearing calculations.
 
 ---
@@ -134,7 +151,6 @@ Used to **start**, **sync**, **reset**, or **set a fixed start time**.
 - Add calculations for:
 - **Time to line** (using STW and heading or polar speeds)
 - **Laylines** and distance/time to them
-- A KIP widget as well as the webapp.
 - Better integration with **Freeboard-SK** and **KIP** dashboards
 
 --- 

package/ReleaseNotes.md

@@ -1,3 +1,10 @@
+## 0.9.11 Release Candidate
+ + Improved documentation
+
+## 0.9.10 Updates for KIP widgets
+ + Do not set a start time unless timer is running
+ + Schema RFC 3339 units for start time.
+
 ## 0.9.9 Working with KIP prototypes
  + Fixed API handlers to use return status rather than callback
 

package/index.js

@@ -50,6 +50,7 @@ module.exports = (app) => {
                     {
                         "path": "navigation.racing.startLineLength",
                         "value": {
+                            "type": "number",
                             "units": "m",
                             "description": "Length of the start line",
                             "displayName": "Length of the start line",
@@ -59,6 +60,7 @@ module.exports = (app) => {
                     {
                         "path": "navigation.racing.stbLineBias",
                         "value": {
+                            "type": "number",
                             "units": "m",
                             "description": "Bias of the start line for the starboard end",
                             "displayName": "Bias of the start line for the starboard end",
@@ -68,6 +70,7 @@ module.exports = (app) => {
                     {
                         "path": "navigation.racing.nextLegHeading",
                         "value": {
+                            "type": "number",
                             "units": "rad",
                             "description": "Heading of the next leg of the course",
                             "displayName": "Next Heading",
@@ -77,12 +80,26 @@ module.exports = (app) => {
                     {
                         "path": "navigation.racing.nextLegTrueWindAngle",
                         "value": {
+                            "type": "number",
                             "units": "rad",
                             "description": "TWA on the next leg of the course",
                             "displayName": "Next TWA",
                             "shortName": "NextTWA",
                         }
                     },
+                    {
+                        "path": "navigation.racing.startTime",
+                        "value": {
+                            "type": "string",
+                            "units": "RFC 3339 (UTC)",
+                            "example": "2014-04-10T08:33:53.123Z",
+                            "format": "date-time",
+                            "pattern" : ".*Z$",
+                            "description": "Time of the race start in RFC 3339 UTC only format ",
+                            "displayName": "Start Time",
+                            "shortName": "StartTime",
+                        }
+                    },
                 ]
             }
         ]
@@ -235,58 +252,62 @@ module.exports = (app) => {
 
             // Set/create the waypoint if we are configured to do so
             if (state.options.updateStartLineWaypoint || updateWaypoint) {
-                const waypointConfig = `startLine${camelCase(end)}`;
-                app.debug(`waypointConfig: ${waypointConfig}`);
-                const waypointName = state.options[waypointConfig];
-                app.debug(`waypointName: ${waypointName}`);
-                let waypointId = startLine ? startLine[end + 'Id'] : null;
-                app.debug(`waypointId: ${waypointId}`);
-
-                // If we have not cached the Id of the line end, then
-                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
-                        }
-                    }
+                try {
+                    const waypointConfig = `startLine${camelCase(end)}`;
+                    app.debug(`waypointConfig: ${waypointConfig}`);
+                    const waypointName = state.options[waypointConfig];
+                    app.debug(`waypointName: ${waypointName}`);
+                    let waypointId = startLine ? startLine[end + 'Id'] : null;
                     app.debug(`waypointId: ${waypointId}`);
-                }
 
-                app.debug(`Startline waypoint to set ${end}(${waypointName}/${waypointId}): ${JSON.stringify(position)}`);
+                    // If we have not cached the Id of the line end, then
+                    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(`waypointId: ${waypointId}`);
+                    }
 
-                const waypoint = {
-                    name: waypointName,
-                    feature: {
-                        type: 'Feature',
-                        geometry: {
-                            type: 'Point',
-                            coordinates: [position.longitude, position.latitude]
+                    app.debug(`Startline waypoint to set ${end}(${waypointName}/${waypointId}): ${JSON.stringify(position)}`);
+
+                    const waypoint = {
+                        name: waypointName,
+                        feature: {
+                            type: 'Feature',
+                            geometry: {
+                                type: 'Point',
+                                coordinates: [position.longitude, position.latitude]
+                            },
+                            properties: {}
                         },
-                        properties: {}
-                    },
-                    type: end === 'port' ? 'start-pin' : 'start-boat',
-                    position: {
-                        latitude: position.latitude,
-                        longitude: position.longitude
+                        type: end === 'port' ? 'start-pin' : 'start-boat',
+                        position: {
+                            latitude: position.latitude,
+                            longitude: position.longitude
+                        }
                     }
-                }
 
-                app.debug(`waypoint: ${waypointId} -> ${end}/${waypointName} : ${JSON.stringify(waypoint)}`);
+                    app.debug(`waypoint: ${waypointId} -> ${end}/${waypointName} : ${JSON.stringify(waypoint)}`);
 
-                if (waypointId)
-                    await app.resourcesApi.setResource('waypoints', waypointId, waypoint);
-                else if (state.options.createStartLineWaypoint)
-                    await app.resourcesApi.createResource('waypoints', waypoint);
-                else
-                    app.debug('startline waypoint not created');
+                    if (waypointId)
+                        await app.resourcesApi.setResource('waypoints', waypointId, waypoint);
+                    else if (state.options.createStartLineWaypoint)
+                        await app.resourcesApi.createResource('waypoints', waypoint);
+                    else
+                        app.debug('startline waypoint not created');
+                }
+                catch (err) {
+                    app.error(`Failed to set startline waypoint: ${err}`);
+                }
             } else {
                 app.debug('startline waypoint not updated');
             }
 
-
             // If we have a startLine, then process position against the new line
             if (startLine)
                 processPosition(null);
@@ -461,17 +482,21 @@ module.exports = (app) => {
                         return;
                     }
 
-                    state.timeToStart += delta;
-                    if (state.timeToStart < 0) state.timeToStart = 0;
+                    state.timeToStart = Math.max(state.timeToStart + delta, 0);
 
-                    let now = Date.now();
-                    const adjustedStart = new Date(now - (now % 1000) + state.timeToStart * 1000).toISOString();
-                    state.startTime = adjustedStart;
+                    if (state.timerRunning) {
+                        let now = Date.now();
+                        state.startTime = new Date(now - (now % 1000) + state.timeToStart * 1000).toISOString();
+                    }
+
+                    const deltas = [
+                        { path: 'navigation.racing.timeToStart', value: state.timeToStart }
+                    ];
+                    if (state.timerRunning && state.startTime) {
+                        deltas.push({path: 'navigation.racing.startTime', value: state.startTime });
+                    }
+                    sendDeltas(deltas);
 
-                    sendDeltas([
-                        {path: 'navigation.racing.timeToStart', value: state.timeToStart},
-                        {path: 'navigation.racing.startTime', value: adjustedStart}
-                    ]);
                     return complete(callback, 200, 'adjust timer: OK');
                 }
 
@@ -480,6 +505,7 @@ module.exports = (app) => {
                 }
             }
         } catch (err) {
+            app.debug('startTimerCommand:', JSON.stringify(err));
             return complete(callback, 500, 'Failed to command timer: ' + JSON.stringify(err));
         }
     }

package/package.json

@@ -1,11 +1,8 @@
 {
   "name": "signalk-racer",
-  "version": "0.9.9",
-  "description": "Signalk plugin to calculate values of interest to sail racers: such as Distance to Line; Next leg TWA.",
+  "version": "0.9.11",
+  "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",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gregw/signalk-racer.git"