synthetic-home 5.0.1

Library for managing synthetic home device registry

synthetic-home

Library for generating synthetic homes, devices, and entities. This project is primarily used by the home-assistant-synthetic-home custom component that can make a home out of an inventory and the 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.

---
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 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 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 to actually load a Home Assistant instance with these areas, devices, and entities.

---
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:

$ 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 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:

---
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:

$ synthetic-home create_inventory famhouse-home.yaml > inventory.yaml

This can then be loaded into a home-assistants-synthetic-home custom component.