@sailingnaturali/signalk-dsc 0.3.0 → 0.4.0

package/README.md

@@ -48,8 +48,12 @@ For every DSC call heard by a connected radio:
   Full detail (MMSI, coordinates, reported time, transport) goes to the call
   log and the logbook entry instead, so TTS pipelines stay terse.
 - **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.
+  notification) under the caller's context, so chartplotters can show where the
+  call came from. A **distress** caller is emitted under the Search-and-Rescue
+  context `sar.urn:mrn:imo:mmsi:<caller>` — which plotters like
+  [Freeboard-SK](https://github.com/SignalK/freeboard-sk) render as a distress
+  (SaR) target rather than an ordinary AIS vessel; every other category stays
+  under `vessels.urn:mrn:imo:mmsi:<caller>`.
 - 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.
@@ -154,6 +158,8 @@ 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
 
@@ -164,6 +170,34 @@ SIGNALK_TOKEN=<readwrite-token> npm run clear-dsc -- --category distress
 - 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

@@ -205,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 &&
@@ -242,8 +244,14 @@ module.exports = function makePlugin(app) {
     return event;
   }
 
-  function remoteContext(mmsi) {
-    return `vessels.urn:mrn:imo:mmsi:${mmsi}`;
+  // The SignalK context the caller's position is emitted under. A distress
+  // caller is a vessel in extremis, so it goes under the Search-and-Rescue
+  // context (`sar.`) — which chartplotters (e.g. Freeboard-SK) render as a
+  // distress/SaR target rather than an ordinary AIS vessel. Every other
+  // category stays under `vessels.` like any AIS contact.
+  function callerContext(category, mmsi) {
+    const prefix = category === 'distress' ? 'sar' : 'vessels';
+    return `${prefix}.urn:mrn:imo:mmsi:${mmsi}`;
   }
 
   // Custom sentence parsers override the stock hooks (a superset of the
@@ -261,8 +269,8 @@ module.exports = function makePlugin(app) {
         receivedAt: input.tags && input.tags.timestamp,
       });
 
-      // Upstream-compatible delta under the sender's context so chartplotters
-      // and AIS-style consumers see the caller's position.
+      // Delta under the caller's context so chartplotters and AIS-style
+      // consumers see the caller's position (distress → SaR target).
       if (parsed.mmsi) {
         const values = [];
         if (parsed.position) {
@@ -279,7 +287,10 @@ module.exports = function makePlugin(app) {
           });
         }
         if (values.length) {
-          return { context: remoteContext(parsed.mmsi), updates: [{ values }] };
+          return {
+            context: callerContext(parsed.category, parsed.mmsi),
+            updates: [{ values }],
+          };
         }
       }
     } catch (err) {
@@ -304,7 +315,7 @@ module.exports = function makePlugin(app) {
       const refined = refinePosition(target.position, ext);
       store.update(target.id, { position: refined, positionResolution: 'enhanced' });
       return {
-        context: remoteContext(ext.mmsi),
+        context: callerContext(target.category, ext.mmsi),
         updates: [{ values: [{ path: 'navigation.position', value: refined }] }],
       };
     } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sailingnaturali/signalk-dsc",
-  "version": "0.3.0",
+  "version": "0.4.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": {