hass-ttlock

Home Assistant integration for TTLock based locks.

Overview

This integration uses the TTLock Cloud to communicate with your lock. It supports the following features:

• Locking and unlocking
• Discovery of locks on startup
• Real-time updates via a webhook (no periodic polling which wastes battery)
• Additional sensors for battery, last operator + reason
• Add new pass codes
• Delete expired pass codes
• List passcodes
• List records history (lock, unlock etc)

Known working locks

If this integration is working for you, please leave a comment here

• Catchface Smart Lock
• Cielsa Dawn Fingerprint Digital Doorknob
• E-Lok 9 series
• Raykube locks
• Simpled locks
• TOTOWISER locks
• YRHAND locks

Usage

Requirements

1. A TTLock based smart lock
2. A Gateway (if your lock doesn't have integrated wifi)
   • These can be purchased from the vendor of your lock or direct from Aliexpress
3. Remote unlock must be enabled for each lock
   • This must be done while in bluetooth range of the lock, from the mobile app
   • Here is a youtube video which explains the process

Creating an OAuth APP

1. Go to https://open.ttlock.com/manager and create an account
2. Register an application (this will take a few days to get approved)
3. Install the extension via HACS and restart Home Assistant
4. Setup the integration via Home Assistant UI
   • The first credentials you will be prompted for are the Application Client ID & Secret that you created earlier.
   • The second credentials you will be prompted for are the username/password you use to login to the ttlock app on your phone.
5. Once the integration is working you should see a repair notice under Settings > Repairs with the webhook url
   • Go back to https://open.ttlock.com/manager
   • Select your application, and edit the "callback url". Enter the webhook url from the repair notice
   • Test by unlocking your door
   • If the event data was received by home assistant the repair notice will resolve itself, indicating that everything is working.

Troubleshooting

Common issues

1. Invalid client_id
   • Your Application (ie oauth) Client ID & Client Secret for the application you created on open.ttlock.com.
   • These are stored in the "Application Credentials" feature of Home Assistant. If you need to remove/update them, please follow the official docs
   • If you get this error, you need to remove the invalid credentials and re-setup the integration with the correct ones.
2. Invalid username or password
   • The username/password for open.ttlock.com is only used for managing API credentials for the ttlock cloud - do not use these within home assistant.
   • The username/password for the ttlock (or 3rd party branded) mobile app. This is the account that will work.
3. "Failed to execute the action lock/lock." or "The function is not supported for this lock"
   • This is most likely because you haven't enabled remote unlock, please follow the instructions in the requirements section.
4. Entities are unavailable and debug logs show hasGateway: 0
   • TTLock cloud can occasionally lose the gateway association for a lock.
   • First, reboot your TTLock gateway/hub (for example, G2) and re-check the integration.
   • If that does not fix it, remove and re-add the lock in the TTLock app.

Reporting issues

When reporting issues, please attach the diagnostic information and consider enabling debug logging to provide extra information.

Development

You can find all the TTLock API calls here https://euopen.ttlock.com/document

Say thanks

If you found this helpful and you'd like to say thanks you can do so via buy me a coffee or a beer. I've put a bunch of time into this integration and it always puts a smile on my face when people say thanks!