mirror of
https://github.com/openhab/openhab-addons.git
synced 2025-01-10 15:11:59 +01:00
120 lines
5.5 KiB
Markdown
120 lines
5.5 KiB
Markdown
# Mycroft Binding
|
|
|
|
This binding connects to Mycroft A.I. in order to control it or react to events by listening on the message bus.
|
|
|
|
Possibilies include:
|
|
|
|
- Press a button in openHAB to wake Mycroft without using a wake word.
|
|
- Simulate a voice command to launch a skill, as if you just spoke it
|
|
- Send some text that Mycroft will say (Using its Text To Speech service)
|
|
- Control the music player
|
|
- Mute the sound volume of Mycroft
|
|
- React to all the aforementioned events ...
|
|
- ... and send/receive any other kind of messages on the message bus
|
|
|
|
## Supported Things
|
|
|
|
The only thing managed by this binding is a Mycroft instance
|
|
|
|
| Thing Type ID | Description |
|
|
|--------------------|----------------------------------------------------------------------------|
|
|
| mycroft | A Mark I/II, a Picroft, or any other variant exposing the message bus |
|
|
|
|
## Discovery
|
|
|
|
There is no discovery service, as Mycroft doesn't announce itself on the network.
|
|
|
|
## Thing Configuration
|
|
|
|
The configuration is simple, as you just need to give the IP/hostname of the Mycroft instance accessible on the network.
|
|
The default port is 8181, which can be changed.
|
|
|
|
```java
|
|
Thing mycroft:mycroft:myMycroft "Mycroft A.I." @ "Living Room" [host="192.168.X.X"]
|
|
```
|
|
|
|
| property | type | description | mandatory |
|
|
|--------------------------|------------------------|------------------------------------------------------------------|-----------|
|
|
| host | IP or string | IP address or hostname | Yes |
|
|
| port | integer | Port to reach Mycroft (default 8181) | No |
|
|
| volume_restoration_level | integer | When unmuted, force Mycroft to restore volume to this value | No |
|
|
|
|
## Channels
|
|
|
|
A Mycroft thing has the following channels:
|
|
|
|
| channel type id | Item type | description |
|
|
|------------------------------|-----------|------------------------------------------------------------------------------------------------|
|
|
| listen | Switch | Switch to ON when Mycroft is listening. Can simulate a wake word detection to trigger the STT |
|
|
| speak | String | The last sentence Mycroft speaks |
|
|
| utterance | String | The last utterance Mycroft receive |
|
|
| player | Player | The music player Mycroft is currently controlling |
|
|
| volume_mute | Switch | Mute the Mycroft speaker |
|
|
| volume | Dimmer | The volume of the Mycroft speaker. (Note: Value unreliable until a volume change occurred) |
|
|
| full_message | String | The last message (full json) seen on the Mycroft Bus. Filtered by the messageTypes properties |
|
|
|
|
The channel 'full_message' has the following configuration available:
|
|
|
|
| property | type | description | mandatory |
|
|
|---------------|---------------------------------|-------------------------------------------------------------------------|-----------|
|
|
| messageTypes | List of string, comma separated | Only these message types will be forwarded to the Full Message Channel | No |
|
|
|
|
## Full Example
|
|
|
|
A manual setup through a `things/mycroft.things` file could look like this:
|
|
|
|
```java
|
|
Thing mycroft:mycroft:myMycroft "Mycroft A.I." @ "Living Room" [host="192.168.X.X", port=8181] {
|
|
Channels:
|
|
Type full-message-channel : Text [
|
|
messageTypes="message.type.1,message.type.4"
|
|
]
|
|
}
|
|
```
|
|
|
|
### Item Configuration
|
|
|
|
The `mycroft.item` file:
|
|
|
|
```java
|
|
Switch myMycroft_mute "Mute" { channel="mycroft:mycroft:myMycroft:volume_mute" }
|
|
Dimmer myMycroft_volume "Volume [%d]" { channel="mycroft:mycroft:myMycroft:volume" }
|
|
Player myMycroft_player "Control" { channel="mycroft:mycroft:myMycroft:player" }
|
|
Switch myMycroft_listen "Wake and listen" { channel="mycroft:mycroft:myMycroft:listen" }
|
|
String myMycroft_speak "Speak STT" { channel="mycroft:mycroft:myMycroft:speak" }
|
|
String myMycroft_utterance "Utterance" { channel="mycroft:mycroft:myMycroft:utterance" }
|
|
String myMycroft_fullmessage "Full JSON message" { channel="mycroft:mycroft:myMycroft:full_message" }
|
|
```
|
|
|
|
### Sitemap Configuration
|
|
|
|
A `demo.sitemap` file:
|
|
|
|
```perl
|
|
sitemap demo label="myMycroft"
|
|
{
|
|
Frame label="myMycroft" {
|
|
Switch item=myMycroft_mute
|
|
Slider item=myMycroft_volume
|
|
Default item=myMycroft_player
|
|
Switch item=myMycroft_listen
|
|
Text item=myMycroft_speak
|
|
Text item=myMycroft_utterance
|
|
Text item=myMycroft_fullmessage
|
|
}
|
|
}
|
|
```
|
|
|
|
### Ask Mycroft to say something
|
|
|
|
mycroft.rules
|
|
|
|
```java
|
|
rule "Say Hello"
|
|
when
|
|
Item Presence_Isaac changed
|
|
then
|
|
myMycroft_speak.sendCommand("Hello Isaac")
|
|
end
|
|
```
|