Signal K Open Wind Plugin

A robust Signal K plugin for integrating OpenWind mast wind sensor data with automatic reinstallation capabilities. This repository is a community Signal K integration; the OpenWind instrument (AWA/AWS, compass, motion, BLE, and related ecosystem) is designed and sold by the team behind openwind.de.

Table of Contents

• Features
• Requirements
• Installation
  • Quick Install
  • Manual Install
• Uninstall
• Configuration
• Plugin Settings
• UDP Data Format
• Python Dependencies
• Troubleshooting
• Development
• Contributing
• License
• Support
• Acknowledgements

Features

• Wind Data Integration: Processes apparent wind speed and angle from OpenWind sensor
• Mast Rotation Compensation: Determines mast rotation via OpenWind Yaw data
• Subtracts mast yaw from available NMEA2000 boat heading to output mast rotation compensated wind data
• use existing SignalK facilities to send wind data to N2K network.
• Debug Data: Comprehensive debug information for monitoring and troubleshooting
• Auto-Reinstallation: Survives Signal K server updates automatically

Requires

• OpenWind Sensor
• RaspberryPi with NMEA2000/CANBUS communication capability
• NMEA2000 heading data from some external source

Installation

Quick Install

git clone https://github.com/vepkenez/signalk-open-wind-plugin.git
cd signalk-open-wind-plugin
npm run install

Alternative: Direct Installation

# Install directly from GitHub
cd ~/.signalk
npm install https://github.com/vepkenez/signalk-open-wind-plugin.git
npm run install

Manual Install (Advanced)

If you prefer manual installation:

1. Copy plugin to Signal K directory:

   cd ~/.signalk
   npm install /path/to/signalk-open-wind-plugin

2. Create startup script:

   # Create startup-plugins.sh in ~/.signalk/
   # (See install.sh for the script content)

3. Modify Signal K server startup script:

   # Modify ~/.signalk/signalk-server to call startup-plugins.sh

Uninstall

If you installed the plugin via the Signal K app store and then ran ./install.sh or npm run setup, the setup script has modified your Signal K config directory so the plugin is automatically reinstalled on every server start. That prevents a normal app-store uninstall from sticking: after you uninstall, the next restart reinstalls the plugin.

To fully uninstall:

1. Revert the setup changes so the server no longer reinstalls the plugin:

   • Restore the original ~/.signalk/signalk-server from the backup (if it exists):

     cp ~/.signalk/signalk-server.backup.YYYYMMDD_HHMMSS ~/.signalk/signalk-server

     Use the latest signalk-server.backup.* file. Or run the provided script:

     ./uninstall-setup.sh

   • Remove the reinstall script so this plugin is not re-added on start:

     rm ~/.signalk/startup-plugins.sh

     If you use startup-plugins.sh for other plugins, edit it instead and remove only the line check_and_install "signalk-open-wind-plugin".

2. Uninstall the plugin via the Signal K app store (or run cd ~/.signalk && npm uninstall signalk-open-wind-plugin).

3. Restart Signal K. The plugin should stay uninstalled.

Optional log file (only created if you enabled logging in the plugin): you can delete ~/.signalk/open-wind-plugin.log if present.

Configuration

The plugin provides the following Signal K data paths:

Wind Data

• environment.wind.speedApparent - Apparent wind speed (m/s)
• environment.wind.angleApparent - Apparent wind angle (rad)

Sensor Data

• sensors.mast.yaw - Raw sensor yaw value (rad)
• sensors.mast.windAngle - Raw wind angle from sensor (rad)

Debug Data

• debug-awa-degrees - Apparent wind angle in degrees
• debug-wind-speed-knots - Wind speed in knots
• debug-mast-rotation-degrees - Mast rotation in degrees
• debug-sensor-yaw-degrees - Raw sensor yaw in degrees

Plugin Settings

Configure the plugin through the Signal K admin interface:

• Max Wind Speed (m/s): Maximum simulated wind speed (default: 10)
• Update Interval (ms): Data update frequency (default: 1000)
• Yaw Sensor Offset (degrees): Offset to calibrate sensor yaw (default: 0)

UDP Data Format

The plugin listens for NMEA sentences on UDP port 2000:

• $WIMWV,angle,R,speed,N,A*checksum - Wind data
• $WIHDM,heading,M*checksum - Heading data

Python Dependencies

The plugin requires Python with the following packages:

• numpy
• bleak (for Bluetooth communication)

These are automatically installed when you run npm run install. The installer will try multiple methods to handle different Python environments.

Manual Installation (if automatic fails)

If the automatic installation fails (common on newer Ubuntu/Debian systems with externally managed Python environments):

# Try normal installation first
pip3 install numpy bleak

# If that fails, try with --break-system-packages
pip3 install --break-system-packages numpy bleak

# Or install for user only
pip3 install --user numpy bleak

Troubleshooting Python Installation

Error: "externally-managed-environment"

• This is a security feature in newer Python systems
• Use --break-system-packages flag (as shown above)
• Or use --user flag for user-only installation

Troubleshooting

Plugin Not Loading After Server Update

The automatic reinstallation system should handle this, but if issues persist:

1. Check the startup script:

   ~/.signalk/startup-plugins.sh

2. Verify plugin installation:

   ls -la ~/.signalk/node_modules/open-wind

3. Check Signal K logs:

   tail -f ~/.signalk/skserver-raw_*.log

Debug Data Not Appearing

1. Verify plugin is enabled in Signal K admin interface
2. Check plugin configuration settings
3. Monitor debug output in Signal K logs

Python Process Issues

1. Verify Python environment:

   /home/damon/penv/bin/python --version

2. Check Python dependencies:

   /home/damon/penv/bin/python -c "import numpy, bleak"

Wind not visible on NMEA 2000 network

Wind is sent to N2K by the signalk-to-nmea2000 plugin (not by this plugin). This plugin only publishes to Signal K; signalk-to-nmea2000 converts that to PGN 130306 and emits it. If other devices don’t see wind:

1. Plugin config (Signal K → Server → Plugins → Signal K to NMEA 2000)

   • Ensure WINDv2 is Enabled.
   • Set Source for environment.wind.angleApparent to your open-wind source (e.g. open-wind.urn:mrn:signalk:uuid:...).
   • Set Source for environment.wind.speedApparent to the same source (or leave blank to use any source). Saving applies the change.

2. Confirm Signal K has wind

   • In Admin UI, Data Browser (or REST): check environment.wind.angleApparent and environment.wind.speedApparent and that their $source is the open-wind plugin.

3. Confirm N2K connection can write

   • In Server → Data Connections, the NMEA 2000 connection (e.g. can0) must be able to write (not read-only). If your setup only has an “input” pipe, add or use a connection that supports output (same interface is often bidirectional).

4. Check for PGN 130306 on the bus
   On the Pi (or host with can0):

   candump can0 | grep -E '130306|1FD02'

   If you see lines when wind is updating in Signal K, the plugin is sending; if not, the problem is before the bus (config or connection).

5. Enable debug (optional)
   In Signal K Admin, enable debug logging, restart, then check the server log for lines like emit nmea2000JsonOut to confirm the N2K plugin is emitting wind PGNs.

Development

Live webapp development

You can run Signal K in Docker and the webapp with hot reload so frontend changes appear immediately. The dev server (Vite) requires Node 18+.

1. Install dev dependency (once): npm install
2. Start Signal K in Docker: npm run dev:docker
   • Starts signalk/signalk-server with the plugin installed and enabled; config is persisted in a Docker volume.
3. Start the dev server: npm run dev
   • Serves public/ at http://localhost:5173/ with Vite and proxies /signalk (API + WebSocket) to the container.
4. Open http://localhost:5173/ in your browser. Edit files in public/ (e.g. index.html) and save; the page will reload automatically.

To stop the container: docker compose -f docker-compose.dev.yml down.

File Structure

signalk-open-wind-plugin/
├── plugin/
│   ├── index.js              # Main plugin code
│   └── OpenWind.py           # BLE → UDP bridge (Python/bleak)
├── public/
│   └── index.html            # Web dashboard
├── package.json              # Plugin metadata
├── install.sh                # Optional post-install setup (npm run setup)
├── uninstall-setup.sh        # Revert install.sh changes so app-store uninstall works
├── install-python-deps.sh    # Python dependency installer (runs on postinstall)
├── test-docker.sh            # Docker integration test
└── README.md

Testing

The project includes a Docker-based integration test that spins up a clean SignalK server, installs the plugin, and verifies everything works. Requires Docker.

npm test
# or
./test-docker.sh

The test will:

1. Start a fresh SignalK server container
2. Install the plugin via npm install
3. Enable the plugin and restart
4. Verify all Signal K data paths are publishing
5. Verify the webapp is served at /open-wind
6. Clean up the container

The full run takes about a minute.

License

MIT License - see LICENSE file for details.

Disclaimer

IMPORTANT SAFETY NOTICE: This software is provided for educational and experimental purposes. The authors and contributors are not responsible for any damage, injury, or loss that may result from the use of this software in marine environments. Always verify wind data with multiple sources and never rely solely on this plugin for navigation or safety-critical decisions. Use at your own risk.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues and questions:

• Check the troubleshooting section above
• Review Signal K server logs
• Verify plugin configuration in Signal K admin interface

Acknowledgements

OpenWind hardware — This plugin exists to bring OpenWind sensor data into Signal K. Special thanks to the OpenWind manufacturer and product team for the device, documentation, and BLE broadcast behaviour that make integrations like this possible.

OpenWind is a trademark of its respective owner; this plugin is not affiliated with or endorsed by the OpenWind manufacturer or openwind.de unless they say otherwise. For calibration, firmware, apps, and official support, use the manufacturer’s site and apps.