A custom Home Assistant integration for the BleBox smartWindowBox (API level 20180604).
This integration provides:
- ✅ Cover entity (open / close / stop)
- ✅ Emulated set position (0–100%)
- ✅ Favorite position support
- ✅ Next step support
- ✅ Rain sensor as binary sensor
- ✅ Cover and rain sensor grouped under one BleBox device
- ✅ Real-time movement metadata
- ✅ Progress %, remaining time & direction tracking
- ✅ Proper Home Assistant entity services with UI selectors
This fork includes position-scale fixes, native endpoint movement, faster status updates, interruptible position control, and improved error handling. The original project is Sjnaaf/bleBoxSmartWindowBox.
-
Open HACS in Home Assistant.
-
Go to Integrations.
-
Click the ⋮ (top right) → Custom repositories.
-
Add this repository URL:
https://github.com/pepijnnichting/bleBoxSmartWindowBox -
Choose Category: Integration.
-
Click Add.
-
Search for BleBox smartWindowBox in HACS and install it.
-
Restart Home Assistant.
-
Add the integration via: Settings → Devices & Services → Add integration.
The cover and rain sensor belong to one BleBox device in Settings → Devices &
Services. Its identity is based on the device ID returned by the BleBox API.
The device page shows the manufacturer, model, available hardware and firmware
versions, and a link to the device's local web interface. The cover uses Home
Assistant's window device class.
Existing entity unique IDs are preserved, so the update does not require recreating automations or removing the configured integration.
The smartWindowBox motor is exposed as a standard Home Assistant cover entity:
OpenCloseStopSet position (0=closed, 100=open)
For intermediate positions, the integration emulates position setting because the BleBox API does not support direct position setting:
- Sending open or close command
- Polling device state
- Stopping the motor once the target position is reached
Fully closed (0%) and fully open (100%) use the native close/open commands. The device completes its calibrated travel without an early stop based on a reported percentage.
All exposed position attributes use the Home Assistant scale (0% closed, 100% open). device_position retains the raw BleBox scale (0% open, 100% closed). Existing automations using numeric positions must invert their targets and comparisons (100 - old_position) when upgrading.
A new cover command cancels any previous intermediate-position controller before sending the new command. Stop, favorite, next-step, and new position requests all take precedence over the old target. Cancelling an active position-control service or unloading the integration also cancels the controller and attempts to stop the motor.
If position control loses contact with the device or exceeds its travel timeout, it attempts a stop and reports an error. A stop cannot be guaranteed while the device is unreachable; the original error is preserved if the stop attempt also fails.
While the window is moving (open, close, favorite, or manual movement), the following attributes are available:
| Attribute | Description |
|---|---|
moving |
True while motor is active |
move_direction |
opening or closing |
move_target_position |
Desired target |
move_start_position |
Starting position |
move_elapsed_s |
Seconds since movement started |
estimated_total_s |
Estimated full travel time |
estimated_remaining_s |
Remaining estimated time |
move_progress_pct |
Movement progress (0–100%) |
These update live during movement.
When the motor changes direction or target, progress starts from the newly observed position and the elapsed time and direction-specific travel estimate are reset.
Device state is refreshed every second while a motor is moving and every five seconds while idle. Commands trigger an immediate refresh. Intermediate-position control also publishes each direct device reading to Home Assistant.
Use Home Assistant 2026.10 or newer when exposing the cover through HomeKit Bridge. In 2026.9.3 the bridge can retain an old target position during movement started outside Apple Home, causing iOS to display the opposite direction even when Home Assistant reports the correct direction. The bridge correction is in Home Assistant; updating this custom integration alone does not fix that issue.
If a movement stops early from Apple Home, enable both loggers temporarily in Home Assistant Developer Tools → Actions:
action: logger.set_level
data:
custom_components.blebox_smartwindowbox: debug
homeassistant.components.homekit: debugReproduce one movement and inspect the logs for the requested Home Assistant
position, native command, and stop reason (target reached, cancellation,
timeout, or connection failure). Include the HomeKit lines immediately before
the stop when reporting the issue. Debug logging does not change motor behavior.
After collecting the logs, run the same action with both levels set to warning
or restart Home Assistant to restore the configured logging levels.
The built-in rain sensor is exposed as a:
binary_sensor.<device_name>_rain
- ON = Rain detected
- OFF = No rain
Additional attributes:
trendelapsedTimeSstateiconSet
The integration registers proper entity services with UI selectors:
| Service | Description |
|---|---|
blebox_smartwindowbox.favorite |
Move to configured favorite position |
blebox_smartwindowbox.next_step |
Perform next-step movement |
blebox_smartwindowbox.set_position |
Move to specific position (0–100) |
These appear in Developer Tools → Actions.
- Download or clone this repository.
- Copy the folder:
custom_components/blebox_smartwindowbox/
into your Home Assistant configuration directory:
config/custom_components/
Your final structure should look like:
config/
└── custom_components/
└── blebox_smartwindowbox/
├── __init__.py
├── api.py
├── binary_sensor.py
├── brand/
│ └── icon.png
├── config_flow.py
├── const.py
├── coordinator.py
├── cover.py
├── manifest.json
├── services.yaml
├── strings.json
└── translations/
└── en.json
-
Restart Home Assistant:
- Settings → System → Restart
Download the latest integration files through HACS, or replace the complete
custom_components/blebox_smartwindowbox/ folder for a manual installation. Restart
Home Assistant afterward. Existing integration entries can remain configured.
If upgrading from the original position scale, review automations and scripts
with numeric position targets: Home Assistant now uses 0% closed, 100% open.
Invert old values with 100 - old_position. Native open, close, stop, and favorite
actions keep their meaning.
After restart:
- Go to Settings → Devices & Services
- Click Add Integration
- Search for:
BleBox smartWindowBox
- Enter the IP address or hostname of your device
- Finish setup
The integration will automatically detect:
- The motor
- The rain sensor
The device appears as a standard cover entity:
cover.motor_1
You can:
- Open
- Close
- Stop
- Drag the position slider
Position scale:
0 = Fully Closed
100 = Fully Open
Go to:
Developer Tools → Actions
Select:
blebox_smartwindowbox.favorite
Choose your cover entity and run.
Service:
blebox_smartwindowbox.set_position
You will get a slider selector (0–100).
Example:
Position: 60
The integration will:
- Move in correct direction
- Track progress
- Stop when the reported position reaches the target within the configured tolerance
Go to:
Developer Tools → States
Open your cover entity and watch:
move_progress_pctestimated_remaining_smove_elapsed_s
These update live while the window moves.
The defaults are defined in custom_components/blebox_smartwindowbox/const.py:
POSITION_TOLERANCE = 1
POLL_INTERVAL_SEC = 0.35
EXTRA_STOP_DELAY_SEC = 0.15
MOVING_UPDATE_INTERVAL_SECONDS = 1
UPDATE_INTERVAL_SECONDS = 5Intermediate-position control polls every 0.35 seconds and uses a tolerance of one percentage point. After reaching the target, a second stop is sent after 0.15 seconds to reduce coasting. A newer command cancels the old controller, including a pending second stop.
Regular status polling runs every second during movement and every five seconds while idle. Fully open and fully closed requests use native commands and do not use the intermediate-position stop loop.
These are source-code constants, not options in the integration UI. Lower polling intervals increase API traffic. Physical accuracy depends on calibration, response time, and motor coasting.
| State | Meaning |
|---|---|
| 0 | Closing |
| 1 | Opening |
| 2 | Idle (intermediate position) |
| 3 | Idle (fully closed) |
| 4 | Idle (fully open) |
- BleBox smartWindowBox
- API level 20180604
- Validated with a single-motor configuration
- Development checks passed on Home Assistant 2026.9.3 and 2026.10.1
- Home Assistant 2026.10 or newer recommended for HomeKit Bridge
- Intermediate-position control is emulated; endpoint movement uses native commands
- Accuracy depends on motor calibration
- Rapid repeated commands may slightly affect precision
With Home Assistant installed in the active Python environment, run the regression tests from the repository root:
python -m unittest discover -s tests -vThese cover position conversion, native endpoints, intermediate movements, command replacement and cancellation, network errors, timeouts, polling intervals, and progress resets after a direction or target change. API tests use a local HTTP server; other device responses are simulated. Physical travel still needs to be verified on a real device. GitHub Actions runs these tests on Home Assistant 2026.9.3 and 2026.10.1 with Python 3.14 for pushes and pull requests, alongside Hassfest validation. The suite also checks actual Home Assistant device/entity registration and identity preservation after reloading the integration.
This version includes the corrected Home Assistant position scale, native endpoint
commands, faster status updates, interruptible position control, improved error
handling, movement-progress resets, shared device metadata, and the window
device class. Upgrade instructions and the position-scale migration are described
above.
- Multi-motor support
- Dedicated progress sensor entity
- Configurable precision via UI
- Automatic overshoot compensation tuning
MIT License