# synthetic-home
Library for generating synthetic homes, devices, and entities. This project is primarily
used by the [home-assistant-synthetic-home](https://github.com/allenporter/home-assistant-synthetic-home)
custom component that can make a home out of an inventory and the [home-assistant-datasets](https://github.com/allenporter/home-assistant-datasets)
which creates instances of synthetic homes and devices.
## Overview
### Home
A home contains a definition of home with areas and devices. This example home is
called *Family Farmhouse* with two devices in the *Kitchen*.
```yaml
---
name: Family Farmhouse
devices:
Kitchen:
- name: Light
device_type: light-dimmable
- name: Coffe Maker
device_type: smart-plug
device_info:
manufacturer: Shelly
```
### Device Registry
The above devices are of type *light-dimmable* and *smart-plug*. These device types
are defined in a *Device Registry* that maps a higher level device type into lower
level entities. For example, a *smart-plug* device is represented by a *switch*
and a *sensor* that measures power draw. A device can also define device states
which are mapped to the individual entity states.
The [home-assistant-datasets](https://github.com/allenporter/home-assistant-datasets) project
uses an LLM to create devices within a home without having to worry about the lower
level details of entities and attributes.
See the [synthetic_home/registry](synthetic_home/registry) for details on the registry.
### Device types
Device types are defined to represent common configured household devices,
but may not support every single feature in the smart home. That is, these
are meant to be representative, but not necessarily exhaustive.
Each file in `synthetic_home/registry` directory contains a device type name. New device
types may be added as new use cases are needed.
### Inventory
An inventory is set of devies, areas, and most importantly individual *Entities*, and a default state and set of attributes. An inventory can be used by [home-assistant-synthetic-home](https://github.com/allenporter/home-assistant-synthetic-home) to actually load a Home Assistant instance with these
areas, devices, and entities.
```yaml
---
areas:
- name: Family room
id: family_room
devices:
- name: Floor Lamp
id: floor_lamp
area: family_room
info:
manufacturer: Wyze
entities:
- name: Floor Lamp Energy
id: sensor.floor_lamp_energy
area: family_room
device: floor_lamp
state: '1'
attributes:
device_class: sensor.SensorDeviceClass.ENERGY
state_class: sensor.SensorStateClass.TOTAL_INCREASING
native_unit_of_measurement: kWh
- name: Floor Lamp
id: switch.floor_lamp
area: family_room
device: floor_lamp
state: true
attributes:
device_class: switch.SwitchDeviceClass.OUTLET
```
## Inventory Creation
There are multiple ways to create an inventory.
### Export from Home Assistant
You can create a synthetic home inventory copied from an existing home assistant
instance. You need to create an access token and export an inventory like this:
```bash
$ HASS_URL="http://home-assistant.home-assistant:8123"
$ API_TOKEN="XXXXXXXXXXX"
$ synthetic-home --debug export_inventory "${HASS_URL}" "${API_TOKEN}" > inventory.yaml
```
### Manual Inventory
You can manually create an inventory by hand, but even better is to use a home definition
for a set of devies. See [home-asssistant-datasets](https://github.com/allenporter/home-assistant-datasets)
for some existing repos of synthetic homes created by an LLM. Or create one yourself based on
devices you want to test defined in the device registry. Given an example `famhouse-home.yaml`:
```yaml
---
name: Family Farmhouse
devices:
Family Room:
- name: Family Room Lamp
device_type: light
device_info:
manufacturer: Phillips
model: Hue
- name: Family Room
device_type: hvac
device_info:
manufacturer: Nest
sw_version: 1.0.0
attributes:
unit_of_measurement: °F
current_temperature: 60
- name: Left Window
device_type: window-sensor
- name: Right Window
device_type: window-sensor
Entry:
- name: Front Door
device_type: smart-lock
Kitchen:
- name: Light
device_type: light-dimmable
- name: Coffe Maker
device_type: smart-plug
device_info:
manufacturer: Shelly
Master Bedroom:
- name: Bedroom Light
device_type: light-dimmable
- name: Bedroom Blinds
device_type: smart-blinds
device_info:
model: RollerBlinds
manufacturer: Motion Blinds
sw_version: 1.1.0
- name: Bedroom Window
device_type: window-sensor
Garage:
- name: Garage Door
device_type: garage-door
Front Yard:
- name: Front motion
device_type: motion-sensor
```
You can export an inventory file:
```bash
$ synthetic-home create_inventory famhouse-home.yaml > inventory.yaml
```
This can then be loaded into a [home-assistants-synthetic-home](https://github.com/allenporter/home-assistant-synthetic-home/) custom component.
Raw data
{
"_id": null,
"home_page": "https://github.com/allenporter/synthetic-home",
"name": "synthetic-home",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Allen Porter",
"author_email": "allen.porter@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/73/0b/30e0c892d94f6613af5612559fbd2fe9763c5a02a7a4ce4eedc811d53fe1/synthetic_home-4.3.2.tar.gz",
"platform": null,
"description": "# synthetic-home\n\nLibrary for generating synthetic homes, devices, and entities. This project is primarily\nused by the [home-assistant-synthetic-home](https://github.com/allenporter/home-assistant-synthetic-home)\ncustom component that can make a home out of an inventory and the [home-assistant-datasets](https://github.com/allenporter/home-assistant-datasets)\nwhich creates instances of synthetic homes and devices.\n\n## Overview\n\n### Home\n\nA home contains a definition of home with areas and devices. This example home is\ncalled *Family Farmhouse* with two devices in the *Kitchen*.\n\n```yaml\n---\nname: Family Farmhouse\ndevices:\n Kitchen:\n - name: Light\n device_type: light-dimmable\n - name: Coffe Maker\n device_type: smart-plug\n device_info:\n manufacturer: Shelly\n```\n\n### Device Registry\n\nThe above devices are of type *light-dimmable* and *smart-plug*. These device types\nare defined in a *Device Registry* that maps a higher level device type into lower\nlevel entities. For example, a *smart-plug* device is represented by a *switch*\nand a *sensor* that measures power draw. A device can also define device states\nwhich are mapped to the individual entity states.\n\nThe [home-assistant-datasets](https://github.com/allenporter/home-assistant-datasets) project\nuses an LLM to create devices within a home without having to worry about the lower\nlevel details of entities and attributes.\n\nSee the [synthetic_home/registry](synthetic_home/registry) for details on the registry.\n\n### Device types\n\nDevice types are defined to represent common configured household devices,\nbut may not support every single feature in the smart home. That is, these\nare meant to be representative, but not necessarily exhaustive.\n\nEach file in `synthetic_home/registry` directory contains a device type name. New device\ntypes may be added as new use cases are needed.\n\n### Inventory\n\nAn inventory is set of devies, areas, and most importantly individual *Entities*, and a default state and set of attributes. An inventory can be used by [home-assistant-synthetic-home](https://github.com/allenporter/home-assistant-synthetic-home) to actually load a Home Assistant instance with these\nareas, devices, and entities.\n\n```yaml\n---\nareas:\n- name: Family room\n id: family_room\ndevices:\n- name: Floor Lamp\n id: floor_lamp\n area: family_room\n info:\n manufacturer: Wyze\nentities:\n- name: Floor Lamp Energy\n id: sensor.floor_lamp_energy\n area: family_room\n device: floor_lamp\n state: '1'\n attributes:\n device_class: sensor.SensorDeviceClass.ENERGY\n state_class: sensor.SensorStateClass.TOTAL_INCREASING\n native_unit_of_measurement: kWh\n- name: Floor Lamp\n id: switch.floor_lamp\n area: family_room\n device: floor_lamp\n state: true\n attributes:\n device_class: switch.SwitchDeviceClass.OUTLET\n```\n\n## Inventory Creation\n\nThere are multiple ways to create an inventory.\n\n### Export from Home Assistant\n\nYou can create a synthetic home inventory copied from an existing home assistant\ninstance. You need to create an access token and export an inventory like this:\n\n```bash\n$ HASS_URL=\"http://home-assistant.home-assistant:8123\"\n$ API_TOKEN=\"XXXXXXXXXXX\"\n$ synthetic-home --debug export_inventory \"${HASS_URL}\" \"${API_TOKEN}\" > inventory.yaml\n```\n\n### Manual Inventory\n\nYou can manually create an inventory by hand, but even better is to use a home definition\nfor a set of devies. See [home-asssistant-datasets](https://github.com/allenporter/home-assistant-datasets)\nfor some existing repos of synthetic homes created by an LLM. Or create one yourself based on\ndevices you want to test defined in the device registry. Given an example `famhouse-home.yaml`:\n\n```yaml\n---\nname: Family Farmhouse\ndevices:\n Family Room:\n - name: Family Room Lamp\n device_type: light\n device_info:\n manufacturer: Phillips\n model: Hue\n - name: Family Room\n device_type: hvac\n device_info:\n manufacturer: Nest\n sw_version: 1.0.0\n attributes:\n unit_of_measurement: \u00b0F\n current_temperature: 60\n - name: Left Window\n device_type: window-sensor\n - name: Right Window\n device_type: window-sensor\n Entry:\n - name: Front Door\n device_type: smart-lock\n Kitchen:\n - name: Light\n device_type: light-dimmable\n - name: Coffe Maker\n device_type: smart-plug\n device_info:\n manufacturer: Shelly\n Master Bedroom:\n - name: Bedroom Light\n device_type: light-dimmable\n - name: Bedroom Blinds\n device_type: smart-blinds\n device_info:\n model: RollerBlinds\n manufacturer: Motion Blinds\n sw_version: 1.1.0\n - name: Bedroom Window\n device_type: window-sensor\n Garage:\n - name: Garage Door\n device_type: garage-door\n Front Yard:\n - name: Front motion\n device_type: motion-sensor\n```\n\nYou can export an inventory file:\n\n```bash\n$ synthetic-home create_inventory famhouse-home.yaml > inventory.yaml\n```\n\nThis can then be loaded into a [home-assistants-synthetic-home](https://github.com/allenporter/home-assistant-synthetic-home/) custom component.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Library for managing synthetic home device registry",
"version": "4.3.2",
"project_urls": {
"Homepage": "https://github.com/allenporter/synthetic-home"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9b4cc14126d83059b6e8e0a7b6328a2e058540840d49859c2774d2b57bfa187b",
"md5": "b0955434d8fd38f18b6b6cbea66ae8eb",
"sha256": "e330dbf730fb5054c3c264edcac11604d6b1d7eb004fb9618dc3f00cb0705412"
},
"downloads": -1,
"filename": "synthetic_home-4.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b0955434d8fd38f18b6b6cbea66ae8eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 34582,
"upload_time": "2024-08-13T05:05:40",
"upload_time_iso_8601": "2024-08-13T05:05:40.511225Z",
"url": "https://files.pythonhosted.org/packages/9b/4c/c14126d83059b6e8e0a7b6328a2e058540840d49859c2774d2b57bfa187b/synthetic_home-4.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "730b30e0c892d94f6613af5612559fbd2fe9763c5a02a7a4ce4eedc811d53fe1",
"md5": "04761779a703cc71ce0b0629b21b765a",
"sha256": "842abc21afd3e960f840b7749bd863ad73d4396d08929bdf8ecc876ddd906741"
},
"downloads": -1,
"filename": "synthetic_home-4.3.2.tar.gz",
"has_sig": false,
"md5_digest": "04761779a703cc71ce0b0629b21b765a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 26229,
"upload_time": "2024-08-13T05:05:41",
"upload_time_iso_8601": "2024-08-13T05:05:41.845439Z",
"url": "https://files.pythonhosted.org/packages/73/0b/30e0c892d94f6613af5612559fbd2fe9763c5a02a7a4ce4eedc811d53fe1/synthetic_home-4.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-13 05:05:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "allenporter",
"github_project": "synthetic-home",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "synthetic-home"
}
JSON
