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

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 receive a system notification with the webhook url
   • This will go away when the webhook receives data
6. Go back to the url from the first step and set the 'Callback URL' for your application

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.

Reporting issues

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

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!