TTLock Integration
Connect your TTLock smart locks to Hygate for QR-code-based paid access.
Overview
TTLock is a smart lock platform that supports Bluetooth, WiFi gateway, and keypad locks. Hygate integrates with TTLock to synchronize your locks, generate QR access codes, and control passage mode.
What You Need
Before setting up TTLock in Hygate, you need:
- A TTLock account with admin access to your locks
- A TTLock Developer account (for API credentials)
- Locks must be registered to your TTLock account
Getting TTLock API Credentials
Step 1: Create a Developer Account
- Go to ttlock.com and log in
- Navigate to the Developer Portal (usually under Account → Developer)
- Create a new application if you don't have one
- Note your Client ID and Client Secret
Step 2: Get Your Account Credentials
The username and password are your TTLock account credentials (the same ones you use in the TTLock app).
Password handling: Your TTLock password is MD5-hashed before being sent to the OAuth2 server. It is never stored in plain text.
Step 3: Enter Credentials in Hygate
- Go to Settings → TTLock
- Enter:
- Client ID — From your TTLock developer application
- Client Secret — From your TTLock developer application
- Username — Your TTLock account email
- Password — Your TTLock account password
- Click Test Connection
- If successful, click Save
How the Integration Works
Synchronization
When you click Sync from TTLock, Hygate calls the TTLock API to retrieve your lock list:
Hygate → TTLock API: listLocks()
│
▼
Returns: lockId, lockName, lockAlias, gatewayType, firmwareVersion
│
▼
Locks matched against Hygate database
Already-added locks shown as disabled
Lock Status Tracking
Hygate tracks these states from TTLock:
| Data | Description |
|---|---|
| Lock name | Name/alias from TTLock |
| Lock state | Locked / Unlocked / Unknown |
| Passage mode | Whether passage mode is configured |
| Gateway type | Bluetooth or WiFi/Gateway |
| Battery level | If reported by the lock |
| Firmware version | Lock firmware |
QR Code Generation
When a guest pays for door access, Hygate calls:
Hygate → TTLock API: addQrcode()
│
▼
Returns: qrCodeContent (unique token string)
│
▼
QR code generated and displayed to guest
QR codes are single-use per session. Each payment generates a new access code.
Passage Mode
TTLock's passage mode is configured per-lock in TTLock's own settings. Hygate can query and display passage mode status, but schedule changes should be made in the TTLock app or through the TTLock gateway API if supported.
Features Available Through TTLock
| Feature | Supported | Description |
|---|---|---|
| Sync lock list | Yes | Retrieve all locks from TTLock |
| Add doors | Yes | Register locks in Hygate |
| Door status tracking | Yes | Locked/unlocked state monitoring |
| Passage mode | Yes | Display current passage mode status |
| QR code generation | Yes | Generate access codes for paid guests |
| Remote lock/unlock | Via TTLock | Control locks directly from TTLock app |
| Gateway support | Yes | Works with WiFi gateway locks |
What Happens When TTLock Is Disabled
If you disable TTLock in Settings → General:
| Effect | Description |
|---|---|
| Doors page hidden | Operators cannot access the Doors module |
| QR payment flow disabled | Guests cannot purchase door access |
| Existing sessions continue | Active sessions are not affected |
| Door status preserved | Door configurations remain in the database |
Troubleshooting
"Connection test failed"
| Check | Action |
|---|---|
| Credentials | Verify Client ID, Client Secret, username, and password |
| TTLock service | Check ttlock.com for downtime |
| Network | Ensure Hygate can reach euapi.ttlock.com |
| Lock ownership | Ensure locks are registered to your account |
Locks Not Appearing
| Check | Action |
|---|---|
| TTLock account | Verify you own the locks in TTLock |
| Developer account | Ensure your app is approved and has API access |
| Network | Check connectivity to TTLock servers |
| Retry sync | Click Sync from TTLock again |
QR Code Not Generating
| Check | Action |
|---|---|
| Lock online | Ensure the lock is connected to TTLock |
| Gateway required | Some locks need a TTLock gateway for cloud QR generation |
| API quota | Check TTLock developer portal for rate limits |
| Lock state | Ensure lock is not in an error state |
Passage Mode Not Working
Passage mode schedule changes should be configured directly in the TTLock app or through the TTLock gateway settings. Hygate displays the current passage mode status but does not currently modify the schedule.
Credential Expiration
TTLock OAuth tokens are automatically refreshed by Hygate when they expire. No manual action is needed.
Security Notes
- TTLock credentials are encrypted at rest in the Hygate database
- The password is MD5-hashed before transmission to TTLock's OAuth server
- OAuth tokens are stored and refreshed automatically
- Rotate credentials if your TTLock account is compromised
- Do not share TTLock credentials with operators — only admins should have access