[amplipi] Initial contribution of AmpliPi binding (openhab#10983)

* Initial contribution of AmpliPi binding Signed-off-by: Kai Kreuzer <[email protected]> * change http client from cxf jax-rs to Jetty Signed-off-by: Kai Kreuzer <[email protected]> * applied spotless Signed-off-by: Kai Kreuzer <[email protected]> * Remove Jackson dependency Signed-off-by: Kai Kreuzer <[email protected]> * Add support for input handling Signed-off-by: Kai Kreuzer <[email protected]> * Clean up, improvements and documentation Signed-off-by: Kai Kreuzer <[email protected]> * Remove unused password from configuration class Signed-off-by: Kai Kreuzer <[email protected]> * Remove example properties file Signed-off-by: Kai Kreuzer <[email protected]> * revert change in .gitignore Signed-off-by: Kai Kreuzer <[email protected]> * Update README Signed-off-by: Kai Kreuzer <[email protected]> * Address review feedback Signed-off-by: Kai Kreuzer <[email protected]> * Handle ExecutionException as network error Signed-off-by: Kai Kreuzer <[email protected]>
frederictobiasc · Oct 26, 2021 · 1a1226f · 1a1226f
1 parent 1c62542
commit 1a1226f
Show file tree

Hide file tree

Showing 42 changed files with 8,849 additions and 0 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -20,6 +20,7 @@
 /bundles/org.openhab.binding.amazondashbutton/ @OLibutzki
 /bundles/org.openhab.binding.amazonechocontrol/ @mgeramb
 /bundles/org.openhab.binding.ambientweather/ @mhilbush
+/bundles/org.openhab.binding.amplipi/ @kaikreuzer
 /bundles/org.openhab.binding.androiddebugbridge/ @GiviMAD
 /bundles/org.openhab.binding.astro/ @gerrieg
 /bundles/org.openhab.binding.atlona/ @tmrobert8

diff --git a/bom/openhab-addons/pom.xml b/bom/openhab-addons/pom.xml
@@ -91,6 +91,11 @@
       <artifactId>org.openhab.binding.ambientweather</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.amplipi</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.androiddebugbridge</artifactId>

diff --git a/bundles/org.openhab.binding.amplipi/NOTICE b/bundles/org.openhab.binding.amplipi/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.amplipi/README.md b/bundles/org.openhab.binding.amplipi/README.md
@@ -0,0 +1,91 @@
+# AmpliPi Binding
+
+This binding supports the multi room audio system [AmpliPi](http://www.amplipi.com/) from [MicroNova](http://www.micro-nova.com/).
+
+
+## Supported Things
+
+The AmpliPi itself is modeled as a Bridge of type `controller`.
+Every available zone as well as group is managed as an individual Thing of type `zone` resp. `group`.
+
+## Discovery
+
+Once the AmpliPi announces itself through mDNS (still a pending feature), it will be automatically discovered on the network.
+
+As soon as the AmpliPi is online, its zones and groups are automatically retrieved and added as Things to the Inbox.
+
+## Thing Configuration
+
+The `controller` Bridge has two configuration parameters:
+
+| Parameter       | Required | Description                                                                                        |
+|-----------------|----------|----------------------------------------------------------------------------------------------------|
+| hostname        | yes      | The hostname or IP address of the AmpliPi on the network                                           |
+| refreshInterval | no       | The time to wait between two polling requests for receiving state updates. Defaults to 10 seconds. |
+
+Both the `zone` and `group` Things only require a single configuration parameter `id`, which corresponds to their id on the AmpliPi.
+
+## Channels
+
+These are the channels of the `controller` Bridge:
+
+| Channel  | Type   | Description                                                                                          |
+|----------|--------|------------------------------------------------------------------------------------------------------|
+| preset   | Number | Allows setting a pre-configured preset. The available options are dynamically read from the AmpliPi. |
+| input1   | String | The selected input of source 1                                                                       |
+| input2   | String | The selected input of source 2                                                                       |
+| input3   | String | The selected input of source 3                                                                       |
+| input4   | String | The selected input of source 4                                                                       |
+
+The `zone` and `group` Things have the following channels:
+
+| Channel  | Type   | Description                                        |
+|----------|--------|----------------------------------------------------|
+| volume   | Dimmer | The volume of the zone/group                       |
+| mute     | Switch | Mutes the zone/group                               |
+| source   | Number | The source (1-4) that this zone/group is playing   |
+
+
+## Full Example
+
+amplipi.things:
+
+```
+Bridge amplipi:controller:1 "My AmpliPi" [ hostname="amplipi.local" ] {
+    zone zone2 "Living Room" [ id=1 ]
+}
+```
+
+amplipi.items:
+
+```
+Number      Preset      "Preset"                { channel="amplipi:controller:1:preset" }
+String      Input1      "Input 1"               { channel="amplipi:controller:1:input1" }
+String      Input2      "Input 2"               { channel="amplipi:controller:1:input2" }
+String      Input3      "Input 3"               { channel="amplipi:controller:1:input3" }
+String      Input4      "Input 4"               { channel="amplipi:controller:1:input4" }
+
+Dimmer      VolumeZ2    "Volume Zone2"          { channel="amplipi:zone:1:zone2:volume" }
+Switch      MuteZ2      "Mute Zone2"            { channel="amplipi:zone:1:zone2::mute" }
+Number      SourceZ2    "Source Zone2"          { channel="amplipi:zone:1:zone2::source" }
+```
+
+amplipi.sitemap:
+
+```
+sitemap amplipi label="Main Menu"
+{
+    Frame label="AmpliPi" {
+        Selection item=Preset
+        Selection item=Input1
+        Selection item=Input2
+        Selection item=Input3
+        Selection item=Input4
+    }
+    Frame label="Living Room Zone" {
+        Slider item=VolumeZ2 label="Volume Zone 1 [%.1f %%]"
+        Switch item=MuteZ2
+        Selection item=SourceZ2
+    }
+}
+```