Intent Handling
After a voice command has been transcribed and your intent has been successfully recognized, Rhasspy is ready to send a JSON event to another system like Home Assistant or Node-RED.
Regardless of which intent handling system you choose, Rhasspy emits JSON events over a websocket connection.
Home Assistant
Add to your profile:
"handle": {
"system": "hass"
},
"home_assistant": {
"access_token": "",
"api_password": "",
"event_type_format": "rhasspy_{0}",
"url": "http://hassio/homeassistant/"
}
If you're running Rhasspy as an add-on inside Hass.io, the access token is automatically provided. Otherwise, you'll need to create a long-lived access token and set home_assistant.access_token
manually.
See rhasspy.intent_handler.HomeAssistantIntentHandler
for details.
Events
Rhasspy will send Home Assistant an event every time an intent is recognized through its REST API. The type of the event is determined by the name of the intent, and the event data comes from the tagged words in your sentences.
For example, if you have an intent like:
[ChangeLightColor]
set the (bedroom light){name} to (red | green | blue){color}
and you say something like "set the bedroom light to blue", Rhasspy will POST to the /api/events/rhasspy_ChangeLightColor
endpoint of your Home Assistant server with the following data:
{
"name": "bedroom light",
"color": "blue"
}
In order to do something with the rhasspy_ChangeLightColor
event, create an automation with an event trigger. For example, add the following to your automation.yaml
file:
- alias: "Set bedroom light color (blue)"
trigger:
platform: event
event_type: rhasspy_ChangeLightColor
event_data:
name: 'bedroom light'
color: 'blue'
action:
...
See the documentation on actions for the different things you can do with Home Assistant.
Intents
More recent versions of Home Assistant can accept intents directly. Add the following to your configuration.yaml
file:
intent:
This will enable intents over the HTTP API. Next, write intent scripts to handle each Rhasspy intent:
intent_script:
ChangeLightColor:
action:
...
The possible actions are the same as in automations.
MQTT
In addition to events, Rhasspy can also publish intents through MQTT (Hermes protocol). This allows Rhasspy to send intents to Snips.AI.
Add to your profile:
"mqtt": {
"enabled": true,
"host": "localhost",
"username": "",
"password": "",
"port": 1883,
"reconnect_sec": 5,
"site_id": "default",
"publish_intents": true,
"tls": {
"enabled": false,
"ca_certs": "",
"cert_reqs": "CERT_REQUIRED",
"certfile": "",
"ciphers": "",
"keyfile": ""
}
}
Adjust the mqtt
configuration to connect to your MQTT broker.
Set mqtt.site_id
to match your Snips.AI siteId.
Add to your Home Assistant's configuration.yaml
file:
snips:
intent_script:
...
See the intent script documentation for details on how to handle the intents.
Self-Signed Certificate
If your Home Assistant uses a self-signed certificate, you'll need to give Rhasspy some extra information.
Add to your profile:
"home_assistant": {
...
"pem_file": "/path/to/certfile"
}
Set home_assistant.pem_file
to the full path to your CA_BUNDLE file or a directory with certificates of trusted CAs.
Use the environment variable RHASSPY_PROFILE_DIR
to reference your current profile's directory. For example, $RHASSPY_PROFILE_DIR/my.pem
will tell Rhasspy to use a file named my.pem
in your profile directory when verifying your self-signed certificate.
Remote Server
Rhasspy can POST the intent JSON to a remote URL.
Add to your profile:
"handle": {
"system": "remote",
"remote": {
"url": "http://<address>:<port>/path/to/endpoint"
}
}
When an intent is recognized, Rhasspy will POST to handle.remote.url
with the intent JSON. You should return JSON back, optionally with additional information. If handle.forward_to_hass
is true
, Rhasspy will look for a hass_event
property of the returned JSON with the following structure:
{
// rest of input JSON
// ...
"hass_event": {
"event_type": "...",
"event_data": {
"key": "value",
// ...
}
}
}
Rhasspy will create the Home Assistant event based on this information. If it is not present, the remaining intent information will be used to construct the event as normal (i.e., intent
and entities
). If handle.forward_to_hass
is false
, the output of your program is not used.
Speech
If the returned JSON contains a "speech" key like this:
{
...
"speech": {
"text": "Some text to speak."
}
}
then Rhasspy will forward speech.text
to the configured text to speech system.
See rhasspy.intent_handler.RemoteIntentHandler
for details.
Command
Once an intent is successfully recognized, Rhasspy will send an event to Home Assistant with the details. You can call a custom program instead or in addition to this behavior.
Add to your profile:
"handle": {
"system": "command",
"command": {
"program": "/path/to/program",
"arguments": []
},
"forward_to_hass": true
}
When an intent is recognized, Rhasspy will call your custom program with the intent JSON printed to standard in. You should return JSON to standard out, optionally with additional information. If handle.forward_to_hass
is true
, Rhasspy will look for a hass_event
property of the returned JSON with the following structure:
{
// rest of input JSON
// ...
"hass_event": {
"event_type": "...",
"event_data": {
"key": "value",
// ...
}
}
}
Rhasspy will create the Home Assistant event based on this information. If it is not present, the remaining intent information will be used to construct the event as normal (i.e., intent
and entities
). If handle.forward_to_hass
is false
, the output of your program is not used.
The following environment variables are available to your program:
$RHASSPY_BASE_DIR
- path to the directory where Rhasspy is running from$RHASSPY_PROFILE
- name of the current profile (e.g., "en")$RHASSPY_PROFILE_DIR
- directory of the current profile (whereprofile.json
is)
See handle.sh or handle.py for example programs.
Speech
If the returned JSON contains a "speech" key like this:
{
...
"speech": {
"text": "Some text to speak."
}
}
then Rhasspy will forward speech.text
to the configured text to speech system.
See rhasspy.intent_handler.CommandIntentHandler
for details.
Dummy
Disables intent handling.
Add to your profile:
"handle": {
"system": "dummy"
}
See rhasspy.intent_handler.DummyIntentHandler
for details.