aiovantage is a Python library for interacting with and controlling Vantage InFusion home automation controllers.

Uses a controller pattern inspired heavily by the aiohue library.

This open-source, non-commercial library is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Vantage, and is provided for interoperability purposes only.

• Example
• Features
• Supported objects types
• Installation
• Usage

from aiovantage import Vantage

async with Vantage("192.168.1.2", "username", "password") as vantage:
    async for load in vantage.loads:
        print(f"{load.name} is at {load.level}%")

See the examples folder for more examples.

• Uses Python asyncio for non-blocking I/O.
• Exposes "controllers" to make fetching and controlling various objects easy.
• Uses SSL connections by default, with automatic reconnection.
• Fetch objects lazily (with async for obj in controller).
• Alternatively, eager-fetch objects with controller.initialize.

The following interfaces/controllers are currently supported.

If you have an object that you expect to show up in one of these controllers but is missing, please create an issue or submit a pull request.

Add aiovantage as a dependency to your project, or install it directly:

pip install aiovantage

Begin by importing the Vantage class:

from aiovantage import Vantage

The most convenient way to create a client is by using the async context manager:

async with Vantage("hostname", "username", "password") as vantage:
    # ...use the vantage client

Alternatively, you can manage the lifecycle of the client yourself:

from aiovantage import Vantage

vantage = Vantage("hostname", "username", "password")
# ...use the vantage client
vantage.close()

The Vantage class exposes a number of controllers, which can be used to query objects. Controllers can either be populated lazily (by using async for), or eagerly (by using controller.initialize()).

For example, to get a list of all loads:

async with Vantage("hostname", "username", "password") as vantage:
    async for load in vantage.loads:
        print(f"{load.name} is at {load.level}%")

Alternatively, you can use controller.initialize() to eagerly fetch all objects:

async with Vantage("hostname", "username", "password") as vantage:
    await vantage.loads.initialize()
    for load in vantage.loads:
        print(f"{load.name} is at {load.level}%")

If you aren't interested in the state of the objects, you can call controller.initialize(fetch_state=False) to slightly speed up the initialization:

async with Vantage("hostname", "username", "password") as vantage:
    await vantage.loads.initialize(fetch_state=False)
    for load in vantage.loads:
        print(f"{load.name}")

All controllers implement a django-like query interface, which can be used to filter objects. You can either query by matching attributes:

async with Vantage("hostname", "username", "password") as vantage:
    async for load in vantage.loads.filter(name="Kitchen"):
        print(f"{load.name} is at {load.level}%")

Or by using a filter predicate:

async with Vantage("hostname", "username", "password") as vantage:
    async for load in vantage.loads.filter(lambda load: load.level > 50):
        print(f"{load.name} is at {load.level}%")

You can fetch a single object by id, by calling controller.aget() or controller.get():

async with Vantage("hostname", "username", "password") as vantage:
    load = await vantage.loads.aget(118)
    print(f"{load.name} is at {load.level}%")

These functions also implement the same query interface as controller.filter() for querying by attributes or filter predicate:

async with Vantage("hostname", "username", "password") as vantage:
    load = await vantage.loads.aget(name="Kitchen")
    print(f"{load.name} is at {load.level}%")

Most controllers expose a various methods for controlling the state of objects. The first parameter to these methods is always the vantage id of the object to control.

For example, to turn on a load:

async with Vantage("hostname", "username", "password") as vantage:
    await vantage.loads.turn_on(118)

You can subscribe to state changes by using the controller.subscribe() method:

def on_load_state_change(event, load, data):
    print(f"{load.name} is at {load.level}%")

async with Vantage("hostname", "username", "password") as vantage:
    vantage.loads.subscribe(on_load_state_change)
    await vantage.loads.initialize()

Note that a subscription will only receive state changes for objects that have populated into the controller.