Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

switched from homekit to ESH ontology #946

Merged
merged 1 commit into from
May 21, 2016
Merged

switched from homekit to ESH ontology #946

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 19 additions & 25 deletions addons/io/org.openhab.io.homekit/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ org.openhab.homekit:networkInterface=192.168.0.6
```

## Item Configuration
After setting this global configuration, you will need to tag your openHAB items in order to map them to the HomeKit ontology. For our purposes, you may consider HomeKit accessories to be of two forms: simple and complex.
After setting this global configuration, you will need to tag your openHAB items in order to map them to an ontology. For our purposes, you may consider HomeKit accessories to be of two forms: simple and complex.

A simple accessory will be mapped to a single openHAB item (i.e. a Lighbulb is mapped to a Switch, Dimmer, or Color item). A complex accessory will be made up of multiple openHAB items (i.e. a Thermostat is composed of Heating and Cooling thresholds, a mode, and current temperature). Complex accessories require a tag on a Group indicating the accessory type, as well as tags on the items it composes.

Expand All @@ -34,31 +34,25 @@ A full list of supported accessory types can be found in the table below.
<td><b>description</b></td>
</tr>
<tr>
<td>Lightbulb</td>
<td>Lighting</td>
<td>&nbsp;</td>
<td>Switch, Dimmer, Color</td>
<td>A lightbulb</td>
<td>A lightbulb, either switchable or dimmable</td>
</tr>
<tr>
<td>DimmableLightbulb</td>
<td>&nbsp;</td>
<td>Dimmer, Color</td>
<td>A lightbulb with the ability to set an output level</td>
</tr>
<tr>
<td>Switch</td>
<td>Switchable</td>
<td>&nbsp;</td>
<td>Switch, Dimmer, Color</td>
<td>An accessory that can be turned off and on. While similar to a lightbulb, this will be presented differently in the Siri grammar and iOS apps</td>
</tr>
<tr>
<td>TemperatureSensor</td>
<td>CurrentTemperature</td>
<td>&nbsp;</td>
<td>Number</td>
<td>An accessory that provides a single read-only temperature value. The units default to celsius but can be overridden globally using the useFahrenheitTemperature global property</td>
</tr>
<tr>
<td>HumiditySensor</td>
<td>CurrentHumidity</td>
<td>&nbsp;</td>
<td>Number</td>
<td>An accessory that provides a single read-only value indicating the relative humidity.</td>
Expand All @@ -71,34 +65,34 @@ A full list of supported accessory types can be found in the table below.
</tr>
<tr>
<td>&nbsp;</td>
<td>currentTemperature</td>
<td>CurrentTemperature</td>
<td>Number</td>
<td>The current temperature, using the same unit rules as TemperatureSensor</td>
<td>The current temperature, same as above</td>
</tr>
<tr>
<td>&nbsp;</td>
<td>heatingCoolingMode</td>
<td>homekit:HeatingCoolingMode</td>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually I don't think this is homekit specific, Amazon uses the same format so I believe this will be important going forward. We are currently depending on this for the Alexa integration.

Copy link
Contributor

@digitaldan digitaldan May 20, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kaikreuzer will also add that the homekit binding has some properties that have to be set as config options, like

org.openhab.homekit:useFahrenheitTemperature=true
org.openhab.homekit:thermostatCoolMode=CoolOn
org.openhab.homekit:thermostatHeatMode=HeatOn
org.openhab.homekit:thermostatAutoMode=Auto
org.openhab.homekit:thermostatOffMode=Off

The temperature format is very important to other integrations, I would propose this be moved to a tag that can be set on the "Thermostat" . The heating modes would also be nice to be able to set not through a specific binding.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually I don't think this is homekit specific

Right, but I am not yet at all clear on how I will model this exactly in the ontology (incl. naming). And since it is then anyhow likely to change again in future, I preferred to keep it here for the moment.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The temperature format is very important to other integrations

You mean the unit? This will be addressed by eclipse-archived/smarthome#601.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mean the unit? This will be addressed by eclipse-archived/smarthome#601.

Hopefully that work will get revived soon.

Right, but I am not yet at all clear on how I will model this exactly in the ontology (incl. naming). And since it is then anyhow likely to change again in future, I preferred to keep it here for the moment.

No problem. Just for reference, the Alexa api has 'temperatureMode' which can be ' AUTO, COOL, HEAT' . It seems this is a common pattern.

<td>String</td>
<td>Indicates the current mode of the device: OFF, AUTO, HEAT, COOL. The string's value must match those defined in the thermostat*Mode properties.</td>
<td>Indicates the current mode of the device: OFF, AUTO, HEAT, COOL. The string's value must match those defined in the thermostat*Mode properties. This is a homekit-specific term and therefore the tags needs to be prefixed with "homekit:"</td>
</tr>
<tr>
<td>&nbsp;</td>
<td>targetTemperature</td>
<td>TargetTemperature</td>
<td>Number</td>
<td>A target temperature that will engage the thermostat's heating and cooling actions as necessary, depending on the heatingCoolingMode</td>
</tr>
</table>

Tags are applied to items using the prefix "homekit:". See the sample below for example items:
See the sample below for example items:

```
Switch KitchenLights "Kitchen Lights" <light> (gKitchen) [ "homekit:Lightbulb" ]
Dimmer BedroomLights "Bedroom Lights" <light> (gBedroom) [ "homekit:DimmableLightbulb" ]
Number BedroomTemperature "Bedroom Temperature" (gBedroom) [ "homekit:TemperatureSensor" ]
Group gDownstairsThermostat "Downstairs Thermostat" (gFF) [ "homekit:Thermostat" ]
Number DownstairsThermostatCurrentTemp "Downstairs Thermostat Current Temperature" (gDownstairsThermostat) [ "homekit:currentTemperature" ]
Number DownstairsThermostatTargetTemperature "Downstairs Thermostat Target Temperature" (gDownstairsThermostat) [ "homekit:targetTemperature" ]
String DownstairsThermostatHeatingCoolingMode "Downstairs Thermostat Heating/Cooling Mode" (gDownstairsThermostat) [ "homekit:heatingCoolingMode" ]
Switch KitchenLights "Kitchen Lights" <light> (gKitchen) [ "Lighting" ]
Dimmer BedroomLights "Bedroom Lights" <light> (gBedroom) [ "Lighting" ]
Number BedroomTemperature "Bedroom Temperature" (gBedroom) [ "CurrentTemperature" ]
Group gDownstairsThermostat "Downstairs Thermostat" (gFF) [ "Thermostat" ]
Number DownstairsThermostatCurrentTemp "Downstairs Thermostat Current Temperature" (gDownstairsThermostat) [ "CurrentTemperature" ]
Number DownstairsThermostatTargetTemperature "Downstairs Thermostat Target Temperature" (gDownstairsThermostat) [ "TargetTemperature" ]
String DownstairsThermostatHeatingCoolingMode "Downstairs Thermostat Heating/Cooling Mode" (gDownstairsThermostat) [ "homekit:HeatingCoolingMode" ]
```

## Additional Notes
Expand Down
6 changes: 3 additions & 3 deletions ...b.io.homekit/src/main/java/org/openhab/io/homekit/internal/HomekitCharacteristicType.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@
*/
public enum HomekitCharacteristicType {

CURRENT_TEMPERATURE("currentTemperature"),
TARGET_TEMPERATURE("targetTemperature"),
HEATING_COOLING_MODE("heatingCoolingMode");
CURRENT_TEMPERATURE("CurrentTemperature"),
TARGET_TEMPERATURE("TargetTemperature"),
HEATING_COOLING_MODE("homekit:HeatingCoolingMode");

private static final Map<String, HomekitCharacteristicType> tagMap = new HashMap<>();

Expand Down
12 changes: 6 additions & 6 deletions ...g.openhab.io.homekit/src/main/java/org/openhab/io/homekit/internal/HomekitDeviceType.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,17 @@

/**
* Enum of the possible device types. The defined tag string can be used
* as a homekit:{tag} tag on an item to enable it for Homekit.
* as a tag on an item to enable it for Homekit.
*
* @author Andy Lintner
*/
public enum HomekitDeviceType {

DIMMABLE_LIGHTBULB("DimmableLightbulb"),
HUMIDITY_SENSOR("HumiditySensor"),
LIGHTBULB("Lightbulb"),
SWITCH("Switch"),
TEMPERATURE_SENSOR("TemperatureSensor"),
DIMMABLE_LIGHTBULB("DimmableLighting"),
HUMIDITY_SENSOR("CurrentHumidity"),
LIGHTBULB("Lighting"),
SWITCH("Switchable"),
TEMPERATURE_SENSOR("CurrentTemperature"),
THERMOSTAT("Thermostat");

private static final Map<String, HomekitDeviceType> tagMap = new HashMap<>();
Expand Down
18 changes: 8 additions & 10 deletions ...g.openhab.io.homekit/src/main/java/org/openhab/io/homekit/internal/HomekitTaggedItem.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,12 @@

import org.apache.commons.lang.builder.HashCodeBuilder;
import org.eclipse.smarthome.core.items.Item;
import org.eclipse.smarthome.core.library.items.DimmerItem;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
* Wraps an Item with data derived from any homekit: tags defined.
* Wraps an Item with data derived from supported tags defined.
*
* @author Andy Lintner
*/
Expand All @@ -34,15 +35,12 @@ public class HomekitTaggedItem {
public HomekitTaggedItem(Item item) {
this.item = item;
for (String tag : item.getTags()) {
if (tag.startsWith("homekit:")) {
String tagValue = tag.substring("homekit:".length()).trim();
homekitDeviceType = HomekitDeviceType.valueOfTag(tagValue);
if (homekitDeviceType == null) {
homekitCharacteristicType = HomekitCharacteristicType.valueOfTag(tagValue);
if (homekitCharacteristicType == null) {
logger.error("Unrecognized homekit type: " + tagValue);
}
}
if (item instanceof DimmerItem) {
tag = "Dimmable" + tag;
}
homekitDeviceType = HomekitDeviceType.valueOfTag(tag);
if (homekitDeviceType == null) {
homekitCharacteristicType = HomekitCharacteristicType.valueOfTag(tag);
}
}
if (homekitDeviceType != null) {
Expand Down
3 changes: 2 additions & 1 deletion addons/io/org.openhab.io.hueemulation/META-INF/MANIFEST.MF
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,11 @@ Bundle-Vendor: openHAB
Bundle-Version: 2.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.7
Bundle-ClassPath: .
Import-Package: com.google.gson;version="2.2.4",
Import-Package: com.google.gson,
javax.servlet,
javax.servlet.http,
org.apache.commons.io,
org.apache.commons.lang,
org.eclipse.smarthome.config.core,
org.eclipse.smarthome.core.events,
org.eclipse.smarthome.core.items,
Expand Down
16 changes: 10 additions & 6 deletions addons/io/org.openhab.io.hueemulation/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,26 @@
Hue Emulation exposes openHAB items as Hue devices to other Hue HTTP API compatible applications like an Amazon Echo.

##Features:

* 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)

##Configuration:

Pairing can be turned on and off:

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

##Device Taging
To expose an item on the service apply any Apple HomeKit style tag to it. The item label will be used as the Hue Device name.
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.

```
Switch TestSwitch1 "Kitchen Switch" [ "Switchable" ]
Switch TestSwitch2 "Bathroom" [ "Lighting" ]
Dimmer TestDimmer3 "Hallway" [ "Lighting" ]
Number TestNumber4 "Temperature Set Point" [ "TargetTemperature" ]
```
Switch TestSwitch1 "Kitchen Switch" ["homekit:Switch"]
Switch TestSwitch2 "Bathroom" ["homekit:Lightbulb"]
Dimmer TestDimmer3 "Hallway" ["homekit:DimmableLightbulb"]
Number TestNumber4 "Cool Set Point" ["homekit:coolingThreshold"]
```
10 changes: 6 additions & 4 deletions ....hueemulation/src/main/java/org/openhab/io/hueemulation/internal/HueEmulationServlet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
import javax.servlet.http.HttpServletResponse;

import org.apache.commons.io.IOUtils;
import org.apache.commons.lang.ArrayUtils;
import org.eclipse.smarthome.config.core.ConfigConstants;
import org.eclipse.smarthome.core.events.EventPublisher;
import org.eclipse.smarthome.core.items.Item;
Expand Down Expand Up @@ -67,7 +68,6 @@ public class HueEmulationServlet extends HttpServlet {
private Logger logger = LoggerFactory.getLogger(HueEmulationServlet.class);
private static final String CONFIG_PAIRING_ENABLED = "pairingEnabled";
private static final String PATH = "/api";
private static final String HOMEKIT_PREFIX = "homekit:";
private static final String METHOD_POST = "POST";
private static final String METHOD_PUT = "PUT";
private static final String APPLICATION_XML = "application/xml";
Expand All @@ -80,6 +80,8 @@ public class HueEmulationServlet extends HttpServlet {
private static final File UDN_FILE = new File(
ConfigConstants.getUserDataFolder() + File.separator + "hueemulation" + File.separator + "udn");

private static final String[] SUPPORTED_TAGS = new String[] { "Switchable", "Lighting", "TargetTemperature" };

/**
* This parses "/api/{username}/{lights}/{id}/{state}"
*/
Expand Down Expand Up @@ -424,9 +426,9 @@ public Map<String, String> getHueDeviceNames() {
}

/**
* Converts an VoiceItem to a HueDevice
* Converts an Item to a HueDevice
*
* @param voiceItem
* @param item
* @return
* HueDevice
*/
Expand All @@ -452,7 +454,7 @@ private Collection<Item> getTaggedItems() {
Collection<Item> items = new LinkedList<Item>();
for (Item item : itemRegistry.getItems()) {
for (String tag : item.getTags()) {
if (tag.startsWith(HOMEKIT_PREFIX)) {
if (ArrayUtils.contains(SUPPORTED_TAGS, tag)) {
items.add(item);
break;
}
Expand Down