node-red-contrib-ntrip 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [0.2.2]
+### Added documentation - [#3](https://github.com/windkh/node-red-contrib-ntrip/issues/3)
+
+## [0.2.1]
+### Added several auth modes for uploading data to the caster.
+###  added pass through mode - [#10](https://github.com/windkh/node-red-contrib-ntrip/issues/10)
+
 ## [0.2.0]
 ### Refactored nodes: data can be forwarded to NTRIP caster now.
 

package/README.md

@@ -10,15 +10,6 @@
 [![Closed Issues](https://img.shields.io/github/issues-closed-raw/windkh/node-red-contrib-ntrip.svg)](https://github.com/windkh/node-red-contrib-ntrip/issues?q=is%3Aissue+is%3Aclosed)
 ...
 
-This package contains nodes for connecting to a NTRIP server. 
-
-# Dependencies
-This package depends on the following libraries
-@gnss/nmea
-@gnss/rtcm
-ntrip-client
-
-
 # Thanks for your donation
 If you want to support this free project. Any help is welcome. You can donate by clicking one of the following links:
 
@@ -28,22 +19,162 @@ If you want to support this free project. Any help is welcome. You can donate by
 <a href="https://www.buymeacoffee.com/windka" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
 
 
+This package contains nodes for connecting to a NTRIP server. 
+
+# Installation
+[![NPM](https://nodei.co/npm/node-red-contrib-ntrip.png?downloads=true)](https://nodei.co/npm/node-red-contrib-ntrip/)
+
+You can install the nodes using node-red's "Manage palette" in the side bar.
+
+Or run the following command in the root directory of your Node-RED installation
+
+    npm install node-red-contrib-ntrip --save
+
+# Dependencies
+This package depends on the following libraries
+- [@gnss/nmea](https://github.com/node-ntrip/nmea)
+- [@gnss/rtcm](https://github.com/node-ntrip/rtcm)
+- [ntrip-client](https://github.com/dxhbiz/ntrip-client)
+
+
 # Credits
 
+# 👥 Contributors
+
+<p align="center">
+  <a href="https://github.com/windkh/node-red-contrib-ntrip/graphs/contributors">
+    <img src="https://contrib.rocks/image?repo=windkh/node-red-contrib-ntrip" />
+  </a>
+</p>
 
 # Changelog
 Changes can be followed [here](/CHANGELOG.md)
 
-
 # NTRIP Client Node
-...
-
+This node connects to a NTRIP caster and can be used in two different modes:
+- upload
+- download
+
+## Download Mode
+### Configuration
+For downloading data from a NTRIP caster you need to provide the following information
+- __host__ - the IP address or hostname of the NTRIP server (e.g. rtk2go.com)
+- __port__ - the Port number of the NTRIP server (usually this is 2101)
+- __mountpoint__ - the mountpoint of the stream data at the NTRIP server (enter name without /)
+
+Depending on the version of the NTRIP caster you need to provide
+- __username__ - the username (e.g. your e-mail address when using rtk2go.com)
+- __password__ - the password (e.g. none)
+
+Some NTRIP casters only send data after the client provided its location via a GGA sentence. 
+In this case you can provide the X Y Z coordinate here or inject it like illustrated in the example flow
+- __X__ - the X coordinate
+- __Y__ - the Y coordinate
+- __Z__ - the Z coordinate
+- __interval__ - the interval in milliseconds to transmit the location to the NTRIP server.
+
+### Provide Client Location (XYZ) to NTRIP caster
+If you want more control about sending your location to the NTRIP server, then you
+can inject the values as described in the following example:
+![Alt text](images/SetXYZFlow.png?raw=true "SetXYZ Flow")  
+
+The function node simply creates an array of X Y Z coordinates in msg.payload.
+Sapos NTRIP casters for example only needs one GGA sentence to initiate streaming.
+
+![Alt text](images/SetXYZFunctionNode.png?raw=true "SetXYZ Function Node")  
+See also example flow [**SetXYZ flow**](examples/sapos.json)  
+
+## Upload Mode
+### Configuration
+The configuation properties are the same as described for the download mode.
+You need to provide these additional properties:
+- __Authentication Mode__ - the mode the NTRIP caster accepts.
+- __Pass through data__ - if checked all data is sent to the output for further processing.
+
+### Authentication Modes
+#### Legacy
+This mode initiates the uploading to a mountpoint using plan text.
+```javascript
+SOURCE ${mountpoint}\r\n\r\n
+```
+or with password and unsername
+```javascript
+SOURCE ${password} /${mountpoint}\r\nSource-Agent: NTRIP ${username}\r\n\r\n
+```
+
+#### Legacy (Basic Auth)
+This hybrid mode initiates the uploading to a mountpoint using plan text and Basic Auth.
+```javascript
+SOURCE ${mountpoint}\r\nAuthorization: Basic ${authorization}\r\n\r\n
+```
+
+#### NTRIP V1
+This mode initiates the uploading to a mountpoint using HTTP with Basic Auth.
+```javascript
+POST /${mountpoint} HTTP/1.0\r\nUser-Agent: NTRIP ${userAgent}\r\nAuthorization: Basic ${authorization}\r\nContent-Type: gnss/data\r\n\r\n
+```
+
+#### NTRIP V2
+THis mode is equal to NTRIP V1 with some more data.
+```javascript
+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
+```
 
 # RTCM Decoder Node
-
+This node accepts binary RTCM data. The node accepts either a single or multiple RTCN messages.
+The converted messages are sent one by one to the output in the following format.
+```javascript
+msg.payload = 
+{
+    rtcm, // RTCm message number
+    messageType, // a string indicating a readyble RTCM message name
+    message, // a structure containing all decoded data
+    input, // the raw input message
+};
+```
 
 # NMEA Decoder Node
-
+This node accepts binary NMEA data. The node accepts either a single or multiple NMEA messages.
+The converted messages are sent one by one to the output in the following format.
+```javascript
+msg.payload = 
+{
+    messageType, // a string indicating a readyble RTCM message name
+    message, // a structure containing all decoded data
+    input, // the raw input message
+};
+```
+
+# Examples 
+Examples are stored in the examples folder an can be imported from within node-red's sidebar via import.
+
+## Download data from NTRIP caster
+Consuming Data is straight forward. Connect to a NTRIP caster, select download mode and
+pass the data to other nodes for further processing: in this example 2 decoder are used.
+The NMEA node is only to show that the stream can be split.
+(It is useless as RTK2Go does not send any NMEA strings)
+See also example flow [**RTK2Go flow**](examples/ntripclient.json)  
+
+## Provide XYZ dato to NTRIP caster 
+This example is the same as the RTK2Go one except for the fact that Sapos requires sending a GGA sentence 
+before transmitting RTCM sentences.
+See also example flow [**Sapos flow**](examples/sapos.json)  
+
+## Consume data from TCP source (RTKBase)
+Next to retrieving data from a remote NTRIP caster you can also consume the RTCM stream from a local
+TCP source like a RTKBase Station (e.g. https://github.com/Stefal/rtkbase).
+You can upload the data to any NTRIP caster like Onocoy, Centipede, RTKOnline, ... and use the same data
+on your own. To accomplish this you can use node-red's TCP receiver node. 
+You need to activate a TCP server either on your ESP32 XBee or RTKBase.
+See also example flow [**TCP flow**](examples/tcp.json)  
+
+## Upload data to NTRIP caster
+Uploading is straight forward, however authentication might be tricky.
+You need to know the mountpoint and credentials before you can initiat an upload.
+Not all NTRIP casters accept the same way of authentication. You can test with 
+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)
 
 # License
 

package/ntrip/99-ntrip.html

@@ -9,6 +9,9 @@
         defaults: {
 			description: { value:"" },
             mode: { value: "download", required: true },
+            authmode: { value: "legacy", required: true },
+            passthrough: { value: false, required: false },
+           
             port: { value: 2101, required: false, validate:function(v) { return ((v === "") || (RED.validators.number(v) && (v >= 0) && (v <= 65535))) }},
             host: { value:"" },
             mountpoint: { value:"" },
@@ -36,11 +39,11 @@
             var updateMode = function() {
                 var mode = $("#node-input-mode").val();
                 if (mode == "download") {
-                    //$("#coordinates").show();
+                    $("#uploadoptions").hide();
                 } else if (mode == "upload"){
-                    //$("#coordinates").hide();
+                    $("#uploadoptions").show();
                 } else {
-                    //$("#coordinates").hide();
+                    $("#uploadoptions").hide();
                 }
             };
             updateMode();
@@ -70,6 +73,23 @@
         </select>
     </div>
 
+    <div class="form-row" id="uploadoptions" style="background: var(--red-ui-tertiary-background)">    
+        <div class="form-row">
+            <label for="node-input-authmode"><i class="fa fa-id-card-o"></i> Authentication Mode</label>
+            <select id="node-input-authmode" style="width:70%">
+                <option value="legacy">Legacy (Plain Text)</option>
+                <option value="hybrid">Legacy (Basic Auth)</option>
+                <option value="ntripv1">NTRIP V1</option>
+                <option value="ntripv2">NTRIP V2</option>
+            </select>
+        </div>
+
+        <div class="form-row">
+            <label for="node-input-passthrough"><i class="fa fa-long-arrow-right"></i> Pass through data to output.</label>
+            <input type="checkbox" id="node-input-passthrough" style="display: inline-block; width: auto; vertical-align: top;">
+        </div>
+    </div>
+
     <hr align="middle"/>
 
     <div class="form-row">
@@ -90,12 +110,6 @@
         <label for="node-input-password"><i class="fa fa-key"></i> Password</label>
         <input type="text" id="node-input-password" placeholder="Enter the password here)">
     </div>
-
-    <div class="form-row">
-        <label for="node-input-interval"><i class="fa fa-comment"></i> Interval (ms)</label>
-        <input type="text" id="node-input-interval" placeholder="The interval in milliseconds or 0">
-    </div> 
-
     
     <hr align="middle"/>
 
@@ -103,18 +117,23 @@
         <label style="width: auto"><i class="fa fa-crosshairs"></i> Optional location (if set a NMEA GGA sentence is sent to the server)</label>
         
         <div class="form-row">
-            <label for="node-input-x"> X</label>
-            <input type="text" id="node-input-x" placeholder="The X position or 0 (optional)">
+            <label for="node-input-xcoordinate"> X</label>
+            <input type="text" id="node-input-xcoordinate" placeholder="The X position or 0 (optional)">
         </div> 
 
         <div class="form-row">
-            <label for="node-input-y"> Y</label>
-            <input type="text" id="node-input-y" placeholder="The Y position or 0 (optional)">
+            <label for="node-input-ycoordinate"> Y</label>
+            <input type="text" id="node-input-ycoordinate" placeholder="The Y position or 0 (optional)">
         </div> 
 
         <div class="form-row">
-            <label for="node-input-z"> Z</label>
-            <input type="text" id="node-input-z" placeholder="The Z position or 0 (optional)">
+            <label for="node-input-zcoordinate"> Z</label>
+            <input type="text" id="node-input-zcoordinate" placeholder="The Z position or 0 (optional)">
+        </div> 
+           
+        <div class="form-row">
+            <label for="node-input-interval"><i class="fa fa-comment"></i> Interval (ms)</label>
+            <input type="text" id="node-input-interval" placeholder="The interval in milliseconds or 0">
         </div> 
     </div>
 

package/ntrip/lib/ntrip-client.js

@@ -8,6 +8,7 @@ const net = require('net');
 class NtripClientUploader extends NtripClient {
     constructor(options) {  
         super(options);
+        this.authmode = options.authmode || 'legacy';
     }
 
     _connect() {
@@ -29,20 +30,38 @@ class NtripClientUploader extends NtripClient {
         // 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;
-            if (this.username === '' && this.password === '') {
-                data = `SOURCE ${mountpoint}\r\n\r\n`;
-            }
-            else {
-                const authorization = Buffer.from(
-                    username + ':' + password,
-                    'utf8'
-                ).toString('base64');
-            
-                data = `SOURCE ${mountpoint}\r\nAuthorization: Basic ${authorization}\r\n\r\n`;            
+            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);

package/ntrip/nodes/ntrip-client-node.js

@@ -3,16 +3,20 @@ module.exports = function (RED) {
 
     const NtripClient = require("../lib/ntrip-client.js");
     const NtripServerOkReply = 'ICY 200 OK';
+    const NtripServerNotOkReply = 'ICY 406';
     const NtripServerMissingMountpoint = 'SOURCETABLE 200 OK';
 
     function NtripClientNode(config) {
         RED.nodes.createNode(this, config);
         let node = this;
         node.messagesReceived = 0;
+        node.passthrough = config.passthrough || false;
+        
         let host = config.host;
         let port = config.port || 2101;
         let mountpoint = config.mountpoint;
-        let mode = config.mode || "download";
+        let mode = config.mode || 'download';
+        let authmode = config.authmode || 'legacy';
         
         let client;
         if(host !== undefined ) {
@@ -27,13 +31,11 @@ module.exports = function (RED) {
             };
 
             // Depending on the caster the clients need to provide the location via GGA sentence.
-            let x = config.xcoordinate;
-            let y = config.ycoordinate;
-            let z = config.zcoordinate;
+            let x = parseFloat(config.xcoordinate || 0);
+            let y = parseFloat(config.ycoordinate || 0);
+            let z = parseFloat(config.zcoordinate || 0);
             
-            if (x !== undefined && x !== 0 &&
-                y !== undefined && y !== 0 &&
-                z !== undefined && z !== 0) {
+            if (x !== 0 && y !== 0 && z !== 0) {
                 options.xyz = [x, y, z];
             }
             
@@ -43,6 +45,7 @@ module.exports = function (RED) {
             }
             else  if (mode === 'upload') {
                 // Uploaders send RTCM data to a mountpoint so that clients can consume it.
+                options.authmode = authmode;
                 client = NtripClient.createUploader(options);
             }
             else {
@@ -69,6 +72,15 @@ module.exports = function (RED) {
                         shape: 'ring',
                         text: 'NTRIP server connected.',
                     }); 
+                }
+                // check if ICY 406 Not Acceptable
+                else if (response.startsWith(NtripServerNotOkReply)) {
+                    node.status({
+                        fill: 'red',
+                        shape: 'ring',
+                        text: 'NTRIP server rejected connection.',
+                    }); 
+                    node.error('Server rejected connect: ' + response); 
                 } 
                 else if (response.startsWith(NtripServerMissingMountpoint)) {
                     node.status({
@@ -108,6 +120,13 @@ module.exports = function (RED) {
 
             this.on('input', async function (msg) {
                 if (msg.payload) {
+                    node.messagesReceived++;
+                    node.status({
+                        fill: 'green',
+                        shape: 'ring',
+                        text: 'Messages ' + node.messagesReceived,
+                    });
+
                     try {
                         let data = msg.payload;
                         if (Array.isArray(data)) {
@@ -115,8 +134,11 @@ module.exports = function (RED) {
                         } 
                         else {
                             client.write(data);
-                        }
 
+                            if(node.passthrough) {
+                                node.send(msg);
+                            }
+                        }
                     } catch (error) {
                         node.status({ fill: 'red', shape: 'ring', text: error });
                         node.error('Failed to write data: ' + error, error);

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

@@ -27,8 +27,7 @@ module.exports = function (RED) {
                             rtcm : message.messageType,
                             messageType : messageType,
                             message : message,
-                            input : buffer,
-                            length : length
+                            input : buffer
                         }
                     };
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-red-contrib-ntrip",
-    "version": "0.2.0",
+    "version": "0.2.2",
     "description": "Node for ntrip and rtcm handling.",
     "node-red": {
         "version": ">=0.1.0",
@@ -15,7 +15,8 @@
         "node-red",
         "rtcm",
         "ntrip",
-        "gnss"
+        "gnss",
+        "mmea"
     ],
     "repository": {
         "type": "git",