@sailingnaturali/signalk-dsc 0.2.0 → 0.3.1

package/README.md

@@ -142,6 +142,21 @@ $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.
+This clears the `self`-context alarm; the transient per-caller notification raised under
+the sender's vessel context is not persisted or re-raised, so it is left untouched.
+
 ## Limitations
 
 - Distress relays, acknowledgements, and cancellations are stored (with
@@ -151,6 +166,34 @@ $CDDSE,1,1,A,3380400790,00,45894494*1B
 - A raised distress notification stays active until cleared from the server —
   deliberate: a received MAYDAY should not silently expire.
 
+## Future work
+
+This plugin is **receive-only**: it reads, logs, and alarms on DSC calls a radio
+puts on the bus, and never transmits. The obvious next capability is the *write*
+path — initiating a DSC call from SignalK, e.g. relaying a MAYDAY or sending a
+distress/MOB alert *to* the radio to broadcast.
+
+The blocker is hardware, not software. Almost no marine VHF exposes an interface
+to be **commanded to transmit** a DSC call:
+
+- NMEA 0183 radios take a GPS position *in* and emit received calls *out*, but
+  there's no standard sentence to initiate a transmission.
+- On NMEA 2000, PGN 129808 carries received call info; there's no
+  widely-implemented PGN to command a transmit. Where "send distress from the
+  chartplotter" exists at all, it's proprietary same-vendor MFD↔radio
+  integration, not an open standard a third-party plugin can drive.
+
+The closest exception we've found is Icom's networked VHFs — the **M510 EVO** and
+**M605** — which expose external/remote DSC initiation, where most radios only
+let you initiate a DSC call on the radio itself. That makes them the realistic
+target for a transmit path.
+
+So a SignalK-driven relay is gated on a radio that actually supports external DSC
+transmission — still rare — plus the care that initiating a distress demands (it
+broadcasts on behalf of a real, licensed MMSI). Until such hardware is common
+this stays out of scope and the plugin remains a passive receiver. If you have a
+radio that exposes a transmit interface, open an issue.
+
 ## License
 
 MIT

package/index.js

@@ -153,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;
@@ -196,7 +205,9 @@ module.exports = function makePlugin(app) {
     if (event.mmsi && event.mmsi === selfMmsi()) event.self = true;
 
     // Re-transmission of the same call (distress alerts auto-repeat until
-    // acknowledged): bump the stored call, do not re-alarm.
+    // acknowledged): bump the stored call, do not re-alarm. This matches on
+    // mmsi+category+nature and ignores `clearedAt`, so an operator-cleared call
+    // that keeps repeating stays silent — a cleared MAYDAY should not re-nag.
     const duplicate = store.findRecent(
       (e) =>
         e.mmsi === event.mmsi &&
@@ -354,6 +365,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
@@ -369,6 +391,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/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.2.0",
+  "version": "0.3.1",
   "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",