TutorialSmarthome - albertmon/smarthome GitHub Wiki

Contents

Introduction

After having done your first steps following the Step-By-Step Guide, you may want to alter the intents, add strings to recognize, adding intents etc.

This page explains the way you can alter, add or remove intents.

  • When you encounter problems, look in the logfile (it is located in the handler directory in volumes/rhasspy/profiles/xx/ where xx is your profile code (en, fr or nl etc)
  • First carefully read the Rhasspy documentation about sentences.ini
    If you followed the Step-By-Step Guide you have already copied a sentences.ini with default intents.
    If you haven't, look at the sentences.ini in the smarthome github, edit and copy it to your Rhasspy profile directory. All changes can be made in the Rhasspy User Interface http://\<your rhasspy pi>:12101/sentences) (replace <your rhasspy pi> by the right IP-number or host)

Passing parameters

Much of the intent handling (as implemented) depends heavily on the tags mechanism. Tags are used to send parameters to the intent handler. In some contexts the term slot is used for tag. (Technically: a tag in sentences.ini is used to put a value in a slot with the name of the tag)
Essentially there are 2 ways to pass parameters:

  1. By using the spoken value as in:
    [DomoSwitch]
    put (on:On|off:Off){state} the (((library lamp):32)|(reading lamp):36){idx}
    In this example the spoken text library lamp is replaced by 32 and put in the parameter idx (slot with name idx)
  2. As an extra parameter to the intenthander as in:
    [Dummy]
    I love you (:){speech:I love you too}

For some intents there are required parameters (e.g. the index of a switch or scene in Domoticz)

Special Parameters

A general optional parameter is speech. This enables you to let Rhasspy answer or acknowledge whatever you want.
You can enhance the answer by adding parameters that will be replaced by the original tag value in the recognized speech. You can enclose the tagname by dots ('.'). This will be replaced by the original value of the tag, that is the value as recognized, not replaced by the string after an optional colon (':').
Example:
[DomoSwitch]
put (on:On|off:Off){state} the (((library lamp):32)|(reading lamp):36){idx!int} (:){speech:I put .state. the .idx.}
After switching On the reading lamp (36), Rhasspy will say: I put on the reading lamp. All parameters (state and idx) will be replaced by the **original **value, as Rhasspy heard it, so state will not be replaced by On, but by on (small difference) and idx not by 36 but by library lamp (big difference)

Standard Intents

The intenthandler implements a small number of general purpose intents.

The intents are:

  1. Dummy: Do nothing
    You can use this intent to let Rhasppy answer something, or ignore specific texts
    Example:
    [Dummy]
    what is your status (:){speech:all systems are operational within normal parameters}

  2. Confirm: Used to give a positive answer to a question from Rhasspy
    Example:
    [Confirm]
    yes [i do]

  3. Deny: Used to give a negative answer to a question from Rhasspy
    Example:
    [Deny]
    no [thanks]

  4. GetTime: Return the current time in hours and minutes

  5. GetDate: Tell me what day it is today. Answer: today is monday september 9 2001
    Example:
    [GetDate]
    What day is today

  6. Timer: Set a timer in minutes and seconds and sound an alarm when expired
    Parameter: seconds Number of seconds before sounding the alarm
    Parameter: minutes Number of minutes before sounding the alarm
    Example:
    [Timer]
    set a timer for (0..240){minutes} minutes and (0..59){seconds} seconds
    set a timer for (0..240){minutes} minutes (0:){seconds}
    set a timer for (0..240){seconds} seconds (0:){minutes}

  7. DuckDuckGo: Send text to a search machine and speak the returned text. You can use your own slotnames. Just list the slotnames into slots.
    Example:
    [DuckDuckGo]
    what do you know about the album ($albums){album} [ from ($artists){artist}] (:){slots:album artist}

Before you can use the next intents you need to create a slots file birthdays with the correct structure. For every person the birthday must be given. You can use another name for the slots file. Take care to use the correct name in the intent!
Example:
jane:1-1-1980
(grandma smith):20-2-1940
(john cleese):27-10-1939
...
If the name contains spaces, use parentheses () around the name
NOTE:

  • Only two formats for dates are accepted: YYYY-MM-DD or DD-MM-YYYY.
  • Only hyphens and digits are permitted,
  • The year is always 4 digits,
  • The month and day must be 1 or 2 digits long.

NOTE: The slotname MUST be birthdays, otherwise the BirthDays intent will not work!
The intents with birthdays are:

  1. GetAge: How many years old is someone.
    Example:
    [GetAge]
    how old is ($birthdays){birthday}

  2. BirthDay: What date is someone's day of birth.
    Example:
    [BirthDay]
    when is ($birthdays){birthday} s birthday

  3. BirthDays: Is it someones birthday or are there upcoming birthdays in the coming month?
    Example:
    [BirthDays]
    is it somebody s birthday
    are there upcoming birthday s

Domoticz Intents

Class IntentDomo implements intents for Domoticz. Every intent accepts parameters.

The intents are:

  1. DomoScene: Set a Scene
    Parameter: idx = scene id
    Example:
    [DomoScene]
    I (want to|must) (go to bed|sleep) (:){idx:1} (:){speech:good night and I will meet you again tomorrow}

  2. DomoDimmer: Set a dimmer to a certain level
    Parameter: idx = switch id
    Parameter: level = percentage of light required
    Example:
    [DomoDimmer]
    set the (bedroom lamp){idx:24} level on (0..100,5){level} [percent] (:){speech:i put .idx. on .level. percent}

  3. DomoSwitch Switch something on or off
    Parameter: idx = switch id
    Parameter: state = On or Off
    Example:
    [DomoSwitch]
    put (on:On|off:Off){state} the (((library lamp):32)|(reading lamp):36){idx} (:){speech:I put .state. the .idx.}

  4. DomoInfo: Get info from sensor in domoticz
    Parameter: idx = sensor id
    Parameter: name = name of data item in returned json. E.g. Temp or Data
    Parameter (optional) result = String to replace with result (can only contain letters!)
    To find the idx of an item you can go to Domoticz and edit the switch or scene or sensor and it will show you the idx.
    To find the name of a data item you can call the api: http://localhost:8080/json.htm?type=devices&rid=XXX
    If your Domoticz is not at localhost substitute localhost by the correct IP-address
    Replace XXX by the correct idx and look for the name of the item you want to use in the result part of the json answer
    Examples:
    [DomoInfo]
    what is the temperature (:){idx:19} (:){name:Temp} (:){speech:the outside temperature is RESULT degrees celsius}
    what is the electricity usage (:){idx:6} (:){name:Data} (:){result:MYRES} (:){speech:the electricity usage is MYRES}

  5. DomoGetWind: Special case, Tells the wind velocity and direction
    Parameter: idx = sensor id
    Example:
    [DomoGetWind]
    how strong is the wind?

  6. DomoSun: Find values for dawn, sunrise, sunset and dusk and speak the result
    Note: This will work only if the location is set in the settings of Domoticz Parameter: speech = text to speak with the times retrieved
    The speech string can contain the keywords DAWN, SUNRISE, SUNSET and DUSK
    These will be replaced by the value as received from Domoticz
    Example:
    [DomoSun]
    when does the sun set (:){speech:the sunset is at SUNSET it will be dark at DUSK}

Kodi Intents

Class IntentKodi implements intents to manage a Kodi installation. See Kodi for more information about installation and configuration.
We assume you have a working kodi server in your network.

Preparation

  • First, we need to tell Rhasspy where the Kodi server is.
    This is done in intentconfig.py.
    The only thing you have to change is the kodi url.
  • Next we will need to learn Rhasspy about artists, composers, albums, songs and genres. This is simply done by executing the intent KodiUpdateSlots. (see intent KodiUpdateSlots)

The intents are:

  1. KodiAlbums: play album by name, optionally by artist
    Parameter: album album name (from slotsfile albums)
    Parameter: artist name of artist, optional (from slotsfile artists)
    Parameter: genre (from slotsfile genres)
    Examples:
    [KodiAlbums]
    play album $(albums){album} [by ($artists){artist}]

  2. KodiSongs: play songs by name, artist, composer, genre or slection
    Parameter: artist (from slotsfile artists)
    Parameter: composer (from slotsfile composers)
    Parameter: genre (from slotsfile genres)
    Parameter: title (from slotsfile songs)
    Parameter: selection - no corresponding slots file. You can use this to filter special things, such as motet or piano.
    Examples:
    [KodiSongs]
    (play:) song ($songs){song} (by|of) ($artists){artist}
    (play:) genre ($genres){genre}
    (play:) (piano music:piano | cello music:cello | nocturne |toccata |all:){selection} [ of ($composers){composer}] [by ($artists){artist}] (:)

  3. KodiStream: start listening to an audiostream (internet radio)
    Parameter: url URL of the stream. I tested with mp3 streams.
    [KodiStream]
    I want to listen to ($streams){url}
    You need a slots file streams with lines like:
    (B B C one):(http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/mediaset/http-icy-mp3-a/vpid/bbc_radio_one/format/pls.pls)
    To find radiostations you can use (e.g.) https://streamurl.link/

  4. KodiVolume: set the volume.
    Parameter: volume volume level between 0 and 100.
    Example:
    [KodiVolume]
    set [music] volume [to] (0..100,10){volume}

  5. KodiPauseResume: pause or resume

  6. KodiStop

  7. KodiStart

  8. KodiPrevious - play the previous song from the playlist

  9. KodiNext - play the next song from the playlist

  10. KodiWhatsPlaying - This intent will tell you the title from the song that is playing

  11. KodiUpdateSlots: update the kodi information
    This intent must be called whenever the music library is updated. It will refresh the following slots files: albums, artists, composers, genres
    This will generate the slots files. Please be patient. Rhasspy will tell you when all the slotsfiles have been generated.
    You can play (selections of) songs or albums.

Suggestion when using kodi

When using kodi, the music can interfere with Rhasspy when you want to give a command.
To avoid kodi making noise when trying to talk to Rhasspy you can make kodi shut up after calling the wake word.
This is done by making a Node-Red flow that listens for MQTT messages with topic "hermes/dialogueManager/sessionStarted"
When receiving this message you can send a SetMute(true) api call to kodi, wait a couple of seconds and send a SetMute(false) api call to kodi
You can find a Node-Red flow here
Do not forget to change the MQTT and Kodi parameters!

Smartcitizen Intents

Class IntentSmartCity implements intents for Smart citizen
Only one intent is implemented:

  1. SmartCityInfo - Retrieve information from a smart citizen sensor
    Parameter: kit (required) - Kit number to retrieve from
    Parameter: idx (required) - Device id from kit
    Parameter: speech - text to speak with the result, see parameter result
    Parameter: result (optional, default RESULT) - string to replace in speech with result
    Parameter: novalue (optional, default "") - value to use when no result was received
    Example:
    [SmartCityInfo]
    what is the air pressure [in amsterdam] (:){kit:12345} (:){idx:99} (:){speech:the air pressure is RESULT kilo pascal}