Doors

Manage TTLock smart locks, configure access pricing, and generate QR codes for guest payments.

Overview

Doors in Hygate are TTLock smart locks that have been synchronized and configured for paid access. Each door has its own pricing, duration, and operational status.

Door Concepts

Sync vs. Add

Sync from TTLock — Retrieves the current list of locks from your TTLock account. Locks already added to Hygate appear disabled to prevent duplicates.

Add to Hygate — Registers a TTLock lock in the Hygate database with custom pricing and settings.

A lock must be synced and added before it can accept payments.

Door Status Modes

Every door has one of three operational modes:

Mode	Payment Flow	Lock Behavior	Guest Experience
Active	Enabled — guests can purchase	Normal lock control	Standard payment page
Passage Mode	Disabled — no payment required	Unlocked on schedule	"Free Access" / "Open Access" indicator
Maintenance Mode	Disabled — payments blocked	No lock change	Branded maintenance message

Adding a Door

Step 1: Configure TTLock Integration

Before syncing, ensure TTLock is configured in Settings → TTLock.

Step 2: Sync Locks

Go to Doors
Click Sync from TTLock
Wait for the lock list to load (may take a few seconds)
Review the list — already-added doors are pre-selected and disabled

Step 3: Configure Each Door

For each door you want to add:

Setting	Required	Default	Description
TTLock Lock	Yes	—	The lock from your TTLock account
Location	Yes	—	Physical location assignment
Name	No	TTLock lock name	Display name (e.g., "Main Entrance")
Description	No	—	Internal notes
Access Price	No	Global default	Override the default price
Access Duration	No	Global default	Override the default duration (minutes)
Notes	No	—	Internal notes (not shown to guests)

Step 4: Save

Click Add Selected Doors to save all configured doors.

Door Status Management

Switching to Active Mode

Open the door detail page
Click the status dropdown
Select Active
The door immediately becomes available for payments

Enabling Passage Mode

Open the door detail page
Click the status dropdown
Select Passage Mode
Configure the schedule:
- Weekdays — Monday through Friday, or select specific days
- Time range — Start and end time (e.g., 09:00 to 18:00)
Save

Passage mode can be configured through the TTLock gateway API with schedule-based unlocking.

Enabling Maintenance Mode

Open the door detail page
Click the status dropdown
Select Maintenance Mode
Save

Maintenance mode takes effect immediately. Guests scanning the QR code see the maintenance message.

Tip: You can enable maintenance mode for a quick break without changing the door's normal status.

Editing a Door

From the Doors list, click any door to open its detail page.

Editable Fields

Field	Description
Name	Display name shown to admins and in audit logs
Description	Internal description
Location	Physical location assignment
Access Price	Override the global default
Access Duration	Override the global default in minutes
Notes	Internal notes

Refresh Sync

Click Refresh to pull the latest status from TTLock:

Current lock state (locked/unlocked)
Passage mode schedule
Battery level
Gateway connectivity

Delete a Door

Click Delete to remove the door from Hygate. This does not delete the lock from TTLock — it's only removed from the Hygate system.

Deleting a door does not affect completed payments or existing sessions.

QR Code PDF Generation

Generate a QR Code

Open the door detail page
Click Generate QR Code
Customize the PDF:
- Header text — Title (e.g., "Front Door Access")
- Subtitle — Description line
- Accent color — Hex code for the theme color (e.g., #0A84FF)
- Footer text — Contact info, instructions, or fine print
Click Download PDF

QR Code Contents

The generated PDF includes:

Your branded header with company name and logo (if configured)
The QR code pointing to the door's public payment page
The configured subtitle and footer text
A scannable URL for manual entry

Placement Best Practices

Recommendation	Why
300+ DPI print resolution	Ensures QR code scans reliably
Laminate outdoor codes	Protects against weather and wear
Eye level, 120–150cm height	Most comfortable scanning height
Minimum 2.5cm × 2.5cm print size	Ensures the QR code is readable
Avoid reflective surfaces	Prevents scan failures
Keep at least one empty margin around code	Prevents interference from the print medium

QR Code Lifecycle

Event	What Happens
Door added	QR code generated from TTLock
QR code displayed	Guest scans → payment page opens
Payment succeeded	Access code created → QR display page shown
Session expires	Access code expires, guest must re-purchase
QR code expires	TTLock codes are single-use per session
Manual refresh	New QR code generated via API

Door Synchronization

Background Sync

Hygate continuously syncs with TTLock in the background:

Lock state is updated every 5 minutes
Status changes (locked/unlocked) are recorded in audit logs
Passage mode state is tracked and reflected in the UI

Manual Refresh

Click Refresh on any door to pull the current state immediately. Useful after a lock is manually operated through the TTLock app.

What Sync Includes

Data	Description
Lock name	TTLock's lock name
Lock state	Current locked/unlocked status
Passage mode	Whether passage mode is active
Gateway type	Bluetooth or WiFi/Gateway
Firmware version	Lock firmware (for reference)
Battery level	If reported by the lock

Passage Mode Deep Dive

How It Works

Passage mode uses TTLock's built-in passage mode feature. When enabled:

You set a schedule (days of the week, time range)
TTLock automatically unlocks the lock at the start time
The lock stays unlocked during the passage window
TTLock re-locks at the end of the window

Schedule Configuration

Configure passage mode through TTLock's settings directly, or via Hygate if the API supports it.

Guest Experience in Passage Mode

When a guest scans the QR code during a passage window:

They see "Free Access" or "Open Access" on the payment page
No payment is required
The door remains unlocked

Security Considerations

Passage mode bypasses payment entirely. Consider:

Physical security — Is there staff present during passage hours?
Time boundaries — Does the schedule match your actual open hours?
Override capability — Can staff quickly disable passage mode if needed?
Audit trail — Hygate logs when passage mode is enabled/disabled

Maintenance Mode Deep Dive

What Changes

Element	Behavior in Maintenance Mode
Payment page	Shows maintenance message instead of payment form
QR code	Still scannable, but payment is blocked
Active sessions	Continue unaffected
Lock itself	No change — Hygate doesn't touch the lock
Admin UI	Door shows "Maintenance Mode" badge

Use Cases

Scenario	Maintenance Mode Use
Cleaning crew	Temporarily disable access while cleaning
Repair work	Block payments while a technician works
Event setup	Disable during setup, re-enable when ready
Unexpected closure	Quick response to a security concern
Seasonal downtime	Disable during off-season

Recovery

To return to normal operation:

Open the door detail page
Change status from Maintenance Mode to Active
Save — payments resume immediately

Troubleshooting

Door Not Syncing from TTLock

Check	Action
TTLock credentials	Verify in Settings → TTLock
TTLock API status	Check ttlock.com for service status
Network connectivity	Ensure Hygate can reach euapi.ttlock.com
Gateway required	Some locks need a TTLock gateway for cloud access

QR Code Won't Scan

Check	Action
Print quality	Increase resolution to 300+ DPI
Print size	Ensure minimum 2.5cm × 2.5cm
Surface type	Avoid glossy or reflective materials
Damage	Check for scratches, folds, or smudges
Regenerate	Try generating a fresh QR code PDF

Payment Not Working

Check	Action
Door status	Ensure door is set to Active
Stripe configured	Verify in Settings → Stripe
Webhook configured	Check Stripe Dashboard → Webhooks
Test mode	Confirm you're using Stripe test mode for testing

Door Shows Wrong Status

Click Refresh to pull the latest state from TTLock. If the issue persists, check the TTLock app directly.