hass-vantage

KO | EN

gitlite — search

#javascript #python #ai #typescript #llm #android #machine-learning #java #cli #awesome-list #ios #mcp #openai #open-source

(★ 11)

Home Assistant custom_component for Vantage Infusion Whole House lighting system.

hass-vantage 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# hass-vantage

By Greg J. Badros <badros@gmail.com>

For license information, see LICENSE -- Vantage systems control high voltage
electricity, you risk shock, fire, injury or death using this software. Use
this at your own risk!

This is a custom component for the Vantage Infusion whole-home lighting system
for use with Home Assistant.

It relies on my pyvantage module (from PyPi at
https://pypi.org/project/pyvantage/ or github at
https://github.com/gjbadros/pyvantage).

# Why?

You probably have a Vantage system because it is one of the best lighting
automation systems on the market. It is super reliable, supports virtually all
types of lighting fixtures, and has excellent quality keypads.

It also integrates with many non-lighting things in your home -- but not all of
them. Personally, I had trouble integrating Vantage with door locks, and found
that the visual programming language Vantage uses was making some automations I
wanted to make too challenging.

If you have something that is not supported by Vantage, you can either: (a)
replace it with something supported by Vantage; (b) write a driver for it; (c)
hire someone else to write a driver; or (d) use this Home Assistant integration!

# Setup

I use the following script to setup pyvantage and the vantage custom component.
You'll have to tweak it based on how you have Home Assistant set up.

```
    # First download pyvantage and add it to homeassistant.  Installs pyvantage
    # in the current directory and assumes home-assistant is in
    # ./home-assistant:

git clone https://github.com/colohan/pyvantage.git
    cd pyvantage
    git remote add upstream https://github.com/gjbadros/pyvantage.git
    cd ..

cd home-assistant
    python3 -m venv venv
    source venv/bin/activate

# If we want to edit pyvantage, we install it from a local mirror of the git
    # repo:
    cd ../pyvantage
    pip3 install --editable .

cd ../home-assistant
    script/setup

# Now install the vantage custom component:

cd ~/.homeassistant/custom_components
    git clone https://github.com/colohan/hass-vantage.git vantage
    cd vantage
    git remote add upstream https://github.com/gjbadros/hass-vantage.git
```

And add something like the following to configuration.yaml:

```
vantage:
  host: 192.168.0.123
  username: !secret vantage_username
  password: !secret vantage_password
  exclude_areas: "SPARE RELAYS"
```

And add the following to secrets.yaml:

```
vantage_username: [my_username]
vantage_password: [my_password]
```

and then restart home assistant.

Note: The specified user must be in group Admin and have "Read State", "Write
State" and "Read Config" permissions to work. See "Settings->Project Security"
in Vantage Design Center.

Note2: if your Vantage system is not set up with a username and password you can
elide the username: and password: lines in the configuration.yaml file, and skip
setting up secrets.yaml. Or, just add a password to your Vantage!

Note3: if your Home Assistant can't talk to Vantage over the network, it can't
work. If you have a firewall configure it to let the connections on ports 2001
and 3001 through.

# Usage

Now that you have the Vantage system set up, it is time to use it!

If you are new to using Home Assistant, you are going to use the default
Lovelace UI. And you'll quickly find out that there is a huge list of Lights
and Badges cluttering up your UI as soon as you install the Vantage module.
This is because the typical Vantage install has a very large number of lights,
loads, and sensors, since it controls everything in the house, and Vantage users
tend to have larger houses.

**WARNING**: At the top of the Light panel is a very tempting, innocuous
looking switch. It turns on (or off) _all_ the lights in your home at the
same time. Turning on all your lights simultaneously IS A BAD IDEA.

Why? If you have LED lighting, the internal capacitors in those lights take a
bunch of current to charge when you first turn them on. If you turn on enough
of them all on at once, the load spike may be large enough to pop several
breakers or worse.

One of the first things you will be strongly tempted to do is manually configure
your Lovelace UI to clean out all the stuff you don't care about. This is not a
bad idea.

So what has the Vantage component added to your home assistant? A number of
things:

1.  For every light controlled by Vantage, a light.\* entity. Lights can be a
    dimmable or non-dimmable, color (DMX) or monochrome.
2.  For every switched load controlled by Vantage, a switch.\* entity.
3.  For every window shade controlled by Vantage, a cover.\* entity.
4.  For every motion sensor, contact sensor (such as a door opening sensor) or
    other binary sensor attached to Vantage, a sensor.\* entity.
5.  Temperature, power and current sensors showing the status of the Infusion
    dimmer modules and their attached loads.
6.  For every light group defined by Vantage, a light.\* entity.
7.  If enabled (set include_buttons to True to enable): for every button on
    every keypad, a sensor.\* entity showing whether the button is current
    pressed or not.
8.  For every keypad, a sensor.\* entity saying which button on the keypad was
    pressed last.
9.  For every variable defined in Vantage, a sensor.\* entity containing the
    current state of that variable.
10. Services for setting Vantage variables and calling Vantage tasks
    (vantage.set_variable, vantage.call_task, vantage.set_variable_vid, and
    vantage.call_task_vid).
11. Events which get fired whenever a keypad button is pressed
    (vantage_button_pressed, vantage_button_released).

# Leaving Stuff Out

If you feel that Home Assistant is overwhelmed by all the Entities from Vantage
you are not going to immediately use, you can just leave them out. Here are
some configuration options you can use:

```
  # Don't include Vantage contacts (such as motion sensors):
  exclude_contacts: True

# Don't include keypads:
  exclude_keypads: True

# Don't include Vantage variables:
  exclude_variables: True

# Don't include any object with the string "DISABLED" or "BROKEN" in the name:
  exclude_name_substring: 'DISABLED,BROKEN'

# Include variables which are prefixed with '_' (they are normally excluded):
  include_underscore_variables: True

# Design Center organizes all Vantage objects into "areas" (floors/rooms),
  # these options let you limit which areas this integration pays attention to:
  only_areas: 'First floor'
  exclude_areas: 'Guest bathroom'
```

This driver can add a lot of devices to your home assistant system all at once
which can bog your system down doing database writes. If you are running Home
Assistant on a low-powered machine like a Raspberry Pi, then offloading the
database to an external system (such as a server running MariaDB) can improve
performance dramatically.

# Naming of Entities

Every entity in Home Assistant needs a unique name. In Vantage, objects don't
need unique names -- they all have a unique VID.

This Vantage component attempts to generate unique names by concatenating the
names of the levels of the object hierarchy in Vantage. So a light in your
second floor master bath might create an Entity called
"light.second_floor_master_bath_vanity_light" with a friendly name of "Second
Floor-Master Bath-Vanity Light" (the friendly name is used by Lovelace in
displaying objects, the Entity name is what you use when you are coding up
automations). If you have two objects with the same name (very common with
buttons, where multiple buttons may have similar names such as "On" and "Off"),
this module will just add the VID to the end.

These names are very long. If you want shorter Entity names, you can do one of
the following:

1.  Use the Configuration->Entity Registry UI to rename your entities. This can
    be tedious, and if you ever re-initialize Home Assistant's Entity registry
    (such as by following step 2 below) then you may lose these changes.

2.  Rename your objects in the Vantage Design Center. The "Display Name" will
    override the "Name" field in Home Assistant if present (Note: only for Load
    objects, for keypads and motion sensors it does not). Once you do this you
    need to ensure that `enable_cache` is not set in your `configuration.yaml`,
    erase the file `~/.homeassistant/.storage/core.entity_registry`, and restart
    Home Assistant to rebuild the entity registry.

3.  Create mappings to rename objects in your `configuration.yaml`, like:

```
  name_mappings:
    - area: 'second floor'
      to: 2F
```

Note that unless you delete the entity registry and rebuild it (as described
    in 2 above) this will only rename the friendly names of entities and not the
    entity name.

In some cases the Vantage component uses object names to infer functionality,
since the Vantage metadata makes it hard to determine. If a light's name ends
in " COLOR" it is assumed to be a color load. If the load type is "High Voltage
Relay" then it assumes it is a switch and not a light.

# Grouping Lights

Chances are you don't want to control each and every circuit from the Lovelace
UI. You can group the Vantage lights into simpler lights using the "group"
plaform like this:

```
light:
  - platform: group
    name: Basement Bath
    entities:
      - light.basement_bath_4_ba4_shower
      - light.basement_bath_4_ba4_vanity
      - light.basement_bath_4_ba4_wc_fan
      - light.basement_bath_4_ba4_wc_light
  - platform: group
    name: Guest Bedroom
    entities:
      - light.basement_bedroom_4_br4_ceiling_cans
      - light.basement_bedroom_4_br4_center_light
      - light.basement_bedroom_4_closet_br4_closet_storage
```

# Power Sensors

Infusion Dimmer modules have a neat feature which is not visible in Design
Center: they measure the power consumption of all of their lighting loads. This
Vantage component gives you the data from your individual power sensors, you may
want to aggregate it into a single measure using some code similar to this:

```
sensor:
  - platform: template
    sensors:
      total_vantage_power:
        friendly_name: "Lighting Energy Usage"
        unit_of_measurement: 'W'
        value_template: "{{ states('sensor.power_sensor_line_d_365') | float + states('sensor.power_sensor_line_d_281') | float + states('sensor.power_sensor_line_d_175') | float + states('sensor.power_sensor_line_d_120') | float + states('sensor.power_sensor_line_d') | float + states('sensor.power_sensor_line_c_364') | float + states('sensor.power_sensor_line_c_280') | float + states('sensor.power_sensor_line_c_174') | float + states('sensor.power_sensor_line_c_119') | float + states('sensor.power_sensor_line_c') | float + states('sensor.power_sensor_line_b_363') | float + states('sensor.power_sensor_line_b_279') | float + states('sensor.power_sensor_line_b_173') | float + states('sensor.power_sensor_line_b_118') | float + states('sensor.power_sensor_line_b') | float + states('sensor.power_sensor_line_a') | float + states('sensor.power_sensor_line_a_117') | float + states('sensor.power_sensor_line_a_172') | float + states('sensor.power_sensor_line_a_278') | float + states('sensor.power_sensor_line_a_362') | float }}"
```

# Not Supported (Yet?)

There are things that Vantage can do which Home Assistant can't do (yet). Here
is an incomplete list with workarounds:

- Change the color, brightness or blink rate of the LED light on each keypad
  button.
  => Write a Vantage function to do this, invoke from Home Assistant
- Dim lights in response to long button presses.
  => Configure the button to invoke the Dim Cycle routine on the Vantage
  controller, and then have Home Assistant events respond to the light
  brightness level changing.
- Cause the keypads to make a tone. (It appears that there is an interface to
  make a keypad start making a tone and stop making a tone, but not to have it
  play a tone for a specified duration...)
  => Write a Vantage function to do this, invoke from Home Assistant
- Enable/disable Vacation mode on the Vantage.
  => Write a Vantage function to do this, invoke from Home Assistant
- Invoke Home Assistant actions or routines from Vantage procedures (this
  component allows Home Assistant to control Vantage, not Vantage to control
  Home Assistant).
  => Use a variable as a signal: increment a Vantage variable from the
  Vantage function, and then trigger Home Assistant events based on the
  variable changing. (This is a real kludge, but it seems to work.)
- Lock/unlock Vantage objects. (Why?)
  => Write a Vantage function to do this, invoke from Home Assistant
- Interface fully with A/V components, thermostats, alarm systems, or other
  non-lighting devices you might have attached to your Vantage system.
  => Hook them up to Home Assistant instead. Alternatively, write a
  Vantage function to do this, invoke from Home Assistant.

An example of this last item: one of the early users of this Vantage module had
an Elk alarm system which was wired to their Vantage Infusion controller through
a serial cable. The Elk driver for Vantage worked, but awkward to use. One
problem: it didn't have different states for an alarm being armed or simply in
the process of arming -- which made it hard to write routines to only run if the
alarm was armed. The Home Assistant Elk driver is more full featured, and makes
creating such automations easy.

As a result, this user chose to create a new serial cable to plug the Elk
directly into their Home Assistant computer (alternatively, they could have
spent more money to buy the Elk IP interface, which is also known to work well).

hass-vantage

hass-vantage 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

hass-vantage

hass-vantage 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README