HomeKitLock

1. Overview

The HomeKitLock class serves as the central bridge between the application’s core logic and the Apple HomeKit ecosystem, facilitated by the HomeSpan library. It is designed as a singleton and is responsible for initializing the HomeKit accessory, defining its services and characteristics, managing the network connection (Wi-Fi or Ethernet), and synchronizing the lock’s state with HomeKit.

A critical function of this class is managing the lifecycle of HomeKey issuers. It listens for changes in paired HomeKit controllers and automatically updates the NvsCredentialStore with the necessary cryptographic keys (LTPK), ensuring that newly paired devices can use HomeKey.

Key Responsibilities:

• HomeSpan Initialization: Configures and starts the HomeSpan framework, setting up the device as a HomeKit lock accessory.
• Accessory Definition: Creates all necessary HomeKit services, including the Lock Mechanism, Lock Management, NFC Access, and an optional Battery Service.
• State Synchronization: Subscribes to internal application events to update the lock’s current state, target state, and battery status in HomeKit in real-time.
• Network Management: Handles the initialization of an Ethernet connection if configured, with a fallback to Wi-Fi managed by HomeSpan.
• HomeKey Issuer Management: Automatically synchronizes the list of trusted HomeKey issuers with the list of paired HomeKit admin controllers.
• Debug Interface: Provides a set of serial commands for runtime debugging and diagnostics.

2. Public API

Constructor

HomeKitLock()

Constructs the HomeKitLock singleton instance. The constructor enforces that only one instance of the class can exist, restarting the device if a second instance is created. It initializes its internal references to the core application managers and subscribes to essential events for state synchronization.

Signature:

HomeKitLock(
    std::function<void(int)> &conn_cb,
    LockManager& lockManager,
    ConfigManager& configManager,
    NvsCredentialStore& readerDataManager
);

Parameters:

• conn_cb: A callback function (std::function<void(int)>) that will be invoked with a status code whenever the HomeKit connection state changes.
• lockManager: A reference to the LockManager instance, used to interact with the lock’s logic.
• configManager: A reference to the ConfigManager instance, used to retrieve device settings.
• readerDataManager: A reference to the NvsCredentialStore, used to manage HomeKey issuer data.

Initialization

begin()

Initializes and starts all HomeKit-related services. This is the main entry point for the class and must be called after the constructor.

It performs the following key actions:

1. Configures HomeSpan settings (e.g., control pin, status pin, OTA password, device name) from ConfigManager.
2. Calls initializeETH() to set up the Ethernet connection if enabled.
3. Starts the HomeSpan stack, advertising the device as a HomeKit lock.
4. Builds the accessory hierarchy, adding all required and optional services (Lock Mechanism, NFC Access, Battery Service, etc.).
5. Registers callbacks for HomeSpan events, such as connection changes and controller list modifications.
6. Sets up a series of developer debug commands accessible via the serial console.

Signature:

void begin();

State Update Methods

updateLockState()

Updates the lock’s Current State and Target State characteristics in HomeKit. To prevent unnecessary network traffic, this method only sends an update if the new state value is different from the currently stored value in the characteristic.

Signature:

void updateLockState(int currentState, int targetState);

Parameters:

• currentState: The new current state of the lock (e.g., HAP_CURRENT_LOCK_STATE_UNSECURED).
• targetState: The new target state of the lock (e.g., HAP_TARGET_LOCK_STATE_UNSECURED).

updateBatteryStatus()

Updates the Battery Level and Status Low Battery characteristics in HomeKit. This method should only be called if the physical battery service is enabled in the configuration. It checks for value changes before sending notifications.

Signature:

void updateBatteryStatus(uint8_t batteryLevel, bool isLow);

Parameters:

• batteryLevel: The battery charge percentage (0-100).
• isLow: The low battery status (true if the battery is low, false otherwise).

3. Network Management

initializeETH()

Delegates Ethernet initialization to the EthernetDriver module, passing the miscellaneous configuration. If Ethernet is disabled, EthernetDriver::start() is a no-op, allowing HomeSpan to manage the Wi-Fi connection instead. All pin leasing, preset/custom configuration handling, and lifecycle event broadcasting live in EthernetDriver (see EthernetDriver).

Signature:

void initializeETH();

4. Core Logic & Callbacks

These methods are central to the class’s operation but are typically invoked by HomeSpan or internal events rather than being called directly by the user.

controllerCallback()

This callback is triggered by HomeSpan whenever a HomeKit controller is paired or unpaired. It contains the critical logic for managing HomeKey issuers:

• When the last admin controller is unpaired, all HomeKey issuer and reader data is wiped to ensure security.
• For each currently paired admin controller, its Long-Term Public Key (LTPK) is hashed to derive a unique issuer ID, and the issuer is added to the NvsCredentialStore if absent.
• Issuers whose controller is no longer paired are automatically removed from the store (this keeps the issuer list in sync with unpaired controllers).
• Any changes to the issuer list are saved to NVS, and an ACCESSDATA_CHANGED event is published so other components (e.g., the NFC ECP data) re-synchronize.

setupDebugCommands()

This method registers a series of single-character commands with HomeSpan’s diagnostic interface, allowing developers to perform actions via a serial terminal.

• D: Deletes all stored HomeKey reader data.
• L: Sets the log level for various system components.
• F: Switches the HomeKey authentication flow (Fast, Standard, Attestation).
• M: Erases the stored MQTT configuration.
• N: Manually toggles the low-battery status characteristic.
• B: Manually sets the battery level characteristic.
• P: Prints a list of all currently registered HomeKey issuers.