@mxtommy/kip 4.5.0-beta.1 → 4.5.0

package/public/assets/help-docs/dashboards.md

@@ -1,9 +1,8 @@
 ## Managing Dashboards
 Dashboards let you group widgets by task—navigation, engines, energy, weather, racing, night watch, and more. This guide covers creating, organizing, and editing dashboards, plus an overview of available widget types.
 
----
 
-## 1. Dashboard Pages Panel
+## Dashboard Pages Panel
 Open the Actions menu and select Settings.
 
 Here you can:
@@ -24,9 +23,8 @@ Choose icons that reflect each dashboard’s purpose (e.g. compass for navigatio
 | Duplicate     | Long press → Duplicate | Long click → Duplicate |
 | Delete        | Long press → Delete    | Long click → Delete    |
 
----
 
-## 2. Editing Dashboard Layouts
+## Editing Dashboard Layouts
 1. Navigate to the dashboard you want to change (swipe or use dashboard selector).
 2. Open the Actions menu.
 3. Tap the Unlock/Lock button at the bottom to toggle edit mode.
@@ -42,11 +40,18 @@ In edit mode, widgets show dashed outlines.
 - Delete a widget (long press → Delete, then confirm)
 - Save changes (Check button) or discard (X button) in the lower right
 
-Tip: If you can’t add a widget, free up space by resizing or moving existing ones first.
+>**Tip:** If you can’t add a widget, free up space by resizing or moving existing ones first.
 
----
+## Viewing Widget History on Locked Dashboards
+When a dashboard is locked (normal viewing mode), you can open a history chart for a widget without entering edit mode:
 
-## 3. Workflow: From Idea to Dashboard
+- **Desktop / mouse:** right-click on the widget
+- **Touch device:** two-finger tap on the widget
+
+KIP opens a history chart dialog and loads historical series data for that widget using the History API.
+
+
+## Workflow: From Idea to Dashboard
 1. Define the purpose (e.g. “Night Nav” = heading, COG, SOG, depth, wind, batteries, minimal brightness)
 2. Create or duplicate a dashboard similar to what you want
 3. Enter edit mode and add required widgets
@@ -54,9 +59,8 @@ Tip: If you can’t add a widget, free up space by resizing or moving existing o
 5. Arrange and size for readability at your viewing distance
 6. Exit edit mode and test switching at real brightness/environment
 
----
 
-## 4. Widget Gallery (Overview)
+## Widget Gallery (Overview)
 KIP widgets turn Signal K data into readable visuals and controls. Available widget types:
 
 - **Numeric** – Displays numeric data in a clear and concise format, with options to show min/max values and a background minichart for trends.
@@ -65,9 +69,9 @@ KIP widgets turn Signal K data into readable visuals and controls. Available wid
 - **Position** – Displays latitude and longitude for location tracking and navigation.
 - **Static Label** – Add customizable labels to organize and clarify your dashboard layout.
 - **Zones State Panel**: Monitor the health/state of path data. Each panel control displays path data severity and status messages (driven by Signal K metadata zones).
-- **Switch Panel** – Group of toggle switches, indicator lights, and press buttons for digital switching and operations.
-- **Slider** – Range slider for adjusting values (e.g. lighting intensity).
-- **Multi State Switch** - Lists all available device/path operating modes/states (e.g., On, Off, Charge Only, Invert Only), highlights the current state, and lets you select a new state to send to the device and see the result.
+- **Switch Panel** – Group of toggle switches, indicator lights, and press buttons for digital switching and operations. See [Digital Switching and PUT Path Setup](putcontrols.md).
+- **Slider** – Range slider for adjusting values (e.g. lighting intensity). See [Digital Switching and PUT Path Setup](putcontrols.md).
+- **Multi State Switch** - Lists all available device/path operating modes/states (e.g., On, Off, Charge Only, Invert Only), highlights the current state, and lets you select a new state to send to the device and see the result. See [Digital Switching and PUT Path Setup](putcontrols.md).
 - **Compact Linear** – Simple horizontal linear gauge with a large value label and modern look.
 - **Linear** – Horizontal or vertical linear gauge with zone highlighting.
 - **Radial** – Radial gauge with configurable dials and zone highlighting.
@@ -87,9 +91,8 @@ KIP widgets turn Signal K data into readable visuals and controls. Available wid
 - **Racer - Start Timer** – Advanced racing countdown timer with OCS status and auto dashboard switching.
 - **Countdown Timer** – Simple race start countdown timer with start, pause, sync, and reset options.
 
----
 
-## 5. Performance & Layout Tips
+## Performance & Layout Tips
 - Favor clarity over cramming: leave space around high‑priority values
 - Group related widgets (navigation, energy, engines, environment)
 - Use consistent units per dashboard (e.g. all speeds in knots, all temps in °C or °F—don’t mix)
@@ -99,19 +102,18 @@ KIP widgets turn Signal K data into readable visuals and controls. Available wid
 - Know your device’s hardware limits and adjust widget count per dashboard accordingly
 - Avoid embedding too many external webpages—each adds load
 
----
 
-## 6. Troubleshooting
+## Troubleshooting
 | Issue                  | Possible Cause                        | Fix                                                                 |
 |------------------------|---------------------------------------|---------------------------------------------------------------------|
 | Data shows “—” or blank| Path missing/not configured/null value | Open widget config, verify Signal K path exists and updates. Use Data Inspector and Signal K Data Browser to view raw data from the server. |
 | Wrong units            | Default convert unit used              | Edit widget config paths and set the desired target unit.            |
 | Slow dashboard switching| Excessive data sampling/too many widgets| Increase sample times; remove unused widgets. Split widgets into separate dashboards. Optimize system resource usage. |
 | Embedded page blank    | Cross‑origin blocked                   | See "Embed Page Viewer" help section.                               |
+| History dialog not opening on locked dashboard | Dashboard is still in edit mode, or interaction did not register as right-click / two-finger tap | Lock the dashboard first, then retry with a right-click (desktop) or two-finger tap (touch). |
 
----
 
-## 7. Next Steps
+## Next Steps
 See also:
 - Remote Control (switch dashboards on unattended displays)
 - Night Mode (automatic theme + brightness)

package/public/assets/help-docs/datainspector.md

@@ -10,7 +10,7 @@ The Data Inspector is a good way to validate raw data and available paths withou
      - Type `self.` to view paths related to your vessel.
      - Type `environment` to view environmental data like wind or temperature.
      - Type `speed` to view any speed related data like wind speed, max speed, polar speed, etc.
-     - Type `derived` to view all path from source derived-data .
+   - Type `derived` to view all paths from source `derived-data`.
 
 2. **Sort and Navigate**:
    - Click on column headers to sort the data by Path, PUT Support, or Source.
@@ -24,7 +24,7 @@ The Data Inspector is a good way to validate raw data and available paths withou
 
 2. **PUT Support**:
    - You can see if a path supports PUT operations, indicated by a green checkmark in the **PUT Support** column.
-   - For more details on PUT support and how to use it, refer to the **Updating Signal K Data** help documentation.
+   - For more details on PUT support and how to use it, refer to the [Updating Signal K Data](putcontrols.md) help documentation.
 
 3. **Multiple Data Sources**:
    - The Data Inspector displays how many sources are providing data for each path.
@@ -41,11 +41,13 @@ The Data Inspector is a good way to validate raw data and available paths withou
   - Use the Data Inspector to validate raw data and available paths without the constraints that widgets can impose. This is especially useful when setting up new devices or debugging data issues.
 
 - **Verify PUT Support**:
-  - Check if a path supports PUT operations before configuring widgets like the Switch Panel or Slider.
+   - Check if a path supports PUT operations. It is required to configure widgets like Switch Panel, Slider, or Multi State Switch.
+   - For more details on PUT support and how to use it, refer to the [Updating Signal K Data](putcontrols.md) help documentation.
+   - If you are learning Node-RED flows and want your flow to work with KIP digital switching widgets, continue with [Node-RED Control Flows for KIP Widgets (Beginner Guide)](nodered-control-flows.md).
 
 - **Troubleshoot Data Issues**:
-  - The Data Inspector is a good troubleshooting tool, but it should be matched with the Signal K Data Browser when trying to understand raw data and what is going on. The combination of these tools provides a more complete picture of the data, it's processing and its behavior.
+   - The Data Inspector is a good troubleshooting tool, but it should be used with the Signal K Data Browser when trying to understand raw data and behavior. The combination of these tools provides a more complete picture of the data, its processing, and its behavior.
 
 ## Summary
 
-The Data Inspector is an essential tool for managing and understanding the data KIP receives from your Signal K server. With its real-time updates, filtering, and unit conversion capabilities, it provides a comprehensive view of your vessel's data. Whether you're monitoring performance, configuring widgets, or troubleshooting issues. For deeper analysis and understanding of raw data, pair it with the Signal K Data Browser to gain even more insights.
+The Data Inspector is an essential tool for managing and understanding the data KIP receives from your Signal K server. With its real-time updates, filtering, and unit conversion capabilities, it provides a comprehensive view of your vessel's data whether you're monitoring performance, configuring widgets, or troubleshooting issues. For deeper analysis and understanding of raw data, pair it with the Signal K Data Browser.

package/public/assets/help-docs/history-api.md

@@ -0,0 +1,116 @@
+## Using the History-API to Obtain Historical Data 
+
+KIP can automatically request History Provider historical data points when opening chart widgets, seamlessly integrating past data with live updates.
+
+This enables the display of minutes, hours, days, weeks, etc. of pre-populated historical data immediately—no waiting, no empty charts. The History-API is used to achieve this.
+
+A History Provider can also be used as a source for the widget historical data feature.
+
+## What Is the History-API?
+
+A Signal K server endpoint that provides access to recorded historical data. Behind the endpoint, the data is served by a history provider plugin. KIP automatically requests historical data points when opening chart widgets, pre-filling the chart instead of starting empty.
+
+## Which Widgets Support History?
+
+### Data Chart Widget
+- **Supported**: Yes, fully seeded with history data when available.
+- **Requirements**: Time scale = minutes or longer.
+- See "Configure Time Scales" below for more details.
+
+### Wind Trends Widget
+- **Supported**: Yes, uses fixed paths (True Wind Direction and Speed).
+- **Requirements**: Time Span of `5 minutes` or `30 minutes`.
+- See [Wind Trends Fixed Paths](#wind-trends-fixed-paths) below for configuration details.
+
+### Numeric Widget (with Mini Chart)
+- **Supported**: No. Mini charts use very short time windows (12 seconds) and skip history seeding.
+- Mini charts start live-only for performance reasons.
+
+## What Plugins and Signal K Version Are Required?
+
+The History-API requires Signal K version 2.22.1 or above and one plugin that records data to a persistent store. Currently, two plugins support the History-API:
+
+### 1. signalk-to-influxdb2, v2.0.0 or above
+- **Purpose**: Records Signal K data to an InfluxDB v2 time-series database. Requires pre-installed InfluxDB v2.
+- **Link**: [signalk-to-influxdb2](https://www.npmjs.com/package/signalk-to-influxdb2)
+- **Setup**: Consult the plugin documentation for installation and configuration.
+- **Path Configuration**: By default, records all paths. Configure filters, resolution, and other settings to match the paths you want available in KIP charts.
+
+### 2. signalk-parquet, (supporting version not release yet)
+- **Purpose**: Records Signal K data to Parquet files for efficient storage and querying. No external database installation required.
+- **Link**: [signalk-parquet](https://www.npmjs.com/package/signalk-parquet)
+- **Setup**: Consult the plugin documentation for installation and configuration.
+- **Path Configuration**: Specify which paths to record in the plugin settings. None are recorded by default.
+
+
+## How History Data Works in KIP
+
+### History Seeding
+When you open a chart widget with a larger time scale (minutes/hours):
+1. KIP checks if history data is available via the History-API.
+2. If available and the time window allows (resolution >= 1000ms), KIP requests historical data points.
+3. The chart immediately displays the historical trend.
+
+### Live Updates
+After history data loads:
+- New data points arrive continuously via Signal K's live WebSocket connection.
+- The chart smoothly transitions from history to live updates.
+- Old data points are removed to maintain a rolling window of the configured time scale.
+
+### When History Is Not Available
+- If a History-API plugin is not installed, or the plugin report the path is not recorded, history requests are skipped silently.
+- The chart will display only live data starting from when it was opened.
+- This is normal and does not indicate an error.
+
+## Wind Trends Fixed Paths
+
+The Wind Trends widget uses two fixed Signal K paths:
+- **True Wind Direction**: `environment.wind.directionTrue`
+- **True Wind Speed**: `environment.wind.speedTrue`
+
+For Wind Trends to display historical data, both of these paths **must be configured in your chosen History-API plugin**. Check your plugin documentation to ensure these paths are included in the capture list.
+
+## Limitations
+
+For historical data to seed widgets, you need to, in most cases, manually configure your chosen provider to collect the said data. This is not an automatic process.
+
+## Troubleshooting
+
+### History Data Is Not Showing
+
+**Check 1: Is the History-API plugin installed?**
+- Confirm that a History-API plugin is installed and enabled on your Signal K server.
+- Verify that the plugin is running without errors (check server logs).
+
+**Check 2: Are the paths configured in the plugin?**
+- Open your plugin's configuration settings.
+- Confirm that the paths you're charting (e.g., `navigation.speedThroughWater`) are in the capture list.
+
+**Check 3: Is there historical data available?**
+- If the plugin was just installed, data will start recording from that moment forward.
+- Charts will not show history for times before the plugin was enabled or the path configured for recording.
+- Allow the plugin to record data for a while (days or weeks) before expecting deep history.
+
+**Check 4: Is the chart time scale eligible?**
+- Very short time scales (seconds) skip history seeding for performance.
+- Use time scales of **minutes or longer** to enable history seeding.
+
+**Check 5: Are there any network or permission issues?**
+- Confirm that KIP can reach the Signal K server's History-API endpoint. Use the OpenApi link in the Server Admin pages to the test.
+- Check browser console logs (F12) for any HTTP errors from history requests.
+
+
+## Next Steps
+
+1. Verify that a History-API plugin is installed on your Signal K server.
+2. Configure the plugin to capture the paths you want to chart.
+3. Wait for plugin to capture enough data to fill your Data Chart's time span.
+4. Open a Data Chart or Wind Trends widget with a time scale of minutes or longer.
+5. Allow the chart to load—history data will appear if available.
+6. For more details, consult your plugin's documentation and the Signal K community resources.
+
+
+## Questions or Issues?
+
+- Refer to the plugin and History-API documentation for plugin-specific configuration and troubleshooting.
+- For general questions or issues, see `Contact-Us` help page—the KIP community is active on Discord and GitHub.

package/public/assets/help-docs/menu.json

@@ -2,15 +2,27 @@
   { "title": "The basics", "file": "welcome.md" },
   { "title": "Login & Configurations", "file": "configuration.md" },
   { "title": "Dashboards and Layout", "file": "dashboards.md" },
+  { "title": "Data Inspector", "file": "datainspector.md" },
   { "title": "Chartplotter Mode", "file": "chartplotter.md" },
   { "title": "Zones, Notifications and Highlights", "file": "zones.md" },
-  { "title": "Data Inspector", "file": "datainspector.md" },
   { "title": "Digital Switching and PUT", "file": "putcontrols.md" },
-  { "title": "The Embed Page Viewer", "file": "embedwidget.md" },
-  { "title": "Datasets and Data Chart Widget", "file": "datasets.md" },
-  { "title": "Kiosk Mode", "file": "kiosk.md" },
-  { "title": "Grafana Integration", "file": "grafana.md" },
-  { "title": "InfluxDB and Signal K", "file": "influxdb.md" },
+  { "title": "Historical Widget Data", "file": "widget-historical-series.md" },
+  {
+    "title": "Integrations",
+    "items": [
+      { "title": "Node-RED (Getting Started)", "file": "nodered-control-flows.md" },
+      { "title": "The Embed Page Viewer", "file": "embedwidget.md" },
+      { "title": "Using The History-API", "file": "history-api.md" },
+      { "title": "Grafana Integration", "file": "grafana.md" },
+      { "title": "InfluxDB and Signal K", "file": "influxdb.md" }
+    ]
+  },
+  {
+    "title": "Advanced Features",
+    "items": [
+      { "title": "Kiosk Mode", "file": "kiosk.md" }
+    ]
+  },
   { "title": "Online Community Content", "file": "community.md" },
   { "title": "Contact Us", "file": "contact-us.md" }
 ]

package/public/assets/help-docs/nodered-control-flows.md

@@ -0,0 +1,125 @@
+## Node-RED Control Flows for KIP Widgets (Beginner Guide)
+
+This guide is for first-time Node-RED users who want KIP control widgets to trigger real actions (like GPIO or relay switching) through Signal K. It is not a full Node-RED product guide or a complete flow-programming course. It focuses on the Signal K and KIP-specific parts you need for digital switching.
+
+Before you start building flows, read **[Digital Switching and PUT Path Setup](putcontrols.md)** so you understand the core concepts, data flow, and control logic.
+
+## What You Are Building
+
+Use this sequence as your basic mental model:
+
+KIP widget → Signal K path (PUT) → Node-RED **put handler** → action node (GPIO/relay/driver/Web Service/etc.)
+
+This is the basic flow:
+
+1. A KIP widget sends a value to a Signal K path (PUT).
+2. Node-RED receives that path value through a **put handler** node.
+3. Your flow converts or uses that value to perform the final action.
+
+Think of Signal K as the shared data bus and Node-RED as the automation logic.
+
+### Why You Need a PUT Handler in the Flow
+
+To receive commands sent by KIP widgets, your flow needs a Signal K node named `put handler`.
+
+Why it is needed:
+- KIP writes values to Signal K paths using PUT.
+- The `put handler` listens for PUT updates on those paths.
+- Without it, your flow will not receive widget commands, so no action will run.
+
+Where to find it:
+- In Node-RED, open the **Signal K** node group.
+- Add the node called **put handler** to your flow.
+
+## Before You Start
+
+Check these basics first:
+
+1. KIP is connected and authenticated to Signal K.
+2. You can see your target path in Data Inspector, unless you plan to create a new path with your flow.
+3. The path type matches your widget type.
+4. Your Node-RED environment can access target hardware (GPIO, relay board, Web Service, etc.).
+
+## Safety First
+
+Always test with non-critical outputs first.
+
+- Start with a debug/test path or non-critical device before controlling live systems.
+- Validate expected behavior in Data Browser and Data Inspector before switching real loads.
+- Add safe defaults so outputs stay in a known state on startup/restart.
+
+## 5-Minute First Success
+
+Goal: prove the full command path works end-to-end (KIP → Signal K PUT → Node-RED `put handler` → value update).
+
+1. In Node-RED, open **Import** (`Cmd+I` on Mac).
+2. In **Examples**, go to: `flows -> @signalk/node-red-embedded -> put-handler`, then click **Import**.
+3. Open the imported **put handler** node and note the path it listens to (default example: `self.red.autoLights.state`).  
+   Leave defaults unchanged for this first test.
+4. Click **Deploy**.
+5. In KIP **Data Inspector**, search for `self.red.autoLights.state`.
+   - Confirm the path exists.
+   - Confirm **PUT Support** is enabled.
+6. In KIP, add a **Switch Panel** widget:
+   - Add a **Toggle** control.
+   - Set the control path to `self.red.autoLights.state`.
+   - Save/apply widget settings.
+7. Toggle ON/OFF in KIP and verify:
+   - The widget changes state without error notifications.
+   - The value updates in both Signal K Admin Data Browser and KIP Data Inspector.
+   - The updated value is visible in Node-RED under the **send autoLights** node (green status dot, e.g. **State: 1**).
+
+Note that this example flow uses numeric `1/0` path values. For ON/OFF control, the preferred value type is `boolean` (`true/false`).
+
+You can change this by double-clicking the **Inject** node labeled `1` and changing `msg.payload` type from `number` to `boolean`.
+
+When changing an existing path type, restart Signal K so the path is recreated with the new type. Path types are not safely changed in-place during runtime.
+
+Remember to click **Deploy** after any flow change.
+
+If this works, your core control pipeline is correctly set up. You can now repeat the same pattern with different path values for Slider and Multi State Switch paths.
+
+## Troubleshooting for Beginners
+
+If something does not work, check these first.
+
+### Widget changes value, but flow does not react
+- Verify Node-RED is watching the same exact Signal K path.
+- Verify your flow includes a Signal K **put handler** node and it is configured for the same path.
+- Verify authentication/permissions and path visibility.
+
+### Flow reacts, but hardware still does nothing
+- Verify hardware node wiring, pin mapping, and runtime permissions.
+- Test with a known manual value from Node-RED first.
+
+### Multi State widget shows no options
+- Metadata is incomplete for that path. Confirm `multiple` type and possible values list in Signal K metadata.
+
+## Suggested Learning Path
+
+Build in this order to keep setup simple.
+
+1. Start with one boolean switch end-to-end.
+2. Add one numeric slider flow.
+3. Add one multi-state mode flow.
+4. After each step, confirm path value in Data Inspector and physical result on hardware.
+
+## Glossary (Beginner)
+
+Use these terms consistently while setting up your flow.
+
+- **PUT**: Writing a value to a Signal K path.
+- **Path**: The Signal K key where a value is stored (for example `self.electrical.switches.bank.0.1.state`).
+- **PUT Support**: Signal K metadata indicating a path handler will react to PUT writes.
+- **put handler**: The Signal K Node-RED node that receives PUT writes from Signal K paths.
+- **Metadata**: Extra path information such as type, units, possible values and more.
+- **Possible values**: The allowed list of modes/states for a Multi State path.
+
+## Related Guides
+
+Use these guides next as needed.
+
+- SignalK signalk-node-red: [Show and tell](https://github.com/SignalK/signalk-node-red/discussions/categories/show-and-tell)
+- Path requirements and widget compatibility: [Digital Switching and PUT Path Setup](putcontrols.md)
+- Finding paths and checking PUT support: [Data Inspector](datainspector.md)
+- Adding and configuring widgets: [Dashboards and Layout](dashboards.md)

package/public/assets/help-docs/putcontrols.md

@@ -1,60 +1,101 @@
-## Digital Switching and using PUT Commands
-
-Signal K allows users to update data paths and trigger device reactions. This can include turning a light on or off, dimming it, activating a bilge pump, or other similar actions. This guide explains how to use the Switch Panel or Slider widgets to achieve this, how to verify if a path supports data reception (known as PUT-enabled in Signal K terms), and what is required to enable PUT functionality.
-
-## What is Required to Trigger Device Reactions
-For Signal K to accept any data from a client application, the application must be authenticated with a valid security token. Read the **Login & Configurations** help section for details on how to setup login in KIP. By default, sending data to a Signal K path only updates the value and broadcasts it to the network. No actions are taken unless an action handler is configured to respond to the updated value. For example:
-- Sending a PUT 'engage' command to `self.steering.autopilot.state` will update the state value, but the autopilot will not engage unless a handler (the autopilot plugin in this case) is set up to process the command and communicate with the hardware.
-
-To enable action handles, you have several options:
-1. **Install a Plugin**:
-   - The simplest option is to look in Signal K's Appstore. There are many plugins already available in the Signal K ecosystem such as plugins for (Shelly)[https://www.shelly.com], (Sonoff)[https://sonoff.tech/collections/diy-smart-switches] and standard N2K, like the (Yacht Devices)[https://www.yachtd.com] YDCC. Search for the plugin you need, install it, and configure it.
-   
-2. **Use Node-RED's Signal K PUT Handler**:
-   - Node-RED is a visual and easy-to-learn automation platform installed with Signal K. The Signal K team has created Signal K-specific Node-RED nodes, allowing you to easily automate your vessel. You can find Node-RED in the Webapps section of the Signal K Admin site.
-
-3. **Build Your Own Plugin**:
-   - If no existing plugin meets your needs, you can create a custom Signal K plugin to handle PUT commands for your specific requirements. See: [Getting Started with Plugin Development](https://github.com/SignalK/signalk-server/blob/master/docs/develop/plugins/README.md)
-
-## Checking for PUT Support
-To verify if a path supports PUT:
-1. Open KIP's **Data Inspector** located in the right sidebar.
-2. Search for the desired path (e.g., `self.electrical.switches.bank.0.1.state` or just `self.electrical` to list many).
-3. Look for a green check indicator in the **PUT Support** column. If PUT is not enabled/supported, the path will not be listed in the path selection options of widgets designed to send data.
-
-## Types of Path Data That Are Supported
-KIP currently supports the following types of paths for widgets:
-1. **Boolean Paths**:
-   - Supported by the Switch Panel widget.
-   - These paths toggle between `true` and `false` values (e.g., turning a device on/off).
-
-2. **Numerical Data Ranges**:
-   - Supported by the Slider widget.
-   - These paths allow for a range of numeric values (e.g., dimming a light or adjusting volume).
-
-For backward compatibility, boolean paths can also support numerical data types with `1/0` values. However, this legacy mode is discouraged. If needed, you can enable this mode by selecting the "Use Numeric" checkbox below the control.
-
-## Using the Switch Panel or Slider Widgets
-1. **Open the Widget Configuration**:
-   - Add a Switch Panel or Slider widget to your dashboard.
-   - Double-tap the widget to access its configuration options.
-   - Configure the widget to use the desired Signal K data path from the list of PUT-enabled paths.
-
-2. **Verify the Path**:
-   - Use the **Data Inspector** to search for the data path you want to update.
-   - Check if the path has **PUT Support** enabled. Paths with PUT support allow you to send updates to Signal K.
-
-3. **Send Updates**:
-   - Once configured, use the widget to send updates to the selected path. For example:
-     - A Switch Panel can toggle a boolean value (e.g., turning a device on/off).
-     - A Slider can adjust a numeric value (e.g., setting a dim percentage or audio system volume level).
-    - Use the **Data Inspector** to search for the data path and see the updated path value.
-    * If you find you have issues or need to troubleshoot further, using the Signal K Data Browser to validate path configuration, metadata, value or consult the server logs is also a best practice.  
-
-## Summary
-To update Signal K data with PUT commands:
-1. Verify PUT support for the path using the Data Inspector.
-2. Enable PUT support by installing a plugin, building one, or using Node-RED with the Signal K PUT Handler.
-3. Use the Switch Panel or Slider widgets to send updates.
-
-With these steps, you can effectively update Signal K data and trigger actions on your vessel's systems.
+## Digital Switching, Node-RED, and PUT
+
+Use KIP digital switching controls when you want to do real actions from your dashboard, like turning devices on/off, changing levels, or selecting operating modes. This guide helps you choose the right Signal K path for Switch Panel, Slider, and Multi State Switch controls so they work reliably in daily use.
+
+The focus here is practical KIP setup: what path type to use, what PUT support is needed, and how to avoid common configuration mistakes. This guide supports built-in server handlers, custom plugins, and Node-RED flows.
+
+If you are new to Node-RED, start with this guide, then continue with **[Node-RED Control Flows for KIP Widgets (Beginner Guide)](nodered-control-flows.md)** for beginner flow examples.
+
+## What PUT Does (and Does Not Do)
+
+Start with this key idea:
+
+PUT writes a value to a Signal K path. By itself, that write does not trigger hardware or system behavior. For actions to happen, a handler must be registered for that path. The handler reacts to the new value and performs the action. This handler capability is commonly called PUT Support.
+
+Examples of server-side handlers:
+- A built-in server handler
+- A Signal K plugin (see [Popular Digital Switching Plugins](#popular-digital-switching-plugins))
+- A Node-RED flow (see [Node-RED Control Flows for KIP Widgets (Beginner Guide)](nodered-control-flows.md))
+
+## Basic Requirements
+
+Check these basics first:
+
+1. For security reasons, KIP must be authenticated against Signal K for the server to accept PUTs.
+2. The target path must exist in Signal K and have metadata matching the digital switching widget type.
+3. For control widgets that send commands, the path metadata must report that PUT Support is enabled.
+4. The appropriate server-side handler must be present to react to value changes and control the targeted hardware.
+
+## Verifying Path Configuration
+
+Use this quick check before widget setup:
+
+1. Open **Data Inspector**.
+2. Search for your candidate path (for example `self.electrical.switches.bank.0.1.state`).
+3. Confirm the path data type and whether **PUT Support** is enabled (a handler is registered).
+4. For Multi State controls, confirm the path metadata includes possible values (use the Signal K Data Browser).
+
+## Path Eligibility by Widget and Control Type
+
+Use this table to match each control to the right path type.
+
+| Widget / Control | Typical Path Type | PUT Required | Notes |
+|---|---|---|---|
+| Switch Panel → Toggle | `boolean` (preferred) or `number` (`1/0` mode) | Yes | Use **Use numeric path** only when your system expects numeric states. |
+| Switch Panel → Push | `boolean` (preferred) or `number` (`1/0` mode) | Yes | Behaves like a momentary action style control. |
+| Switch Panel → Indicator | `boolean` or `number` | No (display only) | Indicator is read-only visualization and does not send commands. |
+| Slider | `number` | Yes | Best for ranges such as dimmer level or percentage setpoints. |
+| Multi State Switch | `multiple` metadata type | Yes | Metadata should expose possible values so options can be shown. |
+
+## Quick Setup Workflow
+
+Follow these steps in order:
+
+1. Install the required plugin or configure a Node-RED flow.
+2. If you installed a new plugin, restart the server. If you created a Node-RED flow, make sure the flow is Deployed.
+3. If using Node-RED, include a Signal K **put handler** node in your flow so widget commands are received.
+4. Confirm path exists in Data Inspector.
+5. Confirm type and PUT support are compatible with widget/control type.
+6. Configure the widget in KIP.
+7. Trigger the control and verify the value changes in Data Inspector.
+8. Validate the server-side handler executes the expected real-world action.
+
+## Popular Digital Switching Plugins
+
+If you prefer plugin-based integrations instead of building your own flow logic, these are commonly used options in the Signal K ecosystem:
+
+- **Shelly Gen 1 integrations**
+	- Commonly used to control Shelly Gen 1 relays, switches, and I/O modules.
+	- npm: [signalk-shelly](https://www.npmjs.com/package/signalk-shelly)
+
+- **Shelly Gen 2+ integrations**
+	- Commonly used to control Shelly Gen 2+ smart devices relays, switches, and I/O modules.
+	- npm: [signalk-shelly2](https://www.npmjs.com/package/signalk-shelly2)
+
+- **Sonoff integrations**
+	- Commonly used for eWeLink switches running the factory firmware.
+	- npm: [signalk-sonoff-ewelink](https://www.npmjs.com/package/signalk-sonoff-ewelink)
+
+
+## Troubleshooting
+
+If something does not work, check these first.
+
+### Path does not appear in widget config
+- Check type compatibility with the control you selected.
+- Check **PUT Support** for controls that write values (all except Indicator).
+
+### Value updates but hardware does nothing
+- The PUT write is working, but no server-side action handler is registered, or the handler has an error.
+- Verify plugin/flow/integration logic and server logs.
+
+### Multi State options are empty
+- Confirm the path metadata is type `multiple` and includes possible values.
+
+## Related Guides
+
+Use these guides next as needed.
+
+- **Node-RED beginners:** [Node-RED Control Flows for KIP Widgets (Beginner Guide)](nodered-control-flows.md)
+- **Path discovery and validation:** [Data Inspector](datainspector.md)
+- **Widget overview and placement:** [Dashboards and Layout](dashboards.md)

package/public/assets/help-docs/welcome.md

@@ -10,8 +10,7 @@ KIP supports multiple input modes for seamless navigation across devices.
 | Toggle Night mode          | N/A           | N/A                          | <kbd>Shift</kbd> + <kbd>Ctrl</kbd> + <kbd>N</kbd>  |
 | Toggle dashboard edit mode | N/A           | N/A                          | <kbd>Shift</kbd> + <kbd>Ctrl</kbd> + <kbd>E</kbd>  |
 
-_Note that the words Touch and Tap are synonymous with mouse click._
-<br/>
+> Note that the words Touch and Tap are synonymous with mouse click.
 
 ## General Layout
 <img src="../../assets/help-docs/img/general-layout.png" alt="Sidebar Menus" title="Sidebar Menus" width="100%">
@@ -101,11 +100,11 @@ If multiple devices log in with the same Signal K user to share configuration, t
 | Wrong device switched | Two devices share same Instance Name—rename one. |
 | Works, then stops | Network drop or Signal K reconnect in progress—wait a few seconds or reload. |
 
-### Tips
-- Keep Instance Names short but meaningful (e.g. Mast, Helm, NavTV).
-- For unattended displays, enable the browser’s keep‑awake / no‑sleep features if supported.
-- Combine with Night Mode + per‑profile layouts for role‑specific remote switching.
-- Use different Signal K users if you want fully isolated configurations.
+> **Tips**
+>- Keep Instance Names short but meaningful (e.g. Mast, Helm, NavTV).
+>- For unattended displays, enable the browser’s keep‑awake / no‑sleep features if supported.
+>- Combine with Night Mode + per‑profile layouts for role‑specific remote switching.
+>- Use different Signal K users if you want fully isolated configurations.
 
 ### Privacy / Safety Note
 Anyone with access to a logged‑in controlling KIP instance can switch dashboards on enabled targets. Only enable remote management on displays where that is acceptable.