[mycroft] Initial contribution (openhab#11040)

This binding will connect to Mycroft A.I. in order to control it or react to event by listening on the message bus. Signed-off-by: Gwendal Roulleau <[email protected]>
nemerdaud · Jan 28, 2022 · 935d462 · 935d462
1 parent 0e5a45d
commit 935d462
Show file tree

Hide file tree

Showing 54 changed files with 2,783 additions and 0 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -198,6 +198,7 @@
 /bundles/org.openhab.binding.mqtt.homeassistant/ @davidgraeff @antroids
 /bundles/org.openhab.binding.mqtt.homie/ @davidgraeff
 /bundles/org.openhab.binding.myq/ @digitaldan
+/bundles/org.openhab.binding.mycroft/ @dalgwen
 /bundles/org.openhab.binding.mystrom/ @pail23
 /bundles/org.openhab.binding.nanoleaf/ @raepple @stefan-hoehn
 /bundles/org.openhab.binding.neato/ @jjlauterbach

diff --git a/bom/openhab-addons/pom.xml b/bom/openhab-addons/pom.xml
@@ -981,6 +981,11 @@
       <artifactId>org.openhab.binding.mqtt.homie</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.mycroft</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.myq</artifactId>

diff --git a/bundles/org.openhab.binding.mycroft/NOTICE b/bundles/org.openhab.binding.mycroft/NOTICE
@@ -0,0 +1,13 @@
+This content is produced and maintained by the openHAB project.
+
+* Project home: https://www.openhab.org
+
+== Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+== Source Code
+
+https://github.com/openhab/openhab-addons
diff --git a/bundles/org.openhab.binding.mycroft/README.md b/bundles/org.openhab.binding.mycroft/README.md
@@ -0,0 +1,128 @@
+# 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.
+
+```
+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 occured)     |
+| 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:
+
+```
+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
+```
diff --git a/bundles/org.openhab.binding.mycroft/pom.xml b/bundles/org.openhab.binding.mycroft/pom.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.openhab.addons.bundles</groupId>
+    <artifactId>org.openhab.addons.reactor.bundles</artifactId>
+    <version>3.3.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.mycroft</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Mycroft Binding</name>
+
+</project>
diff --git a/bundles/org.openhab.binding.mycroft/src/main/feature/feature.xml b/bundles/org.openhab.binding.mycroft/src/main/feature/feature.xml
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.mycroft-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0">
+	<repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${ohc.version}/xml/features</repository>
+
+	<feature name="openhab-binding-mycroft" description="mycroft Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<feature>openhab-transport-http</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.mycroft/${project.version}</bundle>
+	</feature>
+</features>
diff --git a/...g.mycroft/src/main/java/org/openhab/binding/mycroft/internal/MycroftBindingConstants.java b/...g.mycroft/src/main/java/org/openhab/binding/mycroft/internal/MycroftBindingConstants.java
@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) 2010-2022 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.mycroft.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link MycroftBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Gwendal Roulleau - Initial contribution
+ */
+@NonNullByDefault
+public class MycroftBindingConstants {
+
+    private static final String BINDING_ID = "mycroft";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID MYCROFT = new ThingTypeUID(BINDING_ID, "mycroft");
+
+    // List of all Channel ids
+    public static final String LISTEN_CHANNEL = "listen";
+    public static final String SPEAK_CHANNEL = "speak";
+    public static final String PLAYER_CHANNEL = "player";
+    public static final String VOLUME_CHANNEL = "volume";
+    public static final String VOLUME_MUTE_CHANNEL = "volume_mute";
+    public static final String UTTERANCE_CHANNEL = "utterance";
+    public static final String FULL_MESSAGE_CHANNEL = "full_message";
+
+    // Channel property :
+    public static final String FULL_MESSAGE_CHANNEL_MESSAGE_TYPE_PROPERTY = "messageTypes";
+}
diff --git a/...ding.mycroft/src/main/java/org/openhab/binding/mycroft/internal/MycroftConfiguration.java b/...ding.mycroft/src/main/java/org/openhab/binding/mycroft/internal/MycroftConfiguration.java
@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2010-2022 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.mycroft.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link MycroftConfiguration} class contains fields mapping thing configuration parameters.
+ *
+ * @author Gwendal Roulleau - Initial contribution
+ */
+@NonNullByDefault
+public class MycroftConfiguration {
+
+    public String host = "";
+    public int port = 8181;
+    public int volume_restoration_level = 0;
+}