Code Monkey home page Code Monkey logo

homebridge-ttlock's Introduction

Homebridge TTLock Plugin

A Homebridge TTLock plugin that allows you to access your TTLock Device(s) from HomeKit with Homebridge.

verified-by-homebridge github checks github release npm version npm downloads

Requirements

  1. Lock/door handle using TTLock Platform (Wifi, or Bluetooth + Gateway)
  2. If using Bluetooth - TTLock Compatible Gateway (G1, G2, G3, or G4). Successfully tested with this one
  3. TTLock app for iOS or Android
  4. Bash access to run curl command


Setup Instructions

Create TTLock Developer Account

  1. Go to TTLock Platform Registration.
  2. Complete the required information to create a developer account for API access.
  3. Wait for the email confirming activation of your account (manual process that will be completed by TTLock).
  4. Log back into the TTLock Developer Platform and retreive your ClientId and ClientSecret.



Create a New User on Developer Account

  1. Make up a new username. Creating a new user account is required! It must be associated with your developer account (unfortunately you can't use an account you've already set up on the TTLock app).
  2. Come up with a password and save it somewhere. When you submit the request to create the new user, you'll have to submit the password as md5 (use this site).
  3. Using a terminal, run this command to create the new user on your developer account:
curl --location --request POST 'https://euapi.ttlock.com/v3/user/register?clientId=[clientid]&clientSecret=[clientsecret]&username=[username]&password=[passwordasmd5]&date=CURRENTMILLIS' \
--header 'Content-Type: application/x-www-form-urlencoded' \
  1. In the response to the request, note the username that is assigned (it will be your username prefixed with some random characters). This will be the username you'll use to log into the mobile app and the Homebridge plugin from now on.



Associate Lock and Gateway with New Account

  1. Log into the TTLock iOS or Android app with your new account. You'll use the username that the API call returned, and the password you created (NOT as md5).
  2. Add your lock(s) to the app to accociate them with your account. If you have previously used the lock with the app, you'll have to reset and add it to the new account.
  3. If using Bluetooth, add the gateway (and ensure it is associated with the locks).
  4. Important -In the settings for each lock, ensure the Remote Unlock setting is set to On.



Plugin Installation

Recommended: install via the Homebridge UI

Or install the plugin with the following command:

npm install -g homebridge-ttlock



Configuration

        {
            "platform": "ttlock"
            "name": "TTLock Platform",
            "clientid": "clientid",
            "clientsecret": "clientsecret",
            "username": "username",
            "password": "passwordasmd5",
            "batteryLowLevel": 15,
            "maximumApiRetry": 5;
        }

name: Platform display name

clientid: Your ClientId from the TTLock developer platform.

clientsecret: Your ClientSecret from the TTLock developer platform.

username: Username for the user account accociated with the developer account.

password: Password for the user account as md5.

batteryLowLevel: The battery level percentage at which a low battery warning will be displayed in the HomeKit status.

maximumApiRetry: Maximum times to retry hitting the API.



Usage

  • On Homebridge load, plugin will get all locks from TTLock account and add them to Homebridge (if they are not already cached)
  • Use Homekit to lock and unlock your locks!
  • Homekit will show warning when lock has low battery (customize in plugin configuration)



Planned Backlog

  • Better handle condition when gateway is busy
  • Expose each lock to config and allow more customization

homebridge-ttlock's People

Contributors

bwitting avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

homebridge-ttlock's Issues

not working at all

I followed all the steps and doesnt want to work.. it keeps saying: "Ensure your TTLock API keys and username/password are correct in the config. Error: 10003"

Anyone having issues using the created user in the TTLock mobile app?

  1. Created dev account
  2. Created user account using API
  3. Got resulting username
  4. Load up TTLock app on IOS
  5. put in the username from step 3
  6. put in password as provided via md5 in step 2
  7. app complains invalid user/pass

troubleshooting...

  1. but everything works in homekit
  2. Toying with the TTLock API directly, can pull lock list, gateway list, all good
  3. Used API to reset the password to something smaller/simpler thinking maybe the app had issues with length or some characters, but no go
  4. tried to use the md5 pass for just as a sanity check, no go
  5. tried the original username before the API prepended it with some characters, but no go

SIDE NOTE
I would suggest better instructions for when a person has already setup an account with their locks. There's a Transfer option in the app allowing you to send your locks/gateways to the new account username. Worked for me. API Docs: https://euopen.ttlock.com/doc/api/v3/lock/transfer

TTlock current state

Hi - this plugin works great on homebridge but have one issue I can't seem to resolve. I have an automation set with the lock to unlock (from a trigger) if the trigger is set to on. It works great, but with most it would check to see if its unlocked first and then run to unlock. This plugin seems to just trigger regardless, so if the locks current state is unlock, then the automation locks the door not knowing the door is unlocked.

I tried in shortcuts (not homekit automation) to put an if statement to check the current state first before running the automation and that doesn't seem to work (same behavior as before, whatever the current state, it runs and flips it the other way). Any thoughts on whether the current state is getting passed to homebridge/homekit? and what the actual values are ? Maybe I could try that instead..sometimes I get an error in homebridge that it can't get the current state as well. I have this all running in a child bridge so performance to lock and unlock is great. Just need to sort out current state!

Can't create new user account

I have tried to do this several times but it won't give me a user name instead I get --header 'Content-Type: application/x-www-form-urlencoded' :

Logs:

Show the Homebridge logs here, remove any sensitive information.

Plugin Config:

Show your Homebridge config.json here, remove any sensitive information.

Screenshots:

Environment:

  • Plugin Version:
  • Homebridge Version:
  • Node.js Version:
  • NPM Version:
  • Operating System:

Dumb Question 2

so excited for this, been trying to figure out a solution to get a padlock in HK. Ive create the dev account and it is approved, so I am able to get the ID and Secrete. Sorry, but dumber question......I'm on,.....Create a New User on Developer Account. Where do I create this new user account? On the developer website? I cant seem to figure out where. I used a one email when I first set up the lock with the app then a different email account when I did the dev part. Sorry feel like a dumb ass but totally stocked on getting this in.

Plugin slows down Homebridge

Describe The Bug:
Logs report slowing down HB:

To Reproduce:
Simply enable ttlock plugin

Expected behavior:
No errors, I assume?
Logs:

[8/23/2022, 7:49:45 AM] [homebridge-ttlock] This plugin slows down Homebridge. The read handler for the characteristic 'Lock Current State' didn't respond at all!. Please check that you properly call the callback! See https://homebridge.io/w/JtMGR for more info.
[8/23/2022, 8:06:27 AM] [homebridge-ttlock] This plugin slows down Homebridge. The read handler for the characteristic 'Lock Current State' was slow to respond! See https://homebridge.io/w/JtMGR for more info.
[8/23/2022, 8:06:27 AM] [homebridge-ttlock] This plugin slows down Homebridge. The read handler for the characteristic 'Lock Target State' was slow to respond! See https://homebridge.io/w/JtMGR for more info.
[8/23/2022, 9:01:56 AM] [homebridge-ttlock] This plugin slows down Homebridge. The read handler for the characteristic 'Lock Current State' was slow to respond! See https://homebridge.io/w/JtMGR for more info.
[8/23/2022, 9:01:56 AM] [homebridge-ttlock] This plugin slows down Homebridge. The read handler for the characteristic 'Lock Target State' was slow to respond! See https://homebridge.io/w/JtMGR for more info.
[8/23/2022, 9:02:02 AM] [homebridge-ttlock] This plugin slows down Homebridge. The read handler for the characteristic 'Lock Current State' didn't respond at all!. Please check that you properly call the callback! See https://homebridge.io/w/JtMGR for more info.
[8/23/2022, 9:02:02 AM] [homebridge-ttlock] This plugin slows down Homebridge. The read handler for the characteristic 'Lock Target State' didn't respond at all!. Please check that you properly call the callback! See https://homebridge.io/w/JtMGR for more info.

Plugin Config:

        {
            "name": "TTLock",
            "clientid": "xxx",
            "clientsecret": "xxx",
            "username": "xxx",
            "password": "xxx",
            "batteryLowLevel": 15,
            "maximumApiRetry": 5,
            "platform": "ttlock"
        }

Screenshots:
N/A
Environment:

  • Plugin Version:
  • Homebridge Version:
  • Node.js Version:
  • NPM Version:
  • Operating System:

Locks not showing up in Homebridge

I followed through the documentation, made a new account with the Dev account, i can login through the TTLock app with the new username and see my locks, but i cannot see the locks through homebridge, I'v gone over everything and triple checked, but cant get it to work.

Logs:

[2/3/2023, 2:04:16 AM] [HB Supervisor] Restarting Homebridge...
[2/3/2023, 2:04:16 AM] [HB Supervisor] Starting Homebridge with extra flags: -I
[2/3/2023, 2:04:16 AM] [HB Supervisor] Started Homebridge v1.6.0 with PID: 66644
[2/3/2023, 2:04:17 AM] Loaded config.json with 0 accessories and 3 platforms.
[2/3/2023, 2:04:18 AM] Loaded 3 cached accessories from cachedAccessories.
[2/3/2023, 2:04:18 AM] ---
[2/3/2023, 2:04:20 AM] Loaded plugin: [email protected]
[2/3/2023, 2:04:20 AM] Registering platform 'homebridge-config-ui-x.config'
[2/3/2023, 2:04:20 AM] ---
[2/3/2023, 2:04:20 AM] The plugin "homebridge-govee" requires Node.js version of ^14.21.2 || ^16.19.0 || ^18.13.0 which does not satisfy the current Node.js version of v16.16.0. You may need to upgrade your installation of Node.js - see https://homebridge.io/w/JTKEF
[2/3/2023, 2:04:21 AM] Loaded plugin: [email protected]
[2/3/2023, 2:04:21 AM] Registering platform 'homebridge-govee.Govee'
[2/3/2023, 2:04:21 AM] ---
[2/3/2023, 2:04:21 AM] Loaded plugin: [email protected]
[2/3/2023, 2:04:21 AM] Registering platform 'homebridge-ttlock.ttlock'
[2/3/2023, 2:04:21 AM] ---
[2/3/2023, 2:04:21 AM] Loading 3 platforms...
[2/3/2023, 2:04:21 AM] [Govee] Initializing Govee platform...
[2/3/2023, 2:04:21 AM] [Govee] Initialising plugin v7.9.1 | System darwin | Node v16.16.0 | HB v1.6.0 | HAPNodeJS v0.11.0...
[2/3/2023, 2:04:21 AM] [TTLock] Initializing ttlock platform...
[2/3/2023, 2:04:21 AM] [Govee] Plugin initialised. Setting up accessories....            
[2/3/2023, 2:04:21 AM] Homebridge v1.6.0 (HAP v0.11.0) (Homebridge D151) is running on port 51370.
[2/3/2023, 2:04:23 AM] [Govee] [LAN] client enabled and found 0 device(s).
[2/3/2023, 2:04:23 AM] [Govee] [HTTP] client enabled and found 3 device(s).
[2/3/2023, 2:04:26 AM] [Govee] ✓ Setup complete. Have time to give this plugin a review? https://bit.ly/hb-govee-review

Plugin Config:

{
    "name": "TTLock",
    "clientid": “xxx”,
    "clientsecret": “xxx”,
    "username": “xxx”,
    "password": “xxx”,
    "batteryLowLevel": 20,
    "maximumApiRetry": 5,
    "platform": "TTLock Platform"
}

Environment:

  • Plugin Version: v1.1.0
  • Homebridge Version: v1.6.0
  • Node.js Version: v16.16.0
  • NPM Version: 9.4.0
  • Operating System: macOS

Issue with unlocking

I Followed app the API Steps & was able to add the locks successfully & i can even see the status of "locked".
While i unlock on homekit app:
[06/05/2023, 14:03:10] [ttlock] unlocking of apartment failed. The gateway is currently busy.

The lock doesn't get unlocked. Can you please help?

Dumb Question

This might be a dumb question but I’m stuck on step 4.

Log back into the TTLock Developer Platform and retrieve your ClientId and ClientSecret.

ok. How?

Thanks in advance.

Thank you! :D

Hey,

Just wanted to say thanks!

Last week I was looking into setting this up just after receiving my prime day order and didn't find anything that seemed to cover all the bases. 12 hours later I looked again and found this. Worked like a charm!

Cheers!

import users from xls .

hi everyone .
I'm trying to add multiple users by xls format .
anyone has an idea or code how to add it ?
thanks .
Beny

Gateway busy

Howdy, thanks for creating this plugin - I got it setup (not without a bit of messing about with the username/password!), but am having issues with auto-lock.

[8/22/2022, 3:03:23 PM] [TTLock] Basement Door unlocked successfully.
[8/22/2022, 3:07:14 PM] [TTLock] locking of Basement Door failed. The gateway is currently busy.

In this setup, I unlocked via homekit, the lock auto-locked itself, but still reported status = unlocked in homekit. When I then tried to lock (via homekit), I got the message above (locking failed).

Both the error message & status are currently incorrect. Lock stays in "locking" mode indefinitely in HK.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.