homebridge-harmony-control/README.md

# homebridge-harmony-control

A convenient way to control your home through homekit utilizing one or many Logitech Harmony remotes.

## Description

This plugin not only allows for control of your one or many entertainment consoles, but it also supports use of a more complicated matrix switch if applicable. In addition, this plugin can expose any entertainment devices directly to homekit via stateless or stateful switch.

## Installation

1. Clone the repository by running `git clone ssh://git@thebword.ddns.net:3122/watsonb8/homebridge-harmony-control.git`
2. Run `npm install` to install required modules
3. Run `npm run build` to build the module
4. Run `npm link` or install globally to link this instance to your global homebridge instance

## Configuration

```
{
      "platform": "HarmonyHubMatrix",
      "EmitDevicesOnStartup": false,
      "Hubs": [
        {
          "Name": "LivingRoomHub",
          "Ip": "exampleOne.com"
        },
        {
          "Name": "RackHub",
          "Ip": "exampleTwo.com"
        }
      ],
      "Devices": [
        {
          "Name": "LG TV",
          "Hub": "LivingRoomHub"
        },
        {
          "Name": "JVC AV Receiver",
          "Hub": "LivingRoomHub"
        },
        {
          "Name": "Microsoft Xbox One",
          "Hub": "RackHub"
        },
        {
          "Name": "Apple TV Gen 4",
          "Hub": "RackHub"
        },
        {
          "Name": "Gefen AV Switch",
          "Hub": "RackHub"
        }
      ],
      "Matrix": {
        "DeviceName": "Gefen AV Switch",
        "Inputs": [
          {
            "InputNumber": "1",
            "InputDevice": "Microsoft Xbox One"
          },
          {
            "InputNumber": "5",
            "InputDevice": "Apple TV Gen 4"
          },
        ],
        "Outputs": [
          {
            "OutputLetter": "B",
            "OutputDevice": "LG TV"
          },
        ]
      },
      "ControlUnits": [
        {
          "DisplayName": "Living Room",
          "Activities": [
            {
              "DisplayName": "Xbox One",
              "DeviceSetupList": [
                {
                  "DeviceName": "Microsoft Xbox One",
                  "Input": []
                },
                {
                  "DeviceName": "LG TV",
                  "Input": "Hdmi1"
                },
                {
                  "DeviceName": "JVC AV Receiver",
                  "Input": "Dvd"
                }
              ],
              "VolumeDevice": "JVC AV Receiver",
              "ControlDevice": "Microsoft Xbox One",
              "OutputDevice": "LG TV",
              "UseMatrix": true
            },
            {
              "DisplayName": "Apple TV",
              "DeviceSetupList": [
                {
                  "DeviceName": "Apple TV Gen 4",
                  "Input": []
                },
                {
                  "DeviceName": "LG TV",
                  "Input": "Hdmi1"
                },
                {
                  "DeviceName": "JVC AV Receiver",
                  "Input": "Dvd"
                }
              ],
              "VolumeDevice": "JVC AV Receiver",
              "ControlDevice": "Apple TV Gen 4",
              "OutputDevice": "LG TV",
              "UseMatrix": true
            },
          ]
        },
      ],
      "DeviceButtons": [
        {
          "DeviceName": "JVC AV Receiver",
          "ButtonName": "SurroundToggle",
          "DisplayName": "Surround Toggle",
          "IsStateful": true
        },
      ]
    }
```

#### Platform

- `EmitDevicesOnStartup`: If true, each device frome each hub will be written to the console on startup

- `Hubs`: A list of harmony hub configurations

- `Devices`: A list of devices to be used and corresponding hubs

- `Matrix`: An optional configuration for an hdmi matrix

- `ControlUnits`: Configures one logical control unit. This is usually a single TV in a single room.

#### Devices

- `Name`: The name of the device to use from an existing harmony hub configuration

> Note: Use `EmitDevicesOnStartup` if you are unsure of which devices are available.

- `Hub`: The name of the hub to look the device on

#### Matrix

- `DeviceName`: The name of the matrix device as seen in the harmony configuration

> Note: This device must appear in the device list

- `Inputs`: A list of input devices and their corresponding input number as it relates to the matrix switch

- `Outputs`: A list of output devices and their corresponding output letter as it relates to the matrix switch

#### ControlUnits

This is the logical display unit. It will appear as a tv accessory in the home app.

- `DisplayName`: The name of the control unit

- `Activities`: A list of activity configurations. These will be the inputs associated with the tv accessory
- `DeviceSetupList`: A list of devices associated with an activity and their corresponding input setting

- `VolumeDevice`: The device that should be used to control the volume of the activity. This is usually a stereo or a tv

- `ControlDevice`: The device that is used to control UI navigation

- `OutputDevice`: The device that is used to display the content. This is usually a TV

- `UseMatrix`: If true, corresponding commands will be issued to the matrix device to route input to output