# HCA Plugin for Homebridge

[![npm version](https://badge.fury.io/js/homebridge-hca.svg)](https://badge.fury.io/js/homebridge-hca)

## Introduction

The HCA Plugin for Homebridge exposes [Home Control Assistant (HCA)](http://www.hcatech.com) devices, programs, and groups to Apple's [HomeKit](https://www.apple.com/ios/home/) platform.

It provides the following features:

- Bi-directional communication between HomeKit and HCA.
- Real-time accessory state updates in HomeKit when controlled outside of HomeKit.
- Dynamically add or remove an accessory to HomeKit (or change its name) via HCA without restarting Homebridge.
- Control your HCA devices from your iPhone, iPad, Apple Watch, Apple TV (via the Siri Remote), or HomePod.
- Voice control for your HCA devices, via Siri.
- Remotely control your HCA devices from just about anywhere.
  - Requires an iPad (4th generation or later) or Apple TV (3rd generation or later).
- Integration with other (non-HCA) HomeKit-enabled accessories via HomeKit scenes, groups, and automations.

> **Note:** This plugin does not use HCA Cloud and does not require an HCA Cloud account.

## Supported HCA Items

The `homebridge-hca` plugin supports a variety of HCA items. To enable HomeKit support for a specific HCA device, program or group, simply specify a "friendly name" for that item in HCA. Friendly names can be seen on the **Name** tab of the properties of a device, program, or group. You can also see all your items at one time and assign friendly names by pressing the **External Assistants Configuration** button in the **HCA Cloud** ribbon category.

The following HCA item types are currently supported:

- Fans
- Lightbulbs
- Outlets (Modules)
- Sensors
  - Motion Sensors
  - Leak Sensors (2852-222)
- Switches
- HCA Programs
- HCA Groups

> **Note:** HomeKit has a limit of 100 accessories per bridge/platform.

## Prerequisites

- [Homebridge](https://www.npmjs.com/package/homebridge) (version 1.8.0 or later)
- [Node](https://nodejs.org) (version 18.20.4 or later)
- [HCA Plus](http://www.hcatech.com) (version 14.1 or later)

## Step 1: Installing the HCA Plugin for Homebridge

To install the `homebridge-hca` plugin, perform the following steps:

> **Note:** If installing on Windows, reference [Install HomeBridge on Windows 10](https://github.com/nfarina/homebridge/wiki/Install-HomeBridge-on-Windows-10-(new)) for a detailed guide.

1. Install Homebridge:

    ```bash
    sudo npm install -g homebridge --unsafe-perm
    ```

1. Install the HCA Plugin for Homebridge:

    ```bash
    sudo npm install -g homebridge-hca
    ```

1. Update the Homebridge `config.json` file to add a platform for `homebridge-hca`:

    ```json
    "platforms": [
        {
            "platform": "HCA",
            "name": "HCA",
            "clientName": "Homebridge",
            "host": "",
            "port": 2000,
            "password": ""
        }
    ]
    ```

    The following properties may be modified as needed:

    | Property    | Default     | Description
    |-------------|-------------|-----------------------------------------------------------
    | clientName  | Homebridge  | Client name to use when connecting to HCA Server
    | host        | localhost   | IP address or hostname of the HCA Server
    | port        | 2000        | HCA Client-Server communication port
    | password    | (blank)     | HCA Remote Access password

1. Start Homebridge:

    ```bash
    homebridge
    ```

    When Homebridge starts, the `homebridge-hca` plugin will discover supported devices you've made available (via "friendly names") in HCA.

## Step 2: Adding the Homebridge Accessory to iOS

This step works with your Apple device so have it ready and make sure that Homebridge is running and nearby.

1. Open the **Home app** on your iPhone, iPad, or iPod Touch and tap **Add Accessory**, or tap the plus (**+**) button in the upper-right.
1. With the camera on your iOS device, scan the eight-digit HomeKit code (or QR code) in the Homebridge console window.
    - If the scanned code isn't recognized, tap "Don't Have a Code or Can't Scan?" to enter it manually. The default code is `031-45-154` (but this can be changed in the `config.json` file). When the Homebridge accessory appears, tap it.
    - Depending on the number of devices discovered, you may need to scroll up to see the code.
1. If asked to confirm adding an "Uncertified Accessory", tap **Add Anyway**.
1. Add information about your accessory and each device (as needed) and tap **Next**.
1. Then tap **Done**.

## Step 3: Restarting Apple TVs (HomeKit Hubs)

If there are any Apple TVs (3rd generation or later) on your local network when you pair Homebridge with iOS, they will automatically be set up as HomeKit Hubs. This will allow you to interact with your devices via a HomeKit-enabled app, and Siri, when not at home.

After pairing iOS with Homebridge be sure to **restart all Apple TVs** to ensure that everything is synced up completely and remote access is available.

## Updating the HCA Plugin for Homebridge

To update the `homebridge-hca` plugin, perform the following steps:

1. If running, stop Homebridge (`CTRL+C`).
1. Update the `homebridge-hca` plugin:

    ```bash
    sudo npm update -g homebridge-hca
    ```

1. Restart Homebridge:

    ```bash
    homebridge
    ```

> **Tip**: To get the version of the plugin that's currently installed, run the following command:

```bash
npm list -g homebridge-hca
```

## Uninstalling the HCA Plugin for Homebridge

To uninstall the `homebridge-hca` plugin, perform the following steps:

1. If running, stop Homebridge (`CTRL+C`).
1. Uninstall the `homebridge-hca` plugin:

    ```bash
    sudo npm uninstall -g homebridge-hca
    ```

## Troubleshooting Common Issues

### My iOS App Can't Find Homebridge

There are a few reasons why Homebridge may not be discoverable:

1. Your iOS device may not be on the same network as the computer hosting Homebridge.

    **Resolution:** Ensure that Homebridge is running and your iOS device is connected to the same local network as the Homebridge server.

1. Homebridge server thinks it's been paired with, but iOS thinks otherwise.

    **Resolution:** Delete the `persist/` folder which is next to your `config.json` file.

1. iOS device has gotten your Homebridge username (looks like a MAC address) "stuck" somehow, where it's in the database but inactive.

    **Resolution:** Change your username in the "bridge" section of `config.json` to be some new value.

### My iOS App Shows Devices in an "Updating…" State

1. Ensure you have Wi-Fi or cellular connectivity.
1. Restart the computer hosting Homebridge as well as all Apple TVs (3rd generation or later) on your local network.