Groups

A Group is where different Elements are combined into something that can trigger your App. A group can be "and" (&&) type or "or" (||) type. A group's set consists of element names and/or group names joined by its type.

Input fields
  • set: Required. A string with the names of Elements or Groups, joined by the Groups operator. If a component is optional it is placed between parentheses, though each set must have at least one component that is not optional.
  • capturingGroup: Optional. Boolean; set to false if omitted. See below for a detailed description.
  • Ordered: Optional. Boolean, set to false if omitted. In some case the order of components in the set is important, while in other cases it may be irrelevant. Whether or not components should only occur in the listed order is indicated here.
  • allowDisconnect: Optional. Boolean, set to true if omitted. This property is used to indicate whether it's acceptable if components are separated by words which do not match any of the components in the set. Setting this property to false reduces the resources needed by your app, so try to set it to false whenever you can.
  • devices: Optional. An Object where you can specify the properties of devices which are be relevant to this group. More information about device properties to filter can be found in Drivers. Any matching devices will be made available to you in the speech object.

Not every Group you create has to be a combination that should trigger your App. It could be that you want a combination of Groups to trigger your App, even though each of the subgroups should not trigger your App themself. You can indicate this by setting a Group's capturingGroup property. Only if capturingGroup is true will a matched group be used to trigger your App. That means your App will need at least one capturingGroup if you want to use speech. If you omit the capturingGroup property, the Group will not be treated as a capturingGroup.

Example

/app.json

"speech": {
    "en": {
        "element": {...},
        "group": {
            "main": {
                "set": "(verb) && lightRegex && onOff",
                "ordered": false,
                "allowDisconnect": false,
                "capturingGroup": true,
                "devices": {
                    "class": "light",
                    "online": true,
                    "available": true,
                    "capabilities": ["onoff"]
                }
            }
        }
    },
    nl: {
        "element": {...}
    }
}

Some notable things about this example:

  • verb is an optional component. This way both user phrases like "turn on the lights" and "lights on" will match the entire phrase.
  • ordered is false, so phrases with the order "onOff && lightRegex" will also match this group.
  • allowDisconnect is false because we do not expect the user to say anything else than what is covered by the specified Elements.
  • devices we are filtering to get a list of all lights that can be switched on or off, in line with the purpose of this Group.
  • nl doesn't have a group property, so the English group structure will also be used for Dutch user phrases.