search

twrecked / hass-virtual

Virtual Components for Home Assistant
GNU General Public License v3.0
167 stars 28 forks source link
homeassistant homeassistant-integration python virtual

readme

Virtual devices for Home Assistant

Virtual is a component that provides virtual entities for Home Assistant.

icon

!!!BREAKING CHANGES!!!

Version 0.9 supports adding virtual devices using config flow. By default it will move your existing devices into a single file virtual.yaml. If you DO NOT want this behaviour add this to your virtual configuration.

virtual:
  yaml_config: True

Table Of Contents

Introduction

Virtual provides virtual components for testing Home Assistant systems.

Notes

Wherever you see /config in this README it refers to your home-assistant configuration directory. For me, for example, it's /home/steve/ha that is mapped to /config inside my docker container.

Version 0.8 Documentation

This documentation is for the 0.9.x version, you can find the 0.8.x version here.

New Features in 0.9.0

Config Flow

Finally. After sitting on it for far too long I decided to do the work I needed to, this integration now acts much like every integration, splitting down by entity, device and integration.

This means a lot of this documentation is now out of date, I will upgrade it when all the changes have been finalized, for now I will just add a quick note inline.

What pieces are done

  Mezzanine Motion:
    - platform: binary_sensor
      initial_value: 'off'
      class: motion
    - platform: sensor
      initial_value: '98'
      class: battery

What you need to be wary of

What pieces need doing

What if it goes wrong?

For now I recommend leaving your old configuration in place so you can revert back to a 0.8 release if you encounter an issue. Home Assistant will complain about the config but it's OK to ignore it.

If you do encounter and issue if you can turn on debug an create an issue that would be great.

Thanks

Many thanks to:

Installation

HACS

hacs_badge

Virtual is part of the default HACS store. If you're not interested in development branches this is the easiest way to install.

Component Configuration

For example, this enable backwards compatability.

virtual:
  yaml_config: True

Entity Configuration

All component configuration is done through a yaml file. There is a single file per integration instance. The default file, created on upgrade, is /config/virtual.yaml. An empty file looks like this:

version: 1
devices: {}

These two entries are optional. If you remove them then remove the indentation from the following device entries.

This is a small example of an imported file: 

version: 1
devices: 
 Living Room Sensor:
  - platform: binary_sensor
    name: Living Room Motion
    initial_value: 'off'
    class: motion
 Back Door Sensor:
  - platform: binary_sensor
    name: Back Door
    initial_value: 'off'
    class: door

This is an example of a file without the preamble.

Living Room Sensor:
- platform: binary_sensor
  name: Living Room Motion
  initial_value: 'off'
  class: motion
Back Door Sensor:
- platform: binary_sensor
  name: Back Door
  initial_value: 'off'
  class: door

Note that these entities have explicit names, this is because these entities were imported and the integration will re-create the same entity and unique IDs as previous version. You do not need to assign a name on new entries, the system will provide a default suffix based on device class. But, you can also choose to provide names if you wish.

This is the same file without the names:

version: 1
devices: 
  Living Room Sensor:
  - platform: binary_sensor
    initial_value: 'off'
    class: motion
  Back Door Sensor:
  - platform: binary_sensor
    initial_value: 'off'
    class: door

In this case it will create 2 entities, one called Living Room Sensor motion and Back Door Sensor door. The default naming can get a little hairy but you can alter it from the Integration settings.

You can also define virtual multi sensors. In this example a multi sensor devices provides 2 entities.

Living Room Multi Sensor:
- platform: binary_sensor
  initial_value: 'off'
  class: motion
- platform: sensor
  initial_value: '20'
  class: temperature

Common Attributes

Availability

By default, all devices are market as available. As shown below in each domain, adding initial_availability: false to configuration can override default and set as unavailable on HA start. Availability can by set by using the virtual.set_available with value true or false.

This is fully optional and initial_availability is not required to be set.

Persistence

By default, all device states are persistent. You can change this behaviour with the persistent configuration option.

If you have set an initial_value it will only be used if the device state is not restored. The following switch will always start on.

Test Switch:
- platform: virtual
  name: Switch 1
  persistent: False
  initial_value: on

Switches

To add a virtual switch use the following:

Test Switch:
- platform: switch

Binary Sensors

To add a virtual binary_sensor use the following. It supports all standard classes.

Test Binary Sensor:
- platform: binary_sensor
  initial_value: 'on'
  class: presence

Use the virtual.turn_on, virtual.turn_off and virtual.toggle services to manipulate the binary sensors.

Sensors

To add a virtual sensor use the following:

Test Sensor:
- platform: sensor
  class: temperature
  initial_value: 37
  unit_of_measurement: 'F'

Use the virtual.set service to manipulate the sensor value.

Setting unit_of_measurement can override default unit for selected sensor class. This is optional ans any string is accepted. List of standard units can be found here: Sensor Entity

Lights

To add a virtual light use the following:

Test Lights:
- platform: light
  initial_value: 'on'
  support_brightness: true
  initial_brightness: 100
  support_color: true
  initial_color: [0,255]
  support_color_temp: true
  initial_color_temp: 255
  support_white_value: true
  initial_white_value: 240

Only name is required.

_Note; *whitevalue is deprecated and will be removed in future releases.

Locks

To add a virtual lock use the following:

Test Lock:
- platform: lock
  name: Front Door Lock
  initial_value: locked
  locking_time: 5
  jamming_test: 5

Fans

To add a virtual fan use the following:

Test Fan:
- platform: fan
  speed: True
  speed_count: 5
  direction: True
  oscillate: True

You only need one of speed or speed_count.

Covers

To add a virtual cover use the following:

Test Cover:
- platform: cover
  initial_value: 'closed'
  open_close_duration: 10
  open_close_tick: 1

Supports open, close, stop and set_position. Opening and closing of the cover is emulated with timed events, and the timing can be controlled with

Valves

To add a virtual valve use the following:

Test Valve:
- platform: valve
  initial_value: 'closed'
  open_close_duration: 10
  open_close_tick: 1

Supports open, close, stop and set_position. Opening and closing of the valve is emulated with timed events, and the timing can be controlled with

Device Tracking

To add a virtual device tracker use the following:

Test Device_Tracker:
- platform: device_tracker
  initial_value: home

Use the virtual.move service to change device locations.

Old Style Entity Configuration

For now; look at the 0.8 documentation.

Services

The component provides the following services:

Name: virtual.set_availability

Parameters:

This will change the availability setting of any virtual device.

Name: virtual.turn_on

Parameters:

This service will turn on a binary sensor.

Name: virtual.turn_off

Parameters:

This service will turn off a binary sensor.

Name: virtual.toggle

Parameters:

Name: virtual.move

Parameters:

Move a device tracker. You use one of the parameters.