Use JAX-RS for hue emulation

* Split RESTapi class into logical units (ConfigurationAccess, UserManagement, LightsAndGroups)
* rules support
* scenes support
* schedule support
* New self-test page under /api/status
* Refactor tests: Use jersey JAX-RS server to test without requiring the framework (non OSGi tests)

Signed-off-by: David Graeff <[email protected]>

bundles/org.openhab.io.hueemulation/README.md

@@ -1,23 +1,38 @@
 # openHAB Hue Emulation Service
 
-Hue Emulation exposes openHAB items as Hue devices to other Hue HTTP API compatible applications like an Amazon Echo, Google Home or
+Hue Emulation exposes openHAB items as Hue lights to other Hue API compatible applications like Amazon Echos, Google Homes or
 any Hue compatible application.
 
 Because Amazon Echo and Google Home control openHAB locally this way, it is a fast and reliable way
 to voice control your installation. See the Troubleshoot section down below though.
 
+This service is independent of the also available Hue binding!
+
+Currently the following Hue functionality is supported:
+
+* Lights: Maps to items
+* Groups: Maps to group items
+* Rooms: Maps to group items with a specific tag
+* Scenes: Maps to rules (new rule engine) that are tagged with "scene"
+* Rules: Maps to rules (new rule engine) that are tagged with "hueemulation_rule"
+* Schedule: Maps to rules (new rule engine) that are tagged with "hueemulation_schedule"
+
+You can create / modify and remove groups, rooms, scenes, rules and schedules from within Hue compatible devices and apps.
+
 ## Discovery:
 
-As soon as the binding is enabled, it will announce the presence of an (emulated) HUE bridge of the second generation (square bridge).
+As soon as the service is enabled, it will announce the presence of an (emulated) HUE bridge of the second generation (square bridge).
 Hue bridges are using the Universal Plug and Play (UPnP) protocol for discovery.
 
+![Philips Hue Bridge](doc/Philips_Hue_Bridge.jpg)
+
 Like the real HUE bridge the service must be put into pairing mode before other applications can access it. 
 By default the pairing mode disables itself after 1 minute (can be configured).
 
-## Exposed devices
+## Exposed lights
 
 It is important to note that you are exposing *Items* not *Things* or *Channels*.
-Only Color, Dimmer and Switch type *Items* are supported.
+Only Color, Dimmer, Rollershutter, Switch and Group type *Items* are supported.
 
 This service can emulate 3 different devices:
 
@@ -31,9 +46,9 @@ The exposed Hue-type depends on some criteria:
 * If the item has the category "Light": It will be exposed as a switch.
 
 This initial type determination is overridden if the item is tagged.
-Tags can be configured in Paper UI, please refer to the next section.
 
 The following default tags are setup:
+
 * "Switchable": Item will be exposed as an OSRAM SMART+ Plug
 * "Lighting": Item will be exposed as a dimmable white bulb
 * "ColorLighting": Item will be exposed as a color bulb
@@ -45,13 +60,14 @@ You can tag items manually though as well.
 
 ## Exposed names
 
-Your items labels are used for exposing! The default naming schema in Paper UI
-for automatically linked items unfortunately names *Items* like their Channel names,
+Your items labels are used for exposing!
+The default naming schema for automatically linked items unfortunately names *Items* like their Channel names,
 so usually "Brightness" or "Color". You want to rename those.
 
 ## Configuration:
 
-All options are available in Paper UI.
+All options are available in the graphical interface.
+For textual configuration find the following keys to set.
 
 Pairing can be turned on and off:
 
@@ -84,41 +100,57 @@ Usually you do not want to set this option, but change the primary address confi
 org.openhab.hueemulation:discoveryIp=192.168.1.100
 ```
 
+The hue emulation service supports three types of emulated bulbs. You need to tell the service
+which item tag corresponds to which emulated bulb type.
 One of the comma separated tags must match for the item to be exposed.
-Can be empty to match an item based on the other criteria.
+Can be empty to match an item based on other criterias.
 
 ```
 org.openhab.hueemulation:restrictToTagsSwitches=Switchable
 org.openhab.hueemulation:restrictToTagsWhiteLights=Lighting
 org.openhab.hueemulation:restrictToTagsColorLights=ColorLighting
 ```
 
+The above default assignment means that every item that has the tag "Switchable"
+will be emulated as a Zigbee Switch. If You want your Zigbee Switches to be exposed
+as lights instead (because your Amazon Echo does not support switches for example),
+you want to have (this can be set in the graphical interface as well):
+
+```
+org.openhab.hueemulation:restrictToTagsSwitches=NONE
+org.openhab.hueemulation:restrictToTagsWhiteLights=Lighting,Switchable
+org.openhab.hueemulation:restrictToTagsColorLights=ColorLighting
+```
+
 ## Troubleshooting
 
 Some devices like the Amazon Echo, Google Home and all Philips devices expect a Hue bridge to
-run on port 80. You must either port forward your openHAB installation to port 80, install
-a reverse proxy on port 80 or let openHAB run on port 80.
+run on port 80. You must either
+
+* port forward your openHAB installation to port 80,
+* install a reverse proxy on port 80,
+* or let openHAB run on port 80 (the entire java process requires elevated privileges).
 
 You can test if the hue emulation does its job by enabling pairing mode including the option
 "Amazon Echo device discovery fix".
 
 1. Navigate with your browser to "http://your-openhab-ip/description.xml" to check the discovery
    response. Check the IP address in there.
-2. Navigate with your browser to "http://your-openhab-ip/api/testuser/lights?debug=true"
-   to check all exposed lights and switches.
+2. Navigate with your browser to "http://your-openhab-ip/api/status"
+   to check the self test report.
 
-## Text configuration example
+Depending on the firmware version of your Amazon Echo, it may not support coloured bulbs or switches.
+Please assign "ColorLighting" and "Switchable" to the `WhiteLights` type as explained above.
 
-The item label will be used as the Hue device name. 
+Also note that Amazon Echos are stubborn as. You might need to remove all former recognised devices multiple
+times and perform the search via different Echos and also the web or mobile application.
 
-```
-Switch  TestSwitch      "Kitchen Switch" [ "Switchable" ]
-Color   TestColorBulb   "Bathroom"       [ "ColorLighting" ]
-Dimmer  TestDimmer      "Hallway"        [ "Lighting" ]
-```
+## Text configuration example
 
-If you have an item with a channel or binding attached the tag needs to be applied before the channel.
+The item label will be used as the Hue device name. 
 
 ```
-Switch BLamp1 "Bedroom Lamp 1" <switch> (FirstFloor) [ "Lighting" ] {mqtt=">[mosquitto:cmnd/sonoff-BLamp1/POWER:command:*:default],<[mosquitto:stat/sonoff-BLamp1/POWER:state:default]"}
+Switch  TestSwitch      "Kitchen Switch" [ "Switchable" ]    {channel="..."}
+Color   TestColorBulb   "Bathroom"       [ "ColorLighting" ] {channel="..."}
+Dimmer  TestDimmer      "Hallway"        [ "Lighting" ]      {channel="..."}
 ```

bundles/org.openhab.io.hueemulation/pom.xml

@@ -13,4 +13,25 @@
 
   <name>openHAB Add-ons :: Bundles :: Hue Emulation Service</name>
 
+  <dependencies>
+    <!-- https://mvnrepository.com/artifact/org.glassfish.grizzly/grizzly-http-server -->
+    <dependency>
+        <groupId>org.glassfish.grizzly</groupId>
+        <artifactId>grizzly-http-server</artifactId>
+        <version>2.4.4</version>
+        <scope>test</scope>
+    </dependency>
+    <dependency>
+        <groupId>org.glassfish.jersey.containers</groupId>
+        <artifactId>jersey-container-grizzly2-http</artifactId>
+        <version>2.28</version>
+        <scope>test</scope>
+    </dependency>
+    <dependency>
+        <groupId>org.glassfish.jersey.inject</groupId>
+        <artifactId>jersey-hk2</artifactId>
+        <version>2.28</version>
+        <scope>test</scope>
+    </dependency>
+  </dependencies>
 </project>