Getting Started
Home Kat Bridge is a software bridge that makes supported devices available to Apple HomeKit. The app must remain running on a device in your home and connected to the same local network as the equipment it controls.
Choose where to run the bridge
Home Kat Bridge will run on any Mac running macOS 15 (Sequoia) or higher either natively or using OCLP. Alternatively, you can dedicate an old iOS device capable of running iOS 18 or higher, including iPhone 11 and iPhone XR, and leave it plugged in at home on the local network.
- A Mac can run the app in the background, but it must remain switched on, logged in and awake. You have the app hide itself so it doesn;t bother your day to day work. It is also possible to run it under a second user account and switch to your main account, as long as that second account is set up with the same iCloud credentials.
- To use an iPhone or iPad it must be dedicated to Home Kat Bridge, plugged into power, connected to Wi-Fi and left with the app locked frontmost by using Guided Access while the bridge is running.
Home Kat Bridge synchronises its settings through iCloud, so make sure that use the same iCloud account on any devices from which you want to view the Home Kat Bridge configuration. If another active Home Kat Bridge is detected running on the local network, the second app will display its status and Event Log as a remote monitor.
First launch and permissions
When first run, the OS will request permission to
- allow Home Kat Bridge to access the Local Network. Device discovery and control cannot work without this permission.
- Allow access to HomeKit data when requested. Home Kat Bridge uses it to select the correct home, configure accessories that refer to existing HomeKit devices, inspect its rooms and actions, and preserve room, scene and automation assignments.
If you have more than one home, open Settings > HomeKit and select the home that contains the Home Kat Bridge accessory. See HomeKit Settings and Assignment Recovery.
Set up devices and activate categories
Set up physical devices in their manufacturer's app and connect them to the local network before trying to add them in Home Kat Bridge.
Configure your devices in settings. Open Settings > General to see the available categories and Activate Device Categories to choose a plan or the lifetime purchase. One- and two-category subscriptions require you to choose which categories are activated; All Categories and the Golden Ticket activate them all. A category may still be enabled for discovery and setup when it is not activated, but its accessories are not added to HomeKit. See Plans, Purchases and Activated Categories.
Each category has its own Settings page to discover devices and configure, add or remove the accessories exposed to HomeKit:
- Buttons & Sensors
- TP-Link Devices
- Logitech Harmony Hub Devices
- Tuya Outlets & IR Blasters
- Dyson Fans & Purifiers
Start the Home Kat Bridge server
Once the devices have been properly configured, and a category activated, the Home Kat Bridge server can be started. On a Mac, press the large power button on the Home page. Leave the Mac awake and keep Home Kat Bridge running. In Settings > General, Hide app in background can hide the window and Dock icon when you switch away from the app; use the cat menu-bar icon to show the app again. Press the power button to stop the bridge.
On an iPhone or iPad, first configure Guided Access as described in iOS Tips. Return to Home Kat Bridge and start Guided Access with the accessibility shortcut (three clicks on the power button or optionally two or three taps on the back of the phone). The bridge and device discovery start automatically after Guided Access begins. Repeat the shortcut to end the Guided Access session and stop the bridge.
The Home Kat Bridge page shows the bridge state and its running time. Red or grey indicates that the local server has stopped; green indicates that it is running and paired. The Event Log records startup, network and device activity.
Add Home Kat Bridge to HomeKit
When the server is running but not paired, the Home page displays a QR code and an eight-digit HomeKit setup code.
- On your main iPhone, open Apple's Home app.
- Select +, then Add Accessory.
- Scan the QR code displayed by Home Kat Bridge, or select the option to enter the setup code manually.
- HomeKit warns that this is an uncertified accessory, select Add Anyway and complete the setup.
- The Home app will then ask which Room you want to place the bridge. To avoid clutter, you can create a room just for the bridge, such as HomeKat. Any devices added to Home without a preset room will end up in that room by default. You can then change the room of an accessory in the Home app.
Home Kat Bridge is a software bridge rather than certified HomeKit hardware, which is why the warning appears.
After pairing, Home Kat Bridge automatically shares the accessories you have set up. Logitech Harmony televisions are an exception: each Harmony Hub displays its own QR code and must be paired separately.
If you use Unpair from HomeKit, the main bridge and all configured Harmony televisions are removed from HomeKit. If the Mac or iPhone running Home Kat Bridge sleeps or shuts down, the accessories remain in HomeKit but are marked Unavailable until the app resumes.
Finish in the Home app
In Apple's Home app, you may give each new accessory a distinct name and assign it to the correct room. This improves Siri requests and makes scenes and automations easier to understand. Use the manufacturer's app for initial setup or model-specific features that HomeKit does not expose. Changes to a device name in the manufacturer's app are automatically propogate to HomeKit.
If you later need to unpair and pair Home Kat Bridge again, the app retains preferred rooms and supported scene or automation actions. Restoration begins only after the bridge has been added back and its accessories have reappeared. See HomeKit Settings and Assignment Recovery for the manual restore command and the limits on recreating automations.
Finally, test each accessory from both the Home Kat Bridge tile view and the Home app. If a device is missing or unreachable, see the troubleshooting guide.
Remote Access
Run Home Kat Bridge on a second device on the same network, logged in to the same iCloud account, to connect to the main bridge in remote-monitoring mode. You can view status, the Event Log and charts, manage purchases, and restart or shut down the remote server. Changing the activated categories for a one- or two-category plan also requires the server to be stopped. Home Kat Bridge remote monitoring does not connect from outside the home network.
History charts and widgets
Home Kat Bridge retains up to 72 hours of network availability, bridge battery level, process memory and heap use while it runs. Each Smart AC in the Buttons & Sensors category records its room temperature, optional outside temperature, and the times when it is cooling, heating or off. These histories appear as charts in the app. Thread telemetry is a development-build diagnostic and is not recorded by release builds.
Charts initially show today. Swipe right over a compact or expanded chart to show yesterday and swipe left to return to today. Select a chart to expand it; the expanded view can also focus on the most recent four hours.
You can also add Home Screen widgets from the system widget gallery:
- Network and Battery History shows battery level and periods without network availability for a selected Home Kat Bridge instance.
- Memory & Heap History charts process memory and live heap use for a selected Home Kat Bridge instance.
- Smart Thermostat History charts room temperature, optional outside temperature, and heating or cooling deployment for a selected Smart AC.
Widgets are available in medium and large sizes. Configure each widget with the Home Kat Bridge instance or Smart AC it should show, and choose Today or Today + Yesterday as its chart period. A new widget may initially say that it is waiting for history; leave Home Kat Bridge running long enough to collect data.