About
TTLock BLE is an integration that controls TTLock smart locks over Bluetooth from Home Assistant. Lock and unlock commands, state queries and battery readings run over the lock's Bluetooth link, and the TTLock cloud is contacted only once during setup to download the lock keys. Keypad presses, fingerprint reads, card swipes, mechanical key turns and auto-lock events arrive as Home Assistant events. It adds a lock, a Bluetooth connection sensor, battery, clock drift and last seen sensors, and a sound switch. Bolt position and battery level are read from the lock's advertisements without opening a connection, and an option can keep a permanent session open for faster commands at the cost of battery. Locks can be added by signing in to a TTLock account, with a code sent by email when required, or by entering a lock key manually without any account.
Automatic summary of the README and code of roquerodrigo/ha-ttlock-ble. Something wrong, or are you the maintainer and want your own text here? Get in touch
Supports
Works locally Talks to your devices on your own network. No vendor cloud in between.
Found by itself Home Assistant spots it on the network and offers to add it.
From the Marketplace Installed through the Marketplace, formerly HACS.
Actively maintained Its author released or pushed a change in the last six months.
Provides
- Locks
- Switches
- Sensors
Setting it up
Install it from the Marketplace and restart Home Assistant, then add it under Settings, Devices and services.
Enter a lock key manually
- Lock MAC address
- AES key
- Unlock key
- Admin passcode (optional)
- Name (optional)
- Protocol type
- Protocol version
- Scene
- Group ID
- Organisation ID
Also asked when changing the connection.
Set up TTLock BLE
- Password
Also asked when signing in again and changing the connection.
Verify your TTLock account
- Verification code
After setup
- Permanent connectionHold a BLE session open and reopen it the moment it drops. Off, the lock is connected to only to run a command or to read records it says it has; state and battery come from its advertisements, which cost no session at all. On, commands answer immediately, at the cost of the lock's battery.
Texts from the code of roquerodrigo/ha-ttlock-ble.
Entities
- Binary sensorsBluetooth connection
- EventsLog
- LocksLock
- SensorsBattery, Clock drift, Last seen
- SwitchesSound
Troubleshooting
- DiagnosticsDownloads a diagnostics file to attach to a bug report.
From the README
Local control of TTLock smart locks over Bluetooth, for Home Assistant. Lock / unlock, battery level and real-time push events flow over BLE — no cloud round-trip on every operation. Built on the sibling Python SDK ttlock-ble.
- Local BLE control — lock, unlock, and state queries run over the lock's BLE link; the TTLock cloud is only contacted once at setup to download per-lock keys.
- Real-time push events — keypad presses, fingerprint reads, IC-card swipes, mechanical key turns, and auto-lock fires arrive as Home Assistant events the moment the lock emits them.
- Battery sensor — diagnostic entity refreshed by every poll and every push, no extra BLE traffic.
- Clock alignment — the lock's own clock, which stamps every operation-log record, is compared against local time once a day on a session something else already opened, and corrected when it has…
- Bluetooth discovery — a lock in range of any radio Home Assistant manages shows up on its own as a discovered device; the address and the frame header come off the advertisement, so only the keys…
- 2FA-aware config flow — handles TTLock's "new device" verification by emailing a one-time code and prompting for it.
- Works without a cloud account — a lock initialised locally can be added by entering its key directly, no TTLock account involved at any point.
- Passive state tracking — the bolt position and battery level are read from the lock's own BLE advertisements, with no connection and no battery cost. This is what catches an auto-lock or an…
Shows in Vulpo
Quick Toggle card, Lock card, Chart card, Apple Watch, Control Center.Information
- Installs
- 133 sharing analytics
- GitHub stars
- 37
- Connection
- Works locally
- Upkeep
- Updated in the last 6 months
- Version
- v3.10.0,
- Category
- Security and safety, Locks and access
- Kind
- Marketplace integration
- Needs
- Needs the Marketplace (HACS on 2026.10 and older)
- Domain
ttlock_ble- Issues
- Report an issue
