A macOS Swift controller program for the Eqiva eQ-3 Bluetooth Smart Lock, paired with a Homebridge (HomeKit) plugin and Home Assistant integration. Unlike the notoriously unstable Linux BLE stack, this solution leverages the robust and reliable CoreBluetooth stack native to macOS (similar to iOS), providing a constant and stable connection to the lock.
This is a personal project I built to control my Eqiva eQ-3 Bluetooth Smart Lock reliably from macOS, and integrate it initially into my HomeKit setup via Homebridge then in Home Assistant via custom component (integration). I’m publishing it in case it’s helpful to anyone else with similar needs. Also, this README is for future me if I ever need to configure this thing again 😂
- macOS Swift menu bar app (runs as an icon in the top right of your screen) for controlling the lock with a super stable CoreBluetooth stack.
- Homebridge plugin to expose the lock to HomeKit.
- Home Assistant custom component (integration) to expose the lock to Home Assistant.
- WebSocket communication between the app and plugin ensures fast, local integration.
- GUI app is required due to macOS limitations on Bluetooth access for auto-launched background/CLI apps.
-
Manual override switches: Due to occasional firmware quirks where the lock can end up in an incorrect or unknown state (e.g., stuck or misreporting its status), the plugin includes additional HomeKit switches for Lock, Unlock, and Open. These act as emergency controls, allowing you to manually force a command regardless of what state HomeKit thinks the lock is in. This is particularly helpful when the lock jams or becomes unresponsive to standard commands.
💡 Tip: To avoid cluttering the lock accessory view, go into the lock's settings in the Home app, and enable Show as Separate Tiles to hide manual override switches from the default Home view.
Let me know if you'd like that tip styled differently or moved into its own section.
You need a userKey and userID from your lock. Use the keyble-registeruser command-line tool to obtain these.
Download the app from the Releases page. Run it, enter your credentials, and then restart the app.
Search for homebridge-eqiva-swift-bridge in the Homebridge UI and install it. It's published to NPM and can be installed like any other Homebridge plugin.
Copy the home_assistant_eqiva_swift_lock as custom_components/eqiva_swift_lock in your Home Assistant configuration directory. Add the following in configuration.yaml, then restart Home Assistant:
eqiva_swift_bridge:
serial: "REI1234567" # Optional
firmware: "1.7" # OptionalThe Eqiva eQ-3 lock has terrible BLE range. Make sure the Mac running this is physically close to the lock. I’ve got a Mac mini in the hallway about 2 meters from the lock and it works great.
Since macOS doesn’t allow Bluetooth access from CLI apps started via LaunchAgents or LaunchDaemons, this app needs to be launched as a GUI application. Enable the "Launch at Login" option to automatically start the app at login.
- Add emitting online/offline state (swift bridge bluetooth connectivity to the lock) to Home Assistant integration (as availability).
- Map locking/unlocking state triggered by the physical button to Home Assistant's states.
This was built to scratch my own itch, but if you have the same lock and a Mac nearby, this might be just the fix you’re looking for.
Go check out my other Homebridge plugins: