Package: ovos-PHAL-plugin-homeassistant
OVOS PHAL Home Assistant PluginThe PHAL Plugin provides GUI interfaces and API for Home Assistant Instants.NOTE: this plugin is roadmapped for merging withhttps://github.com/OpenVoiceOS/ovos-PHAL-plugin-commonIOTfor ovos-core release 0.0.9, the UI will become IOT framework agnosticDemo GIFInstallationPlugin Support Two Installation Methods:Install from Github URLNote: PIP install from URL will not install the .desktop file and icon if installing to a venv or virtual environment, so you need to manually install them to the system or user directory.Note: PIP install will attempt to install the .desktop file and icon to the system directory, or user directory if the system directory is not writable. If this is not a virtual environemnt.pipinstallgit+https://github.com/OpenVoiceOS/ovos-PHAL-plugin-homeassistantManual Install from Git Clonegitclonehttps://github.com/OpenVoiceOS/ovos-PHAL-plugin-homeassistantcdovos-PHAL-plugin-homeassistant
cp-rres/desktop/ovos-phal-homeassistant.desktop~/.local/share/applications/
cp-rres/icon/ovos-phal-homeassistant.png~/.local/share/icons/
pipinstall.Configuration (Instance Setup)Plugin Supports Two Configuration Methods:Using the GUIInstall the pluginOpen the application from the homescreen menuClick the "Connect Instance" buttonEnter the URL of the Home Assistant InstanceEnter the Long-Lived Access Token (API KEY)Press the "Confirm" buttonManually Editing the Config FileAdd the following to the config file:"PHAL":{"ovos-PHAL-plugin-homeassistant":{"host":"https://someurl.toinstance","api_key":"api key from the instance"}}The config also takes some optional properties:brightness_increment- the amount to increment/decrement the brightness of a light when the brightness up/down commands are sent. The default value is 10 and represents a percentage, e.g. 10%.search_confidence_threshold- the confidence threshold for the search skill to use when searching for devices. The default value is 0.5, or 50%. Must be a value between 0 and 1.Sample config:"PHAL":{"ovos-PHAL-plugin-homeassistant":{"host":"https://someurl.toinstance","api_key":"api key from the instance","brightness_increment":5,"search_confidence_threshold":0.6}}UsageThe plugin provides a GUI interface for Home Assistant Instances. It also provides an API for other plugins or skills to user.The plugin is in early development, so there are some features that are not yet implemented. It currently supports the following entities:Media PlayerLightVacuumBinary SensorSensorBUS API (For Other Plugins / GUIs) - WIP / TODO DocumentationEXPANDING DEVICE / ENTITY SUPPORT - WIP / TODO DocumentationTechnical DocumentationPython Controller Class Specification:Depending on how the controller communicates with the host instance, the minimum required connector initialization properties are:host(type: string): Address to host instanceapi_key(type: string): Access key for host instance authenticationPython Device Class Specification:All devices are required to support the below minimal properties for device initialization.controller(type: string): An instance of the controller class that handles all communications with the API the device talks to for example HomeAssistantConnector, All devices will use the controller class for any kind of communication.device_id(type: string): A device id to associate all communications with this device with, for HomeAssistant device_id = entity_id, all device_id start with device_type.device_name.device_icon(type: string): A device icon to associate the device display icon with including type, for example: "mdi:light" for device type light, "mdi:sensor" for device type sensor, "mdi:media_player" for device type media_playerdevice_name(type: string): A human readable device name that can be used for spoken and visual materialdevice_state(type: string): A device can have multiple states depending on which type of device it is, for example a light can have an "on", "off" and "unavailable" states, a media_player can have "playing", "paused", "off", "on" and "unavailable" states. Refer to HomeAssistant entities list for complete list of entity statesdevice_attributes(type: dict): Device attributes provide information of the device such as supported properties and values, they can consist of information such as: "brightness", "rgb_color", "supported_color_mode" in case of lights for example. Refer to HomeAssistant entities list for complete list of entity attributesQML GUI Device Display Model Specification:id(type: string): Device ID as per the device class specification.name(type: string): Device display name as per the device class specificationicon(type: string): Device icon name as per the device class specificationstate(type: string): Device state as updated or provided by device in the device class specificationtype(type: string): Device type assigned to the device when the device is registerd, this is not an initialization property and is extracted from the device_id where device_id = "device_type.device_name" generally in HomeAssistant APIattributes(type: dict): Device attributes as provided by the device during various state changes and initial state at time of registeration