Keyless Integration Guide for Lock Manufacturers.
This guide outlines a streamlined approach for lock manufacturers to enable their devices to
integrate seamlessly with Keyless, available on iOS and Android platforms. Our goal is to
minimize the integration efforts required from both parties, with manufacturers providing
comprehensive interfaces, including server-based credentials generation and management.
This guide covers the following components:
• Lock Device Module: A set of functions that allow direct communication with the lock
devices via Bluetooth and/or Wi-Fi.
• Server Components: Infrastructure for credential generation, management, and secure
communication between the lock, Keyless, and manufacturer’s servers on-premises or
tenant on the cloud.
• Integration API: The interface provided by the lock manufacturer for easy integration
with Keyless.
The API methods should be a “one-liner” to perform the operations and should be in the form of
suspend functions (utilizing Kotlin for Android) and async functions (utilizing Swift for iOS) that
perform the operation and return a successful result that has finished asynchronously or throw an
error after the operation.
The integration should be provided as a module to link the smart locks with Keyless easily,
prioritizing ease of use and compatibility with both Android and iOS. It should be structured in
layers to efficiently manage communication, security, and various lock features such as
opening/closing locks, configuring settings, updating software, and checking lock health. The
module should work smoothly on different platforms utilizing Kotlin and Swift, and work on
various manufacturer lock types with minimal power use.
Cards must also be supported and work with standard encoders such as ACR122U and ACR1252U.The
card writing SDK must allow only certain card UIDs to be written to and work on
Windows 10/11, MacOS Ventura and later, Linux.
The same requirements for writing to custom card UIDs must be available for iOS and Android as well.
Lock Device Module
Manufacturers are expected to implement and provide a module with the following
functionalities, accessible through simple, asynchronous API calls:
• Scan: Bluetooth scan for manufacturer lock around the device sorted by proximity.
• Connect: Authenticate and establish a connection with the lock.
• Lock/Unlock: Commands to lock or unlock the lock (door).
• Disconnect: Terminate the connection with the lock.
• Time Management: Reset and set the lock’s internal clock as necessary.
• Firmware Update: Facilitate firmware updates with progress callbacks.
• Factory Reset: Allow resetting the lock to factory settings after authentication.
• Battery Level: Retrieve the current battery level of the lock.
• Lock Information: Fetch detailed information about the lock’s status and configuration.
• Access Key Management: Update or replace access keys for the lock.
• Lock Logs: Access event logs stored on the lock.
• Cards: Add/Remove specific Mifare Classic 1K Card UIDs with a duration from the lock.
• Configuration Settings: Modify settings such as auto-lock timing, beep allowance, and
light indicators.
Server Components
Manufacturers are required to provide the following server-side components:
• Credential Generation and Management: A secure mechanism for generating, storing,
and managing access credentials. This includes temporary access tokens for guests or
service personnel.
• API for App Integration: A RESTful API or similar interface that allows the custom lock
app to request and manage credentials, initiate lock commands remotely, and retrieve
lock status and logs.
• Security: Implement industry-standard security practices, including encryption for data
at rest and in transit, to protect sensitive information.
• Scalability: Ensure the server infrastructure can handle a high number of requests
simultaneously without degradation of performance.
API Integration
Manufacturers must provide a well-documented API that abstracts the complexity of the
operations mentioned above. The API should include:
• Simple Integration Steps: Clear instructions on how to integrate the lock device module
with the custom lock app.
• Error Handling: Comprehensive documentation of potential errors, their meanings, and
suggested remedies.
• Code Examples: Sample code for common operations in both Kotlin (for Android) and
Swift (for iOS).
• Support: Information on how to contact technical support for integration assistance.
NOTE: To qualify for a free integration, the manufacturer must model their cloud and client APIs/SDKs on TTLock on premises API.
Sample Device API (Android)
