TTLock + Home Assistant Integration Guide

Smart Lukko is an independent third-party app for TTLock-compatible smart locks and is not affiliated with TTLock or Sciener or with any Home Assistant community project mentioned here. Because this space moves quickly and third-party projects vary in maintenance status, treat specific integration names and version numbers as something to verify yourself in the Home Assistant Community Store or forums before relying on them.

• Community cloud-API integrations. Custom components that authenticate against the vendor's cloud API using your developer/account credentials and expose locks as Home Assistant entities. These generally need a gateway bound to the lock for remote state and commands to work.
• MQTT bridges. A separate script or service polls or listens for lock events and republishes them to an MQTT broker, which Home Assistant's MQTT integration then picks up. This decouples Home Assistant from the vendor API directly and can be easier to maintain long-term.
• BLE proxy approaches. Home Assistant's Bluetooth proxy infrastructure (via ESPHome-based proxies) can extend Bluetooth range to devices near the lock, which may help a local BLE-based integration reach it, but proxying does not by itself grant an integration the ability to control the lock — it still needs a compatible client that speaks the lock's BLE protocol.

1. Decide whether you need remote control or local-only. If home automations only need to react to unlock events while you're home, a local/BLE approach may be enough. If you want to unlock or check status while away, you need a gateway and a cloud-API-based path.
2. Set up and bind a gateway first if remote access matters. No cloud-API integration can perform remote operations without one, regardless of how well the Home Assistant side is configured.
3. Obtain API credentials if the integration requires them. Some community integrations ask for the same account credentials used in a TTLock-compatible app; others require registering as a developer. Follow that specific project's instructions rather than assuming one model.
4. Install the integration via HACS or manually, following its own README, since installation steps and required Home Assistant version vary by project and change over time.
5. Verify entities and test a benign action first, such as reading lock state, before wiring the lock into automations that could leave a door unlocked unexpectedly.

• Polling delays. Cloud-API-based integrations often poll rather than receive instant pushes, so state in Home Assistant can lag a few seconds to a couple of minutes behind reality.
• Gateway single point of failure. If the gateway loses power or Wi-Fi, remote control and fresh state updates stop, even though the lock itself still works locally with a passcode, card or fingerprint.
• Community maintenance risk. Unofficial integrations can lag behind vendor API changes or stop being maintained; check the project's recent activity before depending on it for security-relevant automations.
• Credential handling. Storing account or API credentials inside Home Assistant config means protecting your Home Assistant instance itself becomes part of protecting the lock; use its secrets handling rather than plain-text config where possible.

• Entity shows unavailable. Usually a lost connection between the integration and the cloud API or gateway; check the gateway's power, Wi-Fi and binding status first.
• Lock state never updates. Confirm whether the integration polls on an interval and, if so, whether that interval is configurable; some report state accurately but only on a slow schedule.
• Commands succeed in the log but the door doesn't move. This pattern is consistent with the gateway relaying the command to the cloud but failing to reach the lock over Bluetooth — check gateway-to-lock range and battery level on the lock.
• Authentication failures after working previously. Vendor API changes or expired credentials are common causes; check the integration's issue tracker for recent reports before assuming a local misconfiguration.