Skip to content

Commit

Permalink
HueEmulation IO binding: Support Coloured bulbs (openhab#4216)
Browse files Browse the repository at this point in the history
* HueEmulation IO binding: Support Coloured bulbs

* Use OSGI annotations
* Use config holder class
* Move code into own subclasses instead of having a giant HueEmulationServlet.class
* Introduce UDN class
* Introduce user management class
* Introduce light items management class
* Watch the item registry for changes and keep a cache of published items,
  instead of quering all items from the item registry for each API call.
* Implement /config endpoint. Necessary for Hue App etc.
* Implement /whitelist entpoint including user delete.
* Implement dummy entpoints for nowadays Hue bridges (/group, /scenes etc).
* Fix: Return unauthorized /config
* Fix: error/success response
* Fix: Only allow POST http method for adding a user
* Start service late in the process via the ReadyMarkerService
* Automatically turn off the pairing mode after a time
* Support "extended color light bulbs" with a hue range 0-65535
* Support wall plugs

Signed-off-by: David Graeff <david.graeff@web.de>
Signed-off-by: Maximilian Hess <mail@ne0h.de>
  • Loading branch information
David Gräff authored and ne0h committed Sep 15, 2019
1 parent ee688be commit b7e28c5
Show file tree
Hide file tree
Showing 30 changed files with 2,056 additions and 797 deletions.
36 changes: 29 additions & 7 deletions addons/io/org.openhab.io.hueemulation/ESH-INF/config/config.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,37 @@
xsi:schemaLocation="http://eclipse.org/smarthome/schemas/config-description/v1.0.0
http://eclipse.org/smarthome/schemas/config-description-1.0.0.xsd">
<config-description uri="io:hueemulation">
<parameter name="pairingEnabled" type="text">
<label>Enable Device Pairing</label>
<description>Pairing must be enabled to connect a new device. Once a device has been added, pairing should be disabled.</description>
<options>
<option value="true">Pairing Enabled</option>
<option value="false">Pairing Disabled</option>
</options>
<parameter name="pairingEnabled" type="boolean">
<label>Device Pairing</label>
<description>Pairing must be enabled to connect a new device. Pairing is automatically disabled after the configured pairing time (usually 60 seconds).</description>
<default>false</default>
</parameter>
<parameter name="pairingTimeout" type="integer" required="false">
<label>Pairing timeout</label>
<description>Pairing is automatically disabled after the given time in seconds.</description>
<default>60</default>
<advanced>true</advanced>
</parameter>
<parameter name="createNewUserOnEveryEndpoint" type="boolean">
<label>Amazon Echo device discovery fix</label>
<description>The Amazon echos have no means to recreate a new api key and they don't care about the 403-forbidden http status code. If the addon has pruned its known users (reinstall etc), echos will not be able to discover new devices. Set this option to just create new users on the fly on the next pairing mode period.</description>
<default>false</default>
</parameter>
<parameter name="restrictToTagsSwitches" type="text" required="false">
<label>Switch item tags</label>
<description>The HUE emulation can either publish Switch items if this is set to an empty string or filter items by tags. You can supply multiple tags by separating them with a comma.</description>
<default>Switchable</default>
</parameter>
<parameter name="restrictToTagsColorLights" type="text" required="false">
<label>Color item tags</label>
<description>The HUE emulation can either publish all Color items if this is set to an empty string or filter items by tags. You can supply multiple tags by separating them with a comma.</description>
<default>ColorLighting</default>
</parameter>
<parameter name="restrictToTagsWhiteLights" type="text" required="false">
<label>White item tags</label>
<description>The HUE emulation can either publish all Dimmer items if this is set to an empty string or filter items by tags. You can supply multiple tags by separating them with a comma.</description>
<default>Lighting</default>
</parameter>
<parameter name="discoveryIp" type="text" required="false">
<label>Optional discovery address</label>
<description>If your host has multiple IP addresses you may specify the IP you would like to advertise in the UPNP discovery process. You may safely leave this empty on most systems.</description>
Expand Down
7 changes: 5 additions & 2 deletions addons/io/org.openhab.io.hueemulation/META-INF/MANIFEST.MF
Original file line number Diff line number Diff line change
Expand Up @@ -13,21 +13,24 @@ Import-Package:
com.google.gson.stream,
javax.servlet,
javax.servlet.http,
org.apache.commons.io,
org.apache.commons.lang,
org.eclipse.jdt.annotation;resolution:=optional,
org.eclipse.smarthome.config.core,
org.eclipse.smarthome.core.common.registry,
org.eclipse.smarthome.core.events,
org.eclipse.smarthome.core.items,
org.eclipse.smarthome.core.items.events,
org.eclipse.smarthome.core.library,
org.eclipse.smarthome.core.library.types,
org.eclipse.smarthome.core.net,
org.eclipse.smarthome.core.service,
org.eclipse.smarthome.core.thing,
org.eclipse.smarthome.core.thing.binding,
org.eclipse.smarthome.core.thing.binding.builder,
org.eclipse.smarthome.core.thing.type,
org.eclipse.smarthome.core.types,
org.eclipse.smarthome.io.rest,
org.osgi.framework,
org.osgi.service.cm,
org.osgi.service.component,
org.osgi.service.event,
org.osgi.service.http,
Expand Down
1 change: 1 addition & 0 deletions addons/io/org.openhab.io.hueemulation/OSGI-INF/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
*.xml
24 changes: 0 additions & 24 deletions addons/io/org.openhab.io.hueemulation/OSGI-INF/hueemulation.xml

This file was deleted.

76 changes: 63 additions & 13 deletions addons/io/org.openhab.io.hueemulation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,85 @@

Hue Emulation exposes openHAB items as Hue devices to other Hue HTTP API compatible applications like an Amazon Echo.

## Features:
## Discovery:

* UPNP automatic discovery
* Support ON/OFF and Percent/Decimal item types
* Can expose any type of item, not just lights
* Pairing (security) can be enabled/disabled in real time using the configuration service (under services in the PaperUI for example)
As soon as the binding 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.

Like the real HUE bridge the service must be put into pairing mode before other applications can access it.

## Exposed devices

It is important to note that you are exposing *Items* not *Things* or *Channels*.
Only Color, Dimmer and Switch type *Items* are supported.

This service can emulate 3 different devices:

* An OSRAM SMART+ Plug,
* a dimmable white color Philips A19 bulb and
* an a Philips Gen 3 LCT010 extended color bulb.

The exposed Hue-type depends on some criteria:

* If the item has the category "ColorLight": It will be exposed as a color bulb
* If the item has the category "Light": It will be exposed as a dimmable white bulb.

This initial type determination is overriden 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 a switchable
* "Lighting": Item will be exposed as a dimmable white bulb
* "ColorLighting": Item will be exposed as a color bulb

It is the responsibility of binding developers to categories and default tag their
available *Channels*, so that linked Items are automatically exposed with this service.

## 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,
so usually "Brightness" or "Color". You want to rename those!

## Configuration:

All options are available in Paper UI.

Pairing can be turned on and off:

```
org.openhab.hueemulation:pairingEnabled=false
```

(Optional) For systems with multiple IP addresses the IP to use for UPNP may be specified, otherwise the first non loopback address will be used.
You can define a pairing timeout in seconds.
After that timeout, the `pairingEnabled` is automatically set to `false`.

```
org.openhab.hueemulation:pairingTimeout=60
```

For systems with multiple IP addresses the IP to use for UPNP may optionally be specified.
Otherwise the first non loopback address will be used.

```
org.openhab.hueemulation:discoveryIp=192.168.1.100
```

## Device Tagging
One of the comma separated tags must match for the item to be exposed. Can be empty to match every item.

```
org.openhab.hueemulation:restrictToTagsSwitches=Switchable
org.openhab.hueemulation:restrictToTagsWhiteLights=Lighting
org.openhab.hueemulation:restrictToTagsColorLights=ColorLighting
```


## Text configuration example

To expose an item on the service, apply a supported tag (which are "Lighting", "Switchable", "TargetTemperature") to it.
The item label will be used as the Hue device name.
The item label will be used as the Hue device name.

```
Switch TestSwitch1 "Kitchen Switch" [ "Switchable" ]
Switch TestSwitch2 "Bathroom" [ "Lighting" ]
Dimmer TestDimmer3 "Hallway" [ "Lighting" ]
Number TestNumber4 "Temperature Set Point" [ "TargetTemperature" ]
Switch TestSwitch "Kitchen Switch" [ "Switchable" ]
Color TestColorBulb "Bathroom" [ "ColorLighting" ]
Dimmer TestDimmer "Hallway" [ "Lighting" ]
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
/**
* Copyright (c) 2010-2018 by the respective copyright holders.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*/
package org.openhab.io.hueemulation.internal;

/**
* Device type
*
* @author David Graeff - Initial contribution
*/
public enum DeviceType {
SwitchType,
WhiteType,
WhiteTemperatureType,
ColorType
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
/**
* Copyright (c) 2010-2018 by the respective copyright holders.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*/
package org.openhab.io.hueemulation.internal;

import java.util.Set;
import java.util.stream.Collectors;
import java.util.stream.Stream;

import org.eclipse.jdt.annotation.NonNullByDefault;
import org.eclipse.jdt.annotation.Nullable;

/**
* The configuration for {@link HueEmulationServlet}.
*
* @author David Graeff - Initial Contribution
*/
@NonNullByDefault
public class HueEmulationConfig {
public boolean pairingEnabled = false;
public static final String CONFIG_PAIRING_ENABLED = "pairingEnabled";
/**
* The Amazon echos have no means to recreate a new api key and they don't care about the 403-forbidden http status
* code. If the addon has pruned its api-key list, echos will not be able to discover new devices. Set this option
* to just create a new user on the fly.
*/
public boolean createNewUserOnEveryEndpoint = true;
public static final String CONFIG_CREATE_NEW_USER_ON_THE_FLY = "createNewUserOnEveryEndpoint";
/** Pairing timeout in seconds */
public int pairingTimeout = 60;
public @Nullable String discoveryIp;
public int discoveryHttpPort = 0;
/** Comma separated list of tags */
public String restrictToTagsSwitches = "Switchable";
/** Comma separated list of tags */
public String restrictToTagsColorLights = "ColorLighting";
/** Comma separated list of tags */
public String restrictToTagsWhiteLights = "Lighting";

public Set<String> switchTags() {
return Stream.of(restrictToTagsSwitches.split(",")).collect(Collectors.toSet());
}

public Set<String> colorTags() {
return Stream.of(restrictToTagsColorLights.split(",")).collect(Collectors.toSet());
}

public Set<String> whiteTags() {
return Stream.of(restrictToTagsWhiteLights.split(",")).collect(Collectors.toSet());
}
}
Loading

0 comments on commit b7e28c5

Please sign in to comment.