Smart locks
Z BizKitHub Docs, znalostnej bázy platformy
Electronic locks are an increasingly common part of modern operations — from hotel receptions and co-working spaces to short-term rentals where physically handing over keys is not realistic. The /iot-lock module manages integration with the TTLock cloud and serves as a central dispatcher for all locks in an organization. It allows monitoring lock availability and battery status, issuing access passwords tied to reservations, remotely opening doors for visitors, and reviewing the history of all events recorded by the lock. This transforms the physical lock into a full-fledged operational tool connected to the rest of the system — reservations, contacts, notifications.
Lock Overview
The main table displays all active locks belonging to the current organization (deleted records are hidden). The row order is designed so that the administrator can see at a glance what needs attention — active and online locks are at the top, offline or unavailable ones at the bottom. For each lock, the following is displayed:
- Lock ID — a numerical identifier assigned by the TTLock service.
- Alias — a user-friendly name, typically descriptive ("Main Entrance", "Apartment 3").
- Connection status — online or offline depending on whether a Wi-Fi gateway is available.
- Availability (uptime) — percentage reliability of the gateway over the last 30 days.
- Battery charge — current status in percentage.
- Administrator — the assigned responsible person, if set.
- Hardware — lock model and firmware version, if this information is available.
The table automatically refreshes every 5 seconds and adapts to the device size. Main actions above the table — Add for adding a lock, Refresh for requesting a fresh status from the cloud, and Unlock for immediate opening — are available according to the status of the given row and user permissions.
Lock Lifecycle
Each lock goes through several phases that the system automatically monitors from initial pairing to continuous operation. The pairing itself takes place in two steps: first, the lock is physically connected to the TTLock mobile application on a phone (this is a manufacturer's specific step), then it is added in the administration using the Add button by entering its ID. After registration, the system automatically requests the current status from the cloud and populates hardware metadata — model, firmware, MAC address — to eliminate the need for manual entry. In the operational phase, the system regularly updates the status of each lock. With each refresh, it records the battery level (history is archived for trends), connection status to the gateway, and any changes in firmware or alias. If the gateway goes offline, the event is logged in the system log, and an email is sent to the assigned administrator.
For longer outages, the table row will display Offline since (start of the current outage) and Last online (last successful communication). After reconnection, the system automatically generates a new backup password and saves it with the lock record to ensure administrator access is always maintained even after an incident.
Lock Detail
Clicking on a row opens a detail view divided into four tabs, which thematically separate daily operations from historical records and configuration. The Active Passwords tab is the most frequently used operationally — it contains a list of valid access codes that can be used on the lock. For each password, its validity is shown (from – to, or labeled "Permanent"), an optional description ("Mr. Novak's reservation"), a link to a calendar event if the password was automatically generated for a reservation, and the current status. A new password is added via a modal form: you enter your own code or leave the field blank for the system to generate a random 8-digit code, then complete the optional name and validity range. Leaving the validity end empty creates a permanent password, typical for staff, for example. The Unlock History tab provides a chronological overview of all events recorded by the lock — unlocking by app, keypad, fingerprint, automatic locking. For each event, success, hardware-recorded time, cloud delivery time, and the password used (if available, which only applies to keypad events) are displayed. Event type texts are translated into the user's currently selected language. The Battery Charge tab displays a graph and table of historical battery level measurements. It primarily serves to estimate when the battery will need replacement and helps identify locks that discharge faster than others — typically due to a weaker signal to the gateway or aging hardware. The Settings tab then gathers lock parameters that can be adjusted: alias, active/inactive flag (inactive locks are not refreshed or monitored), deleted flag (hiding from the main overview), and administrator assignment. The administrator is always a contact from the same organization and receives notifications about critical events — gateway outage, critical battery, API error.
Remote Unlocking
The Unlock action sends an immediate command to open the door via the TTLock cloud. This is the most valued function of the module — an administrator can open the door for a visitor from the office without having to go there physically. However, the success of the operation depends on several conditions: the lock must be active (not deleted), it must have a connected Wi-Fi gateway, and the integration with TTLock must have valid login credentials.
Integration Security
Communication with the TTLock cloud relies on four values configured in the module: Client ID and Client Secret identify the application to the TTLock developer portal, while username and password identify the specific account to which the locks are assigned. For routine password changes in the TTLock mobile application, only the new password needs to be entered in the administration — other fields remain preserved, simplifying routine maintenance. At the authorization level, the same rules apply as in the rest of the system: a lock always belongs to a single organization, and every command (unlock, add or delete password) is verified against the current user's organization before being sent. Furthermore, each action stores the initiator's identity, so it is always traceable who opened the lock or to whom a code was issued. Error states (invalid data, API outage) are logged in the system log and can trigger a notification to the administrator.
Notifications
The assigned administrator receives email alerts in situations requiring human intervention: the gateway goes offline, the battery level drops below a critical threshold, communication with the TTLock cloud repeatedly fails, or an extraordinary change in lock status occurs (e.g., an automatic alias switch). The goal is to ensure that no problematic lock goes unnoticed, even if the administrator is not actively viewing the overview.
Súvisiace
- IoT overviewThe `/iot` page is the entry point into the world of connected devices in the administration. It is not a standalone operational tool — that would be…
- CalendarThe `/calendar` page is used for managing calendars and tracking availability in time slots. It allows you to create any number of calendars — for…
- Organization settingsThe `/settings` page is the central hub for all organization, access, and integration configuration. It brings together all operational parameters…
- envReference for BizKitHub environment variables — how the catalogue is organized into categories (payments, SMTP, shipping, IoT, customers, general),…
- Ticket classification modelEvery ticket in BizKitHub is described by three independent labels: a priority (how soon it needs a response), a status (where it sits in the flow of…
- OrganizationThe `/organisation` page contains complete organization settings divided into several tabs. It focuses on the operational and business profile of the…
Stránka bola naposledy upravená 24. apríla 2026.