Skip to content

v0.1.0 - Initial Release

Choose a tag to compare

View all tags
@bramd bramd released this 25 Oct 23:36
· 37 commits to main since this release
v0.1.0
556ef37
This commit was signed with the committer’s verified signature.
bramd Bram Duvigneau
SSH Key Fingerprint: /EAv8uMnQfYQvI0aJal38GFCyNMSPusC3Xn/UuHjVKE
Verified
Learn about vigilant mode.

QStream Home Assistant Integration - Initial Release

This is the first production-ready release of the QStream Home Assistant custom integration for BUVA QStream 2.0 ventilation fans.

Features

Fan Control

  • 5 Preset Modes: Low, Medium, High, Turbo, and Boost
    • Low through Turbo use 4-hour timer duration
    • Boost uses 10-minute timer duration (matching official app)
    • Presets map to device levels 0-4
  • Percentage Control: Full 0-100% speed control via slider
  • Automatic Preset Detection: UI shows active preset when speed matches
  • On/Off Control: Turn fan timer on or cancel timer

Demand Control

  • Switch Entity: Enable/disable automatic speed adjustment based on air quality
  • Preserves current speed when toggling demand control

Sensors

  • Air Quality Index (AQI): Primary sensor with caching for reliability
  • Flow Sensors: Analog flow, set flow, actual flow (diagnostic)
  • Timer/Schedule: Timer remaining, schedule enabled (diagnostic)
  • Binary Sensors: Valve state, timer active, schedule enabled (diagnostic)

Reliability Features

  • DataUpdateCoordinator: 30-second polling interval with automatic retry
  • AQI Caching: Returns last known value during intermittent failures
  • Request Delays: 0.5s delay between commands to prevent HTTP 503 errors
  • Immediate State Updates: Uses async_refresh() for instant UI feedback

Installation

HACS (Recommended)

  1. Add custom repository: https://github.com/bramd/qstream-ha
  2. Search for "QStream" in HACS
  3. Click Install
  4. Restart Home Assistant
  5. Add integration via Settings → Devices & Services → Add Integration

Manual

  1. Copy custom_components/qstream to your HA config directory
  2. Restart Home Assistant
  3. Add integration via Settings → Devices & Services → Add Integration

Configuration

  • Host: IP address or hostname of your QStream device
  • Name: Friendly name for the device (optional, defaults to "QStream Fan")

Requirements

  • Home Assistant 2025.4.4 or newer
  • Python 3.11 or newer
  • BUVA QStream 2.0 device on local network

Dependencies

  • qstream>=0.2.0 - Python library for QStream device communication

Known Limitations

  • Integration polls device every 30 seconds (no push notifications)
  • AQI endpoint may occasionally return HTTP 503 (handled gracefully with caching)
  • Device can only handle one command at a time (handled with delays)

Technical Details

  • IoT Class: Local Polling
  • Config Flow: UI-based configuration
  • Entity Platform: Fan, Switch, Sensor, Binary Sensor
  • Architecture: DataUpdateCoordinator pattern with CoordinatorEntity

Credits

Built with ❤️ using Claude Code

Support

Report issues at: https://github.com/bramd/qstream-ha/issues

Assets 2
Loading