homebridge
Version:
HomeKit support for the impatient
230 lines • 13.5 kB
TypeScript
/**
* Matter API Implementation
*
* Implements the Matter API facade with lazy loading to optimize performance.
*
* Architecture:
* - Separates Matter-specific logic from core HomebridgeAPI class
* - Uses dynamic imports to prevent loading Matter.js at module parse time
* - Loads Matter types on first access to `api.matter` properties
* - Child bridges that don't use Matter have zero Matter.js overhead
*
* Performance Impact:
* - Before: Every child bridge loaded ~800ms of Matter.js code (8-16s on RPi)
* - After: Only child bridges using Matter load it on first access
* - Improvement: 75-90% reduction in startup time for multi-bridge setups
*/
import type { EndpointType } from '@matter/main';
import type { HomebridgeAPI, MatterAPI, PlatformName, PluginIdentifier } from '../api.js';
import type { MatterAccessory } from './index.js';
import { SwitchAPIImpl } from './SwitchAPI.js';
/**
* Implementation of the Matter API
*
* This facade provides Matter protocol support through the Homebridge API.
* It uses lazy loading to prevent loading the heavy Matter.js library until
* actually needed, improving startup performance for child bridges that don't
* use Matter.
*
* Features:
* - Lazy-loads Matter types on first access
* - Validates accessories before registration
* - Handles both bridge accessories and external standalone devices
* - Provides detailed error messages for debugging
* - Delegates to HomebridgeAPI for event emission and server access
*/
export declare class MatterAPIImpl implements MatterAPI {
private readonly api;
readonly switch: SwitchAPIImpl;
constructor(api: HomebridgeAPI);
/**
* Validate a Matter accessory has required fields
* @throws MatterAccessoryValidationError if validation fails
*/
private validateAccessory;
/**
* Validate an array of accessories, logging errors for invalid ones
* @returns Array of valid accessories only
*/
private validateAccessories;
/**
* Validate cluster name is valid
*
* @param clusterName - Cluster name to validate
* @param context - Context string for error messages
*/
private validateClusterName;
/**
* UUID generator (alias of api.hap.uuid for convenience)
*/
get uuid(): typeof import("@homebridge/hap-nodejs/dist/lib/util/uuid.js");
/**
* Matter device types for creating accessories
*/
get deviceTypes(): {
readonly OnOffLight: import("@matter/node/devices/on-off-light").OnOffLightDevice;
readonly DimmableLight: import("@matter/node/devices/dimmable-light").DimmableLightDevice;
readonly ColorTemperatureLight: import("@matter/node/devices/color-temperature-light").ColorTemperatureLightDevice;
readonly ExtendedColorLight: import("@matter/node/devices/extended-color-light").ExtendedColorLightDevice;
readonly OnOffSwitch: import("@matter/node/devices/on-off-light-switch").OnOffLightSwitchDevice;
readonly OnOffOutlet: import("@matter/node/devices/on-off-plug-in-unit").OnOffPlugInUnitDevice;
readonly DimmableOutlet: import("@matter/node/devices/dimmable-plug-in-unit").DimmablePlugInUnitDevice;
readonly AirQualitySensor: import("@matter/node/devices/air-quality-sensor").AirQualitySensorDevice;
readonly TemperatureSensor: import("@matter/node/devices/temperature-sensor").TemperatureSensorDevice;
readonly HumiditySensor: import("@matter/node/devices/humidity-sensor").HumiditySensorDevice;
readonly LightSensor: import("@matter/node/devices/light-sensor").LightSensorDevice;
readonly MotionSensor: import("@matter/node/devices/occupancy-sensor").OccupancySensorDevice;
readonly ContactSensor: import("@matter/node/devices/contact-sensor").ContactSensorDevice;
readonly LeakSensor: import("@matter/node/devices/water-leak-detector").WaterLeakDetectorDevice;
readonly SmokeSensor: import("@matter/node/devices/smoke-co-alarm").SmokeCoAlarmDevice;
readonly Thermostat: import("@matter/main").MutableEndpoint.With<EndpointType.For<{
readonly name: "Thermostat";
readonly deviceType: 769;
readonly deviceRevision: 5;
readonly requirements: typeof import("@matter/node/devices/thermostat").ThermostatRequirements;
readonly behaviors: {
readonly identify: typeof import("@matter/node/behaviors").IdentifyServer;
};
}>, import("@matter/main").SupportedBehaviors.With<{
readonly identify: typeof import("@matter/node/behaviors").IdentifyServer;
}, readonly [import("@matter/main").ClusterBehavior.Type<typeof import("@matter/node/behaviors").ThermostatServer, import("@matter/types").ClusterType.WithSupportedFeatures<import("@matter/main/clusters").Thermostat, {
occupancy: true;
presets: false;
heating: true;
cooling: true;
autoMode: true;
setback: false;
localTemperatureNotExposed: false;
matterScheduleConfiguration: false;
}>, import("@matter/types").ClusterType.Concrete, typeof import("@matter/node/behaviors").ThermostatBaseServer.Internal, "thermostat">]>>;
readonly Fan: import("@matter/node/devices/fan").FanDevice;
readonly DoorLock: import("@matter/node/devices/door-lock").DoorLockDevice;
readonly WindowCovering: import("@matter/node/devices/window-covering").WindowCoveringDevice;
readonly RoboticVacuumCleaner: import("@matter/node/devices/robotic-vacuum-cleaner").RoboticVacuumCleanerDevice;
readonly WaterValve: import("@matter/main").MutableEndpoint.With<EndpointType.For<{
readonly name: "WaterValve";
readonly deviceType: 66;
readonly deviceRevision: 1;
readonly requirements: typeof import("@matter/node/devices/water-valve").WaterValveRequirements;
readonly behaviors: {
readonly identify: typeof import("@matter/node/behaviors").IdentifyServer;
} & {
readonly valveConfigurationAndControl: typeof import("@matter/node/behaviors").ValveConfigurationAndControlServer;
};
}>, import("@matter/main").SupportedBehaviors.With<{
readonly identify: typeof import("@matter/node/behaviors").IdentifyServer;
} & {
readonly valveConfigurationAndControl: typeof import("@matter/node/behaviors").ValveConfigurationAndControlServer;
}, readonly [typeof import("@matter/node/behaviors").ValveConfigurationAndControlServer]>>;
readonly GenericSwitch: import("@matter/node/devices/generic-switch").GenericSwitchDevice;
readonly Pump: import("@matter/node/devices/pump").PumpDevice;
readonly RoomAirConditioner: import("@matter/node/devices/room-air-conditioner").RoomAirConditionerDevice;
readonly BridgedNode: import("@matter/node/endpoints").BridgedNodeEndpoint;
};
/**
* Matter clusters - Direct access to Matter.js cluster definitions
*/
get clusters(): {
AirQuality: typeof import("@matter/main/clusters").AirQuality;
BooleanState: typeof import("@matter/main/clusters").BooleanState;
CarbonMonoxideConcentrationMeasurement: typeof import("@matter/main/clusters").CarbonMonoxideConcentrationMeasurement;
ColorControl: typeof import("@matter/main/clusters").ColorControl;
DoorLock: typeof import("@matter/main/clusters").DoorLock;
FanControl: typeof import("@matter/main/clusters").FanControl;
LevelControl: typeof import("@matter/main/clusters").LevelControl;
NitrogenDioxideConcentrationMeasurement: typeof import("@matter/main/clusters").NitrogenDioxideConcentrationMeasurement;
OnOff: typeof import("@matter/main/clusters").OnOff;
OzoneConcentrationMeasurement: typeof import("@matter/main/clusters").OzoneConcentrationMeasurement;
Pm10ConcentrationMeasurement: typeof import("@matter/main/clusters").Pm10ConcentrationMeasurement;
Pm25ConcentrationMeasurement: typeof import("@matter/main/clusters").Pm25ConcentrationMeasurement;
RvcOperationalState: typeof import("@matter/main/clusters").RvcOperationalState;
Thermostat: typeof import("@matter/main/clusters").Thermostat;
ValveConfigurationAndControl: typeof import("@matter/main/clusters").ValveConfigurationAndControl;
WindowCovering: typeof import("@matter/main/clusters").WindowCovering;
};
/**
* Matter cluster names for type safety and autocomplete
*/
get clusterNames(): {
readonly OnOff: "onOff";
readonly LevelControl: "levelControl";
readonly ColorControl: "colorControl";
readonly DoorLock: "doorLock";
readonly WindowCovering: "windowCovering";
readonly Thermostat: "thermostat";
readonly FanControl: "fanControl";
readonly AirQuality: "airQuality";
readonly CarbonMonoxideConcentrationMeasurement: "carbonMonoxideConcentrationMeasurement";
readonly NitrogenDioxideConcentrationMeasurement: "nitrogenDioxideConcentrationMeasurement";
readonly OzoneConcentrationMeasurement: "ozoneConcentrationMeasurement";
readonly Pm10ConcentrationMeasurement: "pm10ConcentrationMeasurement";
readonly Pm25ConcentrationMeasurement: "pm25ConcentrationMeasurement";
readonly TemperatureMeasurement: "temperatureMeasurement";
readonly RelativeHumidityMeasurement: "relativeHumidityMeasurement";
readonly IlluminanceMeasurement: "illuminanceMeasurement";
readonly OccupancySensing: "occupancySensing";
readonly BooleanState: "booleanState";
readonly SmokeCoAlarm: "smokeCoAlarm";
readonly RvcRunMode: "rvcRunMode";
readonly RvcOperationalState: "rvcOperationalState";
readonly RvcCleanMode: "rvcCleanMode";
readonly ServiceArea: "serviceArea";
readonly PowerSource: "powerSource";
readonly PumpConfigurationAndControl: "pumpConfigurationAndControl";
readonly ValveConfigurationAndControl: "valveConfigurationAndControl";
readonly Identify: "identify";
readonly Switch: "switch";
readonly BasicInformation: "basicInformation";
readonly BridgedDeviceBasicInformation: "bridgedDeviceBasicInformation";
};
/**
* Matter types - Access to Matter.js cluster type definitions and enums
*/
get types(): {
AirQuality: typeof import("@matter/main/clusters").AirQuality;
BooleanState: typeof import("@matter/main/clusters").BooleanState;
CarbonMonoxideConcentrationMeasurement: typeof import("@matter/main/clusters").CarbonMonoxideConcentrationMeasurement;
ColorControl: typeof import("@matter/main/clusters").ColorControl;
DoorLock: typeof import("@matter/main/clusters").DoorLock;
FanControl: typeof import("@matter/main/clusters").FanControl;
LevelControl: typeof import("@matter/main/clusters").LevelControl;
NitrogenDioxideConcentrationMeasurement: typeof import("@matter/main/clusters").NitrogenDioxideConcentrationMeasurement;
OnOff: typeof import("@matter/main/clusters").OnOff;
OzoneConcentrationMeasurement: typeof import("@matter/main/clusters").OzoneConcentrationMeasurement;
Pm10ConcentrationMeasurement: typeof import("@matter/main/clusters").Pm10ConcentrationMeasurement;
Pm25ConcentrationMeasurement: typeof import("@matter/main/clusters").Pm25ConcentrationMeasurement;
RvcOperationalState: typeof import("@matter/main/clusters").RvcOperationalState;
Thermostat: typeof import("@matter/main/clusters").Thermostat;
ValveConfigurationAndControl: typeof import("@matter/main/clusters").ValveConfigurationAndControl;
WindowCovering: typeof import("@matter/main/clusters").WindowCovering;
};
/**
* Register Matter platform accessories
* Automatically handles external accessories (e.g., RoboticVacuumCleaner) that need dedicated bridges
* Validates accessories before registration
* Returns a promise that resolves when all accessories are fully registered
*/
registerPlatformAccessories(pluginIdentifier: PluginIdentifier, platformName: PlatformName, accessories: MatterAccessory[]): Promise<void>;
/**
* Update Matter platform accessories in the cache
* Similar to api.updatePlatformAccessories() for HAP accessories
*/
updatePlatformAccessories(accessories: MatterAccessory[]): Promise<void>;
/**
* Unregister Matter platform accessories
* Automatically handles external accessories (e.g., RoboticVacuumCleaner) that have dedicated bridges
*/
unregisterPlatformAccessories(pluginIdentifier: PluginIdentifier, platformName: PlatformName, accessories: MatterAccessory[]): Promise<void>;
/**
* Update a Matter accessory's cluster state
* Validates inputs before updating
*/
updateAccessoryState(uuid: string, cluster: string, attributes: Record<string, unknown>, partId?: string): Promise<void>;
/**
* Get a Matter accessory's current cluster state
* Checks both external servers and main bridge server
* Validates inputs before retrieving state
*/
getAccessoryState(uuid: string, cluster: string, partId?: string): Promise<Record<string, unknown> | undefined>;
}
//# sourceMappingURL=MatterAPIImpl.d.ts.map