From b97d96cf5f4965eb9d58d186fc9492584e3f5836 Mon Sep 17 00:00:00 2001
From: Thomas Dietrich <Thomas.Dietrich@tu-ilmenau.de>
Date: Mon, 25 Sep 2017 09:51:42 +0200
Subject: [PATCH] Improve first paragraph, add label recomm. (#5)
Signed-off-by: Thomas Dietrich <thomas.dietrich@tu-ilmenau.de>
---
USAGE.md | 78 ++++++++++++++++++++++++++++++++++----------------------
1 file changed, 48 insertions(+), 30 deletions(-)
diff --git a/USAGE.md b/USAGE.md
index 8c6a7e8..f9bdd79 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -1,28 +1,25 @@
-# openHAB skill for Mycroft
+# Mycroft AI Skill
-[Mycroft](https://mycroft.ai/) is the world’s first open source assistant. The skill allows you to connect a running Mycroft
-instance (Mark 1, picroft, etc.) to your openHab. The skill takes advantage of the openHAB REST API, so it works both with the
-v1.x and v2.x, and no openHab upgrade is required.
+[Mycroft AI](https://mycroft.ai/) 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 is supported for English (U.S.), English (U.K.) languages.
+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](https://mycroft.ai/get-mycroft/)
-* A running instance of openHAB
-* openHAB must be reacheable from the Mycroft instance
+- A running [instance of Mycroft](https://mycroft.ai/get-mycroft/) (Mark 1, picroft, ...)
+- A running instance of openHAB (version 1.x or v2.x)
+- openHAB must be reacheable from the Mycroft instance
### Skill Installation
-The openHAB skill has to be installed on you Mycroft instance, please refer to the [official documentation](https://docs.mycroft.ai/skills.and.features/adding.skills)
-about how to install a skill.
+The openHAB skill has to be installed on your Mycroft instance, please refer to the [official documentation](https://docs.mycroft.ai/skills.and.features/adding.skills) to learn how to install a skill.
-Clone the [repository](https://github.com/openhab/openhab-mycroft.git) into your `~/.mycroft/skills` directory.
-Then install the dependencies inside your mycroft virtual environment:
-
-If on picroft just skip the workon part and the directory will be `/opt/mycroft/skills`
+Clone the [skill repository](https://github.com/openhab/openhab-mycroft.git) into the Mycroft skills directory,
+then trigger installation of needed dependencies:
```shell
cd ~/.mycroft/skills
@@ -32,9 +29,11 @@ cd skill-openhab
pip install -r requirements.txt
```
+If on [picroft](https://docs.mycroft.ai/development/installation/raspberry.pi), use the skills directory `/opt/mycroft/skills` and skip the `workon mycroft` command.
+
### Skill Configuration
-Add the block below to your `mycoft.conf` file:
+Add the block below to your `mycroft.conf` file:
```json
"openHABSkill": {
@@ -47,8 +46,8 @@ Restart mycroft for the changes to take effect.
### openHAB Item Configuration
-Items are exposed to openHAB skill for Mycroft through the use of tags which follow the [HomeKit](http://docs.openhab.org/addons/io/homekit/readme.html) binding tagging syntax.
-Pleas see the [HomeKit item configuration](http://docs.openhab.org/addons/io/homekit/readme.html#item-configuration) page for information on how to tag items.
+Items are exposed to openHAB skill for Mycroft through the use of tags.
+See the [Hue Emulation](http://docs.openhab.org/addons/io/hueemulation/readme.html) and [HomeKit Add-on](http://docs.openhab.org/addons/io/homekit/readme.html) documentation for details about tagging and available tags.
* **Items via .items - File**
@@ -57,23 +56,42 @@ Pleas see the [HomeKit item configuration](http://docs.openhab.org/addons/io/hom
Some examples of tagged items are:
```java
- Color DiningroomLight "Diningroom Light" <light> (gKitchen) [ "Lighting" ] {channel="hue:0200:1:bloom1:color"}
- Color KitchenLight "Kitchen Light" <light> (gKitchen) [ "Lighting" ] {channel="hue:0200:1:bloom1:color"}
- Switch GoodNight "Good Night" [ "Switchable" ]
+ 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]"}
+ 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" ]
+ 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 command:
+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:
+
+```java
+// 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="..."}
+```
-- *"Hey Mycroft, refresh openhab items"*
-
### Example Voice Commands
Each item tag supports different command, here is the summary:
@@ -128,4 +146,4 @@ With references to the above item definitions, here are an examples of working c
### 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`).
\ No newline at end of file
+* 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`).