# 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 ```java 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 ```java Bridge harmonyhub:hub:GreatRoom [ name="Great Room"] { device denon [ name="Denon AV Receiver"] } ``` or ```java 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: ```java 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. ```java 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. ```java 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: ```javascript 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: ```perl 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 ```text 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: 1. Go to the main UI page for your installation - This is usually at or, in the case of openhabian, 1. Login if you are not already logged in 1. Using the left panel (or three bars on the upper left corner) go to Developer Tools -> API Explorer -> channel-types 1. Click `GET` next to `/channel-types` 1. Click `Try it out` 1. Click `Execute` 1. 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` ```json { "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 } ```