homebridge/dist/matter/serverHelpers.d.ts

HomeKit support for the impatient

/**
 * Helper functions for MatterServer.registerAccessory()
 * Extracted from the monolithic 521-line function for better maintainability
 */
import type { EndpointType } from '@matter/main';
import type { LevelControl } from '@matter/main/clusters/level-control';
import type { Behavior } from '@matter/node';
import type { MatterAccessory } from './types.js';
/**
 * Type representing a behavior class (constructor)
 */
type BehaviorType = Behavior.Type;
/**
 * Cluster IDs from Matter specification
 * Using Matter.js Cluster references instead of magic numbers
 */
export declare const CLUSTER_IDS: {
    readonly AIR_QUALITY: import("@matter/main").Brand<"ClusterId"> & 91;
    readonly CARBON_MONOXIDE_CONCENTRATION: import("@matter/main").Brand<"ClusterId"> & 1036;
    readonly COLOR_CONTROL: import("@matter/main").Brand<"ClusterId"> & 768;
    readonly DOOR_LOCK: import("@matter/main").Brand<"ClusterId"> & 257;
    readonly LEVEL_CONTROL: import("@matter/main").Brand<"ClusterId"> & 8;
    readonly NITROGEN_DIOXIDE_CONCENTRATION: import("@matter/main").Brand<"ClusterId"> & 1043;
    readonly ON_OFF: import("@matter/main").Brand<"ClusterId"> & 6;
    readonly OZONE_CONCENTRATION: import("@matter/main").Brand<"ClusterId"> & 1045;
    readonly PM10_CONCENTRATION: import("@matter/main").Brand<"ClusterId"> & 1069;
    readonly PM25_CONCENTRATION: import("@matter/main").Brand<"ClusterId"> & 1066;
    readonly THERMOSTAT: import("@matter/main").Brand<"ClusterId"> & 513;
    readonly WINDOW_COVERING: import("@matter/main").Brand<"ClusterId"> & 258;
};
/**
 * Validates required fields on a Matter accessory
 * @throws MatterDeviceError if validation fails
 */
export declare function validateAccessoryRequiredFields(accessory: MatterAccessory): void;
/**
 * Generic feature detection from device type behaviors
 * Extracts supported features from a device type's cluster definition
 *
 * @param deviceType - The Matter device type
 * @param clusterIdOrName - Cluster ID (number) or name (string)
 * @param featureExtractor - Function to extract feature names from supportedFeatures
 * @returns Array of detected features or null if cluster not found
 */
export declare function detectBehaviorFeatures(deviceType: EndpointType, clusterIdOrName: number | string, featureExtractor: (supportedFeatures: Record<string, boolean>) => string[]): string[] | null;
/**
 * Extract ColorControl features from supportedFeatures
 */
export declare function extractColorControlFeatures(supportedFeatures: Record<string, boolean>): string[];
/**
 * Extract Thermostat features from supportedFeatures
 */
export declare function extractThermostatFeatures(supportedFeatures: Record<string, boolean>): string[];
/**
 * Extract LevelControl features from supportedFeatures.
 *
 * Used to read features off a device type's declared LevelControl requirement
 * (e.g. DimmableLightDevice's `LevelControlServer.with("Lighting","OnOff")`).
 * When the device type doesn't declare LevelControl at all (e.g. PumpDevice,
 * which has LevelControl only in its `optional` requirements and not in
 * `SupportedBehaviors`), the caller should apply an empty feature set via
 * `.with()` so the Lighting feature inherited from matter.js's internal
 * `LevelControlBase = LevelControlBehavior.with(OnOff, Lighting)` is stripped
 * — otherwise the Pump endpoint inherits the `[LT]` branch of the spec
 * (minLevel constraint 1-254, initializeLighting warnings) that only applies
 * to lighting devices.
 */
export declare function extractLevelControlFeatures(supportedFeatures: Record<string, boolean>): LevelControl.Features[];
/**
 * Determine ColorControl features based on handlers
 * Only includes features that have corresponding handler methods
 */
export declare function determineColorControlFeaturesFromHandlers(handlers: Record<string, unknown>): string[];
/**
 * Detect WindowCovering features from accessory attributes
 * Auto-detects Lift and Tilt capabilities based on cluster attributes
 *
 * @param accessory - Matter accessory to inspect
 * @returns Array of detected feature names
 */
export declare function detectWindowCoveringFeatures(accessory: MatterAccessory): string[];
/**
 * Detect SmokeCoAlarm features from accessory attributes.
 * The Matter spec requires at least one of SmokeAlarm/CoAlarm, so an accessory
 * that declares neither state attribute falls back to SmokeAlarm — matching the
 * friendly device type name "SmokeSensor".
 */
export declare function detectSmokeCoAlarmFeatures(accessory: MatterAccessory): string[];
/**
 * Apply SmokeCoAlarm features to device type.
 * SmokeCoAlarm is not part of the base SmokeCoAlarmDevice — matter.js requires
 * the features to be chosen — so without this the endpoint would be created
 * without the cluster and the accessory's smokeCoAlarm state silently dropped.
 */
export declare function applySmokeCoAlarmFeatures(deviceType: EndpointType, accessory: MatterAccessory, features: string[]): EndpointType;
/**
 * Detect ServiceArea features from cluster attributes
 */
export declare function detectServiceAreaFeatures(serviceAreaCluster: Record<string, unknown> | undefined): string[];
/**
 * Apply WindowCovering features to device type
 */
export declare function applyWindowCoveringFeatures(deviceType: EndpointType, accessory: MatterAccessory, features: string[]): EndpointType;
/**
 * Build custom behaviors for RoboticVacuumCleaner devices
 */
export declare function buildRvcCustomBehaviors(accessory: MatterAccessory, serviceAreaFeatures: string[] | null): BehaviorType[];
/**
 * Apply detected features to a behavior class
 */
export declare function applyFeaturesToBehavior(behaviorClass: BehaviorType, features: string[] | null, clusterName: string): BehaviorType;
/**
 * The subset of an accessory (or composed-device part) the electrical
 * measurement helpers need - lets the same detection run for both.
 */
export interface ElectricalMeasurementHost {
    clusters?: MatterAccessory['clusters'];
    displayName?: string;
}
/**
 * Result of detecting electrical measurement clusters on an accessory
 */
export interface ElectricalMeasurementDetection {
    /** Accessory declares electricalPowerMeasurement cluster state */
    hasPowerMeasurement: boolean;
    /**
     * ElectricalEnergyMeasurement features derived from the declared attributes
     * (empty when the cluster is not declared)
     */
    energyFeatures: string[];
}
/**
 * Detect electrical measurement clusters from the accessory's declared state.
 *
 * ElectricalEnergyMeasurement is feature-gated in matter.js (Imported/Exported
 * x Cumulative/Periodic), so the features are chosen from which energy
 * attributes the accessory declares.
 */
export declare function detectElectricalMeasurementClusters(accessory: ElectricalMeasurementHost): ElectricalMeasurementDetection;
/**
 * Fill in the mandatory ElectricalPowerMeasurement / ElectricalEnergyMeasurement
 * attributes (powerMode, numberOfMeasurementTypes, accuracy) that plugins should
 * not have to write themselves. Mutates the accessory's declared cluster state
 * so the values flow into the endpoint options and the state cache together.
 */
export declare function applyElectricalMeasurementDefaults(accessory: ElectricalMeasurementHost, detection: ElectricalMeasurementDetection): void;
/**
 * Apply the electrical measurement behaviors to a device type.
 *
 * PowerTopology is mandatory on the ElectricalSensor device type and is
 * feature-gated in matter.js; TreeTopology fits a bridged endpoint that
 * measures itself. The EEM server keeps matter.js's setMeasurement() helper,
 * which also emits the CumulativeEnergyMeasured / PeriodicEnergyMeasured
 * events required by the spec.
 */
export declare function applyElectricalMeasurementClusters(deviceType: EndpointType, accessory: ElectricalMeasurementHost, detection: ElectricalMeasurementDetection): EndpointType;
export {};
//# sourceMappingURL=serverHelpers.d.ts.map