Skip to content

[Feature]: Add Vacuum domain support #35

Description

@Faerkeren

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

  • I expect this change to require tests.
  • I expect this change to require documentation updates.
  • I expect this change to affect the public API.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions