This page is part of archived documentation for openHAB 4.0. Go to the current stable version
# Logitech Harmony Hub Binding
The Harmony Hub binding is used to enable communication between openHAB and multiple Logitech Harmony Hub devices. The API exposed by the Harmony Hub is relatively limited, but it does allow for reading the current activity as well as setting the activity and sending device commands.
# Overview
The Harmony binding represents a "Hub" as a bridge thing type and "Devices" as things connected to the bridge.
# Hub
A hub (bridge thing) represents a physical Harmony Hub. The hub possesses a single channel with the id "activity" which is a StringType set to the name of the current activity. This channel is dynamically generated with the possible activity strings listed as channel state options.
# Devices
Devices are dynamically created. There is a single device thing for every physical device configured on the harmony hub. Each device has a single channel with the id "button" which sends a string with the name of the button to press on the device. This channel is dynamically generated with the possible button press strings listed as channel state options.
# Discovery
The Harmony binding will automatically find all Harmony Hubs on the local network and add them to the inbox. Once a Hub has been added, any connected devices will also added to the Inbox.
# Binding Configuration
The binding requires no special configuration
# Thing Configuration
This is optional, it is recommended to let the binding discover and add hubs and devices.
To manually configure a Harmony Hub thing you may specify its host name ("host") as well as an optional search timeout value in seconds ("discoveryTimeout") and optional heart beat interval (heartBeatInterval) in seconds.
In the thing file, this looks e.g. like
Bridge harmonyhub:hub:GreatRoom [ host="192.168.1.100"]
To manually configure a Harmony device thing you may specify its numeric id ("id") or its name ("name"), but not both. Note that this is prefixed by the hub the device is controlled from.
In the thing file, this looks e.g. like
Bridge harmonyhub:hub:GreatRoom [ name="Great Room"] {
device denon [ name="Denon AV Receiver"]
}
or
Bridge harmonyhub:hub:GreatRoom [ name="Great Room"] {
device denon [ id=176254]
}
# Channels
Note! Hubs cannot receive buttons pressed on the remote. The buttonPress channel described below is sent to the device only.
Hubs can report and change the current activity:
items:
String HarmonyGreatRoomActivity "Current Activity [%s]" (gMain) { channel="harmonyhub:hub:GreatRoom:currentActivity" }
Hubs can also send a button press to a device associated with the current activity. A String item can be used to send any button name/label or a Player item can be used to send Play/Pause/FastForward/Rewind/SkipForward/SkipBackward. This mimics the physical remote where buttons are mapped differently depending on which activity is running. For example the play button may be sent to a DVD player when running a "Watch DVD" activity, or it may be sent to an Apple TV when running a "Watch Movie" activity.
String HarmonyHubGreatButton { channel="harmonyhub:hub:GreatRoom:buttonPress" }
Player HarmonyHubGreatPlayer { channel="harmonyhub:hub:GreatRoom:player" }
Devices can be sent button commands directly, regardless if they are part of the current running activity or not. Note that you must define a Harmony device thing for this to work.
String HarmonyGreatRoomDenon "Denon Button Press" (gMain) { channel="harmonyhub:device:GreatRoom:denon:buttonPress" }
Hubs can also trigger events when a new activity is starting (activityStarting channel) and after it is started (activityStarted channel).
The name of the event is equal to the activity name, with all non-alphanumeric characters replaced with underscore.
rules:
rule "Starting TV"
when
Channel "harmonyhub:hub:GreatRoom:activityStarting" triggered Watch_TV
then
logInfo("Harmony", "TV is starting...")
end
rule "TV started"
when
Channel "harmonyhub:hub:GreatRoom:activityStarted" triggered Watch_TV
then
logInfo("Harmony", "TV is started")
end
rule "Going off"
when
Channel "harmonyhub:hub:GreatRoom:activityStarting" triggered PowerOff
then
logInfo("Harmony", "Hub is going off...")
end
rule "Hub off"
when
Channel "harmonyhub:hub:GreatRoom:activityStarted" triggered PowerOff
then
logInfo("Harmony", "Hub is off - no activity")
end
# Example Sitemap
Using the above things channels and items Sitemap:
sitemap demo label="Main Menu" {
Frame {
Switch item=HarmonyGreatRoomActivity mappings=[PowerOff="PowerOff", TIVO="TIVO", Music="Music","APPLE TV"="APPLE TV", NETFLIX="NETFLIX"]
Switch item=HarmonyHubGreatButton label="Direction Pad" mappings=[DirectionUp='Up', DirectionDown='Down', DirectionLeft='<', DirectionRight='>', Select='OK']
Switch item=HarmonyGreatRoomDenon mappings=["Volume Up"="Volume Up","Volume Down"="Volume Down"]
}
}
# ButtonPress values
Example subset of values for the current activity "buttonPress" channels
Mute,VolumeDown,VolumeUp,DirectionDown,DirectionLeft,DirectionRight,DirectionUp,Select,Stop,Play,Rewind,Pause,FastForward,SkipBackward,SkipForward,Menu,Back,Home,SelectGame,PageDown,PageUp,Aspect,Display,Search,Cross,Circle,Square,Triangle,PS,Info,NumberEnter,Hyphen,Number0,Number1,Number2,Number3,Number4,Number5,Number6,Number7,Number8,Number9,PrevChannel,ChannelDown,ChannelUp,Record,FrameAdvance,C,B,D,A,Live,ThumbsDown,ThumbsUp,TiVo,WiiA,WiiB,Guide,Clear,Green,Red,Blue,Yellow,Dot,Return,Favorite,Exit,Sleep
A complete list of names for device buttons values can be determined via the REST API for channel-types. The easiest way to do this is through the API explorer:
- Go to the main UI page for your installation
- This is usually at http://your-openhab-ip:8080 (opens new window) or, in the case of openhabian, http://openhabian:8080 (opens new window)
- Login if you are not already logged in
- Using the left panel (or three bars on the upper left corner) go to Developer Tools -> API Explorer -> channel-types
- Click
GET
next to/channel-types
- Click
Try it out
- Click
Execute
- Search the
Response Body
"harmonyhub:device" and find your device in the JSON output
The valid commands (read: values) will be listed with the device. For example, the response body might show that for harmonyhub:device:HarmonyHub:lasko_fan
the valid commands are PowerToggle, Speed, Timer
{
"parameters": [],
"parameterGroups": [],
"description": "Send a button press to device Harmony Device",
"label": "Send Button Press",
"itemType": "String",
"kind": "STATE",
"stateDescription": {
"readOnly": false,
"options": [
{
"value": "PowerToggle",
"label": "Power Toggle"
},
{
"value": "Speed",
"label": "Speed"
},
{
"value": "Timer",
"label": "Timer"
}
]
},
"tags": [],
"UID": "harmonyhub:device:GreatRoom:lasko_fan:buttonPress",
"advanced": false
}
← Log Reader Loxone →