HCA Plugin for Homebridge

Introduction

The HCA Plugin for Homebridge exposes Home Control Assistant (HCA) devices, programs, and groups to Apple's HomeKit 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 (version 1.8.0 or later)
• Node (version 18.20.4 or later)
• HCA Plus (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 for a detailed guide.

1. Install Homebridge:

   sudo npm install -g homebridge --unsafe-perm

2. Install the HCA Plugin for Homebridge:

   sudo npm install -g homebridge-hca

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

   "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

4. Start Homebridge:

   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.
2. 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.
3. If asked to confirm adding an "Uncertified Accessory", tap Add Anyway.
4. Add information about your accessory and each device (as needed) and tap Next.
5. 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).

2. Update the homebridge-hca plugin:

   sudo npm update -g homebridge-hca

3. Restart Homebridge:

   homebridge

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

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).

2. Uninstall the homebridge-hca plugin:

   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.

2. 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.

3. 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.
2. Restart the computer hosting Homebridge as well as all Apple TVs (3rd generation or later) on your local network.