@sailingnaturali/signalk-depth-offsets 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bryan Clark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @sailingnaturali/signalk-depth-offsets
+
+Derive **`environment.depth.belowKeel`** and **`environment.depth.belowSurface`**
+from `environment.depth.belowTransducer` using your vessel's measured transducer
+offsets — for depth sounders that only emit NMEA0183 `DBT` (depth below
+transducer) with no offset field.
+
+Zero runtime dependencies.
+
+## What it does
+
+A `DBT`-only sounder maps to `environment.depth.belowTransducer` in Signal K, but
+the keel/surface-referenced depths you actually navigate by (under-keel clearance)
+are never produced. This plugin derives them, using the canonical Signal K
+convention:
+
+```
+belowKeel    = belowTransducer + transducerToKeel    (transducerToKeel < 0)
+belowSurface = belowTransducer + surfaceToTransducer  (surfaceToTransducer > 0)
+```
+
+The offsets come from the data model itself —
+`environment.depth.transducerToKeel` and `environment.depth.surfaceToTransducer`
+(typically set from `baseDeltas.json`). This plugin carries no offsets of its own;
+it's the single transform, the profile is the single source of truth. A derived
+path is only emitted when its offset is present.
+
+## Install
+
+Signal K admin → **Appstore** → search "depth offsets", or
+`npm install @sailingnaturali/signalk-depth-offsets` in your Signal K data dir.
+Set `environment.depth.transducerToKeel` / `surfaceToTransducer` in your vessel's
+`baseDeltas.json` (or any source). No plugin configuration.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,100 @@
+/*
+ * signalk-depth-offsets
+ *
+ * The Wind Chaser's sounder emits NMEA0183 DBT only, which SignalK maps to
+ * environment.depth.belowTransducer. There is no offset field on DBT, so the
+ * keel/surface-referenced depths the agents actually reason about
+ * (under-keel clearance) are never produced.
+ *
+ * This plugin derives them from the transducer offsets, using the canonical
+ * SignalK convention:
+ *   belowKeel    = belowTransducer + transducerToKeel   (transducerToKeel < 0)
+ *   belowSurface = belowTransducer + surfaceToTransducer (surfaceToTransducer > 0)
+ *
+ * The offsets themselves (environment.depth.transducerToKeel /
+ * surfaceToTransducer) come from baseDeltas.json, which the vessel_config
+ * generator renders from the profile (vessels/profiles/*.yaml, offsets.*).
+ * The profile is the single source of truth; this plugin carries no offset
+ * values of its own — it just reads them back off the data model.
+ */
+module.exports = function (app) {
+  const plugin = {
+    id: 'signalk-depth-offsets',
+    name: 'Depth offsets (belowKeel / belowSurface)',
+    description:
+      'Derive belowKeel and belowSurface from belowTransducer for DBT-only sounders.',
+  };
+
+  let unsubscribes = [];
+
+  // No configuration: offsets are sourced from environment.depth.transducerToKeel
+  // and surfaceToTransducer (set by baseDeltas from the vessel profile).
+  plugin.schema = { type: 'object', properties: {} };
+
+  // app.getSelfPath returns the full leaf node ({ value, timestamp, ... }) in
+  // most server versions, but the bare value in some; handle both.
+  function selfNumber(path) {
+    const node = app.getSelfPath(path);
+    if (node == null) return undefined;
+    const v = typeof node === 'object' && 'value' in node ? node.value : node;
+    return typeof v === 'number' ? v : undefined;
+  }
+
+  plugin.start = function () {
+    app.subscriptionmanager.subscribe(
+      {
+        context: 'vessels.self',
+        subscribe: [
+          {
+            path: 'environment.depth.belowTransducer',
+            period: 1000,
+          },
+        ],
+      },
+      unsubscribes,
+      (err) => app.error(err),
+      (delta) => {
+        const transducerToKeel = selfNumber('environment.depth.transducerToKeel');
+        const surfaceToTransducer = selfNumber(
+          'environment.depth.surfaceToTransducer'
+        );
+        if (transducerToKeel === undefined && surfaceToTransducer === undefined) {
+          // Offsets not in the model yet (baseDeltas not applied) — nothing to derive.
+          return;
+        }
+        (delta.updates || []).forEach((update) => {
+          (update.values || []).forEach((v) => {
+            if (
+              v.path === 'environment.depth.belowTransducer' &&
+              typeof v.value === 'number'
+            ) {
+              const values = [];
+              if (transducerToKeel !== undefined) {
+                values.push({
+                  path: 'environment.depth.belowKeel',
+                  value: v.value + transducerToKeel,
+                });
+              }
+              if (surfaceToTransducer !== undefined) {
+                values.push({
+                  path: 'environment.depth.belowSurface',
+                  value: v.value + surfaceToTransducer,
+                });
+              }
+              if (values.length) {
+                app.handleMessage(plugin.id, { updates: [{ values }] });
+              }
+            }
+          });
+        });
+      }
+    );
+  };
+
+  plugin.stop = function () {
+    unsubscribes.forEach((f) => f());
+    unsubscribes = [];
+  };
+
+  return plugin;
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@sailingnaturali/signalk-depth-offsets",
+  "version": "0.1.0",
+  "description": "Derive environment.depth.belowKeel and belowSurface from belowTransducer using measured transducer offsets. For DBT-only feeds that carry no offset field.",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-category-utility",
+    "depth",
+    "marine"
+  ],
+  "author": "Bryan Clark",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sailingnaturali/signalk-depth-offsets.git"
+  },
+  "homepage": "https://github.com/sailingnaturali/signalk-depth-offsets#readme",
+  "bugs": {
+    "url": "https://github.com/sailingnaturali/signalk-depth-offsets/issues"
+  },
+  "files": [
+    "index.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}