homebridge
- Version 2.0.2
- Published
- 1.28 MB
- 8 dependencies
- Apache-2.0 license
Install
npm i homebridgeyarn add homebridgepnpm add homebridgeOverview
HomeKit support for the impatient
Index
Variables
Classes
Interfaces
ClusterStateMap
- airQuality
- booleanState
- carbonMonoxideConcentrationMeasurement
- colorControl
- doorLock
- fanControl
- identify
- illuminanceMeasurement
- levelControl
- nitrogenDioxideConcentrationMeasurement
- occupancySensing
- onOff
- ozoneConcentrationMeasurement
- pm10ConcentrationMeasurement
- pm25ConcentrationMeasurement
- powerSource
- relativeHumidityMeasurement
- rvcCleanMode
- rvcOperationalState
- rvcRunMode
- serviceArea
- switch
- temperatureMeasurement
- thermostat
- valveConfigurationAndControl
- windowCovering
ThermostatState
- absMaxCoolSetpointLimit
- absMaxHeatSetpointLimit
- absMinCoolSetpointLimit
- absMinHeatSetpointLimit
- controlSequenceOfOperation
- externallyMeasuredOccupancy
- externalMeasuredIndoorTemperature
- localTemperature
- maxCoolSetpointLimit
- maxHeatSetpointLimit
- minCoolSetpointLimit
- minHeatSetpointLimit
- minSetpointDeadBand
- numberOfDailyTransitions
- numberOfWeeklyTransitions
- occupancy
- occupiedCoolingSetpoint
- occupiedHeatingSetpoint
- outdoorTemperature
- remoteSensing
- startOfWeek
- systemMode
- thermostatRunningMode
- unoccupiedCoolingSetpoint
- unoccupiedHeatingSetpoint
Enums
Type Aliases
Namespaces
MatterRequests
- AddGroup
- AddGroupIfIdentifying
- AddScene
- ChangeToMode
- ClearCredential
- ClearHolidaySchedule
- ClearUser
- ClearWeekDaySchedule
- ClearYearDaySchedule
- ColorLoopSet
- CopyScene
- EnhancedMoveHue
- EnhancedMoveToHue
- EnhancedMoveToHueAndSaturation
- EnhancedStepHue
- FanStep
- GetCredentialStatus
- GetGroupMembership
- GetHolidaySchedule
- GetSceneMembership
- GetUser
- GetWeekDaySchedule
- GetYearDaySchedule
- GoToLiftPercentage
- GoToTiltPercentage
- IdentifyRequest
- LockDoor
- Move
- MoveColor
- MoveColorTemperature
- MoveHue
- MoveSaturation
- MoveToClosestFrequency
- MoveToColor
- MoveToColorTemperature
- MoveToHue
- MoveToHueAndSaturation
- MoveToLevel
- MoveToSaturation
- OffWithEffect
- OnWithTimedOff
- OpenValve
- RecallScene
- RemoveAllScenes
- RemoveGroup
- RemoveScene
- SelectAreas
- SetActivePreset
- SetActiveSchedule
- SetAliroReaderConfig
- SetCredential
- SetHolidaySchedule
- SetpointRaiseLower
- SetUser
- SetWeekDaySchedule
- SetYearDaySchedule
- SkipArea
- Step
- StepColor
- StepColorTemperature
- StepHue
- StepSaturation
- Stop
- StopMoveStep
- StoreScene
- TriggerEffect
- UnboltDoor
- UnlockDoor
- UnlockWithTimeout
- ViewGroup
- ViewScene
Variables
variable clusterNames
const 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 Cluster Names Commonly used cluster names for type safety and autocomplete Use these with api.updateMatterAccessoryState() and api.getAccessoryState()
Example 1
With autocomplete and type safety:api.updateMatterAccessoryState(uuid, api.matterClusterNames.OnOff, { onOff: true })api.getAccessoryState(uuid, api.matterClusterNames.LevelControl)
variable clusters
const clusters: { AirQuality: any; BooleanState: any; CarbonMonoxideConcentrationMeasurement: any; ColorControl: any; DoorLock: any; FanControl: any; LevelControl: any; NitrogenDioxideConcentrationMeasurement: any; OnOff: any; OzoneConcentrationMeasurement: any; Pm10ConcentrationMeasurement: any; Pm25ConcentrationMeasurement: any; RvcOperationalState: any; Thermostat: any; ValveConfigurationAndControl: any; WindowCovering: any;};Matter cluster types
All supported Matter cluster types, imported from individual files for optimal performance.
variable devices
const devices: { AirQualitySensorDevice: AirQualitySensorDevice; ColorTemperatureLightDevice: ColorTemperatureLightDevice; ContactSensorDevice: ContactSensorDevice; DimmableLightDevice: DimmableLightDevice; DimmablePlugInUnitDevice: DimmablePlugInUnitDevice; DoorLockDevice: DoorLockDevice; ExtendedColorLightDevice: ExtendedColorLightDevice; FanDevice: FanDevice; GenericSwitchDevice: GenericSwitchDevice; HumiditySensorDevice: HumiditySensorDevice; LightSensorDevice: LightSensorDevice; OccupancySensorDevice: OccupancySensorDevice; OnOffLightDevice: OnOffLightDevice; OnOffLightSwitchDevice: OnOffLightSwitchDevice; OnOffPlugInUnitDevice: OnOffPlugInUnitDevice; PumpDevice: PumpDevice; RoboticVacuumCleanerDevice: RoboticVacuumCleanerDevice; RoboticVacuumCleanerRequirements: any; RoomAirConditionerDevice: RoomAirConditionerDevice; SmokeCoAlarmDevice: SmokeCoAlarmDevice; TemperatureSensorDevice: TemperatureSensorDevice; ThermostatDevice: ThermostatDevice; ThermostatRequirements: any; WaterLeakDetectorDevice: WaterLeakDetectorDevice; WaterValveDevice: WaterValveDevice; WaterValveRequirements: any; WindowCoveringDevice: WindowCoveringDevice;};Matter device types
All supported Matter device types, imported from individual files for optimal performance.
variable deviceTypes
const deviceTypes: { readonly OnOffLight: OnOffLightDevice; readonly DimmableLight: DimmableLightDevice; readonly ColorTemperatureLight: ColorTemperatureLightDevice; readonly ExtendedColorLight: ExtendedColorLightDevice; readonly OnOffSwitch: OnOffLightSwitchDevice; readonly OnOffOutlet: OnOffPlugInUnitDevice; readonly DimmableOutlet: DimmablePlugInUnitDevice; readonly AirQualitySensor: AirQualitySensorDevice; readonly TemperatureSensor: TemperatureSensorDevice; readonly HumiditySensor: HumiditySensorDevice; readonly LightSensor: LightSensorDevice; readonly MotionSensor: OccupancySensorDevice; readonly ContactSensor: ContactSensorDevice; readonly LeakSensor: WaterLeakDetectorDevice; readonly SmokeSensor: SmokeCoAlarmDevice; readonly Thermostat: any; readonly Fan: FanDevice; readonly DoorLock: DoorLockDevice; readonly WindowCovering: WindowCoveringDevice; readonly RoboticVacuumCleaner: RoboticVacuumCleanerDevice; readonly WaterValve: any; readonly GenericSwitch: GenericSwitchDevice; readonly Pump: PumpDevice; readonly RoomAirConditioner: RoomAirConditionerDevice; readonly BridgedNode: BridgedNodeEndpoint;};Friendly device type names for the Plugin API Maps simplified names to actual Matter.js device types
variable MatterStatus
const MatterStatus: { MatterProtocolError: typeof MatterProtocolError; Busy: typeof Busy; Timeout: typeof Timeout; ConstraintError: typeof ConstraintError; InvalidAction: typeof InvalidAction; InvalidInState: typeof InvalidInState; Failure: typeof Failure; ResourceExhausted: typeof ResourceExhausted; PermissionDenied: typeof PermissionDenied; NotFound: typeof NotFound; isMatterProtocolError: typeof isMatterProtocolError;};Matter protocol status codes and error classes
Use these error classes to signal specific error conditions to Matter controllers. Each error class corresponds to a Matter protocol status code.
Classes
class Logger
class Logger {}Logger class
constructor
constructor(prefix?: string);property internal
static readonly internal: Logger;property prefix
readonly prefix?: string;method debug
debug: (message: string, ...parameters: any[]) => void;method error
error: (message: string, ...parameters: any[]) => void;method forceColor
static forceColor: () => void;Forces color in logging output, even if it seems like color is unsupported.
method info
info: (message: string, ...parameters: any[]) => void;method isTimestampEnabled
static isTimestampEnabled: () => boolean;Check if timestamps are enabled in log messages.
Returns
{boolean} true if timestamps are enabled
method log
log: (level: LogLevel, message: string, ...parameters: any[]) => void;method setDebugEnabled
static setDebugEnabled: (enabled?: boolean) => void;Turns on debug level logging. Off by default.
Parameter enabled
method setTimestampEnabled
static setTimestampEnabled: (enabled?: boolean) => void;Turns on inclusion of timestamps in log messages. On by default.
Parameter enabled
method success
success: (message: string, ...parameters: any[]) => void;method warn
warn: (message: string, ...parameters: any[]) => void;method withPrefix
static withPrefix: (prefix: string) => Logging;Creates a new Logging device with a specified prefix.
Parameter prefix
the prefix of the logger
class MatterCommissioningError
class MatterCommissioningError extends MatterError {}constructor
constructor(message: string, details?: MatterErrorDetails);class MatterDeviceError
class MatterDeviceError extends MatterError {}constructor
constructor(message: string, details?: MatterErrorDetails);class MatterError
class MatterError extends Error {}Matter error types
constructor
constructor(message: string, code: string, details?: MatterErrorDetails);property code
readonly code: string;property details
readonly details?: MatterErrorDetails;property recoverable
readonly recoverable: boolean;property timestamp
readonly timestamp: Date;property type
readonly type: MatterErrorType;class MatterNetworkError
class MatterNetworkError extends MatterError {}constructor
constructor(message: string, details?: MatterErrorDetails);class MatterStorageError
class MatterStorageError extends MatterError {}constructor
constructor(message: string, details?: MatterErrorDetails);class PlatformAccessory
class PlatformAccessory< T extends UnknownContext = UnknownContext> extends EventEmitter {}constructor
constructor(displayName: string, uuid: string, category?: Categories);property category
category: Categories;property context
context: UnknownContext;This is a way for Plugin developers to store custom data with their accessory
property displayName
displayName: string;property services
services: Service[];property UUID
UUID: string;method addService
addService: { (service: Service): Service; <S extends any>( serviceConstructor: S, ...constructorArgs: ConstructorArgs<S> ): Service;};method configureController
configureController: (controller: Controller | ControllerConstructor) => void;Configures a new controller for the given accessory. See Accessory.configureController.
Parameter controller
method deserialize
static deserialize: (json: SerializedPlatformAccessory) => PlatformAccessory;method getService
getService: <T extends WithUUID<any>>(name: string | T) => Service | undefined;method getServiceById
getServiceById: <T extends WithUUID<any>>( uuid: string | T, subType: string) => Service | undefined;method removeController
removeController: (controller: Controller) => void;Removes a configured controller from the given accessory. See Accessory.removeController.
Parameter controller
method removeService
removeService: (service: Service) => void;method serialize
static serialize: (accessory: PlatformAccessory) => SerializedPlatformAccessory;method updateDisplayName
updateDisplayName: (name: string) => void;class User
class User {}Manages user settings and storage locations.
method cachedAccessoryPath
static cachedAccessoryPath: () => string;method configPath
static configPath: () => string;method matterPath
static matterPath: () => string;method persistPath
static persistPath: () => string;method setStoragePath
static setStoragePath: (...storagePathSegments: string[]) => void;method storagePath
static storagePath: () => string;Interfaces
interface AccessoryConfig
interface AccessoryConfig extends Record<string, any> {}interface AccessoryPlugin
interface AccessoryPlugin {}property getControllers
getControllers?: () => Controller[];This method will be called once on startup, to query all controllers to be exposed by the Accessory. It is optional to implement.
This includes controllers like the RemoteController or the CameraController. Any necessary controller specific setup should have been done when returning the array. In most cases the plugin will only return an array of the size 1.
In the case that the Plugin does not add any additional services (returned by getServices) the method getServices must be defined in any way and should just return an empty array.
Returns
{Controller[]} controllers - returned controllers will be configured for the Accessory
property getServices
getServices: () => Service[];This method will be called once on startup, to query all services to be exposed by the Accessory. All event handlers for characteristics should be set up before the array is returned.
Returns
{Service[]} services - returned services will be added to the Accessory
property identify
identify?: () => void;Optional method which will be called if an 'identify' of an Accessory is requested by HomeKit.
interface AccessoryPluginConstructor
interface AccessoryPluginConstructor {}construct signature
new (logger: Logging, config: AccessoryConfig, api: API): AccessoryPlugin;interface API
interface API {}property hap
readonly hap: HAP;property hapLegacyTypes
readonly hapLegacyTypes: HAPLegacyTypes;property isMatterAvailable
isMatterAvailable: () => boolean;Check if Matter is available in this version of Homebridge
Returns
true if Homebridge version is >= 2.0.0-alpha.0
property isMatterEnabled
isMatterEnabled: () => boolean;Check if Matter is enabled for this bridge For main bridge: returns true if Matter is enabled in
bridge.matterconfig For child bridge: returns true if Matter is enabled in the _bridge.matter configReturns
true if Matter is enabled
property matter
readonly matter?: MatterAPI;Matter Protocol API.
Remarks
Defined when Matter is configured for this bridge (i.e. when
api.isMatterEnabled()returns true), undefined otherwise. Loaded automatically before plugins run on Matter-enabled bridges, so plugins can access it from their initializer, platform/accessory constructor, ordidFinishLaunchinghandler.Safe access patterns:
api.matter?.registerPlatformAccessories(...) // defensive, no-ops when disabledif (api.isMatterEnabled()) {api.matter!.registerPlatformAccessories(...) // explicit guard}Example 1
// Register a Matter accessoryapi.matter?.registerPlatformAccessories('homebridge-example', 'Example', [{UUID: api.hap.uuid.generate('my-light'),displayName: 'Living Room Light',deviceType: api.matter!.deviceTypes.OnOffLight,manufacturer: 'Example',model: 'Example Light',serialNumber: 'EX-001',clusters: { onOff: { onOff: false } },}])// Update stateawait api.matter?.updateAccessoryState(uuid, 'onOff', { onOff: true })
property on
on: ((event: 'didFinishLaunching', listener: () => void) => this) & ((event: 'shutdown', listener: () => void) => this);property platformAccessory
readonly platformAccessory: typeof PlatformAccessory;property publishExternalAccessories
publishExternalAccessories: ( pluginIdentifier: PluginIdentifier, accessories: PlatformAccessory[]) => void;property registerAccessory
registerAccessory: (( accessoryName: AccessoryName, constructor: AccessoryPluginConstructor) => void) & (( pluginIdentifier: PluginIdentifier, accessoryName: AccessoryName, constructor: AccessoryPluginConstructor ) => void);property registerPlatform
registerPlatform: (<Config extends PlatformConfig>( platformName: PlatformName, constructor: PlatformPluginConstructor<Config>) => void) & (<Config extends PlatformConfig>( pluginIdentifier: PluginIdentifier, platformName: PlatformName, constructor: PlatformPluginConstructor<Config> ) => void);property registerPlatformAccessories
registerPlatformAccessories: ( pluginIdentifier: PluginIdentifier, platformName: PlatformName, accessories: PlatformAccessory[]) => void;property serverVersion
readonly serverVersion: string;The current homebridge semver version.
property unregisterPlatformAccessories
unregisterPlatformAccessories: ( pluginIdentifier: PluginIdentifier, platformName: PlatformName, accessories: PlatformAccessory[]) => void;property updatePlatformAccessories
updatePlatformAccessories: (accessories: PlatformAccessory[]) => void;property user
readonly user: typeof User;property version
readonly version: number;The homebridge API version as a floating point number.
property versionGreaterOrEqual
versionGreaterOrEqual: (version: string) => boolean;Returns true if the current running homebridge version is greater or equal to the passed version string.
Example:
We assume the homebridge version 1.3.0-beta.12 (serverVersion) and the following example calls below
versionGreaterOrEqual("1.2.0"); // will return trueversionGreaterOrEqual("1.3.0"); // will return false (the RELEASE version 1.3.0 is bigger than the BETA version 1.3.0-beta.12)versionGreaterOrEqual("1.3.0-beta.8); // will return trueParameter version
interface BridgeConfiguration
interface BridgeConfiguration {}property advertiser
advertiser?: MDNSAdvertiser;property bind
bind?: (InterfaceName | IPAddress) | (InterfaceName | IPAddress)[];property debugModeEnabled
debugModeEnabled?: boolean;property disableIpc
disableIpc?: boolean;property env
env?: { DEBUG?: string; NODE_OPTIONS?: string;};property firmwareRevision
firmwareRevision?: string;property hap
hap?: boolean;When
false, this bridge will not publish HAP. Useful for Matter-only bridges where the user does not want to expose a HomeKit bridge accessory. Default:true(HAP is published).Note: at least one of
hapormattermust be enabled per bridge — settinghap: falsewithout amatterconfiguration is rejected.
property manufacturer
manufacturer?: string;property matter
matter?: MatterConfig;property model
model?: string;property name
name: string;property pin
pin: string;property port
port?: number;property serialNumber
serialNumber?: string;property setupID
setupID?: string;4-character HomeKit setup ID (alphanumeric, e.g. "ABCD"). Validated at runtime.
property username
username: MacAddress;interface ClusterHandlerMap
interface ClusterHandlerMap {}Maps known cluster names to their typed handler interfaces.
Plugin developers get autocomplete for handler methods within each cluster. Handler argument types are derived from matter.js where possible, so they auto-update when the matter.js dependency is bumped.
Example 1
const accessory: MatterAccessory = {// ...handlers: {onOff: {on: async () => { await device.turnOn() },off: async () => { await device.turnOff() },},levelControl: {moveToLevel: async (args) => {// args is typed as LevelControl.MoveToLevelRequestawait device.setBrightness(args?.level ?? 0)},},},}
property colorControl
colorControl: ColorControlHandlers;property doorLock
doorLock: DoorLockHandlers;property fanControl
fanControl: FanControlHandlers;property identify
identify: IdentifyHandlers;property levelControl
levelControl: LevelControlHandlers;property onOff
onOff: OnOffHandlers;property rvcCleanMode
rvcCleanMode: RvcCleanModeHandlers;property rvcOperationalState
rvcOperationalState: RvcOperationalStateHandlers;property rvcRunMode
rvcRunMode: RvcRunModeHandlers;property serviceArea
serviceArea: ServiceAreaHandlers;property thermostat
thermostat: ThermostatHandlers;property valveConfigurationAndControl
valveConfigurationAndControl: ValveConfigurationAndControlHandlers;property windowCovering
windowCovering: WindowCoveringHandlers;interface ClusterStateMap
interface ClusterStateMap {}Maps known cluster names to their typed state interfaces.
Plugin developers get autocomplete for known clusters while unknown clusters fall back to
Record<string, unknown>.Example 1
// With typed overload on api.matter:await api.matter?.updateAccessoryState(uuid, 'onOff', { onOff: true })// ^-- autocomplete!const state = await api.matter?.getAccessoryState(uuid, 'levelControl')// state is Partial<LevelControlState> | undefined
property airQuality
airQuality: { airQuality: number;};property booleanState
booleanState: { stateValue: boolean;};property carbonMonoxideConcentrationMeasurement
carbonMonoxideConcentrationMeasurement: { measuredValue: number | null; minMeasuredValue?: number | null; maxMeasuredValue?: number | null; measurementMedium: number; measurementUnit?: number;};property colorControl
colorControl: ColorControlState;property doorLock
doorLock: DoorLockState;property fanControl
fanControl: FanControlState;property identify
identify: { identifyTime: number; identifyType: number;};property illuminanceMeasurement
illuminanceMeasurement: { measuredValue: number | null; minMeasuredValue?: number | null; maxMeasuredValue?: number | null;};property levelControl
levelControl: LevelControlState;property nitrogenDioxideConcentrationMeasurement
nitrogenDioxideConcentrationMeasurement: { measuredValue: number | null; minMeasuredValue?: number | null; maxMeasuredValue?: number | null; measurementMedium: number; measurementUnit?: number;};property occupancySensing
occupancySensing: { occupancy: { occupied: boolean; }; occupancySensorType?: number; occupancySensorTypeBitmap?: { pir?: boolean; ultrasonic?: boolean; physicalContact?: boolean; };};property onOff
onOff: OnOffState;property ozoneConcentrationMeasurement
ozoneConcentrationMeasurement: { measuredValue: number | null; minMeasuredValue?: number | null; maxMeasuredValue?: number | null; measurementMedium: number; measurementUnit?: number;};property pm10ConcentrationMeasurement
pm10ConcentrationMeasurement: { measuredValue: number | null; minMeasuredValue?: number | null; maxMeasuredValue?: number | null; measurementMedium: number; measurementUnit?: number;};property pm25ConcentrationMeasurement
pm25ConcentrationMeasurement: { measuredValue: number | null; minMeasuredValue?: number | null; maxMeasuredValue?: number | null; measurementMedium: number; measurementUnit?: number;};property powerSource
powerSource: PowerSourceState;property relativeHumidityMeasurement
relativeHumidityMeasurement: { measuredValue: number | null; minMeasuredValue?: number | null; maxMeasuredValue?: number | null;};property rvcCleanMode
rvcCleanMode: RvcCleanModeState;property rvcOperationalState
rvcOperationalState: RvcOperationalState;property rvcRunMode
rvcRunMode: RvcRunModeState;property serviceArea
serviceArea: ServiceAreaState;property switch
switch: { currentPosition: number; numberOfPositions?: number;};property temperatureMeasurement
temperatureMeasurement: { measuredValue: number | null; minMeasuredValue?: number | null; maxMeasuredValue?: number | null;};property thermostat
thermostat: ThermostatState;property valveConfigurationAndControl
valveConfigurationAndControl: ValveConfigurationAndControlState;property windowCovering
windowCovering: WindowCoveringState;interface ColorControlHandlers
interface ColorControlHandlers {}ColorControl cluster handler methods
Note: These use simplified argument types that the behavior passes through, not the raw matter.js request types. The behavior files transform the matter.js requests before calling plugin handlers.
property moveToColorLogic
moveToColorLogic?: MatterCommandHandler<{ targetX: number; targetY: number; transitionTime: number;}>;property moveToColorTemperatureLogic
moveToColorTemperatureLogic?: MatterCommandHandler<{ colorTemperatureMireds: number; transitionTime: number;}>;property moveToHueAndSaturationLogic
moveToHueAndSaturationLogic?: MatterCommandHandler<{ hue: number; saturation: number; transitionTime: number;}>;property moveToHueLogic
moveToHueLogic?: MatterCommandHandler<{ targetHue: number; direction: ColorControl.Direction; transitionTime: number; isEnhancedHue: boolean;}>;property moveToSaturationLogic
moveToSaturationLogic?: MatterCommandHandler<{ targetSaturation: number; transitionTime: number;}>;property stopAllColorMovement
stopAllColorMovement?: MatterCommandHandler;interface ColorControlState
interface ColorControlState {}ColorControl cluster state Based on @matter/main/clusters ColorControl
Note: We use a flexible interface to accommodate both ColorMode and EnhancedColorMode from Matter.js, which are distinct types in the spec but functionally compatible
property colorMode
colorMode?: number;property colorTemperatureMireds
colorTemperatureMireds?: number;property colorTempPhysicalMaxMireds
colorTempPhysicalMaxMireds?: number;property colorTempPhysicalMinMireds
colorTempPhysicalMinMireds?: number;property colorX
colorX?: number;property colorY
colorY?: number;property coupleColorTempToLevelMinMireds
coupleColorTempToLevelMinMireds?: number;property currentHue
currentHue?: number;property currentSaturation
currentSaturation?: number;property currentX
currentX?: number;property currentY
currentY?: number;property enhancedColorMode
enhancedColorMode?: number;property enhancedCurrentHue
enhancedCurrentHue?: number;property options
options?: number;property transitionTime
transitionTime?: number;interface DoorLockHandlers
interface DoorLockHandlers {}DoorLock cluster handler methods
property lockDoor
lockDoor?: MatterCommandHandler<DoorLock.LockDoorRequest>;property unlockDoor
unlockDoor?: MatterCommandHandler<DoorLock.UnlockDoorRequest>;interface DoorLockState
interface DoorLockState {}DoorLock cluster state
property actuatorEnabled
actuatorEnabled?: boolean;property doorClosedEvents
doorClosedEvents?: number;property doorOpenEvents
doorOpenEvents?: number;property doorState
doorState?: number | null;property lockState
lockState?: number | null;property lockType
lockType?: number;property openPeriod
openPeriod?: number;property operatingMode
operatingMode?: number;interface DynamicPlatformPlugin
interface DynamicPlatformPlugin extends PlatformPlugin {}Platform that is able to dynamically add or remove accessories. All configured accessories are stored to disk and recreated on startup. Accessories can be added or removed by using API.registerPlatformAccessories or API.unregisterPlatformAccessories.
property configureAccessory
configureAccessory: (accessory: PlatformAccessory) => void;This method is called for every PlatformAccessory, which is recreated from disk on startup. It should be used to properly initialize the Accessory and setup all event handlers for all services and their characteristics.
Parameter accessory
which needs to be configured
property configureMatterAccessory
configureMatterAccessory?: (accessory: MatterAccessory) => void;This method is called for every Matter accessory, which is recreated from cache on startup. It should be used to track cached accessories so the plugin can determine which accessories to re-register and which to remove (if they no longer exist in the external system).
This is the Matter equivalent of configureAccessory for HAP accessories.
Parameter accessory
cached Matter accessory
interface ExternalPortsConfiguration
interface ExternalPortsConfiguration {}interface FanControlHandlers
interface FanControlHandlers {}FanControl cluster handler methods
property fanModeChange
fanModeChange?: MatterCommandHandler<{ fanMode: FanControl.FanMode; oldFanMode: FanControl.FanMode;}>;property percentSettingChange
percentSettingChange?: MatterCommandHandler<{ percentSetting: number | null; oldPercentSetting: number | null;}>;interface FanControlState
interface FanControlState {}FanControl cluster state
property fanMode
fanMode?: number;property fanModeSequence
fanModeSequence?: number;property percentCurrent
percentCurrent?: number;property percentSetting
percentSetting?: number | null;property rockSetting
rockSetting?: number;property rockSupport
rockSupport?: number;property speedCurrent
speedCurrent?: number;property speedMax
speedMax?: number;property speedSetting
speedSetting?: number | null;property windSetting
windSetting?: number;property windSupport
windSupport?: number;interface HomebridgeConfig
interface HomebridgeConfig {}property accessories
accessories: AccessoryConfig[];property bridge
bridge: BridgeConfiguration;property disabledPlugins
disabledPlugins?: PluginIdentifier[];Array of disabled plugins. Unlike the plugins[] config which prevents plugins from being initialized at all, disabled plugins still have their alias loaded, so we can match config blocks of disabled plugins and show an appropriate message in the logs.
property matterPorts
matterPorts?: ExternalPortsConfiguration;property mdns
mdns?: any;Deprecated
property platforms
platforms: PlatformConfig[];property plugins
plugins?: PluginIdentifier[];property ports
ports?: ExternalPortsConfiguration;interface HomebridgeOptions
interface HomebridgeOptions {}property customPluginPath
customPluginPath?: string;property customStoragePath
customStoragePath?: string;property debugModeEnabled
debugModeEnabled?: boolean;property forceColourLogging
forceColourLogging?: boolean;property hideQRCode
hideQRCode?: boolean;property insecureAccess
insecureAccess?: boolean;property keepOrphanedCachedAccessories
keepOrphanedCachedAccessories?: boolean;property noLogTimestamps
noLogTimestamps?: boolean;property strictPluginResolution
strictPluginResolution?: boolean;interface IdentifyHandlers
interface IdentifyHandlers {}Identify cluster handler methods
property identify
identify?: MatterCommandHandler<Identify.IdentifyRequest>;interface IndependentPlatformPlugin
interface IndependentPlatformPlugin extends PlatformPlugin {}Platform that does not aim to add any accessories to the main bridge accessory. This platform should be used if for example a plugin aims to only expose external accessories. It should also be used when the platform doesn't intend to expose any accessories at all, like plugins providing a UI for homebridge.
interface LevelControlHandlers
interface LevelControlHandlers {}LevelControl cluster handler methods
property move
move?: MatterCommandHandler<LevelControl.MoveRequest>;property moveToLevel
moveToLevel?: MatterCommandHandler<LevelControl.MoveToLevelRequest>;property moveToLevelWithOnOff
moveToLevelWithOnOff?: MatterCommandHandler<LevelControl.MoveToLevelRequest>;property step
step?: MatterCommandHandler<LevelControl.StepRequest>;property stop
stop?: MatterCommandHandler<LevelControl.StopRequest>;interface LevelControlState
interface LevelControlState {}LevelControl cluster state
property currentLevel
currentLevel?: number;property maxLevel
maxLevel?: number;property minLevel
minLevel?: number;property onLevel
onLevel?: number | null;property options
options?: number;property remainingTime
remainingTime?: number;interface Logging
interface Logging {}Represents a logging device which can be used directly as a function (for INFO logging) but also has dedicated logging functions for respective logging levels.
property debug
debug: (message: string, ...parameters: any[]) => void;property error
error: (message: string, ...parameters: any[]) => void;property info
info: (message: string, ...parameters: any[]) => void;property log
log: (level: LogLevel, message: string, ...parameters: any[]) => void;property prefix
prefix: string;property success
success: (message: string, ...parameters: any[]) => void;property warn
warn: (message: string, ...parameters: any[]) => void;call signature
(message: string, ...parameters: any[]): void;interface MatterAccessoriesResponse
interface MatterAccessoriesResponse {}Matter accessories collection
property children
children: { [bridgeId: string]: MatterAccessoryInfo[];};Child bridge accessories indexed by bridge ID
interface MatterAccessory
interface MatterAccessory<T extends UnknownContext = UnknownContext> {}Matter Accessory - Plugin API Interface
This is the main interface that plugin developers use to register Matter accessories with Homebridge.
For composed devices (devices with multiple subcomponents), use the
partsarray to define child endpoints. Each part appears as a separate device in the Home app.
property clusters
clusters?: { [K in keyof ClusterStateMap]?: Partial<ClusterStateMap[K]>;} & { [clusterName: string]: Record<string, unknown>;};Initial cluster states Key is the cluster name, value is an object of attribute name -> value
Known clusters (onOff, levelControl, colorControl, etc.) provide full autocomplete. Unknown clusters are still supported with the fallback
Record<string, unknown>type.Example 1
clusters: {onOff: { onOff: true },levelControl: { currentLevel: 127, minLevel: 1, maxLevel: 254 },}Note: If using
parts, this is optional (main accessory may only be a container)
property context
context: T;Plugin developer storage - persists across restarts This is a way for plugin developers to store custom data with their accessory Similar to
PlatformAccessory.contextfor HAP accessories
property deviceType
deviceType: EndpointType;Matter device type (e.g., OnOffLightDevice, DimmableLightDevice, etc.)
property displayName
displayName: string;Display name for the accessory
property firmwareRevision
firmwareRevision?: string;Firmware revision (optional)
property getState
getState?: (cluster: string, attribute: string) => Promise<unknown> | unknown;Optional: Get current state handler Called when a Matter controller reads an attribute If not provided, the last set value is returned
Parameter cluster
Cluster name (e.g., 'onOff', 'levelControl')
Parameter attribute
Attribute name to read
Returns
Current value of the attribute
property handlers
handlers?: { [K in keyof ClusterHandlerMap]?: Partial<ClusterHandlerMap[K]>;} & { [clusterName: string]: MatterClusterHandlers;};Handlers for Matter commands (Home app -> Device)
These handlers are called when a user controls the accessory via the Home app. Use handlers to send commands to your actual device (cloud API, local network, etc.).
Known clusters (onOff, levelControl, colorControl, etc.) provide full autocomplete for handler method names and argument types.
Example 1
handlers: {onOff: {on: async () => { await device.turnOn() },off: async () => { await device.turnOff() },},levelControl: {moveToLevel: async (args) => {// args is typed as LevelControl.MoveToLevelRequestawait device.setBrightness(args?.level ?? 0)},},}
property hardwareRevision
hardwareRevision?: string;Hardware revision (optional)
property manufacturer
manufacturer: string;Manufacturer name
property model
model: string;Model name/identifier
property parts
parts?: MatterAccessoryPart[];Optional: Array of child endpoints (parts) for composed devices
Use this to create devices with multiple independent subcomponents, such as: - Power strip with multiple outlets - Window covering with shade + light - Multi-zone thermostat or speaker system
Each part appears as a separate device in the Home app and can be controlled independently.
Example:
parts: [{id: 'outlet-1',displayName: 'Outlet 1',deviceType: api.matter!.deviceTypes.OnOffOutlet,clusters: { onOff: { onOff: false } },handlers: {onOff: {on: async (args, context) => {console.log(`Part ${context.partId} turned on`)await controlOutlet(1, true)}}}},// ... more outlets]
property serialNumber
serialNumber: string;Serial number for the device
property softwareVersion
softwareVersion?: string;Software version (optional)
property UUID
UUID: string;Unique identifier for this accessory (must be unique across all accessories)
interface MatterAccessoryInfo
interface MatterAccessoryInfo {}Matter accessory information
property category
category: number;HAP category
property displayName
displayName: string;Display name
property matterInfo
matterInfo?: { /** Whether this is a bridged device */ bridged: boolean; /** Child bridge identifier if bridged */ childBridge?: string; /** Matter device type */ deviceType?: string;};Matter device information
property services
services?: ServiceInfo[];HAP services
property uuid
uuid: string;Unique identifier
interface MatterAPI
interface MatterAPI {}Matter API Interface.
Provides access to Matter protocol functionality for creating Matter-compatible accessories. Similar to
api.hapfor HomeKit Accessory Protocol.api.matterisMatterAPI | undefined— it's defined on bridges where Matter is configured (matchesapi.isMatterEnabled()), undefined otherwise. Plugins must use optional chaining or guard withisMatterEnabled().Example 1
// Defensive pattern (recommended for plugins that work with or without Matter):api.matter?.registerPlatformAccessories('homebridge-example', 'Example', [{UUID: api.hap.uuid.generate('my-light'),displayName: 'Living Room Light',deviceType: api.matter!.deviceTypes.OnOffLight,manufacturer: 'Example',model: 'Example Light',serialNumber: 'EX-001',clusters: { onOff: { onOff: false } },}])// Update state when device changes externallyawait api.matter?.updateAccessoryState(uuid, 'onOff', { onOff: true })// Read current stateconst state = await api.matter?.getAccessoryState(uuid, 'onOff')Example 2
// Guard pattern (recommended for plugins that always require Matter):if (!api.isMatterEnabled()) {log.error('Matter is not enabled for this bridge; the plugin requires Matter.')return}const matter = api.matter!await matter.registerPlatformAccessories(pluginId, platformName, accessories)
property clusterNames
readonly clusterNames: typeof clusterNames;Matter cluster names for type safety and autocomplete Use these constants with updateAccessoryState() and getAccessoryState()
Example 1
api.matter?.updateAccessoryState(uuid, api.matter?.clusterNames.OnOff, { onOff: true })api.matter?.getAccessoryState(uuid, api.matter?.clusterNames.LevelControl)
property clusters
readonly clusters: typeof clusters;Matter clusters - Direct access to Matter.js cluster definitions For advanced use cases requiring low-level cluster access
property deviceTypes
readonly deviceTypes: typeof deviceTypes;Matter device types for creating accessories. Maps friendly names to Matter.js device types, including stateless controller types like
GenericSwitch.
property getAccessoryState
getAccessoryState: { /** Typed overload for known clusters - returns typed state */ <K extends keyof ClusterStateMap>( uuid: string, cluster: K, partId?: string ): Promise<Partial<ClusterStateMap[K]> | undefined>; /** Fallback for unknown/custom clusters */ (uuid: string, cluster: string, partId?: string): Promise< Record<string, unknown> | undefined >;};Get a Matter accessory's current cluster state
Returns the current attribute values that are exposed to Matter controllers. Useful for: - Reading state after plugin restart - Verifying current state before making changes - Debugging and logging
Similar to HAP's
characteristic.valuegetter.Parameter uuid
The UUID of the accessory
Parameter cluster
The cluster name (use api.matter?.clusterNames for autocomplete)
Parameter partId
Optional: ID of the part to get state from (for composed devices with multiple endpoints)
Returns
Current cluster attribute values, or undefined if not found
Example 1
const state = await api.matter?.getAccessoryState(uuid, api.matter?.clusterNames.OnOff)if (state?.onOff) {console.log('Light is currently on')}Get state of a specific outlet in a power strip:const outletState = await api.matter?.getAccessoryState(uuid,api.matter?.clusterNames.OnOff,'outlet-3' // Part ID)
property registerPlatformAccessories
registerPlatformAccessories: ( pluginIdentifier: PluginIdentifier, platformName: PlatformName, accessories: MatterAccessory[]) => Promise<void>;Register Matter platform accessories (works exactly like HAP's registerPlatformAccessories)
Returns a promise that resolves when all accessories are fully registered and ready for state updates. This is especially important for external accessories (like robot vacuums) which require additional setup time.
Parameter pluginIdentifier
The plugin identifier (e.g., 'homebridge-example')
Parameter platformName
The platform name (e.g., 'ExamplePlatform')
Parameter accessories
Array of Matter accessories to register
property switch
readonly switch: SwitchAPI;Helpers for
GenericSwitchaccessories (stateless remotes and buttons).Device-type-specific helpers live under nested namespaces (e.g.
api.matter?.switch) to keep the top-levelMatterAPIsurface focused on the generic, UUID-addressed primitives.Example 1
// Simple single-button press and releaseawait api.matter?.switch.emit(uuid, 'press')await api.matter?.switch.emit(uuid, 'release')See Also
property types
readonly types: typeof MatterTypes;Matter types - Access to Matter.js cluster type definitions and enums Use these for type-safe attribute values (modes, states, etc.)
Example 1
Fan mode enumapi.matter?.updateAccessoryState(uuid,api.matter?.clusterNames.FanControl,{ fanMode: api.matter?.types.FanControl.FanMode.High })
property unregisterPlatformAccessories
unregisterPlatformAccessories: ( pluginIdentifier: PluginIdentifier, platformName: PlatformName, accessories: MatterAccessory[]) => Promise<void>;Unregister Matter platform accessories by UUID
Parameter pluginIdentifier
The plugin identifier
Parameter platformName
The platform name
Parameter accessories
Array of Matter accessories to unregister (only uuid is required)
property updateAccessoryState
updateAccessoryState: { /** Typed overload for known clusters - provides autocomplete for attribute names */ <K extends keyof ClusterStateMap>( uuid: string, cluster: K, attributes: Partial<ClusterStateMap[K]>, partId?: string ): Promise<void>; /** Fallback for unknown/custom clusters */ ( uuid: string, cluster: string, attributes: Record<string, unknown>, partId?: string ): Promise<void>;};Update a Matter accessory's cluster state when device changes externally
Use this for state updates from: - Native app controls - Physical button presses - Webhooks from cloud service - Polling results
DO NOT use inside handlers - state auto-updates after handlers complete! Similar to HAP's characteristic.updateValue()
Parameter uuid
The UUID of the accessory
Parameter cluster
The cluster name (use api.matter?.clusterNames for autocomplete)
Parameter attributes
The attributes to update
Parameter partId
Optional: ID of the part to update (for composed devices with multiple endpoints)
Example 1
Device turned on via native app:await api.matter?.updateAccessoryState(uuid,api.matter?.clusterNames.OnOff,{ onOff: true })Device brightness changed via physical button:await api.matter?.updateAccessoryState(uuid,api.matter?.clusterNames.LevelControl,{ currentLevel: 200 })Update a specific outlet in a power strip (composed device):await api.matter?.updateAccessoryState(uuid,api.matter?.clusterNames.OnOff,{ onOff: true },'outlet-2' // Part ID)
property updatePlatformAccessories
updatePlatformAccessories: (accessories: MatterAccessory[]) => Promise<void>;Update Matter platform accessories in the cache
Use this to update cached accessory information (displayName, manufacturer, model, etc.) without unregistering and re-registering. This is useful when: - Device name changes in the external system - Firmware version gets updated - Other metadata needs to be refreshed
Similar to api.updatePlatformAccessories() for HAP accessories.
Parameter accessories
Array of Matter accessories to update (must include uuid)
Example 1
// Update the display name after it changed in the external systemconst accessory = cachedAccessories.find(a => a.uuid === uuid)if (accessory) {accessory.displayName = 'New Name from API'await api.matter?.updatePlatformAccessories([accessory])}
property uuid
readonly uuid: HAP['uuid'];UUID generator (alias of api.hap.uuid for convenience) Use this to generate unique identifiers for Matter accessories
Example 1
const uuid = api.matter?.uuid.generate('my-light-unique-id')api.matter?.registerAccessory({uuid,displayName: 'Living Room Light',// ...})
interface MatterBridgeMetadata
interface MatterBridgeMetadata {}Metadata for a Matter bridge instance
property commissioned
commissioned?: boolean;Whether the bridge has been commissioned
property deviceCount
deviceCount: number;Number of devices exposed by this bridge
property identifier
identifier: string;Unique identifier for this bridge instance
property manuallyStopped
manuallyStopped?: boolean;Whether the bridge was manually stopped
property manualPairingCode
manualPairingCode?: string;Manual pairing code for commissioning
property name
name: string;Display name of the bridge
property pid
pid?: number;Process ID of the bridge if running as child process
property plugin
plugin: string;Plugin identifier that owns this bridge
property port
port?: number;Bridge port number
property qrCode
qrCode?: string;QR code payload for commissioning
property serialNumber
serialNumber?: string;Device serial number
property status
status: MatterBridgeStatus;Current operational status
property type
type: 'matter';Bridge type identifier (always 'matter')
property username
username?: string;Bridge username/identifier
interface MatterClusterHandlers
interface MatterClusterHandlers {}Matter cluster handlers interface
Maps command names to their handler functions. Each command can have custom argument types.
Note: Uses
anyinstead ofunknownto allow handlers to specify their own argument types without TypeScript variance errors. Handlers can still be strongly typed in their implementations.
index signature
[commandName: string]: MatterCommandHandler<any>;interface MatterCommissioningInfo
interface MatterCommissioningInfo {}Matter commissioning information
property commissioned
commissioned: boolean;Whether the device is commissioned
property manualPairingCode
manualPairingCode?: string;Manual pairing code for commissioning
property pin
pin?: string | null;PIN/pairing code
property port
port?: number;Port number if applicable
property qrCode
qrCode?: string;QR code payload for commissioning
property serialNumber
serialNumber?: string;Device serial number
property setupUri
setupUri?: string | null;Setup URI/QR code for pairing
property type
type?: 'matter';Bridge type (always 'matter')
interface MatterConfig
interface MatterConfig extends Record<string, unknown> {}Matter Configuration (for bridge or child bridge)
interface MatterErrorDetails
interface MatterErrorDetails {}Matter error details interface
property code
code?: string;property context
context?: string;property originalError
originalError?: Error;property recoverable
recoverable?: boolean;property type
type?: MatterErrorType;interface MatterServerConfig
interface MatterServerConfig {}Matter server configuration Used internally by MatterServer class
property debugModeEnabled
debugModeEnabled?: boolean;Enable debug mode for verbose logging
property displayName
displayName?: string;Display name for the Matter bridge/device
property externalAccessory
externalAccessory?: boolean;External accessory mode - device is not bridged and so added before server starts
property firmwareRevision
firmwareRevision?: string;Firmware revision (inherited from bridge config)
property manufacturer
manufacturer?: string;Manufacturer name (inherited from bridge config)
property model
model?: string;Model name (inherited from bridge config)
property networkInterfaces
networkInterfaces?: string[];Network interfaces to bind to (inherited from
bridge.bindconfig)
property port
port?: number;Server port
property serialNumber
serialNumber?: string;Serial number (inherited from bridge config)
property storagePath
storagePath?: string;Storage path
property uniqueId
uniqueId: string;Unique identifier (REQUIRED - must be unique for each Matter bridge instance)
interface OnOffHandlers
interface OnOffHandlers {}OnOff cluster handler methods
interface OnOffState
interface OnOffState {}OnOff cluster state
property onOff
onOff?: boolean;interface PlatformAccessory
interface PlatformAccessory {}interface PlatformConfig
interface PlatformConfig extends Record<string, any> {}interface PlatformPluginConstructor
interface PlatformPluginConstructor< Config extends PlatformConfig = PlatformConfig> {}construct signature
new (logger: Logging, config: Config, api: API): | DynamicPlatformPlugin | StaticPlatformPlugin | IndependentPlatformPlugin;interface PluginInitializer
interface PluginInitializer {}The {PluginInitializer} is a method which must be the default export for every homebridge plugin. It is called once the plugin is loaded from disk.
call signature
(api: API): void | Promise<void>;When the initializer is called the plugin must use the provided api instance and call the appropriate register methods - API.registerAccessory or API.registerPlatform - in order to correctly register for the following startup sequence.
Parameter api
interface RvcCleanModeHandlers
interface RvcCleanModeHandlers {}RvcCleanMode cluster handler methods
property changeToMode
changeToMode?: MatterCommandHandler<ModeBase.ChangeToModeRequest>;interface RvcCleanModeState
interface RvcCleanModeState {}RVC Clean Mode state
property currentMode
currentMode?: number;property onMode
onMode?: number | null;property startUpMode
startUpMode?: number | null;property supportedModes
supportedModes?: Array<{ label: string; mode: number; modeTags?: Array<{ value: number; }>;}>;interface RvcOperationalState
interface RvcOperationalState {}RVC (Robotic Vacuum Cleaner) Operational State
property countdownTime
countdownTime?: number | null;property currentPhase
currentPhase?: number | null;property operationalError
operationalError?: { errorStateId: number; errorStateLabel?: string; errorStateDetails?: string;};property operationalState
operationalState?: number;property operationalStateList
operationalStateList?: Array<{ operationalStateId: number; operationalStateLabel?: string;}>;property phaseList
phaseList?: string[] | null;interface RvcOperationalStateHandlers
interface RvcOperationalStateHandlers {}RvcOperationalState cluster handler methods
interface RvcRunModeHandlers
interface RvcRunModeHandlers {}RvcRunMode cluster handler methods
property changeToMode
changeToMode?: MatterCommandHandler<ModeBase.ChangeToModeRequest>;interface RvcRunModeState
interface RvcRunModeState {}RVC Run Mode state
property currentMode
currentMode?: number;property onMode
onMode?: number | null;property startUpMode
startUpMode?: number | null;property supportedModes
supportedModes?: Array<{ label: string; mode: number; modeTags?: Array<{ value: number; }>;}>;interface SerializedMatterAccessory
interface SerializedMatterAccessory {}Serializable Matter accessory (excludes functions and runtime state) Plugin developers should work with MatterAccessory instead.
property clusters
clusters?: { [clusterName: string]: { [attributeName: string]: unknown; };};property context
context: Record<string, unknown>;property deviceType
deviceType: { name?: string; code?: number;};property displayName
displayName: string;property firmwareRevision
firmwareRevision?: string;property hardwareRevision
hardwareRevision?: string;property manufacturer
manufacturer: string;property model
model: string;property parts
parts?: SerializedMatterAccessoryPart[];property platform
platform: string;property plugin
plugin: string;property serialNumber
serialNumber: string;property softwareVersion
softwareVersion?: string;property uuid
uuid: string;interface ServiceAreaHandlers
interface ServiceAreaHandlers {}ServiceArea cluster handler methods
property selectAreas
selectAreas?: MatterCommandHandler<ServiceArea.SelectAreasRequest>;property skipArea
skipArea?: MatterCommandHandler<ServiceArea.SkipAreaRequest>;interface ServiceAreaState
interface ServiceAreaState {}Service Area state
property currentArea
currentArea?: number | null;property estimatedEndTime
estimatedEndTime?: number | null;property progress
progress?: Array<{ areaId: number; status: number; totalOperationalTime?: number | null;}>;property selectedAreas
selectedAreas?: number[];property supportedAreas
supportedAreas?: Array<{ areaId: number; mapId: number | null; areaInfo: { locationInfo?: { locationName?: string; floorNumber?: number | null; areaType?: number | null; } | null; landmarkInfo?: { landmarkTag?: number; positionTag?: number | null; relativePositionTag?: number | null; } | null; };}>;property supportedMaps
supportedMaps?: Array<{ mapId: number; name: string;}>;interface StaticPlatformPlugin
interface StaticPlatformPlugin extends PlatformPlugin {}Platform that exposes all available characteristics at the start of the plugin. The set of accessories can not change at runtime. The bridge waits for all callbacks to return before it is published and accessible by HomeKit controllers.
property accessories
accessories: (callback: (foundAccessories: AccessoryPlugin[]) => void) => void;This method is called once at startup. The Platform should pass all accessories which need to be created to the callback in form of a AccessoryPlugin. The Platform must respond in a timely manner as otherwise the startup of the bridge would be unnecessarily delayed.
Parameter callback
interface SwitchAPI
interface SwitchAPI {}Switch helper API for
GenericSwitchaccessories (stateless remotes and buttons).Grouped under
api.matter?.switchso device-type-specific helpers don't crowd the top-levelMatterAPIsurface. Built on top ofupdateAccessoryStatefor the Switch cluster.
property emit
emit: ( uuid: string, action: 'press' | 'release', options?: { position?: number; partId?: string; }) => Promise<void>;Emit a switch action for a
GenericSwitchaccessory.High-level helper for stateless switches and remotes (e.g. Pico remotes, scene controllers). Sets the Switch cluster's
currentPositionattribute, which causes the Matter.jsSwitchServerto automatically fire the appropriate cluster events:| Action | When to use | Events fired by Matter.js | |-----------|-------------------------------------------|----------------------------------------| |
press| Physical button pressed / contact closed |initialPress| |release| Physical button released / contact opened |shortReleaseorlongRelease* |shortReleasevslongReleaseis determined automatically by the SwitchServer based on how long the button was held (configurable vialongPressDelay, default 2 s). Multi-press sequences (multiPressComplete) are generated automatically whenpress/releasecycles occur within themultiPressDelaywindow (default 300 ms).Parameter uuid
UUID of the GenericSwitch accessory
Parameter action
'press'to press the button,'release'to release itParameter options
Optional configuration
Parameter
options.position - Button position index (1-based). Defaults to
1. Use when the GenericSwitch has multiple positions (e.g. a multi-button remote).Parameter
options.partId - Part ID for composed devices with GenericSwitch parts.
Example 1
// Simple single-button press and releaseawait api.matter?.switch.emit(uuid, 'press')await api.matter?.switch.emit(uuid, 'release')// Multi-button remote: button 2 press and releaseawait api.matter?.switch.emit(uuid, 'press', { position: 2 })await api.matter?.switch.emit(uuid, 'release', { position: 2 })// GenericSwitch as a part in a composed deviceawait api.matter?.switch.emit(uuid, 'press', { partId: 'button-top' })await api.matter?.switch.emit(uuid, 'release', { partId: 'button-top' })
property emitGesture
emitGesture: ( uuid: string, gesture: 'singlePress' | 'doublePress' | 'longPress', options?: { position?: number; partId?: string; longPressDelayMs?: number; multiPressDelayMs?: number; }) => Promise<void>;Emit a high-level gesture for a
GenericSwitchaccessory.Convenience helper for integrations that already classify gestures (e.g. remotes that report only
single,double, orhold). Translates each gesture into the canonicalpress/releasesequence that Matter.jsSwitchServerexpects, so the server still determines the correct Switch cluster events (shortRelease,longRelease,multiPressComplete) based on timing.| Gesture | Translated sequence | |---------------|-----------------------------------------------------------------| |
singlePress|press→release| |doublePress|press→release→ *(multiPressDelayMs)* →press→release| |longPress|press→ *(longPressDelayMs)* →release|Default delays: -
longPressDelayMs–2500ms (just above the Matter.jslongPressDelaydefault of 2000 ms) -multiPressDelayMs–100ms (well within the Matter.jsmultiPressDelaywindow of 300 ms)Parameter uuid
UUID of the GenericSwitch accessory
Parameter gesture
The gesture to emit:
'singlePress','doublePress', or'longPress'Parameter options
Optional configuration
Parameter
options.position - Button position index (1-based). Defaults to
1.Parameter
options.partId - Part ID for composed devices with GenericSwitch parts.
Parameter
options.longPressDelayMs - How long (ms) to hold the button for a long press. Defaults to
2500. Only relevant for'longPress'.Parameter
options.multiPressDelayMs - Delay (ms) between the two press cycles of a double press. Defaults to
100. Only relevant for'doublePress'.Example 1
// Single press on a simple remoteawait api.matter?.switch.emitGesture(uuid, 'singlePress')// Double press on button 2 of a multi-button remoteawait api.matter?.switch.emitGesture(uuid, 'doublePress', { position: 2 })// Long press on a composed device partawait api.matter?.switch.emitGesture(uuid, 'longPress', { partId: 'button-top' })
interface ThermostatHandlers
interface ThermostatHandlers {}Thermostat cluster handler methods
property occupiedCoolingSetpointChange
occupiedCoolingSetpointChange?: MatterCommandHandler<{ occupiedCoolingSetpoint: number; oldOccupiedCoolingSetpoint: number;}>;property occupiedHeatingSetpointChange
occupiedHeatingSetpointChange?: MatterCommandHandler<{ occupiedHeatingSetpoint: number; oldOccupiedHeatingSetpoint: number;}>;property setpointRaiseLower
setpointRaiseLower?: MatterCommandHandler<Thermostat.SetpointRaiseLowerRequest>;property systemModeChange
systemModeChange?: MatterCommandHandler<{ systemMode: number; oldSystemMode: number;}>;interface ThermostatState
interface ThermostatState {}Thermostat cluster state
property absMaxCoolSetpointLimit
absMaxCoolSetpointLimit?: number;property absMaxHeatSetpointLimit
absMaxHeatSetpointLimit?: number;property absMinCoolSetpointLimit
absMinCoolSetpointLimit?: number;property absMinHeatSetpointLimit
absMinHeatSetpointLimit?: number;property controlSequenceOfOperation
controlSequenceOfOperation?: number;property externallyMeasuredOccupancy
externallyMeasuredOccupancy?: boolean;property externalMeasuredIndoorTemperature
externalMeasuredIndoorTemperature?: number | null;property localTemperature
localTemperature?: number | null;property maxCoolSetpointLimit
maxCoolSetpointLimit?: number;property maxHeatSetpointLimit
maxHeatSetpointLimit?: number;property minCoolSetpointLimit
minCoolSetpointLimit?: number;property minHeatSetpointLimit
minHeatSetpointLimit?: number;property minSetpointDeadBand
minSetpointDeadBand?: number;property numberOfDailyTransitions
numberOfDailyTransitions?: number;property numberOfWeeklyTransitions
numberOfWeeklyTransitions?: number;property occupancy
occupancy?: { occupied?: boolean;};property occupiedCoolingSetpoint
occupiedCoolingSetpoint?: number;property occupiedHeatingSetpoint
occupiedHeatingSetpoint?: number;property outdoorTemperature
outdoorTemperature?: number | null;property remoteSensing
remoteSensing?: number;property startOfWeek
startOfWeek?: number;property systemMode
systemMode?: number;property thermostatRunningMode
thermostatRunningMode?: number;property unoccupiedCoolingSetpoint
unoccupiedCoolingSetpoint?: number;property unoccupiedHeatingSetpoint
unoccupiedHeatingSetpoint?: number;interface WindowCoveringHandlers
interface WindowCoveringHandlers {}WindowCovering cluster handler methods
property downOrClose
downOrClose?: MatterCommandHandler;property goToLiftPercentage
goToLiftPercentage?: MatterCommandHandler<WindowCovering.GoToLiftPercentageRequest>;property goToTiltPercentage
goToTiltPercentage?: MatterCommandHandler<WindowCovering.GoToTiltPercentageRequest>;property stopMotion
stopMotion?: MatterCommandHandler;property upOrOpen
upOrOpen?: MatterCommandHandler;interface WindowCoveringState
interface WindowCoveringState {}WindowCovering cluster state Based on @matter/main/clusters WindowCovering
property configStatus
configStatus?: { operational?: boolean; onlineReserved?: boolean; online?: boolean; liftMovementReversed?: boolean; liftPositionAware?: boolean; tiltPositionAware?: boolean; liftEncoderControlled?: boolean; tiltEncoderControlled?: boolean;};property currentPositionLiftPercent100ths
currentPositionLiftPercent100ths?: number | null;property currentPositionTiltPercent100ths
currentPositionTiltPercent100ths?: number | null;property endProductType
endProductType?: number;property mode
mode?: number;property operationalStatus
operationalStatus?: { global: number; lift: number; tilt: number;};property safetyStatus
safetyStatus?: number;property targetPositionLiftPercent100ths
targetPositionLiftPercent100ths?: number | null;property targetPositionTiltPercent100ths
targetPositionTiltPercent100ths?: number | null;property type
type?: WindowCovering.WindowCoveringType;Enums
enum APIEvent
const enum APIEvent { DID_FINISH_LAUNCHING = 'didFinishLaunching', SHUTDOWN = 'shutdown',}member DID_FINISH_LAUNCHING
DID_FINISH_LAUNCHING = 'didFinishLaunching'Event is fired once homebridge has finished with booting up and initializing all components and plugins. When this event is fired it is possible that the Bridge accessory isn't published yet, if homebridge still needs to wait for some to finish accessory creation.
member SHUTDOWN
SHUTDOWN = 'shutdown'This event is fired when homebridge gets shutdown. This could be a regular shutdown or an unexpected crash. At this stage all Accessories are already unpublished and all PlatformAccessories are already saved to disk!
enum ChildMatterMessageType
enum ChildMatterMessageType { READY = 'ready', LOAD = 'load', LOADED = 'loaded', START = 'start', ONLINE = 'online', ADD_ACCESSORY = 'addAccessory', REMOVE_ACCESSORY = 'removeAccessory', STATUS_UPDATE = 'statusUpdate', ERROR = 'error', SHUTDOWN = 'shutdown',}IPC message types for Matter child bridges These message types coordinate communication between the main process and Matter child bridge processes
member ADD_ACCESSORY
ADD_ACCESSORY = 'addAccessory'Sent to/from child process to add a Matter accessory
member ERROR
ERROR = 'error'Sent from child process when an error occurs
member LOAD
LOAD = 'load'Sent to child process with bridge configuration
member LOADED
LOADED = 'loaded'Sent from child process when configuration has been loaded
member ONLINE
ONLINE = 'online'Sent from child process when Matter bridge is online and advertising
member READY
READY = 'ready'Sent from child process when ready to accept configuration
member REMOVE_ACCESSORY
REMOVE_ACCESSORY = 'removeAccessory'Sent to/from child process to remove a Matter accessory
member SHUTDOWN
SHUTDOWN = 'shutdown'Sent to child process to initiate graceful shutdown
member START
START = 'start'Sent to child process to start the Matter bridge
member STATUS_UPDATE
STATUS_UPDATE = 'statusUpdate'Sent from child process with commissioning and operational status updates
enum LogLevel
const enum LogLevel { INFO = 'info', SUCCESS = 'success', WARN = 'warn', ERROR = 'error', DEBUG = 'debug',}Log levels to indicate importance of the logged message. Every level corresponds to a certain color.
- INFO: no color - SUCCESS: green - WARN: yellow - ERROR: red - DEBUG: gray
Messages with DEBUG level are only displayed if explicitly enabled.
enum MatterAccessoryEventTypes
enum MatterAccessoryEventTypes { READY = 'ready',}Matter Accessory Event Types
Events that can be emitted by Matter accessories during their lifecycle.
Example 1
Listen for when a Matter accessory is readyconst accessory: MatterAccessory = { ... };api.matter?.publishExternalAccessories('plugin-name', [accessory]);const internal = accessory as any;internal._eventEmitter?.on(MatterAccessoryEventTypes.READY, (port: number) => {console.log(`Accessory ready on port ${port}`);});Matter Accessory
member READY
READY = 'ready'Emitted when the Matter server is ready and the accessory is available on the network. This is the main event to listen for to know when an external accessory is ready.
**HAP Equivalent:**
AccessoryEventTypes.ADVERTISEDParameter port
The port number the Matter server is listening on
enum MatterBridgeStatus
enum MatterBridgeStatus { PENDING = 'pending', OK = 'ok', DOWN = 'down',}Matter bridge status states
enum MatterErrorType
enum MatterErrorType { INITIALIZATION = 'INITIALIZATION', NETWORK = 'NETWORK', COMMISSIONING = 'COMMISSIONING', DEVICE_SYNC = 'DEVICE_SYNC', SERVER = 'SERVER', STORAGE = 'STORAGE', CONFIGURATION = 'CONFIGURATION', DEVICE_ERROR = 'DEVICE_ERROR', UNKNOWN = 'UNKNOWN',}Matter error type enum (for error handler categorization)
member COMMISSIONING
COMMISSIONING = 'COMMISSIONING'member CONFIGURATION
CONFIGURATION = 'CONFIGURATION'member DEVICE_ERROR
DEVICE_ERROR = 'DEVICE_ERROR'member DEVICE_SYNC
DEVICE_SYNC = 'DEVICE_SYNC'member INITIALIZATION
INITIALIZATION = 'INITIALIZATION'member NETWORK
NETWORK = 'NETWORK'member SERVER
SERVER = 'SERVER'member STORAGE
STORAGE = 'STORAGE'member UNKNOWN
UNKNOWN = 'UNKNOWN'enum PlatformAccessoryEvent
const enum PlatformAccessoryEvent { IDENTIFY = 'identify',}member IDENTIFY
IDENTIFY = 'identify'enum PluginType
const enum PluginType { ACCESSORY = 'accessory', PLATFORM = 'platform',}Type Aliases
type AccessoryIdentifier
type AccessoryIdentifier = string;type AccessoryName
type AccessoryName = string;type HAP
type HAP = API['hap'];type MatterClusterName
type MatterClusterName = (typeof clusterNames)[keyof typeof clusterNames];Type for Matter cluster names Provides type safety for cluster name strings
type MatterCommandHandler
type MatterCommandHandler<TArgs = unknown> = ( args: TArgs, context?: MatterHandlerContext) => Promise<void> | void;Matter command handler function type
Handlers can be synchronous or asynchronous (returning a Promise). The args parameter contains the command arguments passed by Matter.js (optional). The context parameter provides information about which part triggered the handler (for composed devices).
type PlatformIdentifier
type PlatformIdentifier = string;type PlatformName
type PlatformName = string;type PluginIdentifier
type PluginIdentifier = PluginName | ScopedPluginName;type PluginName
type PluginName = string;type ScopedPluginName
type ScopedPluginName = string;type UnknownContext
type UnknownContext = Record<string, any>;Namespaces
namespace MatterRequests
namespace MatterRequests {}Matter Cluster Command Request Types Use these types for handler arguments to get full type safety
Example 1
import type { MatterRequests } from 'homebridge'handlers: {levelControl: {moveToLevel: async (args: MatterRequests.MoveToLevel) => {console.log(`Level: ${args.level}`)}}}
type AddGroup
type AddGroup = Groups.AddGroupRequest;type AddGroupIfIdentifying
type AddGroupIfIdentifying = Groups.AddGroupIfIdentifyingRequest;type AddScene
type AddScene = ScenesManagement.AddSceneRequest;type ChangeToMode
type ChangeToMode = ModeBase.ChangeToModeRequest;type ClearCredential
type ClearCredential = DoorLock.ClearCredentialRequest;type ClearHolidaySchedule
type ClearHolidaySchedule = DoorLock.ClearHolidayScheduleRequest;type ClearUser
type ClearUser = DoorLock.ClearUserRequest;type ClearWeekDaySchedule
type ClearWeekDaySchedule = DoorLock.ClearWeekDayScheduleRequest;type ClearYearDaySchedule
type ClearYearDaySchedule = DoorLock.ClearYearDayScheduleRequest;type ColorLoopSet
type ColorLoopSet = ColorControl.ColorLoopSetRequest;type CopyScene
type CopyScene = ScenesManagement.CopySceneRequest;type EnhancedMoveHue
type EnhancedMoveHue = ColorControl.EnhancedMoveHueRequest;type EnhancedMoveToHue
type EnhancedMoveToHue = ColorControl.EnhancedMoveToHueRequest;type EnhancedMoveToHueAndSaturation
type EnhancedMoveToHueAndSaturation = ColorControl.EnhancedMoveToHueAndSaturationRequest;type EnhancedStepHue
type EnhancedStepHue = ColorControl.EnhancedStepHueRequest;type FanStep
type FanStep = FanControl.StepRequest;type GetCredentialStatus
type GetCredentialStatus = DoorLock.GetCredentialStatusRequest;type GetGroupMembership
type GetGroupMembership = Groups.GetGroupMembershipRequest;type GetHolidaySchedule
type GetHolidaySchedule = DoorLock.GetHolidayScheduleRequest;type GetSceneMembership
type GetSceneMembership = ScenesManagement.GetSceneMembershipRequest;type GetUser
type GetUser = DoorLock.GetUserRequest;type GetWeekDaySchedule
type GetWeekDaySchedule = DoorLock.GetWeekDayScheduleRequest;type GetYearDaySchedule
type GetYearDaySchedule = DoorLock.GetYearDayScheduleRequest;type GoToLiftPercentage
type GoToLiftPercentage = WindowCovering.GoToLiftPercentageRequest;type GoToTiltPercentage
type GoToTiltPercentage = WindowCovering.GoToTiltPercentageRequest;type IdentifyRequest
type IdentifyRequest = Identify.IdentifyRequest;type LockDoor
type LockDoor = DoorLock.LockDoorRequest;type Move
type Move = LevelControl.MoveRequest;type MoveColor
type MoveColor = ColorControl.MoveColorRequest;type MoveColorTemperature
type MoveColorTemperature = ColorControl.MoveColorTemperatureRequest;type MoveHue
type MoveHue = ColorControl.MoveHueRequest;type MoveSaturation
type MoveSaturation = ColorControl.MoveSaturationRequest;type MoveToClosestFrequency
type MoveToClosestFrequency = LevelControl.MoveToClosestFrequencyRequest;type MoveToColor
type MoveToColor = ColorControl.MoveToColorRequest;type MoveToColorTemperature
type MoveToColorTemperature = ColorControl.MoveToColorTemperatureRequest;type MoveToHue
type MoveToHue = ColorControl.MoveToHueRequest;type MoveToHueAndSaturation
type MoveToHueAndSaturation = ColorControl.MoveToHueAndSaturationRequest;type MoveToLevel
type MoveToLevel = LevelControl.MoveToLevelRequest;type MoveToSaturation
type MoveToSaturation = ColorControl.MoveToSaturationRequest;type OffWithEffect
type OffWithEffect = OnOff.OffWithEffectRequest;type OnWithTimedOff
type OnWithTimedOff = OnOff.OnWithTimedOffRequest;type OpenValve
type OpenValve = ValveConfigurationAndControl.OpenRequest;type RecallScene
type RecallScene = ScenesManagement.RecallSceneRequest;type RemoveAllScenes
type RemoveAllScenes = ScenesManagement.RemoveAllScenesRequest;type RemoveGroup
type RemoveGroup = Groups.RemoveGroupRequest;type RemoveScene
type RemoveScene = ScenesManagement.RemoveSceneRequest;type SelectAreas
type SelectAreas = ServiceArea.SelectAreasRequest;type SetActivePreset
type SetActivePreset = Thermostat.SetActivePresetRequest;type SetActiveSchedule
type SetActiveSchedule = Thermostat.SetActiveScheduleRequest;type SetAliroReaderConfig
type SetAliroReaderConfig = DoorLock.SetAliroReaderConfigRequest;type SetCredential
type SetCredential = DoorLock.SetCredentialRequest;type SetHolidaySchedule
type SetHolidaySchedule = DoorLock.SetHolidayScheduleRequest;type SetpointRaiseLower
type SetpointRaiseLower = Thermostat.SetpointRaiseLowerRequest;type SetUser
type SetUser = DoorLock.SetUserRequest;type SetWeekDaySchedule
type SetWeekDaySchedule = DoorLock.SetWeekDayScheduleRequest;type SetYearDaySchedule
type SetYearDaySchedule = DoorLock.SetYearDayScheduleRequest;type SkipArea
type SkipArea = ServiceArea.SkipAreaRequest;type Step
type Step = LevelControl.StepRequest;type StepColor
type StepColor = ColorControl.StepColorRequest;type StepColorTemperature
type StepColorTemperature = ColorControl.StepColorTemperatureRequest;type StepHue
type StepHue = ColorControl.StepHueRequest;type StepSaturation
type StepSaturation = ColorControl.StepSaturationRequest;type Stop
type Stop = LevelControl.StopRequest;type StopMoveStep
type StopMoveStep = ColorControl.StopMoveStepRequest;type StoreScene
type StoreScene = ScenesManagement.StoreSceneRequest;type TriggerEffect
type TriggerEffect = Identify.TriggerEffectRequest;type UnboltDoor
type UnboltDoor = DoorLock.UnboltDoorRequest;type UnlockDoor
type UnlockDoor = DoorLock.UnlockDoorRequest;type UnlockWithTimeout
type UnlockWithTimeout = DoorLock.UnlockWithTimeoutRequest;type ViewGroup
type ViewGroup = Groups.ViewGroupRequest;type ViewScene
type ViewScene = ScenesManagement.ViewSceneRequest;Package Files (17)
- dist/api.d.ts
- dist/bridgeService.d.ts
- dist/externalPortService.d.ts
- dist/index.d.ts
- dist/logger.d.ts
- dist/matter/SwitchAPI.d.ts
- dist/matter/accessoryCache.d.ts
- dist/matter/clusterHandlerMap.d.ts
- dist/matter/clusterStateMap.d.ts
- dist/matter/clusterTypes.d.ts
- dist/matter/errors.d.ts
- dist/matter/index.d.ts
- dist/matter/sharedTypes.d.ts
- dist/matter/types.d.ts
- dist/platformAccessory.d.ts
- dist/server.d.ts
- dist/user.d.ts
Dependencies (8)
Dev Dependencies (15)
Peer Dependencies (0)
No peer dependencies.
Badge
To add a badge like this oneto your package's README, use the codes available below.
You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/homebridge.
- Markdown[](https://www.jsdocs.io/package/homebridge)
- HTML<a href="https://www.jsdocs.io/package/homebridge"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>
- Updated .
Package analyzed in 5205 ms. - Missing or incorrect documentation? Open an issue for this package.
