SignalK webapp for browsing, modifying, and creating paths for testing and simulation
npm install signalk-whatif-helperA SignalK webapp dev utility for modifying, and creating SignalK paths for testing and simulation.
- Path Browser: List and filter all SignalK paths with real-time values
- Value Editor: Select any path and modify its value with custom source labels
- Path Creator: Create new paths with initial values, metadata, and unit definitions
- PUT Handler Management: Register and manage PUT handlers for paths
``bash`
npm install signalk-whatif-helper
`bash`
cd ~/.signalk/node_modules
git clone https://github.com/motamman/signalk-whatif-helper.git
cd signalk-whatif-helper
npm install
npm run build
Then restart SignalK server.
After installation, access the webapp from the SignalK webapp menu or navigate directly to:
``
http://localhost:3000/signalk-whatif-helper/
Browse all available SignalK paths with filtering options:
- Search: Filter paths by name (e.g., "navigation", "tanks")
- Has Value: Show only paths with non-null values
- Has Meta: Show only paths with metadata defined
- Base Unit: Filter by unit type (m/s, rad, K, etc.)
Click "Edit" on any path to open it in the Value Editor.
Modify values for existing paths:
- Current Value: Displays the live value with real-time WebSocket updates
- Metadata: Shows units and description if available
- New Value: Enter a new value (supports numbers, strings, booleans, and JSON objects)
- Source: Customize the $source label (defaults to )
- Set Value: Inject the value directly into SignalK's data model
- PUT Value: Send via SignalK's PUT API (only available if a PUT handler is registered)
Create new SignalK paths:
- Path: Enter the path name (e.g., tanks.fuel.1.currentLevel)
- Initial Value: Set the starting value
- Base Unit: Select from common SignalK units (ratio, m/s, K, Pa, bool, etc.)
- Description: Optional description for the path metadata
- Enable PUT: Optionally register a PUT handler for the new path
Manage PUT handlers for paths:
- View all registered PUT handlers
- Register new PUT handlers for existing paths
- Unregister PUT handlers
- Test PUT functionality
The plugin exposes the following REST API endpoints:
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /plugins/signalk-whatif-helper/paths | List all paths (supports query filters) |/plugins/signalk-whatif-helper/paths/:path
| GET | | Get single path details |/plugins/signalk-whatif-helper/paths
| POST | | Create a new path |/plugins/signalk-whatif-helper/value/:path
| PUT | | Set value on a path |
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /plugins/signalk-whatif-helper/puts | List registered PUT handlers |/plugins/signalk-whatif-helper/puts
| POST | | Register a PUT handler |/plugins/signalk-whatif-helper/puts/:path
| DELETE | | Unregister a PUT handler |
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /plugins/signalk-whatif-helper/units | List available base units |/plugins/signalk-whatif-helper/created
| GET | | List paths created by this plugin |
Connect to /plugins/signalk-whatif-helper/stream for real-time path value updates.
Subscribe to paths:
`json`
{
"type": "subscribe",
"paths": ["navigation.speedOverGround", "tanks.fuel.0.currentLevel"]
}
Unsubscribe:
`json`
{
"type": "unsubscribe",
"path": "navigation.speedOverGround"
}
When modifying values, the plugin uses a distinctive source label to identify injected data:
- For existing paths: (e.g., n2k-01.whatif-helper)whatif-helper
- For new paths:
This makes it easy to identify simulated/test values in SignalK's data model.
Inject specific values to test how your instrument displays handle edge cases:
`javascript`
// Test speedometer at maximum
PUT /plugins/signalk-whatif-helper/value/navigation.speedOverGround
{ "value": 25.72 } // ~50 knots
Create virtual sensors for development:
`javascript`
// Create a virtual tank sensor
POST /plugins/signalk-whatif-helper/paths
{
"path": "tanks.fuel.virtual.currentLevel",
"value": 0.75,
"meta": { "units": "ratio", "description": "Virtual fuel tank" },
"enablePut": true
}
Test how your SignalK consumers react to specific data patterns without needing physical sensors.
Important: Values injected by this plugin are ephemeral and will not persist across SignalK server restarts. This is by design for testing and simulation purposes.
`bash`
npm install
npm run build
`bash`
npm run dev
```
signalk-whatif-helper/
├── src/
│ ├── index.ts # Plugin entry point
│ ├── types.ts # TypeScript interfaces
│ ├── PathManager.ts # Path operations
│ ├── PutHandlerManager.ts # PUT handler management
│ └── WebSocketServer.ts # Real-time updates
├── public/
│ ├── index.html # Webapp UI
│ └── js/
│ ├── app-main.js # Initialization
│ ├── app-api.js # API layer
│ ├── app-state.js # State management
│ ├── app-utils.js # Utilities
│ ├── app-paths.js # Path browser
│ ├── app-editor.js # Value editor
│ ├── app-create.js # Path creation
│ └── app-puts.js # PUT handlers
└── dist/ # Compiled JavaScript
- SignalK Server v1.x or v2.x
- Node.js 16+
MIT License - see LICENSE file.
Maurice Tamman
Contributions are welcome! Please open an issue or submit a pull request at:
https://github.com/motamman/signalk-whatif-helper
For bugs and feature requests, please use the GitHub Issues page.