home-assistant.io/source/_components/snips.markdown

layout	title	description	date	sidebar	comments	sharing	footer	logo	ha_category	ha_release
page	Snips	Instructions how to integrate Snips within Home Assistant.	2017-06-22 12:00	true	false	true	true	snips.png	Voice	0.48

The Snips Voice Platform allows users to add powerful voice assistants to their Raspberry Pi devices without compromising on privacy. It runs 100% on-device, and does not require an internet connection. It features Hotword Detection, Automatic Speech Recognition (ASR), Natural Language Understanding (NLU) and Dialog Management.

The latest documentation can be found here: Snips Platform Documentation.

Snips takes voice or text as input and produces intents as output, which are explicit representations of an intention behind an utterance and which can subsequently be used by Home Assistant to perform appropriate actions.

{% linkable_title The Snips Voice Platform %}

{% linkable_title Installation %}

The Snips Voice Platform is installed as a Docker image on Raspberry Pi with the following command:

(pi) $ curl https://install.snips.ai -sSf | sh

Snips can also be installed on a Debian/Ubuntu machine as well:

$ sudo apt-get update
$ sudo apt-get install -y dirmngr
$ sudo bash -c  'echo "deb https://debian.snips.ai/$(lsb_release -cs) stable main" > /etc/apt/sources.list.d/snips.list'
$ sudo apt-key adv --keyserver pgp.mit.edu --recv-keys F727C778CCB0A455

$ sudo apt-get update
$ sudo apt-get install -y snips-platform-voice

{% linkable_title Creating an assistant %}

Snips assistants are created via the Snips Console. Once trained, the assistant should be downloaded and copied to the Raspberry Pi:

$ scp assistantproj_XXX.zip pi@pi_hostname:/home/pi/assistant.zip

and installed locally via the snips-install-assistant helper script:

(pi) $ sudo snips-install-assistant assistant.zip

{% linkable_title Running Snips %}

Make sure that a microphone is plugged to the Raspberry Pi. If you are having trouble setting up audio, we have written a guide on Raspberry Pi Audio Configuration.

Start the Snips Voice Platform using the snips command:

Raspberry Pi:

(pi) $ snips

Debian/Ubuntu:

$ sudo systemctl start "snips-*"

Snips is now ready to take voice commands from the microphone. To trigger the listening, simply say

Hey Snips

followed by a command, e.g.

Set the lights to green in the living room

We should see the transcribed phrase in the logs, as well as a properly parsed intent. The intent is published on MQTT, on the hermes/intent/<slotName> topic. The Snips Home Assistant component subscribes to this topic, and handles the intent according to the rules defined in configuration.yaml, as explained below.

{% linkable_title Optional: specifying an external MQTT broker %}

By default, Snips runs its own MQTT broker. But we can also tell Snips to use an external broker by specifying this when launching Snips. In this case, instead of running the snips command above (which assumes we are using the internal MQTT broker), we use the full launch command with explicitly specified parameters (replace MQTT_BROKER_IP and MQTT_BROKER_PORT with appropriate values):

Raspberry Pi:

$ docker run -t --rm --name snips --log-driver none \
    -v /home/pi/.asoundrc:/root/.asoundrc \
    -v /opt/snips/config:/opt/snips/config \
    --privileged -v /dev/snd:/dev/snd snipsdocker/platform \
    --mqtt MQTT_BROKER_IP:MQTT_BROKER_PORT

Debian/Ubuntu:

Edit the /etc/snips.toml file. See snips documentation for more information on configuring this

For more details on launch options, check the documentation on Snips Platform Commands.

{% linkable_title Home Assistant configuration %}

{% linkable_title Specifying the MQTT broker %}

Messages between Snips and Home Assistant are passed via MQTT. We must tell Home Assistant which MQTT broker to use by adding the following entry to the configuration.yaml file:

mqtt:
  broker: MQTT_BROKER_IP
  port: MQTT_BROKER_PORT

As explained above, Snips by default runs an MQTT broker on port 9898. So if we wish to use this broker, the entry will look as follows:

mqtt:
  broker: 127.0.0.1
  port: 9898

Alternatively, MQTT can be configured to bridge messages between servers if using a custom MQTT broker such as mosquitto.

{% linkable_title Triggering actions %}

In Home Assistant, we trigger actions based on intents produced by Snips using the intent_script component. For instance, the following block handles ActivateLightColors intents (included in the Snips IoT intent bundle) to change light colors:

{% raw %}

snips:

intent_script:
  ActivateLightColor:
    action:
      - service: light.turn_on
        data_template:
          entity_id: light.{{ objectLocation | replace(" ","_") }}
          color_name: {{ objectColor }}

{% endraw %}

The variables that can be used in the template are of the form 'slotName = value'.

Snips intents that utilize builtin slot types will contain extended information along with the value and can be exposed using this format:

{% raw %}

SetTimer:
  speech:
    type: plain
    text: weather
  action:
    service: script.set_timer
    data_template:
      name: "{{ timer_name }}"
      duration: "{{ timer_duration }}"
      seconds: "{{ slots.timer_duration.value.seconds }}"
      minutes: "{{ slots.timer_duration.value.minutes }}"
      hours: "{{ slots.timer_duration.value.hours }}"

{% endraw %}

Sending TTS Notifications

You can send TTS notifications to Snips using the snips.say and snips.say_action services. Say_action starts a session and waits for user response, "Would you like me to close the garage door?", "Yes, close the garage door".

{% linkable_title Service snips/say %}

Service data attribute	Optional	Description
text	no	Text to say.
site_id	yes	Site to use to start session.
custom_data	yes	custom data that will be included with all messages in this session.

{% linkable_title Service snips/say_action %}

Service data attribute	Optional	Description
text	no	Text to say.
site_id	yes	Site to use to start session.
custom_data	yes	custom data that will be included with all messages in this session.
can_be_enqueued	yes	If True, session waits for an open session to end, if False session is dropped if one is running.
intent_filter	yes	Array of Strings - A list of intents names to restrict the NLU resolution to on the first query.

Configuration Examples

script:
  turn_on_light:
    sequence:
      service: script.turn_on_light
      service: snips.say
        data:
          text: 'OK, the light is now on'

automation:
  query_garage_door:
    trigger:
     - platform: state
        entity_id: binary_sensor.my_garage_door_sensor
        from: 'off'
        to: 'on'
        for:
          minutes: 10
    sequence:
      service: snips.say_action
        data:
          text: 'Garage door has been open 10 minutes, would you like me to close it?'
          intentFilter:
            - closeGarageDoor

# This intent is fired if the user responds with the appropriate intent after the above notification
intent_script:
  closeGarageDoor:
    speech:
      type: plain
      text: 'OK, closing the garage door'
    action:
      - service: script.garage_door_close