@sailingrotevista/rotevista-dash 6.1.2 → 6.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sailing Rotevista
+
+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,90 @@
+# @sailingrotevista/rotevista-dash
+
+## Sailing Dashboard Pro (v6.0)
+
+A tactical marine dashboard and advanced monitoring system for sailboats, designed to run as a Web App (PWA) fully integrated into the **Signal K** ecosystem. Specifically optimized for precision rendering on boat tablets (such as iPads and Samsung Galaxy Tab Active) and built to run efficiently on low-resource gateways like the **Victron Cerbo GX** (running Venus OS Large) or Raspberry Pi.
+
+---
+
+## Core Features
+
+### 📈 Server-Side RAM-Buffered History
+Unlike traditional dashboards that store history in the volatile memory of the client browser (wiping it whenever the screen locks or the browser reloads), this dashboard performs continuous background logging in RAM directly within the Signal K server process. Upon startup, the client instantly loads up to 60 minutes of pre-populated history via a fast JSON API endpoint, ensuring fully drawn, stable charts from the very first second the page is opened.
+
+### 🔋 Extreme Low-Power Architecture (Battery Saver)
+Engineered for long-range cruising without overheating your mobile devices or draining the boat's house batteries:
+*   **Event-Driven SVG Redraw:** Complex SVG chart elements are not redrawn on a blind timer. Instead, they are redrawn *only* when a new historical data point is appended to the buffer (reducing the browser's active SVG layout and paint cycles by **93%**).
+*   **Virtual-DOM Text Protection (`safeSetText`):** Digital text readouts are updated only if their numerical value has actually changed since the previous second, bypassing expensive browser style and layout calculations (*reflow/repaint*).
+*   **Zero-Overhead Analog Needles:** Pointers (AWA, TWA, Leeway) snap instantly to their new positions at 1Hz instead of forcing continuous 60fps style interpolations, allowing the tablet's GPU to rest in a low-power idle state.
+
+### 🧭 Weather Compass & True Wind Direction (TWD) Trends
+*   **Tactical Trend (Short-term):** Instantly detects lift or header shifts by comparing the 2-second moving average of True Wind Angle (TWA) with the 10-second average.
+*   **Strategic Trend (Long-term):** Flashing green (CW) and red (CCW) dots on the TWD mini-compass indicate meteorological wind rotations, comparing the last 1 minute of wind with a stable strategic baseline of **15 minutes** under sail or **60 minutes** at anchor.
+*   **Absolute UTC Epoch Snapping:** Time windows on both the server and any connected clients are locked to absolute UTC second boundaries (00, 10, 20, 30, 40, 50). This eliminates phase offsets and ensures identical tactical trends across all devices on the boat.
+
+### 🛡️ Shallow Water Alarms & Geometric Safety Lines
+*   Automatically draws high-visibility dashed safety lines across the depth chart background to indicate **Warning (Yellow, e.g. 3.5m)** and **Danger (Red, e.g. 2.5m)** thresholds.
+*   **Non-Scaling Vector Effects:** By using `vector-effect="non-scaling-stroke"`, these lines and the active depth curve remain perfectly sharp, thin, and professional regardless of whether the widget is small or zoomed to full screen.
+*   **Adaptive 0-Baseline:** In shallow water, the chart minimum is locked to 0 for keel safety; in deep water, the scale floats freely (e.g., 98m to 102m) to reveal the fine contour details of the seabed.
+
+### 🔌 Smart Source Locking (Zero-Config)
+An intelligent background algorithm assigns priority scores to active hardware sources on your boat (e.g. Yacht Devices N2K GPS vs a generic USB GPS) and locks onto the highest-quality sensor, switching to a backup only if a signal dropout occurs.
+
+### ⏰ Sleep & Power-Save Watchdog
+Detects when the tablet is unlocked or the browser wakes up a tab from *Power Save* mode, automatically closing orphaned WebSockets, reconnecting, and downloading the latest server-logged history in milliseconds to resume fluid, gap-free operation.
+
+### 🎮 Smart Local Development Auto-Detection
+The dashboard automatically detects if it is running locally on your Mac/PC via the `file://` protocol or on `localhost`. In this mode, it still connects to your boat's Cerbo GX over Wi-Fi to stream real-time data, but **bypasses the server's configuration, preserving your local `CONFIG` edits** so you can test scales, alarms, and steps instantly.
+
+---
+
+## System Requirements
+
+*   **Server:** Signal K Node Server (v1.20.0 or higher) installed on a Victron Cerbo GX, Raspberry Pi, or onboard PC.
+*   **Client:** Any modern PWA-compliant browser supporting ES6 (Safari on iPadOS/iOS, Samsung Internet, Chrome on Android, Chrome/Safari on macOS/Windows).
+
+---
+
+## Signal K Data Requirements
+
+### Required Foundational Paths
+To derive, calculate, and display the entire suite of tactical data, the dashboard must receive the following raw paths from your boat's NMEA network:
+
+*   `navigation.speedThroughWater` (STW - Speed through water)
+*   `navigation.speedOverGround` (SOG - Speed over ground)
+*   `navigation.courseOverGroundTrue` (COG - Course over ground)
+*   `navigation.headingTrue` (True Heading - *If missing, the system automatically falls back to Magnetic Heading*)
+*   `environment.wind.speedApparent` (AWS - Apparent wind speed)
+*   `environment.wind.angleApparent` (AWA - Apparent wind angle)
+*   `environment.depth.belowTransducer` (Depth below keel/transducer)
+*   `navigation.position` (GPS Latitude and Longitude - used for hemisphere detection and CSV logging)
+
+### Optional / Native Fallback Paths (Surgically Supported)
+The dashboard operates on a **"Native First, Fallback Second"** architecture. If any of the following calculated paths are transmitted natively by your boat's instruments, the dashboard will utilize them directly to preserve their calibration. If they are missing, the system silently activates its own local vector formulas:
+
+*   `environment.wind.speedTrue` (**Optional** - Native True Wind Speed in m/s; falls back to local calculation if missing)
+*   `environment.wind.directionTrue` (**Optional** - Native True Wind Direction in radians; falls back to local calculation if missing)
+*   `navigation.headingMagnetic` (**Optional** - Magnetic Heading; automatically used if True Heading is missing on the network)
+*   `navigation.magneticVariation` (**Optional** - Magnetic Variation; used to calibrate the Magnetic Heading fallback to True)
+
+---
+
+## Installation
+
+The dashboard is distributed as a standard Signal K Node Server plugin and Web App.
+
+### Installation via Signal K App Store (Recommended)
+1. Access your Signal K admin panel (`http://<boat-ip>:3000`).
+2. Navigate to **App Store** -> **Available**.
+3. Search for `@sailingrotevista/rotevista-dash` and click **Install**.
+4. Go to **Plugins Config**, activate the **Rotevista Dash Configuration** plugin, and configure your boat's safety thresholds (Draft, alarm offsets, and strategic chart timelines).
+5. Click **Save**. The Signal K server will restart, apply the configurations, and initiate background history logging in RAM.
+
+### Accessing the Dashboard
+Once installed, the dashboard is accessible on your local network by typing into your tablet or computer browser:
+```text
+http://<boat-ip>:3000/@sailingrotevista/rotevista-dash/
+For the best experience in the cockpit, tap your browser's share button and select "Add to Home Screen" to run it as a standalone, distraction-free application.
+
+License
+This project is licensed under the MIT License - see the LICENSE file for details.

package/app.js

@@ -317,34 +317,61 @@ function updateLeewayDisplay(deg) {
     ui.leewayVal.textContent = `LEEWAY: ${deg.toFixed(1)}°`;
 }
 
-// ==========================================================================
-// 5. MOTORE DI CALCOLO VENTO E DATA ROUTING
-// ==========================================================================
+/**
+ * computeTrueWind: Calcola TWS, TWA e TWD strategico.
+ * Gestisce il fallback separato (Split-Fallback) in caso di dati parzialmente nativi di bordo.
+ */
 function computeTrueWind() {
     const aws = store.raw["environment.wind.speedApparent"], awa = store.raw["environment.wind.angleApparent"];
     const stw = store.raw["navigation.speedThroughWater"] || 0, sog = store.raw["navigation.speedOverGround"] || 0;
     const hdg = store.raw["navigation.headingTrue"] || 0, cog = store.raw["navigation.courseOverGroundTrue"] || 0;
     if (aws === undefined || awa === undefined) return;
 
-    const tw_water_x = aws * Math.cos(awa) - stw, tw_water_y = aws * Math.sin(awa);
-    const tws_water = Math.sqrt(tw_water_x * tw_water_x + tw_water_y * tw_water_y);
-
-    const drift = (cog - hdg + Math.PI * 3) % (2 * Math.PI) - Math.PI;
-    const tw_ground_x = aws * Math.cos(awa) - sog * Math.cos(drift), tw_ground_y = aws * Math.sin(awa) - sog * Math.sin(drift);
-    const tws_ground = Math.sqrt(tw_ground_x * tw_ground_x + tw_ground_y * tw_ground_y);
-
     // Usiamo il tempo esatto di arrivo del pacchetto del vento per la coerenza dei buffer
     const now = store.timestamps["environment.wind.speedApparent"] || Date.now();
-    store.raw["environment.wind.speedTrue"] = tws_water;
-    if (tws_water > 0.05) {
-        const twa = Math.atan2(tw_water_y, tw_water_x);
-        store.raw["environment.wind.angleTrueWater"] = twa;
-        safePush(store.smoothBuf.twa, twa, now); safePush(store.longBuf.twa, twa, now);
+
+    // ==========================================================================
+    // 1. GESTIONE TWS (NATIVO vs FALLBACK)
+    // ==========================================================================
+    const hasNativeTws = store.timestamps["environment.wind.speedTrue"] && (Date.now() - store.timestamps["environment.wind.speedTrue"] < 5000);
+    let tws_water = 0;
+
+    if (hasNativeTws) {
+        // Se la barca invia il TWS nativo, usiamo direttamente quello
+        tws_water = store.raw["environment.wind.speedTrue"] ? msToKts(store.raw["environment.wind.speedTrue"]) : 0;
+    } else {
+        // Altrimenti eseguiamo il calcolo vettoriale tattico sull'acqua
+        tws_water = Math.sqrt(aws * aws + stw * stw - 2 * aws * stw * Math.cos(awa));
+        store.raw["environment.wind.speedTrue"] = tws_water;
+        
+        if (tws_water > 0.05) {
+            const twa = Math.atan2(aws * Math.sin(awa), aws * Math.cos(awa) - stw);
+            store.raw["environment.wind.angleTrueWater"] = twa;
+            safePush(store.smoothBuf.twa, twa, now);
+            safePush(store.longBuf.twa, twa, now);
+        }
     }
-    if (tws_ground > 0.05) {
-        let twd = (hdg + Math.atan2(tw_ground_y, tw_ground_x) + 2 * Math.PI) % (2 * Math.PI);
-        store.raw["environment.wind.directionTrue"] = twd;
-        safePush(store.smoothBuf.twd, twd, now); safePush(store.longBuf.twd, twd, now);
+
+    // ==========================================================================
+    // 2. GESTIONE TWD (NATIVO vs FALLBACK)
+    // ==========================================================================
+    const hasNativeTwd = store.timestamps["environment.wind.directionTrue"] && (Date.now() - store.timestamps["environment.wind.directionTrue"] < 5000);
+
+    if (hasNativeTwd) {
+        // Se il TWD è nativo della centralina, lo lasciamo scorrere passivamente
+    } else {
+        // Altrimenti calcoliamo lo scarroccio e ricaviamo il TWD geografico sul fondo
+        const drift = (cog - hdg + Math.PI * 3) % (2 * Math.PI) - Math.PI;
+        const tw_ground_x = aws * Math.cos(awa) - sog * Math.cos(drift);
+        const tw_ground_y = aws * Math.sin(awa) - sog * Math.sin(drift);
+        const tws_ground = Math.sqrt(tw_ground_x * tw_ground_x + tw_ground_y * tw_ground_y);
+
+        if (tws_ground > 0.05) {
+            let twd = (hdg + Math.atan2(tw_ground_y, tw_ground_x) + 2 * Math.PI) % (2 * Math.PI);
+            store.raw["environment.wind.directionTrue"] = twd;
+            safePush(store.smoothBuf.twd, twd, now);
+            safePush(store.longBuf.twd, twd, now); // Alimenta la bussola meteo strategica!
+        }
     }
 }
 
@@ -414,10 +441,26 @@ function processIncomingData(path, val, source, timeMs) {
         safePush(store.smoothBuf.awa, val, now);
         safePush(store.longBuf.awa, val, now);
     }
+    
+    // --- GESTIONE PRUA VERA / MAGNETICA CON AUTODIVIAZIONE ---
     if (path === "navigation.headingTrue") {
         safePush(store.smoothBuf.hdg, val, now);
         safePush(store.longBuf.hdg, val, now);
     }
+    else if (path === "navigation.headingMagnetic") {
+        // Se non abbiamo ricevuto una prua vera negli ultimi 5 secondi, convertiamo quella magnetica!
+        const hasTrueHdg = store.timestamps["navigation.headingTrue"] && (now - store.timestamps["navigation.headingTrue"] < 5000);
+        if (!hasTrueHdg) {
+            const variation = store.raw["navigation.magneticVariation"] || 0; // Legge la declinazione magnetica del GPS
+            const calculatedTrueHdg = (val + variation + 2 * Math.PI) % (2 * Math.PI);
+            
+            // Registriamo il valore calcolato come Prua Vera temporanea
+            store.raw["navigation.headingTrue"] = calculatedTrueHdg;
+            safePush(store.smoothBuf.hdg, calculatedTrueHdg, now);
+            safePush(store.longBuf.hdg, calculatedTrueHdg, now);
+        }
+    }
+    
     if (path === "navigation.courseOverGroundTrue") {
         safePush(store.smoothBuf.cog, val, now);
         safePush(store.longBuf.cog, val, now);

package/index.js

@@ -21,6 +21,9 @@ module.exports = function (app) {
       let graphTempBuf = { stw: [], sog: [], depth: [], tws: [], vmg: [], aws: [], twd: [] };
       let lastUpdates = { stw: 0, sog: 0, depth: 0, tws: 0, vmg: 0, aws: 0, twd: 0 };
       let raw = {};
+    // Memoria temporale per rilevare la presenza di sensori nativi sul Cerbo
+      let lastNativeTwsTime = 0;
+      let lastNativeTwdTime = 0;
 
   /**
    * plugin.start: Inizializza il plugin.
@@ -61,6 +64,8 @@ module.exports = function (app) {
         { path: 'environment.wind.speedApparent' },
         { path: 'environment.wind.angleApparent' },
         { path: 'navigation.headingTrue' },
+        { path: 'navigation.headingMagnetic' },
+        { path: 'navigation.magneticVariation' },
         { path: 'navigation.courseOverGroundTrue' }
       ]
     };
@@ -98,14 +103,17 @@ module.exports = function (app) {
     app.debug(msg);
   };
 
-  /**
+/**
    * processIncomingDelta: Decodifica i dati dei sensori in Knots/Meters ed esegue l'aggregazione
+   * Gestisce l'architettura "Nativo Prima, Fallback Dopo" per il vento reale.
    */
   function processIncomingDelta(path, val) {
     if (val === null || val === undefined) return;
     raw[path] = val;
 
-    // Elaborazione e invio alla macchina a stati temporali dello storico
+    const now = Date.now();
+
+    // 1. Cattura dei dati nativi (Se presenti, li scrive direttamente nello storico)
     if (path === 'navigation.speedThroughWater') {
       manageHistory('stw', val * 1.94384);
     }
@@ -118,8 +126,24 @@ module.exports = function (app) {
     else if (path === 'environment.wind.speedApparent') {
       manageHistory('aws', val * 1.94384);
     }
+    else if (path === 'environment.wind.speedTrue') {
+      lastNativeTwsTime = now; // Rilevato TWS nativo della centralina!
+      manageHistory('tws', val * 1.94384);
+    }
+    // --- DECODIFICA PRUA MAGNETICA SERVER-SIDE ---
+    else if (path === 'navigation.headingMagnetic') {
+      const hasTrueHdg = raw['navigation.headingTrue'] !== undefined;
+      if (!hasTrueHdg) {
+        const variation = raw['navigation.magneticVariation'] || 0;
+        raw['navigation.headingTrue'] = (val + variation + 2 * Math.PI) % (2 * Math.PI);
+      }
+    }
+    else if (path === 'environment.wind.directionTrue') {
+      lastNativeTwdTime = now; // Rilevato TWD nativo della centralina!
+      manageHistory('twd', val);
+    }
 
-    // Calcolo combinato del Vento Reale (TWS) e della VMG a livello Server
+    // 2. Calcolo combinato di FALLBACK (Si attiva solo se la centralina non invia TWS/TWD nativi)
     const aws = raw["environment.wind.speedApparent"];
     const awa = raw["environment.wind.angleApparent"];
     const stw = raw["navigation.speedThroughWater"] || 0;
@@ -128,25 +152,29 @@ module.exports = function (app) {
     const cog = raw["navigation.courseOverGroundTrue"] || 0;
 
     if (aws !== undefined && awa !== undefined) {
-        const awsKts = aws * 1.94384;
-        const stwKts = stw * 1.94384;
-        const tw_water_x = awsKts * Math.cos(awa) - stwKts;
-        const tw_water_y = awsKts * Math.sin(awa);
-        const tws = Math.sqrt(tw_water_x * tw_water_x + tw_water_y * tw_water_y);
+      const awsKts = aws * 1.94384;
+      const stwKts = stw * 1.94384;
+      const tw_water_x = awsKts * Math.cos(awa) - stwKts;
+      const tw_water_y = awsKts * Math.sin(awa);
 
+      // Calcoliamo il TWS di fallback solo se non abbiamo visto dati nativi negli ultimi 5 secondi
+      if (now - lastNativeTwsTime > 5000) {
+        const tws = Math.sqrt(tw_water_x * tw_water_x + tw_water_y * tw_water_y);
         manageHistory('tws', tws);
+      }
 
-        const twa = Math.atan2(tw_water_y, tw_water_x);
-        const vmg = Math.abs(stwKts * Math.cos(twa));
-        manageHistory('vmg', vmg);
-
-        // --- CALCOLO TWD STRATEGICO SERVER-SIDE ---
-        if (hdg !== undefined) {
-          // Calcolo della direzione del vento reale rispetto al nord (TWD) in radianti
-          const twd = (hdg + twa + 2 * Math.PI) % (2 * Math.PI);
-          manageHistory('twd', twd);
-        }
+      const twa = Math.atan2(tw_water_y, tw_water_x);
+      
+      // La VMG viene sempre calcolata a livello server poiché raramente è nativa
+      const vmg = Math.abs(stwKts * Math.cos(twa));
+      manageHistory('vmg', vmg);
+
+      // Calcoliamo il TWD di fallback solo se non abbiamo visto dati nativi negli ultimi 5 secondi
+      if (hdg !== undefined && (now - lastNativeTwdTime > 5000)) {
+        const twd = (hdg + twa + 2 * Math.PI) % (2 * Math.PI);
+        manageHistory('twd', twd);
       }
+    }
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sailingrotevista/rotevista-dash",
-  "version": "6.1.2",
+  "version": "6.1.4",
   "description": "Wind Dashboard with navigation and course aids",
   "main": "index.js",
   "publishConfig": {