Home Assistant Integration

Flask-Assistant includes a HassRemote interface to make requests to Home Assistant’s REST api. This allows your Dialogflow agent to control and retrieve data about your IoT devices.

Integrating your assistant with Home Assistant is as easy as adding a method call to your action functions.

Using the HassRemote

First import and create an instance of the HassRemote.

from flask import Flask
from flask_assistant import Assistant, tell
from flask_assistant.hass import HassRemote

app = Flask(__name__)
assist = Assistant(app)
hass = HassRemote('YOUR Home Assistant PASSWORD')

Sending Requests to Home Assistant

The HassRemote is a simple wrapper around Home Assistant’s own remote module. The remote module can be used in the same way to control Home Assistant. HassRemote just provides a set of methods for commonly sent requests specific to entitiy domain. These methods will often accept the same paramter as the action function itself, allowing clean and more cohesive code within action functions.

Important

Each of these methods require the entity_id parameter. The name of this parameter should be the same as the Home Assistant domain.

For example:

If you have a switch in your HA configuration with the name “switch.coffee_maker”, the name of the parameter should be “switch”. This allows your entities to be properly defined within your entities.yaml template when generating schema.

Controlling Lights

@assist.action('turn-on-light')
def light_on(light, brightness=255):
    speech = 'Turning on {} to {}'.format(light, brightness)
    hass.turn_on_light(light, brightness)
    return tell(speech)

@assist.action('turn-off-light')
def light_off(light):
    speech = 'Turning off {}'.format(light)
    hass.turn_off_light(light)
    return tell(speech)

Flip a Switch

@assist.action('toggle-switch')
def toggle(switch):
    speech = 'Toggling switch for {}'.format(switch)
    hass.switch(switch)
    return tell(speech)

@assist.action('switch-on')
def switch_on(switch):
    speech = 'Flipping on {} switch'.format(switch)
    hass.switch(switch, service='turn_on')
    return tell(speech)

Starting HA Scripts

@assist.action('start-script')
def start(script):
    speech = 'Running {}'.format('script.{}'.format(script))
    hass.start_script(script)
    return tell(speech)

Running Shell Commands

@assist.action('run-command')
def run(shell_command):
    speech = 'Running the {} shell command'.format(shell_command)
    hass.command(shell_command)
    return tell(speech)

Hass Entity Templates

Home Assistant devices used within action functions can easily be included in your entries template, and are automatically added with the when generating schema.

Although Home Assistant and Dialogflow both use the term entities, they are used in slightly different ways.

Home Assistant:
  • uses the term entity to describe any device or service connected to HA.
  • Each entity belongs to a domain (component).
Dialogflow:
  • Uses the term entity to describe a concept that is used within actions
  • Each instance of the entity is called an entry, and may be the value of parameters required by actions

Therefore, the idea of a HA entity is similar to an Dialogflow entry.

So HA devices can be defined as entries under their domain, with their domain serving as the Dialogflow entity.

domain:
    - device1: [synonyms]
    - device2: [synonyms]

Template Examples

A Group of Lights:

light:
  - lamp_1: ['ceiling light', 'fan light', 'main light']
  - lamp_2: ['lamp', 'desk lamp']
  - lamp_3: ['bedroom light', 'room light', 'bedroom']
  - room: ['all lights', 'lights', 'room'] # a group within home assistant

Within Home Assistant lamp_2 would be identified as light.lamp_2 and room as light.room

Switches

switch:
  - coffee_maker: ['coffee', 'brew', 'coffee machine']
  - playstation4: ['ps4', 'playstation']
  - stereo: ['sound', 'sound system']

Scripts

script:
  - flash_lights: ['flash', 'flash the lights', 'strobe']
  - party_mode: ['bump it up', 'start the party']

Shell Commands

shell_command:
  - playstation_netflix_start: ['netflix', 'netflix on the ps4']
  - playstation_overwatch_start: [overwatch]
  - playstation_gtav_start: [gta five, gta]