@sailingnaturali/signalk-dsc 0.5.6 → 0.6.0

package/README.md

@@ -105,6 +105,50 @@ For every DSC call heard by a connected radio:
 | `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). |
 
+## DSCWatch reporting
+
+DSCWatch ([dscwatch.com](https://dscwatch.com)) is a crowdsourced network that
+aggregates received DSC traffic from stations around the world. Participation is
+**opt-in and off by default** — enabling it sends each received call to the network,
+including your receiver's position, to help build coverage maps and distress logs.
+
+### Configuration
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `dscwatchEnabled` | `false` | Must be set to `true` to send any reports. No data leaves the boat until this is on. |
+| `dscwatchReceiverKey` | _empty_ | Leave blank to use an auto-generated UUID that persists in the plugin data directory (`dscwatch-receiver-key`). Enter your station's 9-digit MMSI if you want your reports attributed to a licensed station. |
+| `dscwatchUrl` | `https://dscwatch.com/api/v1/report` | Override for local testing only; the receiver key is appended automatically. |
+
+### What leaves the boat
+
+Each report contains only the call's parsed fields and raw sentence or PGN payload:
+`receivedAt`, `source`, `category`, `format`, `raw`, `mmsi`, `position`,
+`positionResolution`, `utcTime`, `natureOfDistress`, `distressedMmsi`,
+`workingChannel`, `acknowledgement`, `deviceBeacon`, and the boolean flags `relay`,
+`expansion`, `self`, `positionRefined` (only when `true`). The receiver's position
+at the moment the call arrived is added as `ownPosition` when the server has a fix.
+
+### What never leaves the boat
+
+The local-only fields — `ownShip` weather and sea-state snapshots, spoken message
+text, `repeats`, `lastReceivedAt`, `clearedAt`, and internal event IDs — are never
+sent.
+
+### Submission model
+
+Every radio reception — including DSC auto-repeats and every `$DSE` position
+refinement — is submitted as its own POST. The DSCWatch backend deduplicates repeated
+transmissions of the same call; sending each one lets the network track propagation
+and timing.
+
+Undelivered reports (connectivity loss, server restart during delivery) queue on disk
+at `dscwatch-queue.jsonl` in the plugin data directory and are retried when
+connectivity returns. An HTTP 404 response (receiver key unknown to the service, or a
+misconfigured `dscwatchUrl`) sets the plugin status once; subsequent reports are still
+attempted and dropped until the receiver key or endpoint URL is corrected — a fixed
+configuration heals automatically without a restart.
+
 ## Trying it without a radio
 
 ### Quick test script
@@ -212,6 +256,15 @@ 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.
 
+## See also
+
+DSC is the *alerting* signal — it tells you a vessel is in distress and roughly
+where. For *finding* the casualty, pair this with the companion
+[`@sailingnaturali/signalk-ais-distress`](https://github.com/sailingnaturali/signalk-ais-distress),
+which alarms on AIS survival beacons (SART / MOB / EPIRB) and gives you a
+position stream to home on. Both share the same 97x identity classes and build on
+[`@sailingnaturali/signalk-distress-core`](https://github.com/sailingnaturali/signalk-distress-core).
+
 ## License
 
 MIT

package/index.js

@@ -37,8 +37,13 @@ const {
   createNotifier,
   unwrap,
   writeLogbookEntry,
+  createReporter,
+  loadOrCreateReceiverKey,
 } = require('@sailingnaturali/signalk-distress-core');
 
+const { buildReport } = require('./lib/dscwatch');
+const { version } = require('./package.json');
+
 const DSC_PGN = 129808;
 const NOTIFICATION_STATES = { distress: 'emergency', urgency: 'alarm', safety: 'alert' };
 const DEDUPE_WINDOW_MS = 5 * 60 * 1000;
@@ -107,10 +112,31 @@ module.exports = function makePlugin(app) {
           },
         },
       },
+      dscwatchEnabled: {
+        type: 'boolean',
+        title: 'Report received calls to DSCWatch.com',
+        description:
+          'Opt-in: submit every received DSC call — including your receiver position — to the DSCWatch crowdsourced receiver network. Undelivered reports queue on disk and catch up when connectivity returns.',
+        default: false,
+      },
+      dscwatchReceiverKey: {
+        type: 'string',
+        title: 'DSCWatch receiver key',
+        description:
+          'Leave blank to use an auto-generated station UUID (persisted in the plugin data directory), or enter this station\'s 9-digit MMSI for attribution.',
+        default: '',
+      },
+      dscwatchUrl: {
+        type: 'string',
+        title: 'DSCWatch endpoint',
+        description: 'Base report URL; the receiver key is appended. Override for testing only.',
+        default: 'https://dscwatch.com/api/v1/report',
+      },
     },
   };
 
   let store = null;
+  let reporter = null;
   let options = {};
   let started = false;
   let reannounceTimer = null;
@@ -143,6 +169,14 @@ module.exports = function makePlugin(app) {
     };
   }
 
+  // Fire-behind submission to DSCWatch (crowdsourced DSC receiver network).
+  // Called before/independent of the store dedupe: the API wants every radio
+  // repeat and every DSE refinement as its own POST — the backend dedupes.
+  function reportToDscwatch(event, extra) {
+    if (!reporter) return;
+    reporter.report(buildReport({ ...event, ...extra }, { ownPosition: selfPosition() }));
+  }
+
   // Notification plumbing (raise/clear/reannounce) is shared with
   // signalk-ais-distress via signalk-distress-core. A non-alarming category
   // (routine/unknown, not in NOTIFICATION_STATES) makes raise a no-op.
@@ -203,6 +237,8 @@ module.exports = function makePlugin(app) {
     };
     if (event.mmsi && event.mmsi === selfMmsi()) event.self = true;
 
+    reportToDscwatch(event);
+
     // Re-transmission of the same call (distress alerts auto-repeat until
     // acknowledged): bump the stored call, do not re-alarm. This matches on
     // mmsi+category+nature and ignores `clearedAt`, so an operator-cleared call
@@ -313,6 +349,11 @@ module.exports = function makePlugin(app) {
 
       const refined = refinePosition(target.position, ext);
       store.update(target.id, { position: refined, positionResolution: 'enhanced' });
+      reportToDscwatch(target, {
+        receivedAt: new Date(now).toISOString(),
+        raw: input.sentence,
+        positionRefined: true,
+      });
       return {
         context: callerContext(target.category, ext.mmsi),
         updates: [{ values: [{ path: 'navigation.position', value: refined }] }],
@@ -340,6 +381,9 @@ module.exports = function makePlugin(app) {
       logbookRoutine: false,
       logbookUrl: 'http://localhost:3000/plugins/signalk-logbook/logs',
       logbookToken: '',
+      dscwatchEnabled: false,
+      dscwatchReceiverKey: '',
+      dscwatchUrl: 'https://dscwatch.com/api/v1/report',
       ...opts,
     };
 
@@ -348,6 +392,26 @@ module.exports = function makePlugin(app) {
       maxEvents: options.maxEvents,
     });
 
+    if (options.dscwatchEnabled) {
+      try {
+        const receiverKey =
+          options.dscwatchReceiverKey.trim() ||
+          loadOrCreateReceiverKey(path.join(app.getDataDirPath(), 'dscwatch-receiver-key'));
+        reporter = createReporter({
+          url: `${options.dscwatchUrl.replace(/\/+$/, '')}/${receiverKey}`,
+          userAgent: `signalk-dsc/${version}`,
+          queueFile: path.join(app.getDataDirPath(), 'dscwatch-queue.jsonl'),
+          log: (msg) => app.debug(msg),
+          onPermanentError: (status) =>
+            app.setPluginStatus(`DSCWatch: receiver key rejected (HTTP ${status}) — check configuration`),
+        });
+        reporter.start();
+      } catch (err) {
+        app.error(`signalk-dsc: DSCWatch reporting disabled: ${err.message}`);
+        reporter = null;
+      }
+    }
+
     app.registerResourceProvider({
       type: 'dsc-calls',
       methods: {
@@ -432,6 +496,10 @@ module.exports = function makePlugin(app) {
     started = false;
     clearTimeout(reannounceTimer);
     app.removeListener('N2KAnalyzerOut', onPgn);
+    if (reporter) {
+      reporter.stop();
+      reporter = null;
+    }
   };
 
   return plugin;

package/lib/dscwatch.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/*
+ * Map a normalized DSC event onto a DSCWatch report body
+ * (POST https://dscwatch.com/api/v1/report/<receiver-key>).
+ *
+ * Pure field-picker: send what we have, omit what we don't. The pick-list is
+ * also the privacy boundary — local-only fields (id, message, repeats,
+ * lastReceivedAt, ownShip, clearedAt) are never sent because they are never
+ * picked. Boolean flags go out only when true; parseDsc always materializes
+ * `expansion` as false and the API treats absence as false.
+ */
+
+const FIELDS = [
+  'receivedAt',
+  'source',
+  'category',
+  'format',
+  'raw',
+  'mmsi',
+  'position',
+  'positionResolution',
+  'utcTime',
+  'natureOfDistress',
+  'distressedMmsi',
+  'deviceBeacon',
+  'workingChannel',
+  'acknowledgement',
+];
+
+const FLAGS = ['relay', 'expansion', 'self', 'positionRefined'];
+
+function buildReport(event, { ownPosition } = {}) {
+  const body = {};
+  for (const key of FIELDS) {
+    if (event[key] !== undefined) body[key] = event[key];
+  }
+  for (const key of FLAGS) {
+    if (event[key] === true) body[key] = true;
+  }
+  if (!body.format) body.format = 'unknown';
+  if (ownPosition && typeof ownPosition.latitude === 'number') {
+    body.ownPosition = { latitude: ownPosition.latitude, longitude: ownPosition.longitude };
+  }
+  return body;
+}
+
+module.exports = { buildReport };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sailingnaturali/signalk-dsc",
-  "version": "0.5.6",
+  "version": "0.6.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": {
@@ -49,6 +49,6 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@sailingnaturali/signalk-distress-core": "^0.3.0"
+    "@sailingnaturali/signalk-distress-core": "^0.5.1"
   }
 }