{"id":13585797,"url":"https://github.com/twrecked/hass-virtual","last_synced_at":"2025-04-24T00:24:03.281Z","repository":{"id":38388683,"uuid":"245267534","full_name":"twrecked/hass-virtual","owner":"twrecked","description":"Virtual Components for Home Assistant","archived":false,"fork":false,"pushed_at":"2024-05-20T00:28:42.000Z","size":137,"stargazers_count":139,"open_issues_count":41,"forks_count":24,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-05-20T01:33:02.331Z","etag":null,"topics":["homeassistant","homeassistant-integration","python","virtual"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/twrecked.png","metadata":{"files":{"readme":"README.md","changelog":"changelog","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-05T21:04:37.000Z","updated_at":"2024-06-16T13:42:31.470Z","dependencies_parsed_at":"2024-02-03T17:29:41.441Z","dependency_job_id":"c7eb2602-6708-49d0-be23-68f07842e358","html_url":"https://github.com/twrecked/hass-virtual","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twrecked%2Fhass-virtual","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twrecked%2Fhass-virtual/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twrecked%2Fhass-virtual/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twrecked%2Fhass-virtual/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twrecked","download_url":"https://codeload.github.com/twrecked/hass-virtual/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250536551,"owners_count":21446755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["homeassistant","homeassistant-integration","python","virtual"],"created_at":"2024-08-01T15:05:09.145Z","updated_at":"2025-04-24T00:24:03.254Z","avatar_url":"https://github.com/twrecked.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# **Virtual devices for Home Assistant**\n\n_Virtual_ is a component that provides virtual entities for _Home Assistant_.\n\n![icon](images/virtual-icon.png)\n\n\n# !!!BREAKING CHANGES!!!\n\nVersion 0.9 supports adding virtual devices using _config flow_. By default it\nwill move your existing devices into a single file `virtual.yaml`. If you **DO\nNOT** want this behaviour add this to your current `virtual` configuration.\n\n```yaml\nvirtual:\n  yaml_config: True\n```\n\n\n# Table Of Contents\n\n\n\u003c!--toc:start--\u003e\n- [**Virtual devices for Home Assistant**](#virtual-devices-for-home-assistant)\n- [!!!BREAKING CHANGES!!!](#breaking-changes)\n- [Table Of Contents](#table-of-contents)\n- [Introduction](#introduction)\n  - [Notes](#notes)\n  - [Version 0.8 Documentation](#version-08-documentation)\n  - [New Features in 0.9.0](#new-features-in-090)\n    - [Config Flow](#config-flow)\n      - [What pieces are done](#what-pieces-are-done)\n      - [What you need to be wary of](#what-you-need-to-be-wary-of)\n      - [What if it goes wrong?](#what-if-it-goes-wrong)\n  - [Thanks](#thanks)\n- [Installation](#installation)\n  - [Getting the Software](#getting-the-software)\n    - [HACS](#hacs)\n  - [Adding the Integration](#adding-the-integration)\n    - [After a Fresh Install](#after-a-fresh-install)\n    - [After an Upgrade](#after-an-upgrade)\n  - [I don't want the New Behaviour!!!](#i-dont-want-the-new-behaviour)\n  - [Adding More Entries](#adding-more-entries)\n- [Component Configuration](#component-configuration)\n- [Entity Configuration](#entity-configuration)\n  - [File Layout](#file-layout)\n  - [Common Attributes](#common-attributes)\n    - [Availability](#availability)\n    - [Persistence](#persistence)\n  - [Switches](#switches)\n  - [Binary Sensors](#binary-sensors)\n  - [Sensors](#sensors)\n  - [Lights](#lights)\n  - [Locks](#locks)\n  - [Fans](#fans)\n  - [Covers](#covers)\n  - [Valves](#valves)\n  - [Device Tracking](#device-tracking)\n- [Old Style Entity Configuration](#old-style-entity-configuration)\n- [Services](#services)\n\u003c!--toc:end--\u003e\n\n\n# Introduction\n\nVirtual provides virtual components for testing Home Assistant systems.\n\n## Notes\nWherever you see `/config` in this README it refers to your home-assistant\nconfiguration directory. For me, for example, it's `/home/steve/ha` that is\nmapped to `/config` inside my docker container.\n\n## Version 0.8 Documentation\n\n**This documentation is for the 0.9.x version, you can find the\n0.8.x version** [here](https://github.com/twrecked/hass-virtual/tree/version-0.8.x#readme).\n\n## New Features in 0.9.0\n\n### Config Flow\n\nFinally. After sitting on it for far too long I decided to do the work I\nneeded to, this integration now acts much like every integration, splitting\ndown by entity, device and integration.\n\n#### What pieces are done\n\n- _upgrade_; the code will upgrade a _0.8_ build to the _config flow_ system.\n  Your current configuration will be moved into 1 file, `virtual.yaml`. This\n  file contains all your virtual devices. Edit this file to add any type of\n  device.\n- _services_; they follow the _Home Assistant_ standard\n- _multiple integrations_; the integration can be added several times and you\n  can spread your devices across several files\n- _device groupings_; for example, a motion detector can have a motion\n  detection entity and a battery entity, upgraded devices will have a one to\n  one relationship. For example, the following will create a motion device\n  with 2 entities. If you don't provide a name for an entity the system will\n  provide a default.\n\n```yaml\n  Mezzanine Motion:\n    - platform: binary_sensor\n      initial_value: 'off'\n      class: motion\n    - platform: sensor\n      initial_value: '98'\n      class: battery\n```\n\n#### What you need to be wary of\n\n- _device trackers_; the upgrade process is a little more complicated if you\n  have device trackers, because of the way _virtual_ created the old devices\n  you will end up with duplicates entries, you can fix it by running the\n  following steps\n  1. do the upgrade\n  2. comment out device virtual device trackers from `device_trackers.yaml`\n     and `known_devices.yaml`\n  3. restart _Home Assistant_\n  4. delete the virtual integration\n  5. add back the virtual integration in accepting the defaults\n\n#### What if it goes wrong?\n\nFor now I recommend leaving your old configuration in place so you can revert\nback to a _0.8_ release if you encounter an issue. _Home Assistant_ will\ncomplain about the config but it's OK to ignore it.\n\nIf you do encounter and issue if you can turn on debug an create an issue that\nwould be great.\n\n## Thanks\nMany thanks to:\n* [JetBrains](https://www.jetbrains.com/?from=hass-aarlo) for the excellent\n  **PyCharm IDE** and providing me with an open source licence to speed up the\n  project development.\n\n  [![JetBrains](/images/jetbrains.svg)](https://www.jetbrains.com/?from=hass-aarlo)\n\n* Icon from [iconscout](https://iconscout.com) by [twitter-inc](https://iconscout.com/contributors/twitter-inc)\n \n\n# Installation\n\n## Getting the Software\n\n### HACS\n[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg?style=for-the-badge)](https://github.com/hacs/integration)\n\nVirtual is part of the default HACS store. If you're not interested in\ndevelopment branches this is the easiest way to install.\n\n## Adding the Integration \n\n### After a Fresh Install\n\nWhen you have created your initial configuration file do the following:\n\n- go to `Settings` -\u003e `Devices and Integrations` -\u003e `+ ADD INTEGRATION`\n- search for _virtual_ and choose the integration\n- give your configuration a name and point it at your newly created file\n\nThen you click OK \n\n### After an Upgrade\n\nAll your devices will be moved to a group called _import_ and put into\n`/config/virtual.yaml`. The system will create a single _virtual_ integration.\n\n## I don't want the New Behaviour!!!\n\nIf you want to keep your existing behaviour change your current `virtual`\nentry in `configuration.yaml` to this:\n\n```yaml\nvirtual:\n  yaml_config: True\n```\n\n## Adding More Entries\n\nYou can add more than one integration by selecting `Add Entry` on the\n_virtual_ integration page. You will need to give this new entity group a name\nand point it to the new file.\n\n\n# Component Configuration\n\nYou set this to enable backwards compatibility. \n\n- `yaml_config`; set to `True` to enable backwards compatibility, set to `False`\n  to disable it. The default is `False`.\n\nFor example, this enable backwards compatibility.\n\n```yaml\nvirtual:\n  yaml_config: True\n```\n\n\n# Entity Configuration\n\nAll component configuration is done through _yaml_ files. You can put all of\nyour virtual devices into a single _yaml_ file or you can group devices\ntogether in multiple file.\n\nIf this is a fresh install you will need to install a _virtual_ integration\ninstance and tell it about your file. If you are upgrading from _0.8_ the system will\ncreate a single instance and copy all your current devices into a\n`/config/virtual.yaml`.\n\n## File Layout\n\nAn empty file looks like this:\n```yaml\nversion: 1\ndevices: {}\n```\n\n- _version_; this is currently 1\n- _devices_; this is a list of devices and entities associated with that\n  device\n\nThese two entries are optional. If you remove them then remove the indentation\nfrom the following device entries.\n\nThis is a small example of an imported file: \n\n```yaml\nversion: 1\ndevices: \n Living Room Sensor:\n  - platform: binary_sensor\n    name: Living Room Motion\n    initial_value: 'off'\n    class: motion\n Back Door Sensor:\n  - platform: binary_sensor\n    name: Back Door\n    initial_value: 'off'\n    class: door\n```\n\nThis is an example of a file without the preamble.\n\n```yaml\nLiving Room Sensor:\n- platform: binary_sensor\n  name: Living Room Motion\n  initial_value: 'off'\n  class: motion\nBack Door Sensor:\n- platform: binary_sensor\n  name: Back Door\n  initial_value: 'off'\n  class: door\n```\n\nNote that these entities have explicit names, this is because these entities\nwere imported and the integration will re-create the same entity and\nunique IDs as previous version. You do not need to assign a name on new\nentries, the system will provide a default suffix based on device class. But,\nyou can also choose to provide names if you wish.\n\nThis is the same file without the names:\n\n```yaml\nversion: 1\ndevices: \n  Living Room Sensor:\n  - platform: binary_sensor\n    initial_value: 'off'\n    class: motion\n  Back Door Sensor:\n  - platform: binary_sensor\n    initial_value: 'off'\n    class: door\n```\n\nIn this case it will create 2 entities, one called `Living Room Sensor motion`\nand `Back Door Sensor door`. The default naming can get a little hairy but you\ncan alter it from the _Integration_ settings.\n\nYou can also define virtual multi sensors. In this example a multi sensor\ndevices provides 2 entities.\n\n```yaml\nLiving Room Multi Sensor:\n- platform: binary_sensor\n  initial_value: 'off'\n  class: motion\n- platform: sensor\n  initial_value: '20'\n  class: temperature\n```\n\n## Common Attributes\n\n### Availability\n\nBy default, all devices are market as available. As shown below in each domain,\nadding `initial_availability: false` to configuration can override default and\nset as unavailable on HA start. Availability can by set by using\nthe `virtual.set_available` with value `true` or `false`.\n\nThis is fully optional and `initial_availability` is not required to be set.\n\n### Persistence\nBy default, all device states are persistent. You can change this behaviour with\nthe `persistent` configuration option.\n\nIf you have set an `initial_value` it will only be used if the device state is\nnot restored. The following switch will always start _on_.\n\n```yaml\nTest Switch:\n- platform: virtual\n  name: Switch 1\n  persistent: False\n  initial_value: on\n```\n\n## Switches\n\nTo add a virtual switch use the following:\n\n```yaml\nTest Switch:\n- platform: switch\n```\n\n## Binary Sensors\nTo add a virtual binary_sensor use the following. It supports all standard\nclasses.\n\n```yaml\nTest Binary Sensor:\n- platform: binary_sensor\n  initial_value: 'on'\n  class: presence\n```\n\nUse the `virtual.turn_on`, `virtual.turn_off` and `virtual.toggle` services to\nmanipulate the binary sensors.\n\n## Sensors\n\nTo add a virtual sensor use the following:\n\n```yaml\nTest Sensor:\n- platform: sensor\n  class: temperature\n  initial_value: 37\n  unit_of_measurement: 'F'\n```\n\nUse the `virtual.set` service to manipulate the sensor value.\n\nSetting `unit_of_measurement` can override default unit for selected sensor\nclass. This is optional ans any string is accepted. List of standard units can\nbe found here:\n[Sensor Entity](https://developers.home-assistant.io/docs/core/entity/sensor/)\n\n## Lights\n\nTo add a virtual light use the following:\n\n```yaml\nTest Lights:\n- platform: light\n  initial_value: 'on'\n  support_brightness: true\n  initial_brightness: 100\n  support_color: true\n  initial_color: [0,255]\n  support_color_temp: true\n  initial_color_temp: 255\n  support_white_value: true\n  initial_white_value: 240\n```\n\nOnly `name` is required.\n- `support_*`; this allows the light to have colour and temperature properties\n- `initial_*`; this is to set the initial values. `initial_color` is `[hue\n  (0-360), saturation (0-100)]`\n\n_Note; *white_value is deprecated and will be removed in future releases._\n\n## Locks\n\nTo add a virtual lock use the following:\n\n```yaml\nTest Lock:\n- platform: lock\n  name: Front Door Lock\n  initial_value: locked\n  locking_time: 5\n  jamming_test: 5\n```\n\n- Persistent Configuration\n  - `initial_value`: optional, default `locked`; any other value will result in the lock\n    being unlocked at start up\n- Per Run Configuration\n  - `locking_time`: optional, default `0` seconds; any positive value will result in a\n    locking or unlocking phase that lasts `locking_time` seconds\n  - `jamming_test`: optional, default `0` tries; any positive value will result in a\n    jamming failure approximately once per `jamming_test` tries\n\n## Fans\n\nTo add a virtual fan use the following:\n\n```yaml\nTest Fan:\n- platform: fan\n  speed: True\n  speed_count: 5\n  direction: True\n  oscillate: True\n```\n\nYou only need one of `speed` or `speed_count`.\n- `speed`; if `True` then fan can be set to low, medium and high speeds\n- `speed_count`; number of speeds to allow, these will be broken down into\n  percentages. 4 speeds = 25, 50, 75 and 100%.\n- `direction`; if `True` then fan can run in 2 directions\n- `oscillate`; if `True` then fan can be set to oscillate\n\n## Covers\n\nTo add a virtual cover use the following:\n\n```yaml\nTest Cover:\n- platform: cover\n  initial_value: 'closed'\n  open_close_duration: 10\n  open_close_tick: 1\n```\n\nSupports `open`, `close`, `stop` and `set_position`. Opening and closing of\nthe cover is emulated with timed events, and the timing can be controlled with\n- `open_close_duration`: The time it take to go from fully open to fully closed, or back\n- `open_close_tick`: The update interval when opening and closing\n\n## Valves\n\nTo add a virtual valve use the following:\n\n```yaml\nTest Valve:\n- platform: valve\n  initial_value: 'closed'\n  open_close_duration: 10\n  open_close_tick: 1\n```\n\nSupports `open`, `close`, `stop` and `set_position`. Opening and closing of\nthe valve is emulated with timed events, and the timing can be controlled with\n- `open_close_duration`: The time it take to go from fully open to fully closed, or back\n- `open_close_tick`: The update interval when opening and closing\n\n## Device Tracking\n\nTo add a virtual device tracker use the following:\n\n```yaml\nTest Device_Tracker:\n- platform: device_tracker\n  initial_value: home\n```\n\n- `persistent`: default `True`; if `True` then entity location is remembered\n  across restarts otherwise entity always starts at `location`\n- `location`: default `home`; this sets the device location when it is created\n  or if the device is not `persistent`\n\nUse the `virtual.move` service to change device locations.\n\n\n# Old Style Entity Configuration\n\nFor now; look at [the 0.8](https://github.com/twrecked/hass-virtual/tree/version-0.8.x?tab=readme-ov-file#component-configuration) documentation.\n\n\n# Services\n\nThe component provides the following services:\n\n**Name: `virtual.set_availability`**\n\n*Parameters:*\n- `entity_id`; The entity id of the binary sensor to turn on.\n\nThis will change the availability setting of any virtual device.\n\n---\n\n**Name: `virtual.turn_on`**\n\n*Parameters:*\n- `entity_id`; The entity id of the binary sensor to turn on.\n\nThis service will turn on a binary sensor.\n\n---\n\n**Name: `virtual.turn_off`**\n\n*Parameters:*\n- `entity_id`; The entity id of the binary sensor to turn off.\n\nThis service will turn off a binary sensor.\n\n---\n\n**Name: `virtual.toggle`**\n\n*Parameters:*\n- `entity_id`; The entity id of the binary sensor to toggle.\n\n- This service will toggle a binary sensor.\n\n---\n\n**Name: `virtual.move`**\n\n*Parameters:*\n\n- `location`; a named location\n- `gps`; GPS coordinates\n\nMove a device tracker. You use one of the parameters.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwrecked%2Fhass-virtual","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwrecked%2Fhass-virtual","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwrecked%2Fhass-virtual/lists"}