Feature Request: Home Assistant Add-on for BlueRiver Control Server

[switch180]

Problem

Currently, users must run the BlueRiver Control Server (via IPA Manager) on a separate Windows machine to use this integration. This creates several limitations:

• External Dependency: Requires a Windows PC (Win10/Win11) to remain running 24/7
• Additional Hardware: Users need a separate machine beyond their Home Assistant server
• Setup Complexity: Multi-step setup process across different systems
• Network Requirements: The Windows PC must be on the same subnet as SDVoE devices
• Maintenance: Another system to maintain, update, and troubleshoot

Proposed Solution

Create a Home Assistant add-on that runs the BlueRiver Control Server process natively within Home Assistant, eliminating the need for external Windows hardware.

Benefits

✅ Self-Contained Solution

• 100% HA-based - no external dependencies
• Single system to manage and maintain
• Simplified architecture

✅ Easier Setup

• Install add-on from HA UI
• Configure port and settings
• Start integration - done!

✅ Better Integration

• Lifecycle tied to Home Assistant
• Auto-start on HA restart
• Unified logging and monitoring

✅ Cross-Platform Support

• Works on HA OS, Docker, Supervised installations
• No Windows requirement
• Broader hardware compatibility

✅ Cost Savings

• No need for dedicated Windows machine
• Reduced power consumption
• Lower hardware costs

Technical Considerations

Add-on Structure

# config.yaml
name: BlueRiver Control Server
version: 1.0.0
slug: blueriver_control
description: SDVoE API server for RiverLink integration
arch:
  - aarch64
  - amd64
  - armv7
ports:
  6970/tcp: 6970
options:
  port: 6970
  log_level: info
schema:
  port: port
  log_level: list(debug|info|warning|error)

Implementation Approaches

Option 1: Docker Container

• Package blueriver_control binary in Docker image
• Expose port 6970 for API access
• Configure via add-on options

Option 2: Python Reimplementation

• Reimplement SDVoE API server in Python
• Based on publicly documented SDVoE API specification
• Native Python integration with HA

Option 3: Wine/Compatibility Layer (if needed)

• Run Windows binary via Wine if no native option
• Less ideal but potentially workable

Configuration Options

• Port: Default 6970, user-configurable
• API Version: SDVoE API version to implement
• Log Level: Debug, Info, Warning, Error
• Auto-Discovery: Enable/disable device discovery

Integration with RiverLink

# Example configuration
riverlink:
  host: core-blueriver-control  # Add-on hostname
  port: 6970
  api_version: "2.13.0.0"

The integration would automatically detect the local add-on and configure itself accordingly.

Alternative Approaches

Document Linux Installation

If native Linux version of blueriver_control exists:

• Document installation on Linux systems
• Docker container for non-HA deployments
• Still better than Windows-only requirement

Community Server Implementation

If BlueRiver Control Server isn't redistributable:

• Community-developed SDVoE API server
• Based on public SDVoE API documentation
• Open-source alternative implementation

User Impact

Current Workflow:

1. Set up Windows PC
2. Download IPA Manager
3. Install and configure IPA Manager
4. Keep Windows PC running 24/7
5. Install HA integration
6. Configure to point to Windows PC

With Add-on:

1. Install add-on from HA
2. Start add-on
3. Install integration (auto-configures to add-on)
4. Done!

Success Criteria

• Add-on available in HA add-on store (or custom repository)
• Supports all SDVoE API functions used by integration
• Compatible with major HA installation types (HA OS, Docker, Supervised)
• Configurable via HA UI
• Auto-starts with Home Assistant
• Integration auto-discovers add-on

Priority

🟡 Medium-High

While the current Windows-based solution works, an add-on would significantly improve user experience and adoption.

Related Documentation

• Getting Started Guide - Current Windows setup process
• README.md - Integration overview

Next Steps

1. Research technical feasibility of each implementation approach
2. Determine if blueriver_control binary can be redistributed
3. Investigate creating reference implementation from SDVoE API docs
4. Create add-on proof-of-concept
5. Test with real SDVoE hardware
6. Documentation and release