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 0.4.28 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.
-
Install Homebridge:
sudo npm install -g homebridge --unsafe-perm
-
Install the HCA Plugin for Homebridge:
sudo npm install -g homebridge-hca
-
Update the Homebridge
config.json
file to add a platform forhomebridge-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 -
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.
- Open the Home app on your iPhone, iPad, or iPod Touch and tap Add Accessory, or tap the plus (+) button in the upper-right.
- 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 theconfig.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.
- 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
- If asked to confirm adding an "Uncertified Accessory", tap Add Anyway.
- Add information about your accessory and each device (as needed) and tap Next.
- 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:
-
If running, stop Homebridge (
CTRL+C
). -
Update the
homebridge-hca
plugin:sudo npm update -g homebridge-hca
-
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:
-
If running, stop Homebridge (
CTRL+C
). -
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:
-
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.
-
Homebridge server thinks it's been paired with, but iOS thinks otherwise.
Resolution: Delete the
persist/
folder which is next to yourconfig.json
file. -
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
- Ensure you have Wi-Fi or cellular connectivity.
- Restart the computer hosting Homebridge as well as all Apple TVs (3rd generation or later) on your local network.