aiovantage.command_client

Clients for the Vantage Host Command (HC) service.

The Host Command service is a text-based service that allows interaction with devices controlled by a Vantage InFusion Controller.

Among other things, this service allows you to change the state of devices (eg. turn on/off a light) as well as subscribe to status changes for devices.

The service is exposed on port 3010 (SSL) by default, and on port 3001 (non-SSL) if this port has been opened by the firewall on the controller.

The service is discoverable via mDNS as _hc._tcp.local and/or _secure_hc._tcp.local.

Classes:

• CommandClient –

  Client for sending commands to the Vantage Host Command (HC) service.

• CommandResponse –

  Wrapper for command responses.

• Converter –

  Host Command service data conversion functions.

• EventStream –

  Client to subscribe to events from the Vantage Host Command (HC) service.

CommandClient

CommandClient(host: str, username: str | None = None, password: str | None = None, *, ssl: SSLContext | bool = True, ssl_context_factory: Callable[[], SSLContext] | None = None, port: int | None = None, conn_timeout: float = 30, read_timeout: float = 60)

Client for sending commands to the Vantage Host Command (HC) service.

Connections are created lazily when needed, and closed when the client is closed, and will automatically reconnect if the connection is lost.

Parameters:

• host (str) –

  The hostname or IP address of the Vantage controller.

• username (str | None, default: None ) –

  The username to use for authentication.

• password (str | None, default: None ) –

  The password to use for authentication.

• ssl (SSLContext | bool, default: True ) –

  The SSL context to use. True will use a default context, False will disable SSL.

• ssl_context_factory (Callable[[], SSLContext] | None, default: None ) –

  A factory function to use when creating default SSL contexts.

• port (int | None, default: None ) –

  The port to connect to.

• conn_timeout (float, default: 30 ) –

  The connection timeout in seconds.

• read_timeout (float, default: 60 ) –

  The read timeout in seconds.

Methods:

• close –

  Close the connection to the Host Command service.

• command –

  Send a command to the Host Command service and wait for a response.

• raw_request –

  Send a raw command to the Host Command service and return all response lines.

close

close() -> None

Close the connection to the Host Command service.

command async

command(command: str, *params: Any) -> CommandResponse

Send a command to the Host Command service and wait for a response.

Parameters:

• command (str) –

  The command to send, should be a single word string.

• params (Any, default: () ) –

  The parameters to send with the command.

Returns:

• CommandResponse –

  A CommandResponse instance.

raw_request async

raw_request(request: str) -> list[str]

Send a raw command to the Host Command service and return all response lines.

Handles authentication if required, and raises an exception if the response line contains R:ERROR.

Parameters:

• request (str) –

  The request to send.

Returns:

• list[str] –

  The response lines received from the server.

CommandResponse dataclass

CommandResponse(command: str, args: list[str], data: list[str])

Wrapper for command responses.

Almost all commands will respond with a single "response" line, which contains the command name and any arguments that were returned.

Some command, such as the "HELP" command, return multiple lines of text before the response line.

Attributes:

• command (str) –

  The command that was executed.

• args (list[str]) –

  The arguments that were returned on the response line.

• data (list[str]) –

  Any additional lines of text returned before the response line.

command instance-attribute

command: str

The command that was executed.

args instance-attribute

args: list[str]

The arguments that were returned on the response line.

data instance-attribute

data: list[str]

Any additional lines of text returned before the response line.

Converter

Host Command service data conversion functions.

Methods:

• deserialize –

  Deserialize a token from the Host Command service.

• serialize –

  Serialize an object to a string token for the Host Command service.

• tokenize –

  Tokenize a response from the Host Command service.

deserialize staticmethod

deserialize(data_type: type, value: str, **kwargs: Any) -> Any

Deserialize a token from the Host Command service.

Parameters:

• data_type (type) –

  The data type to deserialize the value to.

• value (str) –

  The string data to deserialize.

• **kwargs (Any, default: {} ) –

  Additional deserialization arguments.

Returns:

• Any –

  The deserialized object.

serialize staticmethod

serialize(value: Any, **kwargs: Any) -> str

Serialize an object to a string token for the Host Command service.

Parameters:

• value (Any) –

  The value to serialize to a string.

• **kwargs (Any, default: {} ) –

  Additional serialization arguments.

Returns:

• str –

  A string representation of the object.

tokenize staticmethod

tokenize(string: str) -> list[str]

Tokenize a response from the Host Command service.

Handles quoted strings and byte arrays as single tokens.

Parameters:

• string (str) –

  The response string to tokenize.

Returns:

• list[str] –

  A list of string tokens.

EventStream

EventStream(host: str, username: str | None = None, password: str | None = None, *, ssl: SSLContext | bool = True, ssl_context_factory: Callable[[], SSLContext] | None = None, port: int | None = None, conn_timeout: float = 30)

Bases: EventDispatcher

Client to subscribe to events from the Vantage Host Command (HC) service.

Parameters:

• host (str) –

  The hostname or IP address of the Vantage controller.

• username (str | None, default: None ) –

  The username to use for authentication.

• password (str | None, default: None ) –

  The password to use for authentication.

• ssl (SSLContext | bool, default: True ) –

  The SSL context to use. True will use a default context, False will disable SSL.

• ssl_context_factory (Callable[[], SSLContext] | None, default: None ) –

  A factory function to use when creating default SSL contexts.

• port (int | None, default: None ) –

  The port to connect to.

• conn_timeout (float, default: 30 ) –

  The connection timeout in seconds.

Methods:

• start –

  Initialize the event stream.

• stop –

  Stop the event stream.

• subscribe_status –

  Subscribe to "Status" events from the Host Command service.

• subscribe_enhanced_log –

  Subscribe to "Enhanced Log" events from the Host Command service.

start async

start() -> CommandConnection

Initialize the event stream.

stop

stop() -> None

Stop the event stream.

subscribe_status

subscribe_status(callback: Callable[[StatusReceived], None], *categories: str) -> Callable[[], None]

Subscribe to "Status" events from the Host Command service.

Parameters:

• callback (Callable[[StatusReceived], None]) –

  The callback to invoke when an event is received.

• *categories (str, default: () ) –

  The status categories to subscribe to events for.

Returns:

• Callable[[], None] –

  A function that can be used to unsubscribe from status events.

subscribe_enhanced_log

subscribe_enhanced_log(callback: Callable[[EnhancedLogReceived], None], *log_types: str, peers: Iterable[int] = ()) -> Callable[[], None]

Subscribe to "Enhanced Log" events from the Host Command service.

Parameters:

• callback (Callable[[EnhancedLogReceived], None]) –

  The callback to invoke when an event is received.

• log_types (str, default: () ) –

  The event log type or types to subscribe to.

• peers (Iterable[int], default: () ) –

  Master numbers of the peers whose objects should be logged too.

Returns:

• Callable[[], None] –

  A function that can be used to unsubscribe from log events.