signalk-instrument-widgets 0.5.0

package/README.md

@@ -0,0 +1,32 @@
+# signalk-instrument-widgets
+
+Add live instrument widgets to your chartplotter. Works with any chartplotter
+that supports Signal K plotter extensions (such as Freeboard-SK).
+
+- **Gauge** — a dial for any numeric value.
+- **Meter** — a 0–100% bar for ratio-style values.
+- **Switch** — shows an on/off value; tap to toggle it.
+- **Display Value** — a clean text readout: a small label on top, the live
+  value large in the middle, and an abbreviation below — e.g. "Speed over
+  ground" / value / "SOG".
+
+## Using the widgets
+
+In your chartplotter, press and hold an **empty** widget area to add a
+widget — its setup panel opens automatically. Press and hold a **placed**
+widget to reconfigure or remove it.
+
+Each widget is configured on its own: pick the value to show, choose the
+units, and set the range and labels. So you can place two gauges showing two
+different values side by side. Your settings are remembered for each widget.
+
+## Demo switch
+
+If your server has no real switches to control (for example a demo or
+playback setup), the plugin can provide a demo switch so you can try the
+Switch widget anywhere. It is on by default and can be turned off in the
+plugin settings.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "signalk-instrument-widgets",
+  "version": "0.5.0",
+  "description": "Gauge, meter and switch widgets for Signal K chartplotters that support the plotterExtensions resource type",
+  "main": "plugin/index.js",
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-category-chart-plotters"
+  ],
+  "files": [
+    "plugin",
+    "public",
+    "docs/screenshots",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node --test \"test/**/*.test.js\" \"test/**/*.test.mjs\"",
+    "prepare": "node scripts/build.mjs"
+  },
+  "author": "Joel Kozikowski",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joelkoz/signalk-instrument-widgets.git"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.0",
+    "signalk-plotterext-bus": "file:../signalk-plotterext-bus"
+  },
+  "signalk-plugin-enabled-by-default": false,
+  "signalk": {
+    "displayName": "Instrument Widgets",
+    "appSupport": "none",
+    "screenshots": [
+      "./docs/screenshots/1_freeboard-widget.png"
+    ],
+    "appstore": {
+      "displayName": "Instrument Widgets",
+      "categories": [
+        "chart-plotters"
+      ],
+      "author": "Joel Kozikowski",
+      "description": "Gauge, meter and switch widgets for Signal K chartplotters that support the plotterExtensions resource type"
+    }
+  }
+}

package/plugin/index.js

@@ -0,0 +1,201 @@
+// signalk-instrument-widgets
+//
+// Reference extension for the plotterExtensions specification. The plugin
+// itself is intentionally small: it registers a read-only plotterExtensions
+// resource provider whose single resource is this extension's manifest, and
+// (optionally) provides a demo switch path with a PUT handler so the switch
+// widget can be exercised against playback data that has no real switches.
+//
+// The widget/panel web assets live in public/ and are served by the plugin
+// itself, mounted as a top-level Express static route at
+// /plotterext/<package-name>/. This is a public route (no token required,
+// same as the old signalk-webapp mechanism) but, unlike a signalk-webapp, it
+// does NOT appear in the server's Webapps launcher — these assets are only
+// ever loaded inside a host chartplotter's iframe, never launched directly.
+// It is deliberately NOT a /plugins/* route: those are admin-gated, which
+// would break read-only users.
+
+const path = require('path')
+
+const PLUGIN_ID = 'signalk-instrument-widgets'
+const ASSET_BASE = `/plotterext/${PLUGIN_ID}`
+const PUBLIC_DIR = path.join(__dirname, '..', 'public')
+const DEMO_SWITCH_PATH = 'electrical.switches.demo.state'
+
+const pkg = require('../package.json')
+
+function buildManifest() {
+  return {
+    name: 'Instrument Widgets',
+    description:
+      'Single-value instrument widgets: gauge, percent meter and switch.',
+    version: pkg.version,
+    apiVersion: '1',
+    requires: ['widgets', 'panels.iframe', 'signalk.stream'],
+    optional: ['signalk.put'],
+    widgets: [
+      {
+        id: 'gauge',
+        title: 'Gauge',
+        type: 'iframe',
+        url: `${ASSET_BASE}/gauge.html`,
+        size: '1x1',
+        configPanel: 'instrument-config',
+        lifecycle: 'whileEnabled'
+      },
+      {
+        id: 'meter',
+        title: 'Meter (0-100%)',
+        type: 'iframe',
+        url: `${ASSET_BASE}/meter.html`,
+        size: '2x1',
+        configPanel: 'instrument-config',
+        lifecycle: 'whileEnabled'
+      },
+      {
+        id: 'switch',
+        title: 'Switch',
+        type: 'iframe',
+        url: `${ASSET_BASE}/switch.html`,
+        size: '1x1',
+        configPanel: 'instrument-config',
+        lifecycle: 'whileEnabled'
+      },
+      {
+        id: 'display',
+        title: 'Display Value',
+        type: 'iframe',
+        url: `${ASSET_BASE}/display.html`,
+        size: '1x1',
+        configPanel: 'instrument-config',
+        lifecycle: 'whileEnabled'
+      }
+    ],
+    panels: [
+      {
+        id: 'instrument-config',
+        title: 'Instrument Setup',
+        type: 'iframe',
+        url: `${ASSET_BASE}/config.html`,
+        lifecycle: 'onOpen'
+      }
+    ]
+  }
+}
+
+module.exports = (app) => {
+  let providerRegistered = false
+  let assetsMounted = false
+  let demoSwitchState = 0
+  let running = false
+
+  const debug = (msg) => app.debug(`${PLUGIN_ID}: ${msg}`)
+
+  // Serve public/ as a top-level static route. Express is provided by the
+  // Signal K server, so requiring it adds no runtime dependency of our own.
+  // Guarded so the test harness (a fake app with no .use) is a no-op.
+  const mountAssets = () => {
+    if (assetsMounted) return
+    if (typeof app.use !== 'function') return
+    let serveStatic
+    try {
+      serveStatic = require('express').static
+    } catch {
+      app.error(`${PLUGIN_ID}: express unavailable; cannot serve ${ASSET_BASE}`)
+      return
+    }
+    app.use(ASSET_BASE, serveStatic(PUBLIC_DIR))
+    assetsMounted = true
+    debug(`assets served at ${ASSET_BASE}`)
+  }
+
+  const registerProvider = () => {
+    if (providerRegistered) return
+    if (typeof app.registerResourceProvider !== 'function') {
+      app.error(`${PLUGIN_ID}: server has no resource provider registry`)
+      return
+    }
+    app.registerResourceProvider({
+      type: 'plotterExtensions',
+      methods: {
+        listResources: async () => {
+          if (!running) return {}
+          return { [PLUGIN_ID]: buildManifest() }
+        },
+        getResource: async (id) => {
+          if (!running || id !== PLUGIN_ID) {
+            throw new Error(`No such plotterExtensions resource: ${id}`)
+          }
+          return buildManifest()
+        },
+        setResource: async () => {
+          throw new Error(`${PLUGIN_ID} is a read-only provider`)
+        },
+        deleteResource: async () => {
+          throw new Error(`${PLUGIN_ID} is a read-only provider`)
+        }
+      }
+    })
+    providerRegistered = true
+  }
+
+  const emitDemoSwitch = () => {
+    app.handleMessage(PLUGIN_ID, {
+      updates: [
+        {
+          values: [{ path: DEMO_SWITCH_PATH, value: demoSwitchState }]
+        }
+      ]
+    })
+  }
+
+  const startDemoSwitch = () => {
+    app.registerPutHandler(
+      'vessels.self',
+      DEMO_SWITCH_PATH,
+      (_context, _path, value) => {
+        demoSwitchState = value === true || value === 1 || value === '1' ? 1 : 0
+        emitDemoSwitch()
+        return { state: 'COMPLETED', statusCode: 200 }
+      }
+    )
+    emitDemoSwitch()
+    debug(`demo switch active at ${DEMO_SWITCH_PATH}`)
+  }
+
+  return {
+    id: PLUGIN_ID,
+    name: 'Instrument Widgets',
+    description:
+      'Gauge, meter and switch widgets for chartplotters that support the plotterExtensions resource type.',
+
+    schema: () => ({
+      type: 'object',
+      properties: {
+        enableDemoSwitch: {
+          type: 'boolean',
+          title: 'Provide a demo switch path',
+          description:
+            `Registers a PUT handler and emits ${DEMO_SWITCH_PATH} so the ` +
+            'switch widget can be tested without real switch hardware.',
+          default: true
+        }
+      }
+    }),
+
+    start(options) {
+      running = true
+      mountAssets()
+      registerProvider()
+      if (!options || options.enableDemoSwitch !== false) {
+        startDemoSwitch()
+      }
+      debug('started')
+    },
+
+    stop() {
+      running = false
+      debug('stopped')
+    }
+  }
+}

package/public/config.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Instrument Setup</title>
+<link rel="stylesheet" href="instruments.css">
+</head>
+<body class="panel">
+<div id="root"></div>
+<script src="js/config.js"></script>
+</body>
+</html>

package/public/display.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Display Value</title>
+<link rel="stylesheet" href="instruments.css">
+</head>
+<body class="widget">
+<div id="root"></div>
+<script src="js/display.js"></script>
+</body>
+</html>

package/public/gauge.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Gauge</title>
+<link rel="stylesheet" href="instruments.css">
+</head>
+<body class="widget">
+<div id="root"></div>
+<script src="js/gauge.js"></script>
+</body>
+</html>

package/public/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Instrument Widgets</title>
+<link rel="stylesheet" href="instruments.css"></head>
+<body class="panel">
+<div id="root">
+<h2>Instrument Widgets</h2>
+<p class="status">This package provides gauge, meter, switch and display
+widgets for chartplotters that support the Signal K
+<code>plotterExtensions</code> resource type (e.g. Freeboard-SK). There is
+nothing to configure here: in your chartplotter, press and hold an empty
+widget area to add a widget, and press and hold a placed widget to
+configure it.</p>
+</div>
+</body>
+</html>

package/public/instruments.css

@@ -0,0 +1,248 @@
+/* Shared styling for instrument widgets and the config panel. Widgets render
+   over the chart, so backgrounds stay translucent-dark for contrast on both
+   light and dark map styles. */
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  font-family: 'Helvetica Neue', Arial, sans-serif;
+  -webkit-user-select: none;
+  user-select: none;
+  background: transparent;
+  overflow: hidden;
+}
+
+#root {
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+}
+
+.widget-body {
+  background: rgba(20, 26, 32, 0.78);
+  border-radius: 10px;
+}
+
+/* Widgets fill their frame with one translucent card. */
+body.widget #root {
+  background: rgba(20, 26, 32, 0.78);
+  border-radius: 10px;
+  color: #e8edf2;
+}
+
+body.widget svg {
+  width: 100%;
+  height: 100%;
+}
+
+svg .track {
+  fill: none;
+  stroke: rgba(255, 255, 255, 0.18);
+  stroke-width: 7;
+  stroke-linecap: round;
+}
+svg .fill {
+  fill: none;
+  stroke: #29b6f6;
+  stroke-width: 7;
+  stroke-linecap: round;
+}
+svg .needle {
+  stroke: #ffb300;
+  stroke-width: 2;
+}
+svg .hub {
+  fill: #ffb300;
+}
+svg .value {
+  fill: #ffffff;
+  font-size: 20px;
+  font-weight: 600;
+  text-anchor: middle;
+}
+svg .meter-value {
+  font-size: 28px;
+}
+svg .units {
+  fill: #9fb3c4;
+  font-size: 9px;
+  text-anchor: middle;
+}
+svg .label {
+  fill: #9fb3c4;
+  font-size: 10px;
+  text-anchor: middle;
+}
+svg .meter-label {
+  font-size: 12px;
+}
+svg .bound {
+  fill: #6c7f8e;
+  font-size: 8px;
+  text-anchor: middle;
+}
+svg .fillbar {
+  fill: #29b6f6;
+}
+svg rect.track {
+  fill: rgba(255, 255, 255, 0.18);
+  stroke: none;
+}
+
+/* Switch widget */
+.switch {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+  color: #e8edf2;
+  cursor: pointer;
+}
+.switch-pill {
+  width: 76px;
+  height: 36px;
+  border-radius: 18px;
+  background: rgba(255, 255, 255, 0.18);
+  position: relative;
+  transition: background 0.15s;
+}
+.switch-knob {
+  width: 32px;
+  height: 32px;
+  border-radius: 16px;
+  background: #cfd8dc;
+  position: absolute;
+  top: 2px;
+  left: 2px;
+  transition: left 0.15s, background 0.15s;
+}
+.switch.on .switch-pill {
+  background: #2e7d32;
+}
+.switch.on .switch-knob {
+  left: 42px;
+  background: #ffffff;
+}
+.switch-state {
+  font-size: 20px;
+  font-weight: 600;
+}
+.switch.unknown .switch-state {
+  color: #6c7f8e;
+}
+.switch-label {
+  font-size: 13px;
+  color: #9fb3c4;
+  text-align: center;
+  max-width: 95%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Display Value widget */
+.display {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0;
+  color: #e8edf2;
+  text-align: center;
+  width: 100%;
+  padding: 2px;
+  box-sizing: border-box;
+}
+.display-top {
+  font-size: 13px;
+  color: #9fb3c4;
+  max-width: 97%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.display-value {
+  font-size: 40px;
+  font-weight: 600;
+  line-height: 1.05;
+}
+.display-units {
+  font-size: 15px;
+  font-weight: 400;
+  color: #9fb3c4;
+  margin-left: 4px;
+}
+.display-bottom {
+  font-size: 22px;
+  color: #c3d2de;
+  max-width: 97%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Config panel */
+body.panel {
+  background: #1d242b;
+  color: #e8edf2;
+  overflow: auto;
+}
+body.panel #root {
+  display: block;
+  padding: 14px;
+}
+body.panel h2 {
+  margin: 0 0 12px;
+  font-size: 16px;
+  text-transform: capitalize;
+}
+body.panel .row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-bottom: 10px;
+}
+body.panel .row span {
+  flex: 0 0 110px;
+  font-size: 13px;
+  color: #9fb3c4;
+}
+body.panel input,
+body.panel select {
+  flex: 1;
+  padding: 6px 8px;
+  border-radius: 6px;
+  border: 1px solid #39444d;
+  background: #12181d;
+  color: #e8edf2;
+  font-size: 13px;
+  min-width: 0;
+}
+body.panel .actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 14px;
+}
+body.panel button {
+  padding: 7px 16px;
+  border-radius: 6px;
+  border: 1px solid #39444d;
+  background: #2a333b;
+  color: #e8edf2;
+  font-size: 13px;
+  cursor: pointer;
+}
+body.panel button.primary {
+  background: #1976d2;
+  border-color: #1976d2;
+}
+body.panel .status {
+  font-size: 12px;
+  color: #9fb3c4;
+  min-height: 1em;
+}