node-red-contrib-ntrip 0.2.9 → 0.2.11

package/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [0.2.11]
+### Documentation
+- `examples/watchdog.json` now emits a `RECOVERED` message on the first data frame that arrives after a stall, in addition to the existing `STALLED` notification. Per-frame messages are still suppressed — you only see the two transitions.
+
+### Internal — adopted `node-red-standards` (no runtime behaviour change)
+- Migrated the test suite from `mocha` + `chai` to `node --test` + `node:assert` (still uses `node-red-node-test-helper`; specs renamed `*.spec.js` → `*.test.js`).
+- Added portable `AGENTS.md` as the tool-neutral rule source of truth; `CLAUDE.md` slimmed to a thin adapter.
+- Added `.github/workflows/standards-check.yml` — CI-side audit against `node-red-standards`.
+- Consolidated the previous tag-driven `release.yml` into `npm-publish.yml` (same behaviour, standard-conforming filename).
+- Bumped `engines.node` from `>=18.0.0` to `>=20.0.0`; CI/publish Node matrix trimmed to `20.x, 22.x` (Node 18 is EOL).
+- Refactored all node files to single-exit style — every function has exactly one `return` at its final position. Zero behavioural change; 20/20 tests still pass.
+
+## [0.2.10]
+### NtripClient
+- Reconnect attempts now use an exponential-ish backoff schedule (`1 s`, `2 s`, `5 s`, `10 s`, then capped at `10 s`) instead of the upstream library's fixed `2 s` interval. The schedule resets to `1 s` the moment the caster completes the `ICY 200 OK` handshake, so a brief outage restarts from the short end and a caster that stays down is no longer hammered.
+
+### Documentation
+- Added `examples/watchdog.json` — an example flow that alerts (via a built-in `trigger` node) when the NTRIP correction stream stops delivering data for more than 60 seconds. Closes [#4](https://github.com/windkh/node-red-contrib-ntrip/issues/4).
+
 ## [0.2.9]
 ### NtripClient
 - Status badge now shows the inbound data rate alongside the Rx/Tx message counters (e.g. `2.4 kbps Rx 123 Tx 4`). The rate is sampled once per second and formatted as `bps`, `kbps`, or `Mbps` depending on magnitude.

package/README.md

@@ -299,6 +299,11 @@ A few things that are easy to get wrong:
 - **NTRIP Client: CR/LF in credentials.** `mountpoint`, `username`, and
   `password` are interpolated into the handshake string. CR/LF in these fields
   is rejected at startup to prevent header injection.
+- **NTRIP Client: reconnect backoff.** When the socket to the caster drops the
+  client waits `1 s`, then `2 s`, `5 s`, `10 s` before each successive retry
+  (capped at `10 s`). The schedule resets to `1 s` as soon as the caster
+  completes the `ICY 200 OK` handshake again — so a brief outage restarts at
+  the low end, and a caster that stays down doesn't get hammered.
 - **NMEA Encoder input shape.** The encoder expects `msg.payload` to be an
   object with `messageType` and `nmeaMessage` properties — not a NMEA string.
   To re-encode the output of the NMEA Decoder you can pipe it straight in;
@@ -345,6 +350,18 @@ a local demo version of SNIP by creating a raw TCP input stream.
 (SNIP can be found here https://www.use-snip.com)
 See also example flow [**Upload flow**](examples/upload.json)
 
+## Detect a stalled correction stream
+NTRIP casters occasionally stop emitting data without closing the TCP socket
+— the NtripClient node stays "connected" but no new frames arrive, and any
+downstream rover eventually drops out of RTK-fixed mode without an obvious
+cause. This example wires the NtripClient output into a built-in `trigger`
+node configured to fire after 60 seconds of silence (configurable via the
+trigger's Duration field). A small `function` node then acts as a state
+tracker: it emits a **`STALLED`** notification when the trigger fires and a
+**`RECOVERED`** notification on the first data frame that arrives after a
+stall. Per-frame messages are suppressed — you only see the two transitions.
+See also example flow [**Watchdog flow**](examples/watchdog.json)  (closes [#4](https://github.com/windkh/node-red-contrib-ntrip/issues/4))
+
 # License
 
 Author: Karl-Heinz Wind

package/examples/watchdog.json

@@ -0,0 +1 @@
+[{"id":"47bd8463328d83d3","type":"comment","z":"a604108643639054","name":"NTRIP stream stall + recovery watchdog","info":"Emits a message when the NTRIP correction stream stops flowing\nAND when it starts flowing again — nothing else.\n\nHow it works:\n- Every message from the NTRIP Client resets the trigger node's timer.\n- If no message arrives within 60 seconds, the trigger fires; a change\n  node tags it with topic=stall and the state tracker function emits a\n  STALLED notification (once).\n- When data resumes, the state tracker sees the first data frame after\n  the stall and emits a RECOVERED notification (once).\n- While the stream is flowing normally, the state tracker suppresses\n  per-frame messages — you only see transitions.\n\nAdjust the timeout in the trigger node's Duration field.\n","x":260,"y":80,"wires":[]},{"id":"9f622b9ab6a72772","type":"NtripClient","z":"a604108643639054","description":"RTK2Go","passthrough":false,"port":"2101","host":"rtk2go.com","mountpoint":"Foo","interval":1000,"xcoordinate":"","ycoordinate":"","zcoordinate":"","x":140,"y":180,"wires":[["5107785e11b2425a","eb42f2cd60fcdc8f","1a2b3c4d5e6f7089"]]},{"id":"5107785e11b2425a","type":"debug","z":"a604108643639054","name":"data (each frame)","active":false,"tosidebar":true,"console":false,"tostatus":false,"complete":"false","statusVal":"","statusType":"auto","x":430,"y":140,"wires":[]},{"id":"eb42f2cd60fcdc8f","type":"trigger","z":"a604108643639054","name":"60s stall watchdog","op1":"","op2":"stall","op1type":"nul","op2type":"str","duration":"60","extend":true,"overrideDelay":false,"units":"s","reset":"","bytopic":"all","topic":"topic","outputs":1,"x":440,"y":220,"wires":[["ab12cd34ef567890"]]},{"id":"ab12cd34ef567890","type":"change","z":"a604108643639054","name":"topic=stall","rules":[{"t":"set","p":"topic","pt":"msg","to":"stall","tot":"str"}],"action":"","property":"","from":"","to":"","reg":false,"x":640,"y":220,"wires":[["1a2b3c4d5e6f7089"]]},{"id":"1a2b3c4d5e6f7089","type":"function","z":"a604108643639054","name":"state tracker","func":"if (msg.topic === 'stall') {\n    context.set('stalled', true);\n    msg.payload = 'STALLED — no data for 60 s';\n    return msg;\n}\n\n// Data frame from NtripClient — check whether we just recovered.\nif (context.get('stalled')) {\n    context.set('stalled', false);\n    msg.payload = 'RECOVERED — NTRIP stream is flowing again';\n    return msg;\n}\n\n// Stream is fine; no transition to report.\nreturn null;\n","outputs":1,"timeout":0,"noerr":0,"initialize":"","finalize":"","libs":[],"x":840,"y":260,"wires":[["25f028d01cad6b57"]]},{"id":"25f028d01cad6b57","type":"debug","z":"a604108643639054","name":"STATUS","active":true,"tosidebar":true,"console":false,"tostatus":true,"complete":"payload","targetType":"msg","statusVal":"payload","statusType":"auto","x":1020,"y":260,"wires":[]}]

package/ntrip/lib/ntrip-client.js

@@ -4,8 +4,43 @@
 const { NtripClient } = require('ntrip-client');
 const net = require('net');
 
+// Backoff schedule for reconnect attempts, in milliseconds. The upstream
+// client's default is a fixed 2000ms interval which flooded casters (and the
+// Node-RED error log) when a server was down for a while. See issue on repeated
+// error output during outages. The last entry acts as a cap for further retries.
+const RECONNECT_BACKOFF_MS = [1000, 2000, 5000, 10000];
+
+// Extends the upstream client with an exponential backoff on reconnect.
+// The schedule advances on each failed reconnect and resets to the first
+// entry as soon as the caster completes the handshake (`ICY 200 OK`).
+class NtripClientWithBackoff extends NtripClient {
+    constructor(options) {
+        super(options);
+        this._backoffIndex = 0;
+        this.reconnectInterval = RECONNECT_BACKOFF_MS[0];
+    }
+
+    _onData(data) {
+        const wasReady = this.isReady;
+        super._onData(data);
+        // Reset the backoff schedule the moment the handshake completes —
+        // subsequent connection failures start over at the first entry.
+        if (!wasReady && this.isReady) {
+            this._backoffIndex = 0;
+            this.reconnectInterval = RECONNECT_BACKOFF_MS[0];
+        }
+    }
+
+    async _reconnect() {
+        const step = Math.min(this._backoffIndex, RECONNECT_BACKOFF_MS.length - 1);
+        this.reconnectInterval = RECONNECT_BACKOFF_MS[step];
+        this._backoffIndex++;
+        return super._reconnect();
+    }
+}
+
 // Orginal class is extended to be able to send data to the caster.
-class NtripClientUploader extends NtripClient {
+class NtripClientUploader extends NtripClientWithBackoff {
     constructor(options) {
         super(options);
         this.authmode = options.authmode || 'legacy';
@@ -21,84 +56,82 @@ class NtripClientUploader extends NtripClient {
     }
 
     _connect() {
-        if (this.isClose) {
-            return;
+        if (!this.isClose) {
+            // init connection of client
+            this.client = net.createConnection({
+                host: this.host,
+                port: this.port,
+            });
+
+            // on timeout event
+            this.client.on('timeout', () => {
+                this._onError('socket timeout');
+            });
+
+            // on connect event
+            this.client.on('connect', () => {
+                const mountpoint = this.mountpoint;
+                const userAgent = this.userAgent;
+                const username = this.username;
+                const password = this.password;
+                const host = this.host;
+                const port = this.port;
+                const authmode = this.authmode;
+                const authorization = Buffer.from(username + ':' + password, 'utf8').toString('base64');
+
+                let data;
+                switch (authmode) {
+                    case 'legacy': // Legacy --> rtk2Go accepts this.
+                        if (username === '' && password === '') {
+                            data = `SOURCE ${mountpoint}\r\n\r\n`;
+                        } else {
+                            data = `SOURCE ${password} /${mountpoint}\r\nSource-Agent: NTRIP ${username}\r\n\r\n`;
+                        }
+                        break;
+                    case 'hybrid': // hybrid (legacy + http auth) --> SNIP accepts this.
+                        data = `SOURCE ${mountpoint}\r\nAuthorization: Basic ${authorization}\r\n\r\n`;
+                        break;
+                    case 'ntripv1': // NTRIP V1 POST
+                        data = `POST /${mountpoint} HTTP/1.0\r\nUser-Agent: NTRIP ${userAgent}\r\nAuthorization: Basic ${authorization}\r\nContent-Type: gnss/data\r\n\r\n`;
+                        break;
+                    case 'ntripv2': // NTRIP V2 POST
+                        data = `POST /${mountpoint} HTTP/1.1\r\nHost: ${host}:${port}\r\nUser-Agent: NTRIP ${userAgent}\r\nAuthorization: Basic ${authorization}\r\nNtrip-Version: Ntrip/2.0\r\nContent-Type: gnss/data\r\nConnection: keep-alive\r\n\r\n`;
+                        break;
+                    default:
+                        throw new Error('Auth mode is not supported ' + authmode);
+                }
+
+                this.client.write(data);
+            });
+
+            // on data event
+            this.client.on('data', (data) => {
+                this._onData(data);
+            });
+
+            // on end event
+            this.client.on('end', () => {
+                this._onError('socket ended');
+            });
+
+            // on close event
+            this.client.on('close', () => {
+                this._onError('socket closed');
+            });
+
+            // on error event
+            this.client.on('error', (err) => {
+                // TODO: check for code = ECONNREFUSED
+                this._onError(err);
+            });
+
+            this.client.setTimeout(this.timeout);
         }
-
-        // init connection of client
-        this.client = net.createConnection({
-            host: this.host,
-            port: this.port,
-        });
-
-        // on timeout event
-        this.client.on('timeout', () => {
-            this._onError('socket timeout');
-        });
-
-        // on connect event
-        this.client.on('connect', () => {
-            const mountpoint = this.mountpoint;
-            const userAgent = this.userAgent;
-            const username = this.username;
-            const password = this.password;
-            const host = this.host;
-            const port = this.port;
-            const authmode = this.authmode;
-            const authorization = Buffer.from(username + ':' + password, 'utf8').toString('base64');
-
-            let data;
-            switch (authmode) {
-                case 'legacy': // Legacy --> rtk2Go accepts this.
-                    if (username === '' && password === '') {
-                        data = `SOURCE ${mountpoint}\r\n\r\n`;
-                    } else {
-                        data = `SOURCE ${password} /${mountpoint}\r\nSource-Agent: NTRIP ${username}\r\n\r\n`;
-                    }
-                    break;
-                case 'hybrid': // hybrid (legacy + http auth) --> SNIP accepts this.
-                    data = `SOURCE ${mountpoint}\r\nAuthorization: Basic ${authorization}\r\n\r\n`;
-                    break;
-                case 'ntripv1': // NTRIP V1 POST
-                    data = `POST /${mountpoint} HTTP/1.0\r\nUser-Agent: NTRIP ${userAgent}\r\nAuthorization: Basic ${authorization}\r\nContent-Type: gnss/data\r\n\r\n`;
-                    break;
-                case 'ntripv2': // NTRIP V2 POST
-                    data = `POST /${mountpoint} HTTP/1.1\r\nHost: ${host}:${port}\r\nUser-Agent: NTRIP ${userAgent}\r\nAuthorization: Basic ${authorization}\r\nNtrip-Version: Ntrip/2.0\r\nContent-Type: gnss/data\r\nConnection: keep-alive\r\n\r\n`;
-                    break;
-                default:
-                    throw new Error('Auth mode is not supported ' + authmode);
-            }
-
-            this.client.write(data);
-        });
-
-        // on data event
-        this.client.on('data', (data) => {
-            this._onData(data);
-        });
-
-        // on end event
-        this.client.on('end', () => {
-            this._onError('socket ended');
-        });
-
-        // on close event
-        this.client.on('close', () => {
-            this._onError('socket closed');
-        });
-
-        // on error event
-        this.client.on('error', (err) => {
-            // TODO: check for code = ECONNREFUSED
-            this._onError(err);
-        });
-
-        this.client.setTimeout(this.timeout);
     }
 }
 
 function createDownloader(options) {
-    return new NtripClient(options);
+    return new NtripClientWithBackoff(options);
 }
 
 function createUploader(options) {

package/ntrip/nodes/nmea-decoder-node.js

@@ -49,49 +49,47 @@ module.exports = function (RED) {
         }
 
         this.on('input', function (msg) {
-            if (msg.payload === undefined || msg.payload === null) {
-                return;
-            }
+            if (msg.payload !== undefined && msg.payload !== null) {
+                // rawInput is the value the user provided (Buffer, string, ...).
+                // Keep it untouched so the error output can return it as-is.
+                let rawInput = typeof msg.payload === 'object' && msg.payload.nmeaMessage !== undefined ? msg.payload.nmeaMessage : msg.payload;
 
-            // rawInput is the value the user provided (Buffer, string, ...).
-            // Keep it untouched so the error output can return it as-is.
-            let rawInput = typeof msg.payload === 'object' && msg.payload.nmeaMessage !== undefined ? msg.payload.nmeaMessage : msg.payload;
+                let rawString;
+                if (Buffer.isBuffer(rawInput)) {
+                    rawString = rawInput.toString('utf8');
+                } else if (typeof rawInput === 'string') {
+                    rawString = rawInput;
+                }
 
-            let rawString;
-            if (Buffer.isBuffer(rawInput)) {
-                rawString = rawInput.toString('utf8');
-            } else if (typeof rawInput === 'string') {
-                rawString = rawInput;
-            } else {
-                node.send([
-                    null,
-                    {
-                        payload: {
-                            error: 'Payload is neither string nor Buffer',
-                            input: rawInput,
-                            inputString: String(rawInput),
+                if (rawString === undefined) {
+                    node.send([
+                        null,
+                        {
+                            payload: {
+                                error: 'Payload is neither string nor Buffer',
+                                input: rawInput,
+                                inputString: String(rawInput),
+                            },
                         },
-                    },
-                ]);
-                node.invalidMessagesReceived++;
-                updateStatus();
-                return;
-            }
+                    ]);
+                    node.invalidMessagesReceived++;
+                    updateStatus();
+                } else {
+                    // A single chunk may carry several sentences delimited by \r\n.
+                    let sentences = rawString.split(/\r?\n/);
+                    let any = false;
+                    for (let i = 0; i < sentences.length; i++) {
+                        let s = sentences[i].trim();
+                        if (s.length > 0) {
+                            decodeOne(s, rawInput, rawString);
+                            any = true;
+                        }
+                    }
 
-            // A single chunk may carry several sentences delimited by \r\n.
-            let sentences = rawString.split(/\r?\n/);
-            let any = false;
-            for (let i = 0; i < sentences.length; i++) {
-                let s = sentences[i].trim();
-                if (s.length === 0) {
-                    continue;
+                    if (any) {
+                        updateStatus();
+                    }
                 }
-                decodeOne(s, rawInput, rawString);
-                any = true;
-            }
-
-            if (any) {
-                updateStatus();
             }
         });
 

package/ntrip/nodes/nmea-encoder-node.js

@@ -39,14 +39,15 @@ module.exports = function (RED) {
         }
 
         function safeToString(value) {
-            if (value === undefined || value === null) {
-                return '';
-            }
-            try {
-                return String(value);
-            } catch {
-                return '';
+            let result = '';
+            if (value !== undefined && value !== null) {
+                try {
+                    result = String(value);
+                } catch {
+                    result = '';
+                }
             }
+            return result;
         }
 
         this.on('input', function (msg) {
@@ -63,102 +64,101 @@ module.exports = function (RED) {
                 node.send([null, errMsg]);
                 node.invalidMessagesReceived++;
                 updateStatus(false);
-                return;
-            }
-
-            let input = payload.nmeaMessage;
+            } else {
+                let input = payload.nmeaMessage;
 
-            try {
-                let messageType = String(payload.messageType).toUpperCase();
+                try {
+                    let messageType = String(payload.messageType).toUpperCase();
 
-                let nmeaMessage;
-                if (input instanceof NmeaMessage) {
-                    nmeaMessage = input;
-                } else {
-                    switch (messageType) {
-                        case 'OBJECT':
-                            nmeaMessage = NmeaMessageUnknown.construct(input);
-                            break;
-                        case 'DTM':
-                            nmeaMessage = NmeaMessageDtm.construct(input);
-                            break;
-                        case 'GBS':
-                            nmeaMessage = NmeaMessageGbs.construct(input);
-                            break;
-                        case 'GGA':
-                            nmeaMessage = NmeaMessageGga.construct(input);
-                            break;
-                        case 'GLL':
-                            nmeaMessage = NmeaMessageGll.construct(input);
-                            break;
-                        case 'GNS':
-                            nmeaMessage = NmeaMessageGns.construct(input);
-                            break;
-                        case 'GRS':
-                            nmeaMessage = NmeaMessageGrs.construct(input);
-                            break;
-                        case 'GSA':
-                            nmeaMessage = NmeaMessageGsa.construct(input);
-                            break;
-                        case 'GST':
-                            nmeaMessage = NmeaMessageGst.construct(input);
-                            break;
-                        case 'GSV':
-                            nmeaMessage = NmeaMessageGsv.construct(input);
-                            break;
-                        case 'RMC':
-                            nmeaMessage = NmeaMessageRmc.construct(input);
-                            break;
-                        case 'THS':
-                            nmeaMessage = NmeaMessageThs.construct(input);
-                            break;
-                        case 'TXT':
-                            nmeaMessage = NmeaMessageTxt.construct(input);
-                            break;
-                        case 'VHW':
-                            nmeaMessage = NmeaMessageVhw.construct(input);
-                            break;
-                        case 'VLW':
-                            nmeaMessage = NmeaMessageVlw.construct(input);
-                            break;
-                        case 'VPW':
-                            nmeaMessage = NmeaMessageVpw.construct(input);
-                            break;
-                        case 'VTG':
-                            nmeaMessage = NmeaMessageVtg.construct(input);
-                            break;
-                        case 'ZDA':
-                            nmeaMessage = NmeaMessageZda.construct(input);
-                            break;
-                        default:
-                            throw new Error('Unsupported NMEA message type: ' + messageType);
+                    let nmeaMessage;
+                    if (input instanceof NmeaMessage) {
+                        nmeaMessage = input;
+                    } else {
+                        switch (messageType) {
+                            case 'OBJECT':
+                                nmeaMessage = NmeaMessageUnknown.construct(input);
+                                break;
+                            case 'DTM':
+                                nmeaMessage = NmeaMessageDtm.construct(input);
+                                break;
+                            case 'GBS':
+                                nmeaMessage = NmeaMessageGbs.construct(input);
+                                break;
+                            case 'GGA':
+                                nmeaMessage = NmeaMessageGga.construct(input);
+                                break;
+                            case 'GLL':
+                                nmeaMessage = NmeaMessageGll.construct(input);
+                                break;
+                            case 'GNS':
+                                nmeaMessage = NmeaMessageGns.construct(input);
+                                break;
+                            case 'GRS':
+                                nmeaMessage = NmeaMessageGrs.construct(input);
+                                break;
+                            case 'GSA':
+                                nmeaMessage = NmeaMessageGsa.construct(input);
+                                break;
+                            case 'GST':
+                                nmeaMessage = NmeaMessageGst.construct(input);
+                                break;
+                            case 'GSV':
+                                nmeaMessage = NmeaMessageGsv.construct(input);
+                                break;
+                            case 'RMC':
+                                nmeaMessage = NmeaMessageRmc.construct(input);
+                                break;
+                            case 'THS':
+                                nmeaMessage = NmeaMessageThs.construct(input);
+                                break;
+                            case 'TXT':
+                                nmeaMessage = NmeaMessageTxt.construct(input);
+                                break;
+                            case 'VHW':
+                                nmeaMessage = NmeaMessageVhw.construct(input);
+                                break;
+                            case 'VLW':
+                                nmeaMessage = NmeaMessageVlw.construct(input);
+                                break;
+                            case 'VPW':
+                                nmeaMessage = NmeaMessageVpw.construct(input);
+                                break;
+                            case 'VTG':
+                                nmeaMessage = NmeaMessageVtg.construct(input);
+                                break;
+                            case 'ZDA':
+                                nmeaMessage = NmeaMessageZda.construct(input);
+                                break;
+                            default:
+                                throw new Error('Unsupported NMEA message type: ' + messageType);
+                        }
                     }
-                }
 
-                let message = NmeaTransport.encode(nmeaMessage);
+                    let message = NmeaTransport.encode(nmeaMessage);
 
-                let outMsg = {
-                    payload: {
-                        nmeaMessage: message,
-                        messageType: payload.messageType,
-                        input: input,
-                    },
-                };
+                    let outMsg = {
+                        payload: {
+                            nmeaMessage: message,
+                            messageType: payload.messageType,
+                            input: input,
+                        },
+                    };
 
-                node.send([outMsg, null]);
-                node.nmeaMessagesReceived++;
-                updateStatus(true);
-            } catch (ex) {
-                let errMsg = {
-                    payload: {
-                        error: ex,
-                        input: input,
-                        inputString: safeToString(input),
-                    },
-                };
-                node.send([null, errMsg]);
-                node.invalidMessagesReceived++;
-                updateStatus(false);
+                    node.send([outMsg, null]);
+                    node.nmeaMessagesReceived++;
+                    updateStatus(true);
+                } catch (ex) {
+                    let errMsg = {
+                        payload: {
+                            error: ex,
+                            input: input,
+                            inputString: safeToString(input),
+                        },
+                    };
+                    node.send([null, errMsg]);
+                    node.invalidMessagesReceived++;
+                    updateStatus(false);
+                }
             }
         });