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).

• Stable
• Latest