How roquerodrigo/ha-ttlock-ble works
This Home Assistant integration configures TTLock locks, obtains cloud-backed or manually entered keys, then exposes local BLE control and lock state as Home Assistant entities. Its runtime combines passive advertisement tracking with on-demand BLE sessions; sessions also read operation logs, credentials, and clock/settings data. The README documents discovery, 2FA, reauthentication, and diagnostics, while sampled source confirms setup, advertisement tracking, connection handling, and log-event dispatch. Some platform and configuration-flow links are documented rather than verified in sampled implementation.
Main entry points: coordinator.py Runtime coordinator · __init__.py Entry setup · connection.py BLE connection · config_flow.py Config and reauth
Components 25
Setup and keys
- Config and reauth
custom_components/ttlock_ble/config_flow.py - Options flow
custom_components/ttlock_ble/options_flow.py - Cloud API client
custom_components/ttlock_ble/api.py - Manual key entry
custom_components/ttlock_ble/manual_key.py - Entry setup
custom_components/ttlock_ble/__init__.py - Key privileges
custom_components/ttlock_ble/key_privileges.py
BLE runtime
- Advertisement tracker
custom_components/ttlock_ble/advertisement.py - Runtime coordinator
custom_components/ttlock_ble/coordinator.py - BLE connection
custom_components/ttlock_ble/connection.py
State and records
- Credential naming
custom_components/ttlock_ble/passcode_ledger.py - Lock state model
custom_components/ttlock_ble/data/lock_state.py
Home Assistant entities
- Lock controls
custom_components/ttlock_ble/lock.py - Entity base
custom_components/ttlock_ble/entity.py - Sensors
custom_components/ttlock_ble/sensor.py - Binary sensors
custom_components/ttlock_ble/binary_sensor.py - Operation events
custom_components/ttlock_ble/event.py - Other platforms
custom_components/ttlock_ble/button.py
Diagnostics and persistence
- Clock sync store
custom_components/ttlock_ble/clock_sync_store.py - Device description store
custom_components/ttlock_ble/device_description_store.py - Diagnostics export
custom_components/ttlock_ble/diagnostics.py - Integration constants
custom_components/ttlock_ble/const.py
Other components
- Home Assistant user
- Home Assistant
- TTLock cloud
- TTLock lock
Connections 25
- Home Assistant user → Config and reauth: configures
- Config and reauth → Cloud API client: authenticates
- Cloud API client → TTLock cloud: downloads keys
- Config and reauth → Manual key entry: accepts key
- Home Assistant user → Options flow: edits options
- Home Assistant → Entry setup: sets up entry
custom_components/ttlock_ble/__init__.py - Entry setup → Advertisement tracker: registers tracking
custom_components/ttlock_ble/__init__.py - Entry setup → Runtime coordinator: creates coordinator
custom_components/ttlock_ble/__init__.py - Entry setup → BLE connection: creates connections
custom_components/ttlock_ble/__init__.py - Entry setup → Other platforms: forwards platforms
custom_components/ttlock_ble/__init__.py - Advertisement tracker → Runtime coordinator: publishes state
custom_components/ttlock_ble/advertisement.py - TTLock lock → Advertisement tracker: broadcasts state
- Runtime coordinator → BLE connection: fetches log
custom_components/ttlock_ble/coordinator.py - BLE connection → TTLock lock: communicates BLE
- Lock controls → BLE connection: commands lock
custom_components/ttlock_ble/lock.py - Runtime coordinator → Lock state model: publishes snapshot
custom_components/ttlock_ble/coordinator.py - Runtime coordinator → Clock sync store: persists clock sync
custom_components/ttlock_ble/coordinator.py - Runtime coordinator → Device description store: persists description
custom_components/ttlock_ble/coordinator.py - Runtime coordinator → Operation events: dispatches log records
custom_components/ttlock_ble/event.py - Operation events → Credential naming: resolves credentials
- Runtime coordinator → Sensors: supplies state
custom_components/ttlock_ble/sensor.py - Runtime coordinator → Binary sensors: supplies state
custom_components/ttlock_ble/binary_sensor.py - Entity base → Runtime coordinator: reads snapshot
custom_components/ttlock_ble/entity.py - Home Assistant → Diagnostics export: requests dump
- Entry setup → Key privileges: uses privileges
custom_components/ttlock_ble/__init__.py