Description
Cuevox is a simple but extensible voice control tool for openHAB. The OH Android App can be used to send voice commands to OH and interpret them using voice command rules that can be easily extended in the rule script. Apart from the voice command itself, no OH internal data needs to be sent to any external API.
The voice command is split in tokens, which are tried to be matched for the pre-defined rules.
Features:
- Supported languages: English, German
- Send ON/OFF or UP/DOWN command to a single item (matched by label or synonym)
-
turn off the kitchen light
-
lower the living room blinds
- Assuming in above examples that
kitchen light
andliving room blinds
are the labels of single items.
-
- Turn all lights on/off or raise/lower all roller shutters in a group, e.g. a location.
- All descendant items of the respective group can be matched.
-
turn off the light in the first floor
- This will match all
Switch
items with theLight
tag.
- This will match all
-
raise all shutters in the living room
- Assuming in above examples that
first floor
andliving room
are group items.
- Item matching via the item label or
Synonym
metadata. - Create custom voice command rules, including custom script execution upon matching.
Examples (English)
Light Controls
Turning lights on/off in a specific location:
- âTurn on all the lights in the living room.â
- âSwitch the light off in the kitchen.â
- âTurn all lights off in the bedroom.â
- âSwitch the lights on.â
Turning lights on/off with labels:
- âTurn the kitchen light off.â
- âSwitch on the bedroom lights.â
- âTurn off the living room lights.â
Rollershutter Controls
Raising or lowering rollershutters:
- âPut the rollershutter up in the office.â
- âPull all the blinds down in the living room.â
- âLower the shutters in the bedroom.â
- âRaise all the roller blinds in the kitchen.â
Specifying rollershutters by label:
- âLower the kitchen shutters.â
- âRaise the office blinds.â
- âPull the living room blinds down.â
- âPut the bathroom roller shutter up.â
Generic Item Commands
Turning items on/off:
- âTurn the fan on.â
- âSwitch the heater off.â
- âTurn the lamp off.â
Adjusting items up/down:
- âPull the screen down.â
- âLower the projector.â
- âRaise the curtain.â
Examples (German)
Lichtsteuerung (Light Controls)
Schalten von Lichtern ein/aus in einem bestimmten Raum:
- âSchalte alle Lichter im Wohnzimmer ein.â
- âMach das Licht in der KĂŒche aus.â
- âSchalt alle Lampen im Schlafzimmer aus.â
- âMach die Lichter im Flur an.â
Schalten von Lichtern mit Labels:
- âSchalte die Wohnzimmerlampe aus.â
- âMach das KĂŒchenlicht an.â
- âSchalt das Schlafzimmerlicht ein.â
- âMach die Flurlampe aus.â
Rolladensteuerung (Rollershutter Controls)
Hoch- oder Herunterfahren von Rollos in einem Raum:
- âFahr die Rollos im Wohnzimmer hoch.â
- âMach das Rollo im Schlafzimmer runter.â
- âFahre die Rolladen in der KĂŒche hoch.â
- âFahr die RollĂ€den im BĂŒro herunter.â
Hoch- oder Herunterfahren von Rollos mit Labels:
- âFahr das KĂŒchenrollo hoch.â
- âMach den Wohnzimmerrolladen runter.â
- âFahre die SchlafzimmerrollĂ€den herunter.â
- âFahr die BĂŒrorollos hoch.â
Generische Befehle (Generic Commands)
Ein- und Ausschalten von GerÀten:
- âSchalte den Ventilator ein.â
- âMach die Heizung aus.â
- âSchalt die Lampe an.â
Hoch- oder Herunterfahren von GerÀten:
- âFahre den Bildschirm runter.â
- âMach die Leinwand hoch.â
- âFahr die Jalousie herunter.â
Requirements
Language: JavaScript, Scripting with openhab-js
Dependencies:
- JavaScript Scripting add-on
- openhab-js 4.5.1 or later
- A voice command String item, which stores the spoken text
- The voice command item configured under Rule Voice Interpreter and the openHAB Android App, connected to your OH instance and configured to send voice commands to OH
- Alternatively: any other system that captures your voice and stores the spoken text in the voice command item.
How to setup the voice command item to use with the openHAB Android App
-
Create the item, called e.g. âVoiceCommandâ
-
Configure it in the settings as target for the rule voice interpreter: Settings->Rule Voice Interpreter->Voice Command Item
â
Create Custom Voice Command Rules
As of now, custom voice command rules must be defined in the inline script.
NOTE: If the rule template has been updated and youâd like to update your rule, you must create a new rule from the latest template. Any changes to your previous rule/script, particularly your custom voice command rules, must be copied from the previous rule script to the newly created rule script.
At the very bottom of the script, the // RULES
section defines the rules. Below, there is a section for your custom voice command rules:
// ** CUSTOM RULES *********************
// Add your rules here
// *************************************
You can define variables for common expressions or reuse the ones from the pre-defined rules and add the rule to the rbi
object (the instance of the RuleBasedInterpreter
class), e.g.
let the = opt("the");
let lowerRaise = alt(cmd("lower", DOWN),cmd("raise", UP));
rbi.addRule(seq(lowerRaise, the, itemLabel()));
/**
* Adds a rule.
* Either the expression must contain a function to execute (e.g. send a command) or a specific function must be given.
* @param {Expression} expression
* @param {function} executeFunction If a specific function is given, it will override any function from the expression.
*/
addRule(expression, executeFunction)
The following expressions are available to define a rule:
/**
* Creates an alternative expression. All given expressions can be used alternatively, i.e. using an OR logic.
* @param {...Expression} expressions Any expression types.
*/
function alt(...expressions)
/**
* Creates a sequential expression. All given expressions are processed sequentially in that order.
* @param {...Expression} expressions Any expression types.
*/
function seq(...expressions)
/**
* Creates an optional expression. The given expression is not mandatory for a match.
* @param {Expression} expression
*/
function opt(expression)
/**
* Creates a command expression.
* If the given expression is matched, the given command is sent to all found items of that rule.
* @param {Expression} expression
* @param {string} command
*/
function cmd(expression, command)
/**
* Creates an item label expression.
* It will try to match an item's label or its synonyms to the tokens at this point.
* Only a single item must be matched.
* The found item can be included in the final execution parameter, e.g. to send a command to that item.
* @param {boolean} includeInExecuteParameter Default: true.
* @param {boolean} isGroup Default: false. If true, only group items (type: "Group") are matched.
* @returns
*/
function itemLabel(includeInExecuteParameter, isGroup)
/**
* Creates an item properties expression.
* It tries to filter items according to their properties: tags, item type or parent group.
* If none of filter properties are given, then all items in the registry will be matched.
* All matched items will be included in the final execution parameter, e.g. to send a command to these items.
* @param {Expression} expression The expression to match.
* @param {string[]} tags Default: []. Only items that have all the given tags will be matched.
* @param {boolean} groupRequired Default: true. If true, the expression must contain a group Item Label Expression. Only descendants of that group will be matched.
* @param {string} itemType Default: null. If a type is given, then only items of that type will be matched.
*/
function itemProperties(expression, tags, groupRequired, itemType)
Future Improvements
The rule template source code is maintained at GitHub: JanMattner/voice-control-openhab: A simple but extensible rule based voice control tool for openHAB.
Feel free to add your ideas for improvements there or in this forum thread.
- Add more out of the box rules, including other languages
- Verify rules in various scenarios
- Include custom rules from a separate script, so the update of the rule template is easier without the risk of data loss
Changelog
Version 0.2
- rename and update documentation
Version 0.1
- initial release
Resources
https://raw.githubusercontent.com/JanMattner/voice-control-openhab/main/rule-template/cuevox.yaml