nicodujhomebridge-harmony
Logitech Harmony plugin for HomeBridge using WebSockets.
You can discuss this plugin on Discord in #harmony channel
This plugin is publishing harmony hub activities and devices as switches, with some advanced option (see below) for custom needs like macros, sequences, and much more. The TV mode is focused on harmony hub activities only at the moment : each activity of the hub is mapped to an input. A main activity is linked to the on/off switch of the accessory. Buttons on the remote app and volume controls will be binded to the one defined in the activity (if so). VOLUME IS BIND TO PHYSICAL BUTTONS WHEN REMOTE FROM CONTROL CENTER IS SHOWN . There is an option to override default mappings.
Note
- This plugin was developed with Homebridge and therefore has not been tested with Hoobs. If you use Hoobs, please report any issues there first - or migrate to homebridge.
Installation
- Install Homebridge using:
npm install -g homebridge - Install this plugin using:
npm install -g homebridge-harmony - Update your Homebridge
config.jsonusing the sample below.
Note about homebridge configuration
Since this plugin can expose external accessories (TV), you should probably set ports configuration in your homebridge conf with a dedicated range, like this :
"ports": {
"start": 52100,
"end": 52150,
"comment": "This section is used to control the range of ports that separate accessory (like camera or television) should be bind to."
},Also, if you use child Bridge (since Homebridge 1.3.0), it makes sense only if you publish switches / bridges accessories. If you are only running a default TV accessory, it will publish an empty bridge that might be confusing (see https://github.com/nicoduj/homebridge-harmony/issues/347 for more details)
Migration from 0.X to 1.X
You have to move your other platforms if you have more than one in a new key : "otherPlatforms": [{ }] , see sample below. The plugin MUST be adde donly One time in your config
- TV mode is now the default. If you want switches, use option
switchAccessories(oractivitiesToPublishAsAccessoriesSwitch) - You have to rename
skipedIfSameStateActivitiestoskippedIfSameStateActivities(with 2p) oraddAllActivitiesToSkipedIfSameStateActivitiesListtoaddAllActivitiesToSkippedIfSameStateActivitiesList(also with 2p) if you were using one of those options. - You have to rename
publishActivitiesAsIndividualAccessoriestopublishSwitchActivitiesAsIndividualAccessories - You have to modify
devicesToPublishAsAccessoriesSwitchoption if you were using it, see details below - If you were overriding MENU through
remoteOverrideCommandsListyou have to use SETUP instead now (since it is in the settings of the remote).
In case of any trouble like accessories allready added (or missing), you can try to use the option cleanCache but please report in order for me to fix if possible (see Fields section).
To setup mutliple tv platorm, you will have to add others manually in homekit. Other ones (than the first one) won't be cached. See publishAllTVAsExternalAccessory for details.
Configuration samples
Simple Config (only TV Accessory)
"platforms": [
{
"platform": "HarmonyHubWebSocket",
"name": "HubName",
"hubIP": "192.168.1.XX"
}
]Only switch mode
"platforms": [
{
"platform": "HarmonyHubWebSocket",
"name": "HubName",
"TVAccessory" : false,
"switchAccessories" : true
}
]Mutliple hubs - fixedIP
"platforms": [
{
"platform": "HarmonyHubWebSocket",
"name": "HubName",
"hubIP": "192.168.1.XX",
"otherPlatforms": [{
"name": "OtherHubName",
"hubIP": "192.168.1.YY"
}]
}
]Mutliple hubs - using harmonyNames
"platforms": [
{
"platform": "HarmonyHubWebSocket",
"name": "HubName",
"hubName": "myFirstHub",
"otherPlatforms": [{
"name": "OtherHubName",
"hubName": "mySecondHub",
}]
}
]Fields:
platformGLOBAL must be "HarmonyHubWebSocket" (required).publishAllTVAsExternalAccessoryGLOBAL publish all TV accessory as external Accessories. This way, if another plugin on the same homebridge instance as one, the one on harmony will also be visible, but you will have to add them manually after the hub itself. Defaults to TRUE (if set to false, only second tv accessory or following will be published by this plugin as external accessories, first one will be linked to the hub and might not display a TV icon).cleanCacheGLOBAL option to clean all cached Accessory. Please use with caution, might be needed if you change names / config of the hub and there is some ghost devices in Homekit. Be sure that all your icloud sync is done while launching Homebridge with this option set to true. Set it back to false after and launch again ! It does not affect external accessories.DELAY_BEFORE_RETRY_AFTER_NETWORK_LOSSGLOBAL retry timer in case of network loss (optionnal - defaults 60s).HUB_CONNECT_TIMEOUTGLOBAL connect timeout (optionnal - defaults 10s).HUB_SEND_TIMEOUTGLOBAL send timeout (optionnal - defaults 30s).nameis the name of the published Platform (required).hubNameis the name of your hub in harmony app (optional, but mandatory if you have mutliple hubs). In case both hubName and hubIP are not set, it will discover your hub automatically, providing there is only onehubIPis the static IP address of the hub (optional). A static IP address is required.TVAccessorypublish hub with its activities as a TV Accessory (defaults to true).sortInputsort input list in TV accessory : 0-default,1:Alpha,2:activityOrder property of hub, 3:activitiesToPublishAsInputForTVMode order (defaults to 0).switchAccessoriespublish all activities as a Switch Accessory (defaults to false).activitiesToPublishAsAccessoriesSwitcharray of Activities you want to expose as switches (all by default if switchAccessories is set to true, otherwise specify the list you want)showTurnOffActivityconfigures whether to publish a "switch" accessory to turn off every activity (defaults to false).- if you set to true, The "switch" will be "on" if and only if there is no current activity, and toggling it while "on" does nothing.
- if you set to "inverted", The "switch" will be "off" if and only if there is no current activity, and toggling it while "off" does nothing.
- if you set to "stateless", it will always be off, but can be triggered to switch off current activity.
skippedIfSameStateActivitiesarray of Activities name to trigger only if their state is different from the action sent. Can be useful if your devices in the activity have the same on / off command and you want to automate them outside off the home app. For TV mode, and PowerOff feature, "PowerOff" is added by default, but you have to add it manually to this list if this list is set.addAllActivitiesToSkippedIfSameStateActivitiesListoption to add all activities automatically to skippedIfSameStateActivities behavior. (defaults : false)publishSwitchActivitiesAsIndividualAccessoriesoption to publish activities as individual accessories. Defaults to true.devicesToPublishAsAccessoriesSwitcharray of Devices to exposes with on/off function or custom functionspublishDevicesAsIndividualAccessoriesoption to publish devices as individual accessories. Defaults to true.sequencesToPublishAsAccessoriesSwitcharray of Sequences to exposes through a switch.publishSequencesAsIndividualAccessoriesoption to publish sequences as individual accessories. Defaults to true.homeControlsToPublishAsAccessoriesSwitcharray of home controls you want to publish as switchespublishHomeControlsAsIndividualAccessoriesoption to publish home controls as individual accessories. Defaults to true.mainActivityset the mainactivity of the TV modeplayPauseBehaviorplay/pause behavior in TV mode : if set to true, will send pause if played was set and vice-verca. Be aware that both commands must be available, and that it might be out of sync in case of external events (defaults : false - always send play command)configureAccesscontrolconfigure Access control service (false by default)publishGeneralMuteSwitchpublish a mute switch, stateless, that will send a mute command to current activity.publishGeneralVolumeSliderpublish a volume slider, stateless, that will send a volume commands to current activity. Approximativley, it will send an Up / Down Volume command each 5%. It can be combined withnumberOfCommandsSentForVolumeControloption to multiply the number of up / down commands sent.publishGeneralVolumeSwitchespublish switches, stateless, for volume up / down on TV Accessory. It can be combined withnumberOfCommandsSentForVolumeControloption to multiply the number of up / down commands sent.linkVolumeControlToTVlinks mute / volume switch to TV accessory if presentremoteOverrideCommandsListoption to override default commands mapping in TV Platform Mode. See below for format.activitiesToPublishAsInputForTVModearray of Activities you want to expose as inputs (all by default)numberOfCommandsSentForVolumeControloption to set the number of commands to send for each volum (up or down) press. Defaults to 1showCommandsAtStartupshow commands and device losts at startup (defaults to false)otherPlatformsis an array of hubs platform . All option are available except GLOBAL ones
All devices / Activites names are the one configured in harmony configuration, even if you rename them in home app.
Option devicesToPublishAsAccessoriesSwitch is an array that behaves this way :
- You should put the name of the device as it is named in harmony app,
- You can add a specific command or multiple ones JUST AFTER A ";" or a series of ";" if you want a switch to be added for this specific command or serie of commands (a default delay of 350ms will be added between each command if no sepecif delay is specified),
- If you do not specify any specific command, the plugin will add either powerToggle if found in Power command group, or PowerOn and/or PowerOff if there is no powerToggle feature,
As a sample :
"devicesToPublishAsAccessoriesSwitch" : ["Apple TV Gen 4|Button1;Play","Apple TV Gen 4;DirectionDown","Caisson","Sony PS4","MyDevice;Up;Up|2500;Down"]will add
- a switch for "Apple TV Gen 4" "Play" command, named Button1,
- a switch for "Apple TV Gen 4" "DirectionDown" command,
- a powerToggle switch for the device named "Caisson",
- a powerOff switch only for PS4 (since there is no powerToggle nor powerOn command for it)
- a switch that will send Up , then Up, then wait 2.5 seconds, then send Down to MyDevice
All commands available are displayed at startup. If no name is specified, it will be added with a generated name.
If you use a "/", it will do a non stateless switch and send commands before the / on On, and after on Off. Be aware that it can be out of sync .
As a sample :
"devicesToPublishAsAccessoriesSwitch" : ["Apple TV Gen 4|Button1;Play/Pause","Caisson;/","Sony PS4;/","MyDevice;/","MyDevice;Up;Up|2500;Down/Down;Down|2500;Up"]will add
- a switch for "Apple TV Gen 4" "Play" command on on, "Pause" command on off, named Button1,
- a powerToggle switch for the device named "Caisson", which will send PowerToggle on on and off,
- a powerOff switch only for PS4 (since there is no powerToggle nor powerOn command for it) - thus no effect
- a switch that will PowerOn on On and PowerOff on off to MyDevice since it doe not have a powerToggle and have both powerOn / PowerOff
- a switch that will send Up , then Up, then wait 2.5 seconds, then send Down to MyDevice on On and reverse on Off
Option sequencesToPublishAsAccessoriesSwitch is an array that behaves this way :
- You should put the name of the sequence as it is named in harmony app,
As a sample :
"sequencesToPublishAsAccessoriesSwitch" : ["Test"]will expose the sequence Test as a button.
See Logitech Harmony Sequence Configuration for sequences configuration.
Please note that the sequence can only be triggered if its activity is in use. (Sequences are linked to an activity by design in harmony app).
Option remoteOverrideCommandsList is an array that behaves this way :
- You should put the name of the activity as it is named in harmony app,
- Then an Array CommandsList with :
- the name of the command you want to override
- the commands like in devicesToPublishAsAccessoriesSwitch (with the name of the device first)
"remoteOverrideCommandsList": [
{
"ActivityName": "La TV",
"CommandsList": [
{
"CommandName": "PAUSE",
"NewCommand": "Ampli;Number0;Number0"
},
{
"CommandName": "BACK",
"NewCommand": "TV;Back"
}
]
},
{
"ActivityName": "Un Film",
"CommandsList": [
{
"CommandName": "ARROW_LEFT",
"NewCommand": "TV;PreviousChannel"
}
]
}
]will bahaves this way :
- for "La TV" activity :
- override PAUSE button in the remote with Number0 command for Ampli device, and send it 5 times
- override BACK button in the remote with Back Command of TV device
- for "Un Film" activity :
- override ARROW_LEFT in the remote with PreviousChannel of TV device
Button List is :
- REWIND
- FAST_FORWARD
- NEXT_TRACK
- PREVIOUS_TRACK
- ARROW_UP
- ARROW_DOWN
- ARROW_LEFT
- ARROW_RIGHT
- SELECT
- BACK
- EXIT
- INFORMATION
- PLAY
- PAUSE
- VOLUME_UP
- VOLUME_DOWN
- MUTE
- SETUP
Commands of your device is shown in the log at startup in lines like : 'INFO - Command : COMMAND_NAME discovered for device : DEVICENAME'
Changelog
See CHANGELOG.
Inspiration
Thanks to
- iandday for the Harmoney WebSocket protocol implementation and understanding of it.
- lopelex for his clean plugin.
- every tester / contributor that test, and give feedback in any way , and especially
- gitgayhub for Home controls in 0.6.0
- donavanbecker for testing multiple hubs auto discovery (and supporting homebirdge :) )
Donating
Support this project and others by nicoduj via PayPal.
License
As of Dec 01 2018, Nicolas Dujardin has released this repository and its contents to the public domain.
It has been released under the UNLICENSE.