Maico Powerbox WS 75

A custom integration for Home Assistant to control and monitor the Maico Powerbox WS 75 ventilation system. The device provides decentralized ventilation with heat and humidity recovery.

With this integration, you can monitor and manage key features of the Maico Powerbox WS 75, including operation mode and ventilation level switching, monitoring of temperature and air humidity values and controlling device parameters directly from Home Assistant.

Prerequisites

The integration uses the device's ability to communication via modbus. You have to make sure that the powerbox is connected to your Network (either wired or WiFi) and modbus is activated. This requires to disable the AIR@home feature. You'll probably have to connect to the device via USB using the 'KWL-Inbetriebnahme-Software' in order to set things up.

Features

• Operation Mode Control: Switch between the different operation modes.
• Ventilation Level Control: Switch between the different ventilation levels.
• Control device parameter: Change sleep function duration or reset error memory.
• Temperature and Humidity Monitoring: Real-time tracking of temperature valuess and air humidity.
• Real time Energy Monitoring: Real-time tracking of current power consumption.
• Real time device parameter monitoring: Real-time tracking of device parameters (air flow, internal states, etc.)

Installation

1. Download via HACS:

   • Make sure HACS is installed on your Home Assistant.
   • In HACS, go to Integrations > + Explore & Download Repositories.
   • Add the custom repository https://github.com/markusmauch/powerbox-ws-75-custom-integration.
   • Click Download and follow the prompts to add the integration.

2. Manual Installation:

   • Clone or download this repository.
   • Copy the content of the repository folder to the custom_components/powerbox directory within your Home Assistant configuration.
   • Restart Home Assistant.

Configuration

After installation, click the 'Add Integration' button in 'Settings', 'Devices and Services' and search for 'powerbox'. Then add the connection parameters to connect with your device:

name: "Maico Powerbox WS 75" host: IP address of your Maico Powerbox device port: Port (default is 80, change if necessary) unit_id: # The modbus unit id (10 is default)

Screenshots

Changelog

Version 2025.12.2 (December 2024)

This release focuses on stability and observability improvements for WiFi/Modbus TCP connections while maintaining the proven round-robin polling pattern.

Stability Improvements

• Connection Timeout: Added 10-second timeout to all Modbus operations (connect, read, write)
  • Prevents indefinite hangs on WiFi issues
  • Faster failure detection and automatic recovery
  • Clean resource cleanup on timeout
• Smart Logging: Improved logging reduces noise while providing better visibility
  • Unavailability logged once (not spammy)
  • Recovery events logged with failure count
  • Debug logging for detailed troubleshooting

Monitoring & Diagnostics

• Connection Health Metrics: Added diagnostics tracking
  • Connection success/failure counts
  • Success rate calculation
  • Current availability status
  • Write queue depth visibility
• Enable Detailed Logging: Add to configuration.yaml for troubleshooting:

  logger:
    logs:
      homeassistant.components.powerbox_ws_75: debug

Technical Details

• Maintains proven round-robin polling (1 block per 5-second cycle)
• 10-second timeout applied to connection, read, and write operations
• Health tracking with minimal performance impact
• No changes to connection frequency or polling pattern

Note: This is a conservative update focused on reliability and observability. The working polling pattern remains unchanged to respect the fragile Modbus hardware.

Version 2025.12.1 (December 2024)

This release brings the integration up to modern Home Assistant standards with significant code quality improvements and guideline compliance.

Breaking Changes

• Configuration Flow: Device name and polling interval are no longer user-configurable
  • Device names are now auto-generated as "Powerbox WS 75 (hostname)"
  • Polling interval is hardcoded at 5 seconds (per Home Assistant guidelines)
  • Action Required: Existing configurations will continue to work, but device names may change on next reload

New Features

• Connection Validation: Config flow now tests connection before creating entry
• Reconfigure Flow: Update connection details without removing and re-adding the device
• Duplicate Prevention: Prevents adding the same device twice
• Diagnostics Support: Added diagnostics data collection for troubleshooting
• English Translations: Complete translation support with strings.json

Code Quality Improvements

• Runtime Data Pattern: Migrated from hass.data to typed ConfigEntry.runtime_data
• Type Hints: Comprehensive type annotations throughout codebase using Python 3.13+ syntax
• Async Methods: All entity control methods are now properly async
  • async_turn_on / async_turn_off for switches
  • async_press for buttons
  • async_set_native_value for number entities
  • async_select_option for select entities
• Modern Entity Pattern: All entities use has_entity_name with translation_key
• Entity Descriptions: Migrated to dataclass-based EntityDescription pattern
• Better Error Handling: Proper use of ConfigEntryNotReady, UpdateFailed, and CannotConnect exceptions
• Removed Deprecated Code: Eliminated @HANDLERS.register and CONNECTION_CLASS

Technical Details

• Removed pymodbus requirement (uses Home Assistant's bundled version)
• Added integration_type: device to manifest
• Improved coordinator error handling and connection management
• Binary sensor now uses is_on property instead of state strings
• All platforms modernized with consistent patterns

Developer Notes

• Code now follows Home Assistant 2025 guidelines
• Ready for potential Home Assistant Core submission
• Improved maintainability and code organization

Version 2025.10.1 (Previous Release)

• Initial HACS release
• Basic Modbus TCP support
• Core sensor, switch, select, button, and number entities

Support

If you want to support my work feel free to