Problem Statement
There is no domain helper for vacuum entities. Users must use raw service calls to start, pause, dock, or locate a vacuum, and manually parse attributes for battery level, fan speed, and cleaning status. This is inconsistent with the typed domain experience provided for other complex device domains like Climate and Media Player.
Proposed Solution
Add a Vacuum domain class in src/haclient/domains/vacuum.py that exposes intent-specific methods for vacuum control.
Core capabilities:
- State properties:
is_cleaning, is_docked, is_idle, is_paused, is_returning, is_error, battery_level, fan_speed, fan_speed_list
- Actions:
start(), pause(), stop(), return_to_base(), locate(), set_fan_speed(speed), send_command(command, **params)
- Listener decorators:
on_start(), on_dock(), on_error(), on_battery_change()
- Graceful degradation: Methods like
locate(), set_fan_speed(), and send_command() should detect feature support and degrade safely for vacuums that do not support them.
Use Case
A smart home control panel needs to display vacuum status (cleaning, docked, battery) and let users start/stop cleaning or send the vacuum home. Without a Vacuum domain, all operations require unstructured service payloads with no state introspection.
API Sketch
async with HAClient(url, token) as ha:
robo = ha.vacuum("vacuum.roborock")
# State
robo.is_cleaning # True
robo.battery_level # 72
robo.fan_speed # "balanced"
# Actions
await robo.pause()
await robo.return_to_base()
await robo.set_fan_speed("turbo")
await robo.locate()
# Listeners
@robo.on_dock
async def docked(event):
print("Vacuum returned to dock")
Alternatives Considered
- Raw service calls — works but defeats the purpose of a typed client library.
- Generic on/off helper — vacuums have rich state (cleaning, docked, returning, error) and multiple actions that do not fit a binary model.
Scope
Problem Statement
There is no domain helper for
vacuumentities. Users must use raw service calls to start, pause, dock, or locate a vacuum, and manually parse attributes for battery level, fan speed, and cleaning status. This is inconsistent with the typed domain experience provided for other complex device domains like Climate and Media Player.Proposed Solution
Add a
Vacuumdomain class insrc/haclient/domains/vacuum.pythat exposes intent-specific methods for vacuum control.Core capabilities:
is_cleaning,is_docked,is_idle,is_paused,is_returning,is_error,battery_level,fan_speed,fan_speed_liststart(),pause(),stop(),return_to_base(),locate(),set_fan_speed(speed),send_command(command, **params)on_start(),on_dock(),on_error(),on_battery_change()locate(),set_fan_speed(), andsend_command()should detect feature support and degrade safely for vacuums that do not support them.Use Case
A smart home control panel needs to display vacuum status (cleaning, docked, battery) and let users start/stop cleaning or send the vacuum home. Without a Vacuum domain, all operations require unstructured service payloads with no state introspection.
API Sketch
Alternatives Considered
Scope