Skip to content

aiovantage.object_interfaces

Object interfaces classes.

Object interface classes define how an object's state is accessed and modified. Each object implements one or more interfaces, with all objects automatically supporting ObjectInterface through inheritance from SystemObject.

Object interfaces expose state properties, which represent dynamic attributes that change during the operation of the system, such as the level a light or the current temperature of a thermostat. These properties are distinct from configuration properties, which are set when the system is programmed from Design Center and remain fixed during normal operation.

State properties can be retrieved using fetch_state and are kept up to date by calling handle_object_status or handle_category_status when messages are received from the command client event stream.

In practice, controllers are responsible for managing state properties. They handle the initial retrieval of state, process updates from the event stream, and ensure that the latest state is reflected in the system.

Classes:

AnemoSensorInterface

Bases: Interface

Anemo sensor object interface.

Methods:

  • get_speed –

    Get the speed of an anemo sensor.

  • set_speed –

    Set the speed of an anemo sensor.

get_speed async 

get_speed(*, hw: bool = False) -> Decimal

Get the speed of an anemo sensor.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The speed of the anemo sensor, in mph.

set_speed async 

set_speed(speed: Decimal, *, sw: bool = False) -> None

Set the speed of an anemo sensor.

Parameters:

  • speed (Decimal) –

    The speed to set, in mph.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

Interface

Base class for object interfaces.

Methods:

Attributes:

interface_name class-attribute 

interface_name: str

The name of the interface.

command_client class-attribute instance-attribute 

command_client: CommandClient | None = None

The command client instance to use for making requests.

vid instance-attribute 

vid: int

The Vantage ID of the object to send requests to, typically set in a subclass.

invoke async 

invoke(method: str, *params: Any) -> Any

invoke(method: str, *params: Any, as_type: type[T]) -> T

invoke(method: str, *params: Any, as_type: type[T] | None = None) -> T | Any

Invoke a method on an object, and return the parsed response.

Parameters:

  • method (str) –

    The method to invoke.

  • params (Any, default: () ) –

    The parameters to send with the method.

  • as_type (type[T] | None, default: None ) –

    The expected return type of the method, will attempt to infer if not provided.

Returns:

  • T | Any –

    A parsed response, or None if no response was expected.

update_properties 

update_properties(properties: dict[str, Any]) -> list[str]

Update object properties.

Parameters:

  • properties (dict[str, Any]) –

    A dictionary of property names and their new values.

Returns:

  • list[str] –

    A list of property names that were updated.

fetch_state async 

fetch_state() -> list[str]

Fetch state properties provided by the interface(s) this object implements.

Returns:

  • list[str] –

    A list of property names that were updated.

handle_object_status 

handle_object_status(method: str, result: str, *args: str) -> list[str]

Handle an object interface status message.

Parameters:

  • method (str) –

    The method that was invoked.

  • result (str) –

    The result of the command.

  • args (str, default: () ) –

    The arguments that were sent with the command.

Returns:

  • list[str] –

    A list of property names that were updated.

handle_category_status 

handle_category_status(category: str, *args: str) -> list[str]

Handle category status messages.

Object interfaces which can handle "legacy" status messages from the Host Command service should override this method.

Parameters:

  • category (str) –

    The category of the status message, eg. "LOAD".

  • args (str, default: () ) –

    The arguments that were sent with the command.

Returns:

  • list[str] –

    A list of property names that were updated.

BlindInterface dataclass 

BlindInterface(*, shade_orientation: str | None = None)

Bases: Interface, ShadeOrientation, ShadeType

Blind object interface.

Classes:

Methods:

BlindState dataclass 

BlindState(is_moving: bool, start_pos: Decimal, end_pos: Decimal, transition_time: Decimal, start_time: int)

The state of a blind.

TravelTimes dataclass 

TravelTimes(open_time: Decimal, close_time: Decimal)

The travel times of a blind.

open async 

open() -> None

Open a blind.

close async 

close() -> None

Close a blind.

stop async 

stop() -> None

Stop a blind.

set_position async 

set_position(position: float, *, sw: bool = False) -> None

Set the position of a blind.

Parameters:

  • position (float) –

    The position to set the blind to, as a percentage.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_position async 

get_position(*, hw: bool = False) -> Decimal

Get the position of a blind.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The position of the blind, as a percentage.

set_tilt_angle async 

set_tilt_angle(angle: int, *, sw: bool = False) -> None

Set the tilt angle of a blind.

Parameters:

  • angle (int) –

    The angle to set the blind to, from -100 to 100.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_tilt_angle async 

get_tilt_angle(*, hw: bool = False) -> int

Get the tilt angle of a blind.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • int –

    The tilt angle of the blind, from -100 to 100.

tilt_clockwise async 

tilt_clockwise(angle: int) -> None

Tilt the blinds clockwise by the specified angle.

Parameters:

  • angle (int) –

    The angle offset the blinds should be tilted.

tilt_counter_clockwise async 

tilt_counter_clockwise(angle: int) -> None

Tilt the shades counter-clockwise by the specified angle.

Parameters:

  • angle (int) –

    The angle offset the blinds should be tilted.

is_tilt_available async 

is_tilt_available() -> bool

Check if the blind can tilt in its current state.

Returns:

  • bool –

    Whether the blind supports tilting.

set_tilt_available async 

set_tilt_available(available: bool) -> None

Set the cached tilt availability of a blind.

Parameters:

  • available (bool) –

    Whether the blind supports tilting.

get_blind_state async 

get_blind_state() -> BlindState

Get the state of a blind.

Returns:

set_upper_limit async 

set_upper_limit(limit: Decimal, *, sw: bool = False) -> None

Set the upper limit of a blind.

Parameters:

  • limit (Decimal) –

    The upper limit to set the blind to, as a percentage.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_upper_limit async 

get_upper_limit(*, hw: bool = False) -> Decimal

Get the upper limit of a blind.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The upper limit of the blind, as a percentage.

set_lower_limit async 

set_lower_limit(limit: Decimal, *, sw: bool = False) -> None

Set the lower limit of a blind.

Parameters:

  • limit (Decimal) –

    The lower limit to set the blind to, as a percentage.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_lower_limit async 

get_lower_limit(*, hw: bool = False) -> Decimal

Get the lower limit of a blind.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The lower limit of the blind, as a percentage.

get_travel_times async 

get_travel_times() -> TravelTimes

Get the travel times of a blind.

Returns:

ButtonInterface

Bases: Interface

Button object interface.

Classes:

Methods:

Attributes:

  • is_down (bool | None) –

    Return True if the button is down.

is_down property 

is_down: bool | None

Return True if the button is down.

State

Bases: IntEnum

Button state.

SndType

Bases: IntEnum

Button sound type.

Polarity

Bases: IntEnum

Button polarity.

get_state async 

get_state(*, hw: bool = False) -> State

Get the state of a button.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • State –

    The pressed state of the button.

set_state async 

set_state(state: State, *, sw: bool = False) -> None

Set the state of a button.

Parameters:

  • state (State) –

    The state to set the button to, either a State.UP or State.DOWN.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_hold_on async 

get_hold_on(*, hw: bool = False) -> Decimal

Get the hold on time of a button.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The hold on time of the button, in seconds.

set_hold_on async 

set_hold_on(seconds: Decimal, *, sw: bool = False) -> None

Set the hold on time of a button.

Parameters:

  • seconds (Decimal) –

    The hold on time to set, in seconds.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_polarity async 

get_polarity(*, hw: bool = False) -> Polarity

Get the polarity of a button.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Polarity –

    The polarity of the button.

set_polarity async 

set_polarity(polarity: Polarity, *, sw: bool = False) -> None

Set the polarity of a button.

Parameters:

  • polarity (Polarity) –

    The polarity to set the button to.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_snd_type async 

get_snd_type(*, hw: bool = False) -> SndType

Get the sound type of a button.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • SndType –

    The sound type of the button.

set_snd_type async 

set_snd_type(snd_type: SndType, *, sw: bool = False) -> None

Set the sound type of a button.

Parameters:

  • snd_type (SndType) –

    The sound type to set the button to.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_placement async 

get_placement(*, hw: bool = False) -> int

Get the placement of a button.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • int –

    The placement of the button on the keypad.

set_placement async 

set_placement(placement: int, *, sw: bool = False) -> None

Set the placement of a button.

Parameters:

  • placement (int) –

    The placement of the button on the keypad.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

press async 

press() -> None

Press a button.

release async 

release() -> None

Release a button.

press_and_release async 

press_and_release() -> None

Press and release a button.

ColorTemperatureInterface

Bases: Interface

Interface for querying and controlling color temperature.

Classes:

  • Preset –

    Color temperature preset.

Methods:

Preset

Bases: IntEnum

Color temperature preset.

set_color_temp async 

set_color_temp(temp: int, transition: int = 0, *, sw: bool = False) -> None

Set the color temperature of a light.

Parameters:

  • temp (int) –

    The color temperature to set the light to, in Kelvin.

  • transition (int, default: 0 ) –

    The time in seconds to transition to the new color temperature.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_color_temp async 

get_color_temp(*, hw: bool = False) -> int

Get the color temperature of a light.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • int –

    The color temperature of the light, in Kelvin.

stop_transition async 

stop_transition() -> None

Stop any ongoing color temperature transitions.

warm async 

warm(amount: int, transition_time: float | Decimal) -> None

Decrease the color temperature of a light.

Parameters:

  • amount (int) –

    The amount to decrease the color temperature by.

  • transition_time (float | Decimal) –

    The time in seconds to transition to the new color.

cool async 

cool(amount: int, transition_time: float | Decimal) -> None

Increase the color temperature of a light.

Parameters:

  • amount (int) –

    The amount to increase the color temperature by.

  • transition_time (float | Decimal) –

    The time in seconds to transition to the new color.

set_temperature_preset async 

set_temperature_preset(value: Preset, transition_time: float | Decimal) -> None

Set the color temperature of a light to a preset value.

Parameters:

  • value (Preset) –

    The preset value to set the light to.

  • transition_time (float | Decimal) –

    The time in seconds to transition to the new color.

get_temperature_preset async 

get_temperature_preset() -> Preset

Get the color temperature preset of a light.

Returns:

  • Preset –

    The color temperature preset of the light.

get_max_value async 

get_max_value(*, hw: bool = False) -> int

Get the maximum color temperature of a light.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • int –

    The maximum color temperature of the light, in Kelvin.

set_max_value async 

set_max_value(value: int) -> None

Set the cached maximum color temperature of a light.

Parameters:

  • value (int) –

    The maximum color temperature to set the light to, in Kelvin.

get_min_value async 

get_min_value(*, hw: bool = False) -> int

Get the minimum color temperature of a light.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • int –

    The minimum color temperature of the light, in Kelvin.

set_min_value async 

set_min_value(value: int) -> None

Set the cached minimum color temperature of a light.

Parameters:

  • value (int) –

    The minimum color temperature to set the light to, in Kelvin.

get_transition_temperature async 

get_transition_temperature() -> int

Get the current color temperature of a light in transition.

Returns:

  • int –

    The transition temperature of the light, in Kelvin.

ConfigurationInterface

Bases: Interface

Configuration object interface.

Classes:

Methods:

Store

Bases: IntEnum

Configuration store.

Compression

Bases: IntFlag

Configuration compression type.

SolarEvent

Bases: IntEnum

Solar event types.

get_controller_vid async 

get_controller_vid(controller: int) -> int

Get the VID of a controller, based on the controller number.

Parameters:

  • controller (int) –

    The controller number to get the VID of.

delete_object async 

delete_object(store: Store, vid: int) -> None

Delete an object from the controller.

Parameters:

  • store (Store) –

    The store to delete the object from.

  • vid (int) –

    The VID of the object to delete.

create_object async 

create_object(type: str) -> int

Create an object on the controller.

Parameters:

  • type (str) –

    The type of object to create, eg. "Load".

Returns:

  • int –

    The VID of the created object, 0 if the object could not be created.

get_modification_time async 

get_modification_time() -> datetime

Get the modification time of this object.

Returns:

  • datetime –

    The modification time of the object, as a datetime object.

get_last_delete_time async 

get_last_delete_time(store: Store) -> datetime

Get the time of the last object deletion.

Parameters:

  • store (Store) –

    The store to get the last deletion time of.

Returns:

  • datetime –

    The time of the last object deletion, as a datetime object.

get_last_clear_time async 

get_last_clear_time() -> datetime

Get the time of the last clear.

Returns:

  • datetime –

    The time of the last store clear, as a datetime object.

open_filter async 

open_filter(store: Store, types: str = '', xpath: str = '') -> int

Open a filter on a store.

Parameters:

  • store (Store) –

    The store to open the filter on.

  • types (str, default: '' ) –

    An optional comma-separated list of object types to filter on.

  • xpath (str, default: '' ) –

    An optional xpath expression to filter on, eg. "/Load", "/*[@VID='12']"

Returns:

  • int –

    An integer "handle" representing the opened filter.

get_next_object_vid async 

get_next_object_vid(handle: int) -> int

Get the VID of the next object in a filter.

Parameters:

  • handle (int) –

    The filter handle to get the next object of.

Returns:

  • int –

    The VID of the next object in the filter, or 0 if there are no more objects.

close_filter async 

close_filter(handle: int) -> None

Close a filter.

Parameters:

  • handle (int) –

    The filter handle to close.

find_local_object async 

find_local_object(vid: int) -> bool

Find a "local" object by VID, i.e. an object managed by this object.

Parameters:

  • vid (int) –

    The VID of the object to find.

Returns:

  • bool –

    True if the object is found, False otherwise.

get_time_zone async 

get_time_zone() -> str

Get the time zone.

Returns:

  • str –

    The vantage time zone string, eg. "UTCPlusEight+8DAY,M3.2.0/02:00,M11.1.0/02:00"

get_time_location async 

get_time_location() -> str

Get the time location.

Returns:

  • str –

    A latitude and longitude string, eg. "51.178908N1.826212W"

get_astronomical_time async 

get_astronomical_time(event: SolarEvent, year: int, month: int, day: int) -> datetime

Get the astronomical time of a solar event.

Parameters:

  • event (SolarEvent) –

    The solar event to get the time of.

  • year (int) –

    The year of the event.

  • month (int) –

    The month of the event.

  • day (int) –

    The day of the event.

Returns:

  • datetime –

    The time of the solar event, as a datetime object.

CurrentSensorInterface

Bases: Interface

Current sensor object interface.

Methods:

get_current async 

get_current(*, hw: bool = False) -> Decimal

Get the value of a current sensor.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The value of the current sensor, in Amps.

set_current async 

set_current(value: Decimal, *, sw: bool = False) -> None

Set the value of a current sensor.

Parameters:

  • value (Decimal) –

    The value to set, in Amps.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

FanInterface

Bases: Interface

Fan object interface.

Classes:

Methods:

FanSpeed

Bases: IntEnum

Fan speed.

get_speed async 

get_speed(*, hw: bool = False) -> FanSpeed

Get the speed of a fan.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

set_speed async 

set_speed(speed: FanSpeed, *, sw: bool = False) -> None

Set the speed of a fan.

Parameters:

  • speed (FanSpeed) –

    The speed to set the fan to.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

increase_speed async 

increase_speed(vid: int) -> None

Increase the speed of a fan.

decrease_speed async 

decrease_speed() -> None

Decrease the speed of a fan.

GMemInterface

Bases: Interface

GMem object interface.

Classes:

  • Buffer –

    Response from a GMem fetch operation.

Methods:

  • fetch –

    Fetch the contents of the variable.

  • commit –

    Set the contents of the variable.

  • get_value –

    Get the value of a variable.

  • set_value –

    Set the value of a variable.

Buffer dataclass 

Buffer(type: int, data: bytes)

Response from a GMem fetch operation.

fetch async 

fetch() -> Buffer

Fetch the contents of the variable.

Returns:

  • Buffer –

    The contents of the variable.

commit async 

commit(buffer: bytes) -> None

Set the contents of the variable.

Parameters:

  • buffer (bytes) –

    The contents to set the variable to.

get_value async 

get_value() -> int | str | bytes

Get the value of a variable.

Returns:

  • int | str | bytes –

    The value of the variable, either a bool, int, or str.

set_value async 

set_value(value: Any) -> None

Set the value of a variable.

Parameters:

  • value (Any) –

    The value to set, either a bool, int, or str.

IntrospectionInterface

Bases: Interface

Introspection object interface.

Classes:

Methods:

Firmware

Bases: IntEnum

Firmware image.

LicenseType

Bases: IntEnum

License type.

LicenseInfo dataclass 

LicenseInfo(used: int, total: int)

A license info response.

get_app_controllers async 

get_app_controllers() -> str

Get a list of controllers in application mode, excluding this controller.

Returns:

  • str –

    A comma-separated list of controller numbers.

get_firmware_version async 

get_firmware_version(image: Firmware) -> str

Get the firmware version.

Parameters:

  • image (Firmware) –

    The firmware image to get the version of.

get_license_info async 

get_license_info(type: LicenseType) -> LicenseInfo

Get license information.

Parameters:

  • type (LicenseType) –

    The license type to get information for.

get_application_version async 

get_application_version() -> str

Get the application firmware version.

LightSensorInterface

Bases: Interface

Light sensor object interface.

Methods:

  • get_level –

    Get the level of a light sensor.

  • set_level –

    Set the level of a light sensor.

get_level async 

get_level(*, hw: bool = False) -> Decimal

Get the level of a light sensor.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The level of the light sensor, in foot-candles.

set_level async 

set_level(level: Decimal) -> None

Set the level of a light sensor.

Parameters:

  • level (Decimal) –

    The level to set, in foot-candles.

LoadInterface

Bases: Interface

Load object interface.

Classes:

Methods:

  • set_level –

    Set the level of a load.

  • get_level –

    Get the level of a load.

  • ramp –

    Ramp a load to a level over a number of seconds.

  • set_profile –

    Set the id of the power profile used by this load.

  • get_profile –

    Get the id of the power profile used by this load.

  • get_override_level –

    Get the override level of a load.

  • ramp_auto_off –

    Ramp a load to a level over a number of seconds, then ramp off after a timeout.

  • get_alert_state –

    Get the alert state of a load.

  • set_alert_state –

    Set the cached alert state of a load.

  • get_dimming_config –

    Get the dimming configuration of a load.

  • turn_on –

    Turn on a load with an optional transition time.

  • turn_off –

    Turn off a load with an optional transition time.

Attributes:

  • is_on (bool) –

    Return True if the load is on.

is_on property 

is_on: bool

Return True if the load is on.

RampType

Bases: IntEnum

Load ramp type.

AlertState

Bases: IntEnum

Load alert state.

DimmingConfig

Bases: IntEnum

Load dimming config.

set_level async 

set_level(level: float | Decimal, *, sw: bool = False) -> None

Set the level of a load.

Parameters:

  • level (float | Decimal) –

    The level to set the load to (0-100).

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_level async 

get_level(*, hw: bool = False) -> Decimal

Get the level of a load.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The level of the load, as a percentage (0-100).

ramp async 

ramp(cmd: RampType, ramptime: float | Decimal, finallevel: float | Decimal) -> None

Ramp a load to a level over a number of seconds.

Parameters:

  • cmd (RampType) –

    The type of ramp to perform.

  • ramptime (float | Decimal) –

    The number of seconds to ramp the load over.

  • finallevel (float | Decimal) –

    The level to ramp the load to (0-100).

set_profile async 

set_profile(profile: int) -> None

Set the id of the power profile used by this load.

Parameters:

  • profile (int) –

    The power profile id to set the load to.

get_profile async 

get_profile() -> int

Get the id of the power profile used by this load.

Returns:

  • int –

    The power profile id used by the load.

get_override_level async 

get_override_level() -> Decimal

Get the override level of a load.

Returns:

  • Decimal –

    The override level of the load, as a percentage (0-100).

ramp_auto_off async 

ramp_auto_off(cmd: RampType, ramptime: float | Decimal, finallevel: float | Decimal, offcmd: RampType, offramptime: float | Decimal, offtimeout: float | Decimal) -> None

Ramp a load to a level over a number of seconds, then ramp off after a timeout.

Parameters:

  • cmd (RampType) –

    The type of ramp to perform.

  • ramptime (float | Decimal) –

    The number of seconds to ramp the load over.

  • finallevel (float | Decimal) –

    The level to ramp the load to (0-100).

  • offcmd (RampType) –

    The type of ramp to perform to turn the load off.

  • offramptime (float | Decimal) –

    The number of seconds to ramp the load off over.

  • offtimeout (float | Decimal) –

    The number of seconds to wait before turning the load off.

get_alert_state async 

get_alert_state() -> AlertState

Get the alert state of a load.

Returns:

set_alert_state async 

set_alert_state(alert_state: AlertState) -> None

Set the cached alert state of a load.

Parameters:

  • alert_state (AlertState) –

    The alert state to set the load to.

get_dimming_config async 

get_dimming_config() -> DimmingConfig

Get the dimming configuration of a load.

Returns:

turn_on async 

turn_on(transition: float | None = None, level: float | None = None) -> None

Turn on a load with an optional transition time.

Parameters:

  • transition (float | None, default: None ) –

    The time in seconds to transition to the new level, defaults to immediate.

  • level (float | None, default: None ) –

    The level to set the load to (0-100), defaults to 100.

turn_off async 

turn_off(transition: float | None = None) -> None

Turn off a load with an optional transition time.

Parameters:

  • transition (float | None, default: None ) –

    The time in seconds to ramp the load down, defaults to immediate.

ObjectInterface

Bases: Interface

'Object' object interface.

Methods:

get_vid async 

get_vid() -> int

Get the Vantage ID of an object.

Returns:

  • int –

    The Vantage ID of the object.

get_controller async 

get_controller() -> int

Get the VID of the controller of an object.

Returns:

  • int –

    The VID of the controller of the object.

get_type async 

get_type() -> str

Get the type of an object.

Returns:

  • str –

    The type of the object.

get_name async 

get_name() -> str

Get the name field of an object.

Returns:

  • str –

    The name of the object.

get_model async 

get_model() -> str

Get the model field of an object.

Returns:

  • str –

    The model of the object.

get_note async 

get_note() -> str

Get the note field of an object.

Returns:

  • str –

    The note of the object.

get_property async 

get_property(xpath: str) -> int

Get an integer property of an object.

Parameters:

  • xpath (str) –

    XPath of the property to get, eg: "DName", "Get/Formula/@ReturnType, etc.

Returns:

  • int –

    The value of the property.

get_property_ex async 

get_property_ex(xpath: str) -> str

Get a string property of an object.

Parameters:

  • xpath (str) –

    XPath of the property to get, eg: "DName", "Get/Formula/@ReturnType, etc.

Returns:

  • str –

    The value of the property.

lock async 

lock() -> None

Lock an object.

unlock async 

unlock() -> None

Unlock an object.

is_locked async 

is_locked() -> bool

Check if an object is locked.

Returns:

  • bool –

    True if the object is locked, False otherwise.

is_interface_supported async 

is_interface_supported(iid: int) -> bool

Check if an interface is supported by an object.

Parameters:

  • iid (int) –

    The interface ID to check.

Returns:

  • bool –

    True if the interface is supported, False otherwise.

is_method_supported async 

is_method_supported(iid: int, mid: int) -> bool

Check if a method is supported by an object.

Parameters:

  • iid (int) –

    The interface ID to check.

  • mid (int) –

    The method ID to check.

Returns:

  • bool –

    True if the method is supported, False otherwise.

set_property async 

set_property(property: str, value: int) -> None

Set an integer property of an object.

Parameters:

  • property (str) –

    The property to set.

  • value (int) –

    The value to set the property to.

set_property_ex async 

set_property_ex(property: str, value: str) -> None

Set a string property of an object.

Parameters:

  • property (str) –

    The property to set.

  • value (str) –

    The value to set the property to.

is_enumerator_supported async 

is_enumerator_supported(interface_name: str, enumeration_name: str, enumerator_name: str) -> bool

Check if an enumerator is supported by an object.

Parameters:

  • interface_name (str) –

    The name of the interface to check.

  • enumeration_name (str) –

    The name of the enumeration to check.

  • enumerator_name (str) –

    The name of the enumerator to check.

Returns:

  • bool –

    True if the enumerator is supported, False otherwise.

get_m_time async 

get_m_time() -> datetime

Get the modification time of an object.

Returns:

  • datetime –

    The modification time of the object, as a datetime object.

get_d_name async 

get_d_name() -> str

Get the display name of an object.

Returns:

  • str –

    The display name of the object.

get_area async 

get_area() -> int

Get the area of an object.

Returns:

  • int –

    The area of the object.

get_supported_enum_values async 

get_supported_enum_values(interface: type[Interface], enum: type[IntEnumT]) -> list[IntEnumT]

Get all supported enum values of an object.

PowerSensorInterface

Bases: Interface

Power sensor interface.

Methods:

  • get_power –

    Get the value of a power sensor.

  • set_power –

    Set the value of a power sensor.

get_power async 

get_power(*, hw: bool = False) -> Decimal

Get the value of a power sensor.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The value of the power sensor, in Watts.

set_power async 

set_power(value: Decimal, *, sw: bool = False) -> None

Set the value of a power sensor.

Parameters:

  • value (Decimal) –

    The value to set, in Watts.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

RGBLoadInterface

Bases: Interface

RGB load interface.

Classes:

Methods:

RGBChannel

Bases: IntEnum

The RGB color channels.

HSLAttribute

Bases: IntEnum

The HSL color attributes.

ColorName

Bases: IntEnum

Color.

set_rgb async 

set_rgb(red: int = 255, green: int = 255, blue: int = 255, *, sw: bool = False, follow_level: bool = False) -> None

Set the color of an RGB load.

Parameters:

  • red (int, default: 255 ) –

    The red value of the color, (0-255)

  • green (int, default: 255 ) –

    The green value of the color, (0-255)

  • blue (int, default: 255 ) –

    The blue value of the color, (0-255)

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

  • follow_level (bool, default: False ) –

    Follow the level of the load.

get_rgb async 

get_rgb(channel: RGBChannel, *, hw: bool = False) -> int

Get a single RGB color channel of a load from the controller.

Parameters:

  • channel (RGBChannel) –

    The channel to get the color of.

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • int –

    The value of the RGB channel, 0-255.

set_hsl async 

set_hsl(hue: int, saturation: float | Decimal, lightness: float | Decimal, *, sw: bool = False) -> None

Set the color of an HSL load.

Parameters:

  • hue (int) –

    The hue value of the color, in degrees (0-360).

  • saturation (float | Decimal) –

    The saturation value of the color, in percent (0-100).

  • lightness (float | Decimal) –

    The lightness value of the color, in percent (0-100).

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_hsl async 

get_hsl(attribute: HSLAttribute, *, hw: bool = False) -> int

Get a single HSL color attribute of a load from the controller.

Parameters:

  • attribute (HSLAttribute) –

    The attribute to get the value of.

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • int –

    The value of the HSL attribute, 0-360 for hue, 0-100 for saturation and

  • int –

    lightness.

dissolve_rgb async 

dissolve_rgb(red: int, green: int, blue: int, rate: float | Decimal, *, follow_level: bool = False) -> None

Transition the color of an RGB load over a number of seconds.

Parameters:

  • red (int) –

    The new red value of the color, (0-255)

  • green (int) –

    The new green value of the color, (0-255)

  • blue (int) –

    The new blue value of the color, (0-255)

  • rate (float | Decimal) –

    The number of seconds the transition should take.

  • follow_level (bool, default: False ) –

    Follow the level of the load.

dissolve_hsl async 

dissolve_hsl(hue: int, saturation: float | Decimal, lightness: float | Decimal, rate: float | Decimal) -> None

Transition the color of an HSL load over a number of seconds.

Parameters:

  • hue (int) –

    The new hue value of the color, in degrees (0-360).

  • saturation (float | Decimal) –

    The new saturation value of the color, in percent (0-100).

  • lightness (float | Decimal) –

    The new lightness value of the color, in percent (0-100).

  • rate (float | Decimal) –

    The number of seconds the transition should take.

set_dissolve_rate async 

set_dissolve_rate(rate: float | Decimal, *, sw: bool = False) -> None

Set the default dissolve rate for RGB and HSL transitions.

Parameters:

  • rate (float | Decimal) –

    The number of seconds the transition should take.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_dissolve_rate async 

get_dissolve_rate(*, hw: bool = False) -> Decimal

Get the default dissolve rate for RGB and HSL transitions.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The number of seconds the transition should take.

increment_rgb_component async 

increment_rgb_component(channel: RGBChannel) -> None

Increment a single RGB color channel of a load.

Parameters:

  • channel (RGBChannel) –

    The channel to increment the color of.

decrement_rgb_component async 

decrement_rgb_component(channel: RGBChannel) -> None

Decrement a single RGB color channel of a load.

Parameters:

  • channel (RGBChannel) –

    The channel to decrement the color of.

set_rgb_component async 

set_rgb_component(channel: RGBChannel, value: int) -> None

Set a single RGB(W) color channel of a load.

Parameters:

  • channel (RGBChannel) –

    The channel to set the color of.

  • value (int) –

    The value to set the channel to, 0-255.

increment_hsl_attribute async 

increment_hsl_attribute(attribute: HSLAttribute) -> None

Increment a single HSL color attribute of a load.

Parameters:

  • attribute (HSLAttribute) –

    The attribute to increment the value of.

decrement_hsl_attribute async 

decrement_hsl_attribute(attribute: HSLAttribute) -> None

Decrement a single HSL color attribute of a load.

Parameters:

  • attribute (HSLAttribute) –

    The attribute to decrement the value of.

set_hsl_attribute async 

set_hsl_attribute(attribute: HSLAttribute, value: int) -> None

Set a single HSL color attribute of a load.

Parameters:

  • attribute (HSLAttribute) –

    The attribute to set the value of.

  • value (int) –

    The value to set the attribute to, 0-360 for hue, 0-100 for saturation and lightness.

stop async 

stop() -> None

Stop the transition.

next_preset async 

next_preset() -> None

Change to the next lighting preset.

previous_preset async 

previous_preset() -> None

Change to the previous lighting preset.

next_effect async 

next_effect() -> None

Change to the next lighting effect.

previous_effect async 

previous_effect() -> None

Change to the previous lighting effect.

set_preset async 

set_preset(index: int, *, sw: bool = False) -> None

Change to a specific lighting preset.

Parameters:

  • index (int) –

    The index of the preset to change to.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_preset async 

get_preset(*, hw: bool = False) -> int

Get the current lighting preset.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • int –

    The index of the current preset.

set_effect async 

set_effect(index: int, *, sw: bool = False) -> None

Change to a specific lighting effect.

Parameters:

  • index (int) –

    The index of the effect to change to.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_effect async 

get_effect(*, hw: bool = False) -> int

Get the current lighting effect.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • int –

    The index of the current effect.

set_color_by_name async 

set_color_by_name(color: ColorName) -> None

Set the color of an RGB load by name.

Parameters:

  • color (ColorName) –

    The name of the color to set the load to.

get_color_name async 

get_color_name() -> ColorName

Get the name of the color of a load from the controller.

Returns:

get_color async 

get_color(*, hw: bool = False) -> int

Get the RGB/RGBW color of a load from the controller.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • int –

    The RGB(W) value of the color as a packed big-endian integer.

set_rgbw async 

set_rgbw(red: int = 255, green: int = 255, blue: int = 255, white: int = 255, *, sw: bool = False, follow_level: bool = False) -> None

Set the color of an RGBW load.

Parameters:

  • red (int, default: 255 ) –

    The red value of the color, (0-255)

  • green (int, default: 255 ) –

    The green value of the color, (0-255)

  • blue (int, default: 255 ) –

    The blue value of the color, (0-255)

  • white (int, default: 255 ) –

    The white value of the color, (0-255)

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

  • follow_level (bool, default: False ) –

    Follow the level of the load.

get_rgbw async 

get_rgbw(channel: int, *, hw: bool = False) -> int

Get a single RGBW color channel of a load from the controller.

Parameters:

  • channel (int) –

    The channel to get the color of.

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • int –

    The value of the RGBW channel, 0-255.

get_transition_level async 

get_transition_level() -> Decimal

Get the transition level of a load.

Returns:

  • Decimal –

    The transition level of the load.

dissolve_rgbw async 

dissolve_rgbw(red: int, green: int, blue: int, white: int, rate: float | Decimal, *, follow_level: bool = False) -> None

Transition the color of an RGBW load over a number of seconds.

Parameters:

  • red (int) –

    The new red value of the color, (0-255)

  • green (int) –

    The new green value of the color, (0-255)

  • blue (int) –

    The new blue value of the color, (0-255)

  • white (int) –

    The new white value of the color, (0-255)

  • rate (float | Decimal) –

    The number of seconds the transition should take.

  • follow_level (bool, default: False ) –

    Follow the level of the load.

get_rgb_color async 

get_rgb_color() -> tuple[int, int, int]

Get the RGB color of a load from the controller.

Returns:

  • tuple[int, int, int] –

    The value of the RGB color as a tuple of (red, green, blue).

get_rgbw_color async 

get_rgbw_color() -> tuple[int, int, int, int]

Get the RGBW color of a load from the controller.

Returns:

  • tuple[int, int, int, int] –

    The value of the RGBW color as a tuple of (red, green, blue, white).

get_hsl_color async 

get_hsl_color() -> tuple[int, int, int]

Get the HSL color of a load from the controller.

Returns:

  • tuple[int, int, int] –

    The value of the HSL color as a tuple of (hue, saturation, lightness).

SensorInterface

Bases: Interface

Sensor interface.

Methods:

get_level async 

get_level(*, hw: bool = False) -> Decimal

Get the level of a sensor.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The level of the sensor.

set_level async 

set_level(level: Decimal) -> None

Set the level of a sensor.

Parameters:

  • level (Decimal) –

    The level to set the sensor to.

get_high_range async 

get_high_range() -> Decimal

Get the high range of a sensor.

Returns:

  • Decimal –

    The high range of the sensor.

get_low_range async 

get_low_range() -> Decimal

Get the low range of a sensor.

Returns:

  • Decimal –

    The low range of the sensor.

get_hold_on_time async 

get_hold_on_time() -> Decimal

Get the hold on time of a sensor.

Returns:

  • Decimal –

    The hold on time of the sensor, in seconds.

is_tracking async 

is_tracking() -> bool

Get whether the sensor is tracking.

Returns:

  • bool –

    Whether the sensor is tracking.

get_tracking_delta async 

get_tracking_delta() -> Decimal

Get the tracking delta of a sensor.

Returns:

  • Decimal –

    The tracking delta of the sensor.

get_tracking_min async 

get_tracking_min() -> Decimal

Get the tracking min time of a sensor.

Returns:

  • Decimal –

    The tracking min time of the sensor, in seconds.

get_tracking_max async 

get_tracking_max() -> Decimal

Get the tracking max time of a sensor.

Returns:

  • Decimal –

    The tracking max time of the sensor, in seconds.

SounderInterface

Bases: Interface

Sounder interface.

Classes:

Methods:

  • get_frequency –

    Get the frequency of the keypad speaker.

  • set_frequency –

    Set the frequency of the keypad speaker.

  • get_duration –

    Get the length of time the keypad speaker will sound.

  • set_duration –

    Set the length of time the keypad speaker will sound.

  • get_status –

    Get the status of the keypad speaker.

  • set_status –

    Set the status of the keypad speaker.

  • play_fx –

    Play a sound effect on the keypad speaker.

  • turn_on –

    Turn on the keypad speaker.

  • turn_off –

    Turn off the keypad speaker.

Status

Bases: IntEnum

Sounder status.

get_frequency async 

get_frequency(*, hw: bool = False) -> Decimal

Get the frequency of the keypad speaker.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The frequency of the keypad speaker in Hz.

set_frequency async 

set_frequency(frequency: float | Decimal) -> None

Set the frequency of the keypad speaker.

Parameters:

  • frequency (float | Decimal) –

    The frequency to set the sounder to, in Hz.

get_duration async 

get_duration(*, hw: bool = False) -> Decimal

Get the length of time the keypad speaker will sound.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The duration of the keypad speaker sound in seconds.

set_duration async 

set_duration(duration: Decimal) -> None

Set the length of time the keypad speaker will sound.

Parameters:

  • duration (Decimal) –

    The duration to set the sounder to, in seconds.

get_status async 

get_status(*, hw: bool = False) -> Status

Get the status of the keypad speaker.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Status –

    The status of the keypad speaker.

set_status async 

set_status(status: Status) -> None

Set the status of the keypad speaker.

Parameters:

  • status (Status) –

    The status to set the keypad speaker to.

play_fx async 

play_fx(effect: int, duration: float = 0, volume: float = 0) -> None

Play a sound effect on the keypad speaker.

Parameters:

  • effect (int) –

    The effect to play.

  • duration (float, default: 0 ) –

    The duration to play the FX for, in seconds, 0 for default.

  • volume (float, default: 0 ) –

    The volume to play the FX at, as a percentage, 0 for default.

turn_on async 

turn_on() -> None

Turn on the keypad speaker.

turn_off async 

turn_off() -> None

Turn off the keypad speaker.

TaskInterface

Bases: Interface

Task interface.

Classes:

Methods:

Status

Bases: IntEnum

Task status.

start async 

start() -> None

Start a task.

stop async 

stop() -> None

Stop a running task.

cancel async 

cancel() -> None

Cancel a scheduled task.

is_running async 

is_running() -> bool

Get the running state of a task.

get_state async 

get_state() -> int

Get the state of a task.

Returns:

  • int –

    The LED state of the task.

set_state async 

set_state(state: int) -> None

Set the state of a task.

Parameters:

  • state (int) –

    The state to set the task to.

get_status async 

get_status() -> Status

Get the status of a task.

Returns:

  • Status –

    The status of the task.

get_context_state async 

get_context_state() -> int

Get the context-aware task state.

Returns:

  • int –

    The context aware state of the task.

has_context_state async 

has_context_state() -> bool

Check if the task is context-aware.

Returns:

  • bool –

    True if the task is context-aware, False otherwise.

TemperatureInterface

Bases: Interface

Temperature interface.

Methods:

  • get_value –

    Get the value of a temperature sensor.

  • set_value –

    Set the value of a temperature sensor.

get_value async 

get_value(*, hw: bool = False) -> Decimal

Get the value of a temperature sensor.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The value of the temperature sensor, in degrees Celsius.

set_value async 

set_value(value: Decimal, *, sw: bool = False) -> None

Set the value of a temperature sensor.

Parameters:

  • value (Decimal) –

    The value to set the sensor to.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

ThermostatInterface

Bases: Interface

Thermostat interface.

Classes:

Methods:

OperationMode

Bases: IntEnum

Thermostat operation mode.

FanMode

Bases: IntEnum

Thermostat fan mode.

DayMode

Bases: IntEnum

Thermostat day mode.

HoldMode

Bases: IntEnum

The hold mode of the thermostat.

Status

Bases: IntEnum

The status of the thermostat.

get_indoor_temperature async 

get_indoor_temperature(*, hw: bool = False) -> Decimal

Get the current indoor temperature.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The indoor temperature of the thermostat, in degrees Celsius.

set_indoor_temperature async 

set_indoor_temperature(temp: float | Decimal) -> None

Set the cached indoor temperature.

Parameters:

  • temp (float | Decimal) –

    The indoor temperature to set, in degrees Celsius.

get_outdoor_temperature async 

get_outdoor_temperature(*, hw: bool = False) -> Decimal

Get the current outdoor temperature.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The outdoor temperature of the thermostat, in degrees Celsius.

set_outdoor_temperature async 

set_outdoor_temperature(temp: float | Decimal) -> None

Set the cached outdoor temperature.

Parameters:

  • temp (float | Decimal) –

    The outdoor temperature to set, in degrees Celsius.

get_heat_set_point async 

get_heat_set_point(*, hw: bool = False) -> Decimal

Get the current heat set point.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The heat set point of the thermostat, in degrees Celsius.

set_heat_set_point async 

set_heat_set_point(temp: float | Decimal, *, sw: bool = False) -> None

Set the current heat set point.

Parameters:

  • temp (float | Decimal) –

    The heat set point to set, in degrees Celsius.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_cool_set_point async 

get_cool_set_point(*, hw: bool = False) -> Decimal

Get the current cool set point.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The cool set point of the thermostat, in degrees Celsius.

set_cool_set_point async 

set_cool_set_point(temp: float | Decimal, *, sw: bool = False) -> None

Set the current cool set point.

Parameters:

  • temp (float | Decimal) –

    The cool set point to set, in degrees Celsius.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_operation_mode async 

get_operation_mode(*, hw: bool = False) -> OperationMode

Get the current operation mode.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

set_operation_mode async 

set_operation_mode(mode: int, *, sw: bool = False) -> None

Set the current operation mode.

Parameters:

  • mode (int) –

    The operation mode to set.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_fan_mode async 

get_fan_mode(*, hw: bool = False) -> FanMode

Get the current fan mode.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • FanMode –

    The fan mode of the thermostat.

set_fan_mode async 

set_fan_mode(mode: int, *, sw: bool = False) -> None

Set the current fan mode.

Parameters:

  • mode (int) –

    The fan mode to set.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_day_mode async 

get_day_mode(*, hw: bool = False) -> DayMode

Get the current day mode.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • DayMode –

    The day mode of the thermostat.

set_day_mode async 

set_day_mode(mode: int, *, sw: bool = False) -> None

Set the current day mode.

Parameters:

  • mode (int) –

    The day mode to set.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

set_hold_mode async 

set_hold_mode(mode: int, *, sw: bool = False) -> None

Set the current hold mode.

Parameters:

  • mode (int) –

    The hold mode to set.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.

get_hold_mode async 

get_hold_mode(*, hw: bool = False) -> HoldMode

Get the current hold mode.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • HoldMode –

    The hold mode of the thermostat.

get_status async 

get_status(*, hw: bool = False) -> Status

Get the current status.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Status –

    The status of the thermostat.

set_status async 

set_status(status: int) -> None

Set the cached status.

Parameters:

  • status (int) –

    The status to set.

get_auto_set_point async 

get_auto_set_point(*, hw: bool = False) -> Decimal

Get the current auto set point.

Parameters:

  • hw (bool, default: False ) –

    Fetch the value from hardware instead of cache.

Returns:

  • Decimal –

    The auto set point of the thermostat, in degrees Celsius.

set_auto_set_point async 

set_auto_set_point(temp: float | Decimal, *, sw: bool = False) -> None

Set the current auto set point.

Parameters:

  • temp (float | Decimal) –

    The auto set point to set, in degrees Celsius.

  • sw (bool, default: False ) –

    Set the cached value instead of the hardware value.