@sailingnaturali/signalk-dsc 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,88 @@
+# signalk-dsc
+
+SignalK plugin that receives, logs, and alerts on **DSC** (VHF digital selective
+calling) traffic — distress, urgency, safety, and routine calls — from both
+**NMEA 0183** (`$--DSC`/`$--DSE`) and **NMEA 2000** (PGN 129808).
+
+## Why
+
+When a vessel hits the red button, its radio broadcasts a DSC burst on channel 70
+with MMSI, position, and nature of distress — perfectly readable even when the
+follow-up voice call on 16 is not. Stock SignalK mostly drops this data: the 0183
+hook misses common sentence variants and persists nothing, and the N2K converter
+has **no** PGN 129808 mapping at all. If you might be the nearest boat, you want
+every received alert stored with its position and surfaced as an alarm — that is
+this plugin.
+
+## What you get
+
+For every DSC call heard by a connected radio:
+
+- **A persistent call log** — JSONL on disk, served at
+  `GET /signalk/v2/api/resources/dsc-calls` (anonymously readable when the server
+  allows read-only access). Raw sentence/PGN is always kept alongside the parsed
+  fields: time, MMSI, category, nature of distress, position, UTC time.
+- **Alarms under your own vessel** — `notifications.dsc.distress` (state
+  `emergency`), `notifications.dsc.urgency` (`alarm`), `notifications.dsc.safety`
+  (`alert`). Routine calls never alarm. Repeated re-transmissions of the same
+  alert (DSC auto-repeats until acknowledged) update the stored call instead of
+  re-alarming. Alerts received within the last hour are **re-raised after a
+  server restart** — notifications are in-memory, and a received MAYDAY must
+  not vanish because the server bounced.
+- **A voice-sized message** — the notification message is deliberately minimal
+  (type, vessel, situation, range and direction from own position, action):
+  > DSC distress alert: vessel Wind Chaser, sinking, 2.3 nautical miles
+  > northwest. Monitor channel 16.
+
+  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.
+- **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.
+
+## Transports
+
+- **NMEA 0183**: registers custom `DSC` and `DSE` sentence parsers (these replace
+  the server's stock DSC hook with a superset: tolerant of sparse distress alerts
+  some radios emit — see [nmea0183-signalk#217](https://github.com/SignalK/nmea0183-signalk/issues/217)
+  — and with `DSE` position refinement from ±1 NM to ten-thousandths of a minute,
+  which the stock parser ignores entirely).
+- **NMEA 2000**: listens to the server's analyzer stream (`N2KAnalyzerOut`) for
+  PGN 129808, since `n2k-signalk` produces no delta for it.
+
+## Configuration
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `maxEvents` | `1000` | Oldest calls dropped beyond this. |
+| `logbookEnabled` | `true` | Requires signalk-logbook and a token. |
+| `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). |
+
+## Trying it without a radio
+
+Feed sentences through any NMEA 0183 connection (TCP, UDP, file playback):
+
+```
+$CDDSC,12,3380400790,12,05,00,1423108312,2019,,,S,E*69
+$CDDSE,1,1,A,3380400790,00,45894494*1B
+```
+
+…then `GET /signalk/v2/api/resources/dsc-calls`.
+
+## Limitations
+
+- Distress relays, acknowledgements, and cancellations are stored (with
+  `acknowledgement`/`distressedMmsi` fields) but don't yet clear or transform the
+  original alarm.
+- Multi-sentence `DSE` groups are ignored (single-sentence covers Class-D gear).
+- A raised distress notification stays active until cleared from the server —
+  deliberate: a received MAYDAY should not silently expire.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,364 @@
+'use strict';
+
+/*
+ * signalk-dsc
+ *
+ * Receive, log, and alert on DSC (VHF digital selective calling) calls.
+ *
+ * A DSC-equipped radio that hears traffic on channel 70 re-emits it digitally:
+ * as $--DSC/$--DSE sentences on NMEA 0183, or as PGN 129808 on NMEA 2000.
+ * SignalK's stock pipeline handles neither well — the 0183 hook drops sparse
+ * sentences and persists nothing, and n2k-signalk has no 129808 mapping at all.
+ *
+ * This plugin listens on both transports and, for every call received:
+ *   - appends it to an on-disk JSONL log (forensics: raw input always kept)
+ *   - serves the call history at /signalk/v2/api/resources/dsc-calls
+ *     (anonymously readable under allow_readonly)
+ *   - raises notifications.dsc.<category> under *self* — distress → emergency,
+ *     urgency → alarm, safety → alert — so the vessel's own alarm chain fires
+ *   - optionally writes a GMDSS-style radio-log entry via signalk-logbook
+ *
+ * Distress alerts repeat every few minutes until acknowledged; repeats inside
+ * a 5-minute window update the stored call instead of re-alarming.
+ */
+
+const path = require('node:path');
+
+const { parseDsc } = require('./lib/dsc');
+const { parseDse, refinePosition } = require('./lib/dse');
+const { normalizePgn129808 } = require('./lib/pgn129808');
+const { EventStore } = require('./lib/store');
+const { buildMessage, buildLogbookText } = require('./lib/format');
+
+const DSC_PGN = 129808;
+const NOTIFICATION_STATES = { distress: 'emergency', urgency: 'alarm', safety: 'alert' };
+const DEDUPE_WINDOW_MS = 5 * 60 * 1000;
+const DSE_PAIR_WINDOW_MS = 2 * 60 * 1000;
+// Notifications are in-memory on the server: a restart silently drops an
+// active alarm. On start, re-raise any alert this recent.
+const REANNOUNCE_WINDOW_MS = 60 * 60 * 1000;
+
+module.exports = function makePlugin(app) {
+  const plugin = {
+    id: 'signalk-dsc',
+    name: 'DSC call logger',
+    description:
+      'Receive, log, and alert on DSC (VHF digital selective calling) calls from NMEA 0183 ($CDDSC/$CDDSE) and NMEA 2000 (PGN 129808).',
+  };
+
+  plugin.schema = {
+    type: 'object',
+    properties: {
+      maxEvents: {
+        type: 'number',
+        title: 'Calls to keep',
+        description: 'Oldest calls are dropped beyond this count.',
+        default: 1000,
+      },
+      logbookEnabled: {
+        type: 'boolean',
+        title: 'Write received calls to the ship\'s log (signalk-logbook)',
+        default: true,
+      },
+      logbookRoutine: {
+        type: 'boolean',
+        title: 'Also log routine calls',
+        description: 'By default only distress/urgency/safety traffic is logged, GMDSS-style.',
+        default: false,
+      },
+      logbookUrl: {
+        type: 'string',
+        title: 'Logbook API URL',
+        default: 'http://localhost:3000/plugins/signalk-logbook/logs',
+      },
+      logbookToken: {
+        type: 'string',
+        title: 'SignalK access token for logbook writes',
+        description: 'Plugin routes are auth-gated; without a token the logbook write is skipped.',
+        default: '',
+      },
+    },
+  };
+
+  let store = null;
+  let options = {};
+  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;
+  }
+
+  function selfPosition() {
+    const value = unwrap(app.getSelfPath('navigation.position'));
+    return value && typeof value.latitude === 'number' ? value : undefined;
+  }
+
+  /** Vessel name from the data model (AIS static data), if we have heard it. */
+  function vesselName(mmsi) {
+    if (!mmsi || typeof app.getPath !== 'function') return undefined;
+    try {
+      const value = unwrap(app.getPath(`vessels.urn:mrn:imo:mmsi:${mmsi}.name`));
+      return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  function messageContext(event) {
+    return {
+      ownPosition: selfPosition(),
+      vesselName: vesselName(event.distressedMmsi || event.mmsi),
+    };
+  }
+
+  function notify(event) {
+    const state = NOTIFICATION_STATES[event.category];
+    if (!state) return;
+    app.handleMessage(plugin.id, {
+      updates: [
+        {
+          values: [
+            {
+              path: `notifications.dsc.${event.category}`,
+              value: {
+                state,
+                method: ['visual', 'sound'],
+                // Kept terse on purpose: this string gets spoken by the
+                // voice pipeline. Full detail lives in the resource store
+                // and the logbook entry.
+                message: buildMessage(event, messageContext(event)),
+                timestamp: event.receivedAt,
+              },
+            },
+          ],
+        },
+      ],
+    });
+  }
+
+  function shouldLogbook(event) {
+    if (options.logbookEnabled === false) return false;
+    if (!options.logbookToken) return false;
+    if (event.category === 'routine' || event.category === 'unknown') {
+      return Boolean(options.logbookRoutine);
+    }
+    return true;
+  }
+
+  async function postLogbook(event) {
+    const res = await fetch(options.logbookUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        // signalk-server's auth gate reads the Authorization header; the
+        // logbook plugin reads the author from the JAUTHENTICATION cookie.
+        Authorization: `Bearer ${options.logbookToken}`,
+        Cookie: `JAUTHENTICATION=${options.logbookToken}`,
+      },
+      body: JSON.stringify({ text: buildLogbookText(event, messageContext(event)), ago: 0 }),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  }
+
+  /** Store a normalized call, alarm on it, and log it. Returns the stored event. */
+  function record(parsed, { source, raw, receivedAt }) {
+    const event = {
+      receivedAt: receivedAt || new Date().toISOString(),
+      source,
+      raw,
+      ...parsed,
+    };
+    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.
+    const duplicate = store.findRecent(
+      (e) =>
+        e.mmsi === event.mmsi &&
+        e.category === event.category &&
+        e.natureOfDistress === event.natureOfDistress,
+      Date.parse(event.receivedAt),
+      DEDUPE_WINDOW_MS
+    );
+    if (duplicate) {
+      store.update(duplicate.id, {
+        repeats: (duplicate.repeats || 0) + 1,
+        lastReceivedAt: event.receivedAt,
+      });
+      return duplicate;
+    }
+
+    store.add(event);
+    notify(event);
+    if (shouldLogbook(event)) {
+      postLogbook(event).catch((err) =>
+        app.error(`signalk-dsc: logbook write failed: ${err.message}`)
+      );
+    }
+    if (typeof app.setPluginStatus === 'function') {
+      app.setPluginStatus(
+        `${event.category} call from MMSI ${event.mmsi || 'unknown'} at ${event.receivedAt}`
+      );
+    }
+    return event;
+  }
+
+  function remoteContext(mmsi) {
+    return `vessels.urn:mrn:imo:mmsi:${mmsi}`;
+  }
+
+  // Custom sentence parsers override the stock hooks (a superset of the
+  // upstream DSC hook's behavior, plus DSE support it lacks).
+  function dscParser(input) {
+    if (!started) return null;
+    try {
+      const parsed = parseDsc(input.parts);
+      if (!parsed) return null;
+      if (parsed.position) parsed.positionResolution = 'minute';
+
+      const event = record(parsed, {
+        source: 'nmea0183',
+        raw: input.sentence,
+        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.
+      if (parsed.mmsi) {
+        const values = [];
+        if (parsed.position) {
+          values.push({ path: 'navigation.position', value: parsed.position });
+        }
+        if (parsed.category === 'distress') {
+          values.push({
+            path: `notifications.${parsed.natureOfDistress}`,
+            value: {
+              state: 'emergency',
+              method: ['visual', 'sound'],
+              message: buildMessage(event, messageContext(event)),
+            },
+          });
+        }
+        if (values.length) {
+          return { context: remoteContext(parsed.mmsi), updates: [{ values }] };
+        }
+      }
+    } catch (err) {
+      app.error(`signalk-dsc: DSC parse failed: ${err.message}`);
+    }
+    return null;
+  }
+
+  function dseParser(input) {
+    if (!started) return null;
+    try {
+      const ext = parseDse(input.parts);
+      if (!ext) return null;
+      const now = (input.tags && Date.parse(input.tags.timestamp)) || Date.now();
+      const target = store.findRecent(
+        (e) => e.mmsi === ext.mmsi && e.position && e.positionResolution === 'minute',
+        now,
+        DSE_PAIR_WINDOW_MS
+      );
+      if (!target) return null;
+
+      const refined = refinePosition(target.position, ext);
+      store.update(target.id, { position: refined, positionResolution: 'enhanced' });
+      return {
+        context: remoteContext(ext.mmsi),
+        updates: [{ values: [{ path: 'navigation.position', value: refined }] }],
+      };
+    } catch (err) {
+      app.error(`signalk-dsc: DSE parse failed: ${err.message}`);
+    }
+    return null;
+  }
+
+  function onPgn(pgnData) {
+    if (!started || !pgnData || pgnData.pgn !== DSC_PGN) return;
+    try {
+      record(normalizePgn129808(pgnData), { source: 'n2k', raw: pgnData.fields });
+    } catch (err) {
+      app.error(`signalk-dsc: PGN 129808 handling failed: ${err.message}`);
+    }
+  }
+
+  plugin.start = function (opts) {
+    options = {
+      maxEvents: 1000,
+      logbookEnabled: true,
+      logbookRoutine: false,
+      logbookUrl: 'http://localhost:3000/plugins/signalk-logbook/logs',
+      logbookToken: '',
+      ...opts,
+    };
+
+    store = new EventStore({
+      filePath: path.join(app.getDataDirPath(), 'dsc-calls.jsonl'),
+      maxEvents: options.maxEvents,
+    });
+
+    app.registerResourceProvider({
+      type: 'dsc-calls',
+      methods: {
+        async listResources() {
+          const out = {};
+          for (const event of store.list()) out[event.id] = event;
+          return out;
+        },
+        async getResource(id) {
+          const event = store.get(id);
+          if (!event) throw new Error(`No such DSC call: ${id}`);
+          return event;
+        },
+        setResource() {
+          throw new Error('dsc-calls is read-only');
+        },
+        deleteResource() {
+          throw new Error('dsc-calls is read-only');
+        },
+      },
+    });
+
+    app.emitPropertyValue('nmea0183sentenceParser', { sentence: 'DSC', parser: dscParser });
+    app.emitPropertyValue('nmea0183sentenceParser', { sentence: 'DSE', parser: dseParser });
+    app.on('N2KAnalyzerOut', onPgn);
+
+    started = true;
+
+    // Survive server restarts mid-incident: re-raise the newest alert per
+    // category that is still fresh (a received MAYDAY must not vanish just
+    // because the server bounced). Delayed so position providers are up and
+    // the spoken message can say "N miles <direction>" instead of raw
+    // coordinates.
+    reannounceTimer = setTimeout(() => {
+      if (!started) return;
+      const now = Date.now();
+      const reannounced = new Set();
+      const events = store.list();
+      for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (!NOTIFICATION_STATES[event.category] || reannounced.has(event.category)) continue;
+        const at = Date.parse(event.lastReceivedAt || event.receivedAt);
+        if (now - at <= REANNOUNCE_WINDOW_MS) {
+          notify(event);
+          reannounced.add(event.category);
+        }
+      }
+    }, options.reannounceDelayMs ?? 30000);
+  };
+
+  plugin.stop = function () {
+    started = false;
+    clearTimeout(reannounceTimer);
+    app.removeListener('N2KAnalyzerOut', onPgn);
+  };
+
+  return plugin;
+};

package/lib/dsc.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/*
+ * $--DSC sentence parsing (ITU-R M.493 datagram as flattened by NMEA 0183).
+ *
+ * Field reference: http://continuouswave.com/whaler/reference/DSC_Datagrams.html
+ *
+ *        0  1          2  3  4  5          6    7 8 9 10
+ *        |  |          |  |  |  |          |    | | | |
+ * $--DSC,XX,XXXXXXXXXX,XX,XX,XX,XXXXXXXXXX,XXXX,,,A,C*hh
+ *
+ *  0: format specifier (ITU symbol minus the leading 1: 12 = 112 distress alert)
+ *  1: address — MMSI * 10 (trailing zero). Distress alert: vessel in distress.
+ *  2: category (00 routine / 08 safety / 10 urgency / 12 distress)
+ *  3: nature of distress, or 1st telecommand for non-distress calls
+ *  4: subsequent comms / 2nd telecommand
+ *  5: position (quadrant + ddmm + dddmm, truncated toward zero) or channel/number
+ *  6: UTC time hhmm (8888 = unavailable)
+ *  7: MMSI of vessel in distress (relays/acknowledgements/cancellations)
+ *  8: nature of distress (relays)
+ *  9: acknowledgement (R/B/S)
+ * 10: expansion flag — 'E' means a $--DSE sentence follows
+ */
+
+const FORMATS = {
+  '02': 'area',
+  '12': 'distressAlert',
+  '14': 'group',
+  '16': 'allShips',
+  '20': 'individual',
+  '23': 'autoService',
+};
+
+const CATEGORIES = {
+  '00': 'routine',
+  '08': 'safety',
+  '10': 'urgency',
+  '12': 'distress',
+};
+
+const NATURES = {
+  '00': 'fire',
+  '01': 'flooding',
+  '02': 'collision',
+  '03': 'grounding',
+  '04': 'listing',
+  '05': 'sinking',
+  '06': 'adrift',
+  '07': 'undesignated',
+  '08': 'abandon',
+  '09': 'piracy',
+  '10': 'mob',
+  '12': 'epirb',
+};
+
+// Telecommand 21 on a non-distress call = "ship position" — field 5 holds a position.
+const TELECOMMAND_SHIP_POSITION = '21';
+
+function field(parts, i) {
+  const v = parts[i];
+  return typeof v === 'string' ? v.trim() : '';
+}
+
+function parseMmsi(raw) {
+  if (typeof raw !== 'string') return undefined;
+  const digits = raw.trim();
+  if (!/^\d{9,10}$/.test(digits)) return undefined;
+  // DSC sentences carry the MMSI with a trailing zero (MMSI * 10).
+  return digits.length === 10 ? digits.substring(0, 9) : digits;
+}
+
+function parsePosition(raw) {
+  if (typeof raw !== 'string' || !/^\d{10}$/.test(raw)) return undefined;
+  if (raw === '9999999999') return undefined; // "position not available"
+  const quadrant = Number(raw[0]); // 0 NE, 1 NW, 2 SE, 3 SW
+  if (quadrant > 3) return undefined;
+  let latitude = Number(raw.substring(1, 3)) + Number(raw.substring(3, 5)) / 60;
+  let longitude = Number(raw.substring(5, 8)) + Number(raw.substring(8, 10)) / 60;
+  if (quadrant === 1 || quadrant === 3) longitude = -longitude;
+  if (quadrant === 2 || quadrant === 3) latitude = -latitude;
+  return { latitude, longitude };
+}
+
+function parseUtcTime(raw) {
+  if (typeof raw !== 'string' || !/^\d{4}$/.test(raw.trim())) return undefined;
+  const t = raw.trim();
+  if (t === '8888') return undefined; // "time not available"
+  return `${t.substring(0, 2)}:${t.substring(2, 4)}`;
+}
+
+/**
+ * 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
+ * cannot interpret stays undefined and the caller keeps the raw sentence.
+ * Returns null only when there is nothing usable at all.
+ */
+function parseDsc(parts) {
+  if (!Array.isArray(parts) || parts.length < 2) return null;
+
+  const formatCode = field(parts, 0);
+  let categoryCode = field(parts, 2);
+  // Some radios omit the category on distress alerts — it is implied by
+  // format 112 (see SignalK/nmea0183-signalk#217).
+  if (!categoryCode && formatCode === '12') categoryCode = '12';
+
+  const event = {
+    format: FORMATS[formatCode] || 'unknown',
+    category: CATEGORIES[categoryCode] || 'unknown',
+    mmsi: parseMmsi(parts[1]),
+  };
+
+  const distress = event.category === 'distress';
+  if (distress) {
+    const natureCode = field(parts, 3);
+    event.natureOfDistress =
+      NATURES[natureCode] || (natureCode ? `code-${natureCode}` : 'undesignated');
+    event.distressedMmsi = parseMmsi(parts[7]);
+  }
+
+  if (distress || field(parts, 3) === TELECOMMAND_SHIP_POSITION) {
+    event.position = parsePosition(field(parts, 5));
+    event.utcTime = parseUtcTime(field(parts, 6));
+  }
+
+  const ack = field(parts, 9);
+  if (ack) event.acknowledgement = ack;
+  event.expansion = field(parts, 10) === 'E';
+
+  return event;
+}
+
+module.exports = { parseDsc, parsePosition, parseMmsi, parseUtcTime, NATURES };

package/lib/dse.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/*
+ * $--DSE sentence parsing — the expansion that can follow a $--DSC sentence,
+ * refining its position from whole minutes to ten-thousandths of a minute.
+ *
+ *        0 1 2 3          4  5
+ * $--DSE,t,n,A,XXXXXXXXXX,00,llllyyyy*hh
+ *
+ *  0: total sentences in this group
+ *  1: sentence number
+ *  2: query flag ('A' = automatic/unsolicited)
+ *  3: address — MMSI * 10, same convention as DSC
+ *  4+: repeated (code, data) pairs; code 00 = enhanced position resolution,
+ *      data = 4 digits lat + 4 digits lon, in 1/10000 of a minute
+ */
+
+const { parseMmsi } = require('./dsc');
+
+const CODE_ENHANCED_POSITION = '00';
+
+/**
+ * Returns { mmsi, latMinuteFraction, lonMinuteFraction } for single-sentence
+ * DSE groups carrying a position extension, else null.
+ */
+function parseDse(parts) {
+  if (!Array.isArray(parts) || parts.length < 6) return null;
+  // Multi-sentence groups are vanishingly rare on Class-D gear; skip them.
+  if (parts[0].trim() !== '1' || parts[1].trim() !== '1') return null;
+
+  const mmsi = parseMmsi(parts[3]);
+  if (!mmsi) return null;
+
+  for (let i = 4; i + 1 < parts.length; i += 2) {
+    const code = (parts[i] || '').trim();
+    const data = (parts[i + 1] || '').trim();
+    if (code === CODE_ENHANCED_POSITION && /^\d{8}$/.test(data)) {
+      return {
+        mmsi,
+        latMinuteFraction: Number(data.substring(0, 4)) / 10000,
+        lonMinuteFraction: Number(data.substring(4, 8)) / 10000,
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Apply a DSE extension to a DSC position. DSC truncates coordinates toward
+ * zero, so the fractional minutes always extend the magnitude (sign-preserving).
+ */
+function refinePosition(position, ext) {
+  const extend = (value, minuteFraction) => {
+    const sign = value < 0 ? -1 : 1;
+    return sign * (Math.abs(value) + minuteFraction / 60);
+  };
+  return {
+    latitude: extend(position.latitude, ext.latMinuteFraction),
+    longitude: extend(position.longitude, ext.lonMinuteFraction),
+  };
+}
+
+module.exports = { parseDse, refinePosition };

package/lib/format.js

@@ -0,0 +1,94 @@
+'use strict';
+
+/*
+ * Two renderings of a DSC event:
+ *
+ * - buildMessage: the notification message. This ends up SPOKEN by the voice
+ *   pipeline, so it is deliberately minimal — type, vessel, situation, range
+ *   and direction from us, action. Nothing else.
+ * - buildLogbookText: the ship's-log entry — full detail (MMSI, coordinates,
+ *   reported time, transport), GMDSS radio-log style.
+ */
+
+const { distanceNm, bearingDegrees, compassWord } = require('./geo');
+
+const NATURE_TEXT = {
+  fire: 'fire and explosion',
+  flooding: 'flooding',
+  collision: 'collision',
+  grounding: 'grounding',
+  listing: 'listing, in danger of capsize',
+  sinking: 'sinking',
+  adrift: 'disabled and adrift',
+  undesignated: 'undesignated distress',
+  abandon: 'abandoning ship',
+  piracy: 'piracy attack',
+  mob: 'man overboard',
+  epirb: 'EPIRB emission',
+};
+
+function formatCoordinate(value, axis) {
+  const hemisphere = axis === 'lat' ? (value < 0 ? 'S' : 'N') : value < 0 ? 'W' : 'E';
+  const abs = Math.abs(value);
+  const degrees = Math.floor(abs);
+  const minutes = (abs - degrees) * 60;
+  return `${degrees}°${minutes.toFixed(3)}′${hemisphere}`;
+}
+
+function formatPosition(position) {
+  return `${formatCoordinate(position.latitude, 'lat')} ${formatCoordinate(position.longitude, 'lon')}`;
+}
+
+// Spoken form. No MMSI fallback here on purpose: TTS reads 366123456 as
+// "three hundred sixty-six million...". The MMSI stays in the call log and
+// the logbook entry.
+function vesselPhrase(event, vesselName) {
+  return vesselName ? `vessel ${vesselName}` : 'unidentified vessel';
+}
+
+/** "2.3 nautical miles northwest" | "position 48°47.700′N ..." | "position unknown" */
+function wherePhrase(event, ownPosition, { spoken }) {
+  if (event.position && ownPosition) {
+    const range = distanceNm(ownPosition, event.position);
+    const direction = compassWord(bearingDegrees(ownPosition, event.position));
+    const unit = spoken ? 'nautical miles' : 'NM';
+    const suffix = spoken ? '' : ' of us';
+    return `${range.toFixed(1)} ${unit} ${direction}${suffix}`;
+  }
+  if (event.position) return `position ${formatPosition(event.position)}`;
+  return 'position unknown';
+}
+
+function buildMessage(event, { ownPosition, vesselName } = {}) {
+  const who = vesselPhrase(event, vesselName);
+  const where = wherePhrase(event, ownPosition, { spoken: true });
+  if (event.category === 'distress') {
+    const nature = NATURE_TEXT[event.natureOfDistress] || event.natureOfDistress || 'undesignated distress';
+    return `DSC distress alert: ${who}, ${nature}, ${where}. Monitor channel 16.`;
+  }
+  const kind = event.category === 'unknown' ? 'call' : `${event.category} call`;
+  return `DSC ${kind}: ${who}, ${where}.`;
+}
+
+function buildLogbookText(event, { ownPosition, vesselName } = {}) {
+  const parts = [];
+  const name = vesselName ? `${vesselName} (MMSI ${event.mmsi || 'unknown'})` : `MMSI ${event.mmsi || 'unknown'}`;
+  if (event.category === 'distress') {
+    const nature = NATURE_TEXT[event.natureOfDistress] || event.natureOfDistress || 'undesignated distress';
+    parts.push(`DISTRESS alert from ${name}: ${nature}`);
+  } else {
+    parts.push(`${event.category} call from ${name}`);
+  }
+  if (event.position) {
+    let pos = `position ${formatPosition(event.position)}`;
+    if (event.utcTime) pos += ` at ${event.utcTime} UTC`;
+    if (ownPosition) pos += `, ${wherePhrase(event, ownPosition, { spoken: false })}`;
+    parts.push(pos);
+  } else if (event.utcTime) {
+    parts.push(`reported at ${event.utcTime} UTC`);
+  }
+  if (event.source) parts.push(`via ${event.source}`);
+  return `[DSC] ${parts.join('. ')}`;
+}
+
+module.exports = { buildMessage, buildLogbookText, formatPosition };

package/lib/geo.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/* Range and bearing from own ship to a reported position, for voice alerts. */
+
+const EARTH_RADIUS_NM = 3440.065;
+
+function toRad(deg) {
+  return (deg * Math.PI) / 180;
+}
+
+function distanceNm(from, to) {
+  const dLat = toRad(to.latitude - from.latitude);
+  const dLon = toRad(to.longitude - from.longitude);
+  const a =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRad(from.latitude)) * Math.cos(toRad(to.latitude)) * Math.sin(dLon / 2) ** 2;
+  return 2 * Math.asin(Math.sqrt(a)) * EARTH_RADIUS_NM;
+}
+
+function bearingDegrees(from, to) {
+  const phi1 = toRad(from.latitude);
+  const phi2 = toRad(to.latitude);
+  const dLon = toRad(to.longitude - from.longitude);
+  const y = Math.sin(dLon) * Math.cos(phi2);
+  const x =
+    Math.cos(phi1) * Math.sin(phi2) - Math.sin(phi1) * Math.cos(phi2) * Math.cos(dLon);
+  return ((Math.atan2(y, x) * 180) / Math.PI + 360) % 360;
+}
+
+const COMPASS_WORDS = [
+  'north',
+  'northeast',
+  'east',
+  'southeast',
+  'south',
+  'southwest',
+  'west',
+  'northwest',
+];
+
+function compassWord(bearing) {
+  return COMPASS_WORDS[Math.round(((bearing % 360) + 360) % 360 / 45) % 8];
+}
+
+module.exports = { distanceNm, bearingDegrees, compassWord };

package/lib/pgn129808.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/*
+ * NMEA 2000 PGN 129808 "DSC (Distress) Call Information" → canonical DSC event.
+ *
+ * canboatjs (useCamelCompat) resolves lookups to their names; the distress
+ * variant uses dscFormat/dscCategory/natureOfDistress, the general variant
+ * dscFormatSymbol/dscCategorySymbol. When a lookup cannot be resolved the raw
+ * ITU symbol number (1xx) comes through instead — handle both.
+ */
+
+// Lookup-name → canonical (lowercased keys); ITU symbols as numeric fallback.
+const FORMATS = new Map([
+  ['geographical area', 'area'],
+  ['distress', 'distressAlert'],
+  ['common interest', 'group'],
+  ['group call', 'group'],
+  ['all ships', 'allShips'],
+  ['individual stations', 'individual'],
+  ['individual station automatic', 'autoService'],
+  [102, 'area'],
+  [112, 'distressAlert'],
+  [114, 'group'],
+  [116, 'allShips'],
+  [120, 'individual'],
+  [123, 'autoService'],
+]);
+
+const CATEGORIES = new Map([
+  ['routine', 'routine'],
+  ['safety', 'safety'],
+  ['urgency', 'urgency'],
+  ['distress', 'distress'],
+  [100, 'routine'],
+  [108, 'safety'],
+  [110, 'urgency'],
+  [112, 'distress'],
+]);
+
+const NATURES = new Map([
+  ['fire, explosion', 'fire'],
+  ['flooding', 'flooding'],
+  ['collision', 'collision'],
+  ['grounding', 'grounding'],
+  ['listing, in danger of capsizing', 'listing'],
+  ['sinking', 'sinking'],
+  ['disabled and adrift', 'adrift'],
+  ['undesignated distress', 'undesignated'],
+  ['abandoning ship', 'abandon'],
+  ['piracy/armed robbery attack', 'piracy'],
+  ['man overboard', 'mob'],
+  ['epirb emission', 'epirb'],
+  [0, 'fire'],
+  [1, 'flooding'],
+  [2, 'collision'],
+  [3, 'grounding'],
+  [4, 'listing'],
+  [5, 'sinking'],
+  [6, 'adrift'],
+  [7, 'undesignated'],
+  [8, 'abandon'],
+  [9, 'piracy'],
+  [10, 'mob'],
+  [12, 'epirb'],
+]);
+
+function lookup(map, value) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'string') {
+    const hit = map.get(value.trim().toLowerCase());
+    if (hit) return hit;
+    const asNumber = Number(value);
+    if (!Number.isNaN(asNumber)) return map.get(asNumber);
+    return undefined;
+  }
+  return map.get(value);
+}
+
+function normalizeMmsi(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const digits = String(value).trim();
+  if (!/^\d{1,9}$/.test(digits)) return undefined;
+  if (Number(digits) === 0) return undefined;
+  return digits.padStart(9, '0');
+}
+
+function normalizeTime(value) {
+  if (typeof value === 'string') {
+    const m = value.match(/^(\d{2}):(\d{2})/);
+    if (m) return `${m[1]}:${m[2]}`;
+    return undefined;
+  }
+  if (typeof value === 'number' && value >= 0 && value < 86400) {
+    // Seconds since midnight.
+    const h = String(Math.floor(value / 3600)).padStart(2, '0');
+    const min = String(Math.floor((value % 3600) / 60)).padStart(2, '0');
+    return `${h}:${min}`;
+  }
+  return undefined;
+}
+
+/** Normalize a canboatjs-parsed PGN 129808 object into a canonical DSC event. */
+function normalizePgn129808(pgnData) {
+  const f = (pgnData && pgnData.fields) || {};
+
+  const event = {
+    format: lookup(FORMATS, f.dscFormat ?? f.dscFormatSymbol) || 'unknown',
+    category: lookup(CATEGORIES, f.dscCategory ?? f.dscCategorySymbol) || 'unknown',
+    mmsi: normalizeMmsi(f.dscMessageAddress),
+  };
+
+  if (event.category === 'distress') {
+    const nature = f.natureOfDistress ?? f['1stTelecommand'];
+    event.natureOfDistress = lookup(NATURES, nature) || 'undesignated';
+  }
+
+  const lat = f.latitudeOfVesselReported;
+  const lon = f.longitudeOfVesselReported;
+  if (typeof lat === 'number' && typeof lon === 'number') {
+    event.position = { latitude: lat, longitude: lon };
+  }
+
+  const time = normalizeTime(f.timeOfPosition);
+  if (time) event.utcTime = time;
+
+  const distressed = normalizeMmsi(f.mmsiOfShipInDistress);
+  if (distressed) event.distressedMmsi = distressed;
+
+  return event;
+}
+
+module.exports = { normalizePgn129808 };

package/lib/store.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/*
+ * Append-only JSONL store for received DSC calls. DSC traffic is rare (a busy
+ * day in range of a coast station might see dozens of calls), so synchronous
+ * I/O and full-file compaction are entirely adequate — and the simplest thing
+ * that survives a power cut mid-write (a torn last line is skipped on load).
+ */
+class EventStore {
+  constructor({ filePath, maxEvents = 1000 }) {
+    this.filePath = filePath;
+    this.maxEvents = maxEvents;
+    this.events = [];
+    this._load();
+  }
+
+  _load() {
+    let raw;
+    try {
+      raw = fs.readFileSync(this.filePath, 'utf8');
+    } catch {
+      return; // no log yet
+    }
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        this.events.push(JSON.parse(line));
+      } catch {
+        // torn/corrupt line — skip it, keep the rest
+      }
+    }
+    if (this.events.length > this.maxEvents) {
+      this.events = this.events.slice(-this.maxEvents);
+      this._compact();
+    }
+  }
+
+  _compact() {
+    const tmp = `${this.filePath}.tmp`;
+    fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+    fs.writeFileSync(tmp, this.events.map((e) => JSON.stringify(e)).join('\n') + '\n');
+    fs.renameSync(tmp, this.filePath);
+  }
+
+  add(event) {
+    if (!event.id) {
+      event.id = `${event.receivedAt || new Date().toISOString()}-${event.mmsi || 'unknown'}`;
+    }
+    this.events.push(event);
+    if (this.events.length > this.maxEvents) {
+      this.events = this.events.slice(-this.maxEvents);
+      this._compact();
+    } else {
+      fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+      fs.appendFileSync(this.filePath, JSON.stringify(event) + '\n');
+    }
+    return event;
+  }
+
+  update(id, patch) {
+    const event = this.get(id);
+    if (!event) return undefined;
+    Object.assign(event, patch);
+    this._compact();
+    return event;
+  }
+
+  list() {
+    return this.events;
+  }
+
+  get(id) {
+    return this.events.find((e) => e.id === id);
+  }
+
+  /** Newest event matching `predicate` received within `windowMs` of `nowMs`. */
+  findRecent(predicate, nowMs, windowMs) {
+    for (let i = this.events.length - 1; i >= 0; i--) {
+      const e = this.events[i];
+      const age = nowMs - Date.parse(e.receivedAt);
+      if (age > windowMs) return undefined;
+      if (age >= 0 && predicate(e)) return e;
+    }
+    return undefined;
+  }
+}
+
+module.exports = { EventStore };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@sailingnaturali/signalk-dsc",
+  "version": "0.1.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"
+  },
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-category-utility",
+    "dsc",
+    "gmdss",
+    "vhf",
+    "distress",
+    "marine"
+  ],
+  "author": "Bryan Clark",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sailingnaturali/signalk-dsc.git"
+  },
+  "homepage": "https://github.com/sailingnaturali/signalk-dsc#readme",
+  "bugs": {
+    "url": "https://github.com/sailingnaturali/signalk-dsc/issues"
+  },
+  "files": [
+    "index.js",
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}