@sailingnaturali/signalk-dsc 0.1.3 → 0.3.0

package/README.md

@@ -50,10 +50,22 @@ For every DSC call heard by a connected radio:
 - **Remote-vessel deltas** — the caller's `navigation.position` (and a distress
   notification) under `vessels.urn:mrn:imo:mmsi:<caller>`, so chartplotters can
   show where the call came from.
+- Every stored call carries an `ownShip` snapshot of the moment it arrived —
+  position, course, heading, speed, wind, pressure, and (when a source publishes them)
+  sea state, visibility, and cloud coverage. Absent sensor, absent field.
+- Logbook entries are written with `vhf: "70"` (DSC is received on channel 70
+  by definition) plus structured `observations`; non-distress calls that
+  propose a working channel get it in the entry text and on the stored event
+  as `workingChannel`.
 - **Optional ship's-log entries** via
   [signalk-logbook](https://github.com/meri-imperiumi/signalk-logbook) — a
   GMDSS-style radio log of received distress/urgency/safety traffic.
 
+> **Note:** Visibility on `environment.outside.visibility` is read as meters
+> and converted to the logbook 0–9 fog scale; an integer value ≤ 9 is assumed
+> to already be a fog-scale code, so sub-10-meter metric readings would be
+> misread.
+
 ## Transports
 
 - **NMEA 0183**: registers custom `DSC` and `DSE` sentence parsers (these replace
@@ -73,6 +85,7 @@ For every DSC call heard by a connected radio:
 | `logbookRoutine` | `false` | Also log routine calls. |
 | `logbookUrl` | `http://localhost:3000/plugins/signalk-logbook/logs` | |
 | `logbookToken` | _empty_ | SignalK access token; logbook writes are skipped without one (plugin routes are auth-gated). |
+| `snapshotPaths` | `[]` | Extra `{ field, path }` pairs added to the `ownShip` snapshot on each stored call (position, course, heading, speed, wind, pressure, sea state, visibility and cloud coverage are always attempted). |
 
 ## Trying it without a radio
 
@@ -129,6 +142,19 @@ $CDDSC,12,3380400790,12,05,00,1423108312,2019,,,S,E*69
 $CDDSE,1,1,A,3380400790,00,45894494*1B
 ```
 
+### Clearing an alarm
+
+A received distress/urgency/safety call raises `notifications.dsc.<category>` and is
+re-raised for up to an hour across server restarts. To clear an active alarm — dropping
+the live notification and stopping the restart re-raise:
+
+```bash
+SIGNALK_TOKEN=<readwrite-token> npm run clear-dsc -- --category distress
+```
+
+`--category all` clears all three. Clearing is a write, so it needs a readwrite token
+(the same one used to fire a test MOB). A new incoming call still alarms normally.
+
 ## Limitations
 
 - Distress relays, acknowledgements, and cancellations are stored (with

package/index.js

@@ -29,6 +29,7 @@ const { parseDse, refinePosition } = require('./lib/dse');
 const { normalizePgn129808 } = require('./lib/pgn129808');
 const { EventStore } = require('./lib/store');
 const { buildMessage, buildLogbookText } = require('./lib/format');
+const { captureOwnShip, buildObservations, unwrap } = require('./lib/snapshot');
 
 const DSC_PGN = 129808;
 const NOTIFICATION_STATES = { distress: 'emergency', urgency: 'alarm', safety: 'alert' };
@@ -77,6 +78,20 @@ module.exports = function makePlugin(app) {
         description: 'Plugin routes are auth-gated; without a token the logbook write is skipped.',
         default: '',
       },
+      snapshotPaths: {
+        type: 'array',
+        title: 'Extra own-ship paths to snapshot on each call',
+        description:
+          'Each entry adds a field to the stored event\'s ownShip block (position, course, speed, wind, pressure, sea state, visibility and cloud coverage are always attempted).',
+        default: [],
+        items: {
+          type: 'object',
+          properties: {
+            field: { type: 'string', title: 'Field name in ownShip' },
+            path: { type: 'string', title: 'SignalK self path' },
+          },
+        },
+      },
     },
   };
 
@@ -85,10 +100,6 @@ module.exports = function makePlugin(app) {
   let started = false;
   let reannounceTimer = null;
 
-  function unwrap(node) {
-    return node && typeof node === 'object' && 'value' in node ? node.value : node;
-  }
-
   function selfMmsi() {
     const value = unwrap(app.getSelfPath('mmsi'));
     return typeof value === 'string' ? value : undefined;
@@ -142,6 +153,15 @@ module.exports = function makePlugin(app) {
     });
   }
 
+  /** Clear an active DSC alarm: drop the live notification from our own source
+   *  and stamp the stored events so the restart reannounce skips them. */
+  function clearCategory(category) {
+    app.handleMessage(plugin.id, {
+      updates: [{ values: [{ path: `notifications.dsc.${category}`, value: null }] }],
+    });
+    store.markCleared((e) => e.category === category, new Date().toISOString());
+  }
+
   function shouldLogbook(event) {
     if (options.logbookEnabled === false) return false;
     if (!options.logbookToken) return false;
@@ -152,6 +172,7 @@ module.exports = function makePlugin(app) {
   }
 
   async function postLogbook(event) {
+    const observations = buildObservations(event.ownShip);
     const res = await fetch(options.logbookUrl, {
       method: 'POST',
       headers: {
@@ -161,7 +182,14 @@ module.exports = function makePlugin(app) {
         Authorization: `Bearer ${options.logbookToken}`,
         Cookie: `JAUTHENTICATION=${options.logbookToken}`,
       },
-      body: JSON.stringify({ text: buildLogbookText(event, messageContext(event)), ago: 0, category: 'radio' }),
+      body: JSON.stringify({
+        text: buildLogbookText(event, messageContext(event)),
+        ago: 0,
+        category: 'radio',
+        // DSC is received on VHF channel 70 by definition.
+        vhf: '70',
+        ...(observations ? { observations } : {}),
+      }),
     });
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
   }
@@ -194,6 +222,11 @@ module.exports = function makePlugin(app) {
       return duplicate;
     }
 
+    // Own-ship context at receive time — the forensic record of the moment
+    // the call arrived. First receipt only: repeats keep the original.
+    const ownShip = captureOwnShip(app, options.snapshotPaths);
+    if (ownShip) event.ownShip = ownShip;
+
     store.add(event);
     notify(event);
     if (shouldLogbook(event)) {
@@ -330,6 +363,17 @@ module.exports = function makePlugin(app) {
     app.emitPropertyValue('nmea0183sentenceParser', { sentence: 'DSE', parser: dseParser });
     app.on('N2KAnalyzerOut', onPgn);
 
+    // Let an operator clear an active DSC alarm: a PUT to the notification path
+    // drops the live alert and marks the stored call(s) so a restart will not
+    // re-raise it. The readwrite device token authorizes this write.
+    for (const category of Object.keys(NOTIFICATION_STATES)) {
+      // Value ignored: any PUT to these paths means "clear" — no partial-update semantics.
+      app.registerPutHandler('vessels.self', `notifications.dsc.${category}`, () => {
+        clearCategory(category);
+        return { state: 'COMPLETED', statusCode: 200 };
+      });
+    }
+
     started = true;
 
     // Survive server restarts mid-incident: re-raise the newest alert per
@@ -345,6 +389,7 @@ module.exports = function makePlugin(app) {
       for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
         if (!NOTIFICATION_STATES[event.category] || reannounced.has(event.category)) continue;
+        if (event.clearedAt) continue; // operator-cleared: never resurrect
         const at = Date.parse(event.lastReceivedAt || event.receivedAt);
         if (now - at <= REANNOUNCE_WINDOW_MS) {
           notify(event);

package/lib/dsc.js

@@ -88,6 +88,23 @@ function parseUtcTime(raw) {
   return `${t.substring(0, 2)}:${t.substring(2, 4)}`;
 }
 
+// VHF channel plausibility: 1–99 (international) or the 4-digit simplex
+// forms (10NN / 20NN). The field arrives over the air unvalidated — anything
+// that does not normalize to one of these shapes is dropped.
+function parseChannel(raw) {
+  if (typeof raw !== 'string' || !/^\d{1,6}$/.test(raw.trim())) return undefined;
+  const t = raw.trim();
+  // ITU-R M.493 frequency field: a leading 9 on a 6-digit value marks
+  // "channel number follows", zero-padded (900072 = channel 72).
+  const digits = /^9\d{5}$/.test(t) ? t.slice(1) : t;
+  const n = Number(digits);
+  if (!Number.isInteger(n)) return undefined;
+  if ((n >= 1 && n <= 99) || (n >= 1001 && n <= 1099) || (n >= 2001 && n <= 2099)) {
+    return String(n);
+  }
+  return undefined;
+}
+
 /**
  * Parse the comma-split fields of a $--DSC sentence (sentence id and checksum
  * already stripped) into a partial DSC event. Tolerant by design: anything we
@@ -127,6 +144,9 @@ function parseDsc(parts) {
   if (distress || field(parts, 3) === TELECOMMAND_SHIP_POSITION) {
     event.position = parsePosition(field(parts, 5));
     event.utcTime = parseUtcTime(field(parts, 6));
+  } else {
+    const channel = parseChannel(field(parts, 5));
+    if (channel) event.workingChannel = channel;
   }
 
   const ack = field(parts, 9);
@@ -136,4 +156,4 @@ function parseDsc(parts) {
   return event;
 }
 
-module.exports = { parseDsc, parsePosition, parseMmsi, parseUtcTime, NATURES };
+module.exports = { parseDsc, parsePosition, parseMmsi, parseUtcTime, parseChannel, NATURES };

package/lib/format.js

@@ -87,6 +87,7 @@ function buildLogbookText(event, { ownPosition, vesselName } = {}) {
   } else if (event.utcTime) {
     parts.push(`reported at ${event.utcTime} UTC`);
   }
+  if (event.workingChannel) parts.push(`proposed working channel ${event.workingChannel}`);
   if (event.source) parts.push(`via ${event.source}`);
   return `[DSC] ${parts.join('. ')}`;
 }

package/lib/snapshot.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/*
+ * Own-ship context snapshot, taken at DSC call receive time.
+ *
+ * The stored event is the forensic record of the moment a call arrived; the
+ * snapshot answers "what was our situation when we heard it". Values are
+ * stored exactly as SignalK provides them (rad, m/s, Pa, meters) — absent
+ * sensor, absent field, never fabricated. Conversion to logbook units
+ * happens only in buildObservations.
+ */
+
+const DEFAULT_SNAPSHOT_FIELDS = [
+  { field: 'position', path: 'navigation.position' },
+  { field: 'cog', path: 'navigation.courseOverGroundTrue' },
+  { field: 'sog', path: 'navigation.speedOverGround' },
+  { field: 'heading', path: 'navigation.headingTrue' },
+  { field: 'wind.speed', path: 'environment.wind.speedOverGround' },
+  { field: 'wind.direction', path: 'environment.wind.directionTrue' },
+  { field: 'pressure', path: 'environment.outside.pressure' },
+  // signalk-logbook conventions (no SignalK spec paths exist for these).
+  { field: 'seaState', path: 'environment.water.swell.state' },
+  { field: 'visibility', path: 'environment.outside.visibility' },
+  { field: 'cloudCoverage', path: 'environment.outside.cloudCoverage' },
+];
+
+const UNSAFE_KEY = /^(__proto__|constructor|prototype)$/;
+
+function unwrap(node) {
+  return node && typeof node === 'object' && 'value' in node ? node.value : node;
+}
+
+/** Read the default + configured paths off the data model. Best-effort:
+ *  a throwing read skips that field. Returns undefined when empty. */
+function captureOwnShip(app, extraFields = []) {
+  const snapshot = {};
+  const fields = DEFAULT_SNAPSHOT_FIELDS.concat(Array.isArray(extraFields) ? extraFields : []);
+  for (const entry of fields) {
+    if (!entry || typeof entry.field !== 'string' || typeof entry.path !== 'string') continue;
+    const keys = entry.field.split('.');
+    if (keys.some((k) => !k || UNSAFE_KEY.test(k))) continue;
+    let value;
+    try {
+      value = unwrap(app.getSelfPath(entry.path));
+    } catch {
+      continue;
+    }
+    // Decouple from the live data model and refuse anything that could
+    // break the JSON store on the alarm-critical receive path.
+    try {
+      value = JSON.parse(JSON.stringify(value));
+    } catch {
+      continue;
+    }
+    if (value === undefined || value === null) continue;
+    let target = snapshot;
+    for (const key of keys.slice(0, -1)) {
+      if (typeof target[key] !== 'object' || target[key] === null) target[key] = {};
+      target = target[key];
+    }
+    target[keys[keys.length - 1]] = value;
+  }
+  return Object.keys(snapshot).length ? snapshot : undefined;
+}
+
+// Upper bounds (meters, exclusive) for fog-scale codes 0–8; ≥50 km is 9.
+const FOG_SCALE_METERS = [50, 200, 500, 1000, 2000, 4000, 10000, 20000, 50000];
+
+/** Meters → logbook fog-scale 0–9. A small integer (≤9) is assumed to
+ *  already be a fog-scale code and passes through. */
+function visibilityToFogScale(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return undefined;
+  if (Number.isInteger(value) && value <= 9) return value;
+  const idx = FOG_SCALE_METERS.findIndex((limit) => value < limit);
+  return idx === -1 ? 9 : idx;
+}
+
+/** signalk-logbook observations block from a snapshot. Only keys with valid
+ *  values; undefined when there are none. */
+function buildObservations(ownShip) {
+  if (!ownShip) return undefined;
+  const obs = {};
+  if (Number.isInteger(ownShip.seaState) && ownShip.seaState >= 0 && ownShip.seaState <= 9) {
+    obs.seaState = ownShip.seaState;
+  }
+  if (
+    Number.isInteger(ownShip.cloudCoverage) &&
+    ownShip.cloudCoverage >= 0 &&
+    ownShip.cloudCoverage <= 8
+  ) {
+    obs.cloudCoverage = ownShip.cloudCoverage;
+  }
+  const visibility = visibilityToFogScale(ownShip.visibility);
+  if (visibility !== undefined) obs.visibility = visibility;
+  return Object.keys(obs).length ? obs : undefined;
+}
+
+module.exports = { captureOwnShip, buildObservations, visibilityToFogScale, unwrap, DEFAULT_SNAPSHOT_FIELDS };

package/lib/store.js

@@ -76,6 +76,17 @@ class EventStore {
     return this.events.find((e) => e.id === id);
   }
 
+  /** Stamp `clearedAt` on every matching event not already cleared. Returns the
+   *  count newly stamped; compacts once. */
+  markCleared(predicate, at) {
+    let touched = 0;
+    for (const e of this.events) {
+      if (predicate(e) && !e.clearedAt) { e.clearedAt = at; touched += 1; }
+    }
+    if (touched) this._compact();
+    return touched;
+  }
+
   /** Newest event matching `predicate` received within `windowMs` of `nowMs`. */
   findRecent(predicate, nowMs, windowMs) {
     for (let i = this.events.length - 1; i >= 0; i--) {

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@sailingnaturali/signalk-dsc",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Receive, log, and alert on DSC (VHF digital selective calling) calls — distress, urgency, safety, routine — from NMEA 0183 ($CDDSC/$CDDSE) and NMEA 2000 (PGN 129808).",
   "main": "index.js",
   "scripts": {
     "test": "node --test",
-    "send-test-dsc": "node scripts/send-test-dsc.js"
+    "send-test-dsc": "node scripts/send-test-dsc.js",
+    "clear-dsc": "node scripts/clear-dsc-alarm.js"
   },
   "keywords": [
     "signalk-node-server-plugin",