This page is part of archived documentation for openHAB 4.1. Go to the current stable version
# Mycroft AI Skill
Mycroft AI (opens new window) is the world’s first open source voice enabled assistant. The skill allows you to connect a running Mycroft instance to your openHAB system. Supported natural voice commands and responses can freely be modified and extended.
The skill currently supportes the English (U.S.) and English (U.K.) languages but new languages are easily added via configuration files.
# General Configuration Instructions
# Requirements
- A running instance of Mycroft (opens new window) (Mark 1, picroft, ...)
- A running instance of openHAB
- openHAB must be reacheable from the Mycroft instance
# Skill Installation
The openHAB skill has to be installed on your Mycroft instance, please refer to the official documentation (opens new window) to learn how to install a skill.
From 18.2.5b mycroft-core release it is possible to install the skill using the voice command:
- "Hey Mycroft, install openhab"
or via the msm (opens new window) command:
msm install openhab
To manually install the skill:
Clone the skill repository (opens new window) into the Mycroft skills directory, then trigger installation of needed dependencies:
cd ~/.mycroft/skills
git clone https://github.com/openhab/openhab-mycroft.git skill-openhab
workon mycroft
cd skill-openhab
pip install -r requirements.txt
If on picroft (opens new window), use the skills directory /opt/mycroft/skills
and skip the workon mycroft
command.
# Skill Configuration
The skill is configured using the mycroft skill settings. After the skill installation, configuration will be available at https://home.mycroft.ai/skills (opens new window). After it is updated there, reload configuration is needed by saying:
- "Hey Mycroft, reload configuration"
The new settings will downloaded to settings.json in the skill folder.
# openHAB Item Configuration
Items are exposed to openHAB skill for Mycroft through the use of tags. See the Hue Emulation (opens new window) and HomeKit Add-on (opens new window) documentation for details about tagging and available tags.
Items via .items - File
See Item Definition and Syntax (opens new window)
Some examples of tagged items are:
Color KitchenLight "Kitchen Light" <light> (gKitchen) ["Lighting"] {channel="hue:0200:1:bloom1:color"} Color DiningroomLight "Diningroom Light" <light> (gKitchen) ["Lighting"] {channel="hue:0200:1:bloom1:color"} Switch GoodNight "Good Night" ["Switchable"] Number MqttID1Temperature "Bedroom Temperature" <temperature> ["CurrentTemperature"] {mqtt="<[mosquitto:mysensors/SI/1/1/1/0/0:state:default]"} Number MqttID1Humidity "Bedroom Humidity" ["CurrentHumidity"] {mqtt="<[mosquitto:mysensors/SI/1/0/1/0/1:state:default]"} Group gThermostat "Main Thermostat" ["gMainThermostat"] Number MainThermostatCurrentTemp "Main Thermostat Current Temperature" (gMainThermostat) ["CurrentTemperature"] Number MainThermostatTargetTemperature "Main Thermostat Target Temperature" (gMainThermostat) ["TargetTemperature"] String MainThermostatHeatingCoolingMode "Main Thermostat Heating/Cooling Mode" (gMainThermostat) ["homekit:HeatingCoolingMode"]
If items are modified in openHAB, a refresh in Mycroft is needed by the voice command:
- "Hey Mycroft, refresh openHAB Items"
# Item Label Recommendation
Matching of voice commands to Items happens based on the Item label (e.g. "Kitchen Light"). It is therefore advisable, to choose labels that can be used to form natural commands. As an example, compare "Hey Mycroft, turn on the Kitchen Light" vs. "Hey Mycroft, turn on the Ground Floor LEDs Kitchen".
In combination with the Mycroft skill (and other similar services) you are thereby tempted to break with your naming scheme and introduce confusion into your setup. openHAB Tip: You may define multiple Items bound to one channel. Instead of manipulating the label of one single Item, you can define multiple Items specifically for voice commands. See the following example:
// Common/main Item bound to a binding channel
Switch Kitchen_Light "Ground Floor LEDs Kitchen" <light> (gKitchen) {channel="..."}
// Two Items with labels fitting for voice commands, bound to the same binding channel
Switch Kitchen_Light_A "Kitchen Light" ["Lighting"] {channel="..."}
Switch Kitchen_Light_A2 "Kitchen LEDs" ["Lighting"] {channel="..."}
# Example Voice Commands
Each item tag supports different command, here is the summary:
Tag | Key word | Commands |
---|---|---|
Switchable | turn | on, off |
switch | on, off | |
put | on, off | |
what's | status | |
Lighting | turn | on, off |
switch | on, off | |
put | on, off | |
dim | ||
dim by | value in percentage | |
bright | ||
bright by | value in percentage | |
Thermostat | adjust to | values in degrees |
regulate to | values in degrees | |
tune to | values in degrees | |
decrease by | values in degrees | |
increase by | values in degrees | |
what's | adjusted to | |
what's | regulated to | |
what's | tuned to | |
CurrentHumidity | what's | humidity |
CurrentTemperature | what's | temperature |
With references to the above item definitions, here are an examples of working commands:
- "Hey Mycroft, turn on Diningroom Light"
- "Hey Mycroft, switch off Kitchen Light"
- "Hey Mycroft, put on Good Night"
- "Hey Mycroft, what is Good Night status?"
- "Hey Mycroft, what is the status of Good Night?"
- "Hey Mycroft, set Diningroom to 50 percent"
- "Hey Mycroft, dim Kitchen"
- "Hey Mycroft, bright Kitchen"
- "Hey Mycroft, dim Kitchen by 20 percent"
- "Hey Mycroft, what's Bedroom temperature?"
- "Hey Mycroft, tell me the temperature of Bedroom"
- "Hey Mycroft, what's the Bedroom humidity?"
- "Hey Mycroft, I'd like to know the humidity of Bedroom"
- "Hey Mycroft, adjust Main Thermostat to 21 degrees"
- "Hey Mycroft, regulate Main Thermostat to 20 degrees"
- "Hey Mycroft, decrease Main Thermostat by 2 degrees"
- "Hey Mycroft, increase Main Thermostat by 1 degrees"
- "Hey Mycroft, what is Main Thermostat is regulated to?"
- "Hey Mycroft, how the Main Thermostat tuned to?"
# Additional Comments
- By default all temperatures are in Celsius, no test so far about the tag Fahrenheit to the thermostat group item (which should also be tagged with
Thermostat
).