Interface MatterAPI

Matter API Interface.

Provides access to Matter protocol functionality for creating Matter-compatible accessories. Similar to api.hap for HomeKit Accessory Protocol.

api.matter is MatterAPI | undefined — it's defined on bridges where Matter is configured (matches api.isMatterEnabled()), undefined otherwise. Plugins must use optional chaining or guard with isMatterEnabled().

Example

// 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 externally
await api.matter?.updateAccessoryState(uuid, 'onOff', { onOff: true })

// Read current state
const state = await api.matter?.getAccessoryState(uuid, 'onOff')

Example

// 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)

interface MatterAPI {
    clusterNames: {
        AirQuality: "airQuality";
        BasicInformation: "basicInformation";
        BooleanState: "booleanState";
        BridgedDeviceBasicInformation: "bridgedDeviceBasicInformation";
        CarbonMonoxideConcentrationMeasurement: "carbonMonoxideConcentrationMeasurement";
        ColorControl: "colorControl";
        DoorLock: "doorLock";
        FanControl: "fanControl";
        Identify: "identify";
        IlluminanceMeasurement: "illuminanceMeasurement";
        LevelControl: "levelControl";
        NitrogenDioxideConcentrationMeasurement: "nitrogenDioxideConcentrationMeasurement";
        OccupancySensing: "occupancySensing";
        OnOff: "onOff";
        OzoneConcentrationMeasurement: "ozoneConcentrationMeasurement";
        Pm10ConcentrationMeasurement: "pm10ConcentrationMeasurement";
        Pm25ConcentrationMeasurement: "pm25ConcentrationMeasurement";
        PowerSource: "powerSource";
        PumpConfigurationAndControl: "pumpConfigurationAndControl";
        RelativeHumidityMeasurement: "relativeHumidityMeasurement";
        RvcCleanMode: "rvcCleanMode";
        RvcOperationalState: "rvcOperationalState";
        RvcRunMode: "rvcRunMode";
        ServiceArea: "serviceArea";
        SmokeCoAlarm: "smokeCoAlarm";
        Switch: "switch";
        TemperatureMeasurement: "temperatureMeasurement";
        Thermostat: "thermostat";
        ValveConfigurationAndControl: "valveConfigurationAndControl";
        WindowCovering: "windowCovering";
    };
    clusters: {
        AirQuality: typeof AirQuality;
        BooleanState: typeof BooleanState;
        CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement;
        ColorControl: typeof ColorControl;
        DoorLock: typeof DoorLock;
        FanControl: typeof FanControl;
        LevelControl: typeof LevelControl;
        NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement;
        OnOff: typeof OnOff;
        OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement;
        Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement;
        Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement;
        RvcOperationalState: typeof RvcOperationalState;
        Thermostat: typeof Thermostat;
        ValveConfigurationAndControl: typeof ValveConfigurationAndControl;
        WindowCovering: typeof WindowCovering;
    };
    deviceTypes: {
        AirQualitySensor: AirQualitySensorDevice;
        BridgedNode: BridgedNodeEndpoint;
        ColorTemperatureLight: ColorTemperatureLightDevice;
        ContactSensor: ContactSensorDevice;
        DimmableLight: DimmableLightDevice;
        DimmableOutlet: DimmablePlugInUnitDevice;
        DoorLock: DoorLockDevice;
        ExtendedColorLight: ExtendedColorLightDevice;
        Fan: FanDevice;
        GenericSwitch: GenericSwitchDevice;
        HumiditySensor: HumiditySensorDevice;
        LeakSensor: WaterLeakDetectorDevice;
        LightSensor: LightSensorDevice;
        MotionSensor: OccupancySensorDevice;
        OnOffLight: OnOffLightDevice;
        OnOffOutlet: OnOffPlugInUnitDevice;
        OnOffSwitch: OnOffLightSwitchDevice;
        Pump: PumpDevice;
        RoboticVacuumCleaner: RoboticVacuumCleanerDevice;
        RoomAirConditioner: RoomAirConditionerDevice;
        SmokeSensor: SmokeCoAlarmDevice;
        TemperatureSensor: TemperatureSensorDevice;
        Thermostat: With<
            For<{}>,
            With<
                {},
                readonly [
                    Type<
                        typeof ThermostatServer,
                        WithSupportedFeatures<
                            Thermostat,
                            {
                                autoMode: true;
                                cooling: true;
                                heating: true;
                                localTemperatureNotExposed: false;
                                matterScheduleConfiguration: false;
                                occupancy: true;
                                presets: false;
                                scheduleConfiguration: false;
                                setback: false;
                            },
                        >,
                        Concrete,
                        typeof Internal,
                        "thermostat",
                    >,
                ],
            >,
        >;
        WaterValve: With<
            For<{}>,
            With<{} & {}, readonly [typeof ValveConfigurationAndControlServer]>,
        >;
        WindowCovering: WindowCoveringDevice;
    };
    getAccessoryState: {
        <K extends keyof ClusterStateMap>(
            uuid: string,
            cluster: K,
            partId?: string,
        ): Promise<Partial<ClusterStateMap[K]> | undefined>;
        (
            uuid: string,
            cluster: string,
            partId?: string,
        ): Promise<Record<string, unknown> | undefined>;
    };
    registerPlatformAccessories: (
        pluginIdentifier: string,
        platformName: string,
        accessories: MatterAccessory<UnknownContext>[],
    ) => Promise<void>;
    switch: SwitchAPI;
    types: {
        AirQuality: typeof AirQuality;
        BooleanState: typeof BooleanState;
        CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement;
        ColorControl: typeof ColorControl;
        DoorLock: typeof DoorLock;
        FanControl: typeof FanControl;
        LevelControl: typeof LevelControl;
        NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement;
        OnOff: typeof OnOff;
        OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement;
        Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement;
        Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement;
        RvcOperationalState: typeof RvcOperationalState;
        Thermostat: typeof Thermostat;
        ValveConfigurationAndControl: typeof ValveConfigurationAndControl;
        WindowCovering: typeof WindowCovering;
    };
    unregisterPlatformAccessories: (
        pluginIdentifier: string,
        platformName: string,
        accessories: MatterAccessory<UnknownContext>[],
    ) => Promise<void>;
    updateAccessoryState: {
        <K extends keyof ClusterStateMap>(
            uuid: string,
            cluster: K,
            attributes: Partial<ClusterStateMap[K]>,
            partId?: string,
        ): Promise<void>;
        (
            uuid: string,
            cluster: string,
            attributes: Record<string, unknown>,
            partId?: string,
        ): Promise<void>;
    };
    updatePlatformAccessories: (
        accessories: MatterAccessory<UnknownContext>[],
    ) => Promise<void>;
    uuid: __module;
}

Index

Properties

clusterNames clusters deviceTypes getAccessoryState registerPlatformAccessories switch types unregisterPlatformAccessories updateAccessoryState updatePlatformAccessories uuid

Properties

`Readonly`clusterNames

clusterNames: {
    AirQuality: "airQuality";
    BasicInformation: "basicInformation";
    BooleanState: "booleanState";
    BridgedDeviceBasicInformation: "bridgedDeviceBasicInformation";
    CarbonMonoxideConcentrationMeasurement: "carbonMonoxideConcentrationMeasurement";
    ColorControl: "colorControl";
    DoorLock: "doorLock";
    FanControl: "fanControl";
    Identify: "identify";
    IlluminanceMeasurement: "illuminanceMeasurement";
    LevelControl: "levelControl";
    NitrogenDioxideConcentrationMeasurement: "nitrogenDioxideConcentrationMeasurement";
    OccupancySensing: "occupancySensing";
    OnOff: "onOff";
    OzoneConcentrationMeasurement: "ozoneConcentrationMeasurement";
    Pm10ConcentrationMeasurement: "pm10ConcentrationMeasurement";
    Pm25ConcentrationMeasurement: "pm25ConcentrationMeasurement";
    PowerSource: "powerSource";
    PumpConfigurationAndControl: "pumpConfigurationAndControl";
    RelativeHumidityMeasurement: "relativeHumidityMeasurement";
    RvcCleanMode: "rvcCleanMode";
    RvcOperationalState: "rvcOperationalState";
    RvcRunMode: "rvcRunMode";
    ServiceArea: "serviceArea";
    SmokeCoAlarm: "smokeCoAlarm";
    Switch: "switch";
    TemperatureMeasurement: "temperatureMeasurement";
    Thermostat: "thermostat";
    ValveConfigurationAndControl: "valveConfigurationAndControl";
    WindowCovering: "windowCovering";
}

Matter cluster names for type safety and autocomplete Use these constants with updateAccessoryState() and getAccessoryState()

Example

api.matter?.updateAccessoryState(uuid, api.matter?.clusterNames.OnOff, { onOff: true })
api.matter?.getAccessoryState(uuid, api.matter?.clusterNames.LevelControl)

`Readonly`clusters

clusters: {
    AirQuality: typeof AirQuality;
    BooleanState: typeof BooleanState;
    CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement;
    ColorControl: typeof ColorControl;
    DoorLock: typeof DoorLock;
    FanControl: typeof FanControl;
    LevelControl: typeof LevelControl;
    NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement;
    OnOff: typeof OnOff;
    OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement;
    Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement;
    Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement;
    RvcOperationalState: typeof RvcOperationalState;
    Thermostat: typeof Thermostat;
    ValveConfigurationAndControl: typeof ValveConfigurationAndControl;
    WindowCovering: typeof WindowCovering;
}

Matter clusters - Direct access to Matter.js cluster definitions For advanced use cases requiring low-level cluster access

Type Declaration

AirQuality: typeof AirQuality
Definitions for the AirQuality cluster.

This cluster provides an interface to air quality classification using distinct levels with human-readable labels.

See
MatterSpecification.v142.Cluster § 2.9
BooleanState: typeof BooleanState
Definitions for the BooleanState cluster.

This cluster provides an interface to a boolean state.

See
MatterSpecification.v142.Cluster § 1.7
CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement
Definitions for the CarbonMonoxideConcentrationMeasurement cluster.
ColorControl: typeof ColorControl
Definitions for the ColorControl cluster.

This cluster provides an interface for changing the color of a light. Color is specified according to the CIE 1931 Color space. Color control is carried out in terms of x,y values, as defined by this specification.

Additionally, color may optionally be controlled in terms of color temperature, or as hue and saturation values based on optionally variable RGB and W color points. It is recommended that the hue and saturation are interpreted according to the HSV (a.k.a. HSB) color model.

Control over luminance is not included, as this is provided by means of the Level Control for Lighting cluster. It is recommended that the level provided by this cluster be interpreted as representing a proportion of the maximum intensity achievable at the current color.

See
MatterSpecification.v142.Cluster § 3.2
DoorLock: typeof DoorLock
Definitions for the DoorLock cluster.

The door lock cluster provides an interface to a generic way to secure a door. The physical object that provides the locking functionality is abstracted from the cluster. The cluster has a small list of mandatory attributes and functions and a list of optional features.

See
MatterSpecification.v142.Cluster § 5.2
FanControl: typeof FanControl
Definitions for the FanControl cluster.

This cluster specifies an interface to control the speed of a fan.

See
MatterSpecification.v142.Cluster § 4.4
LevelControl: typeof LevelControl
Definitions for the LevelControl cluster.

This cluster provides an interface for controlling a characteristic of a device that can be set to a level, for example the brightness of a light, the degree of closure of a door, or the power output of a heater.

See
MatterSpecification.v142.Cluster § 1.6
NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement
Definitions for the NitrogenDioxideConcentrationMeasurement cluster.
OnOff: typeof OnOff
Definitions for the OnOff cluster.

Attributes and commands for turning devices on and off.

See
MatterSpecification.v142.Cluster § 1.5
OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement
Definitions for the OzoneConcentrationMeasurement cluster.
Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement
Definitions for the Pm10ConcentrationMeasurement cluster.
Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement
Definitions for the Pm25ConcentrationMeasurement cluster.
RvcOperationalState: typeof RvcOperationalState
Definitions for the RvcOperationalState cluster.

This cluster is derived from the Operational State cluster and provides an interface for monitoring the operational state of a robotic vacuum cleaner.

See
MatterSpecification.v142.Cluster § 7.4
Thermostat: typeof Thermostat
Definitions for the Thermostat cluster.

This cluster provides an interface to the functionality of a thermostat.

See
MatterSpecification.v142.Cluster § 4.3
ValveConfigurationAndControl: typeof ValveConfigurationAndControl
Definitions for the ValveConfigurationAndControl cluster.

This cluster is used to configure a valve.

See
MatterSpecification.v142.Cluster § 4.6
WindowCovering: typeof WindowCovering
Definitions for the WindowCovering cluster.

The window covering cluster provides an interface for controlling and adjusting automatic window coverings such as drapery motors, automatic shades, curtains and blinds.

See
MatterSpecification.v142.Cluster § 5.3

`Readonly`deviceTypes

deviceTypes: {
    AirQualitySensor: AirQualitySensorDevice;
    BridgedNode: BridgedNodeEndpoint;
    ColorTemperatureLight: ColorTemperatureLightDevice;
    ContactSensor: ContactSensorDevice;
    DimmableLight: DimmableLightDevice;
    DimmableOutlet: DimmablePlugInUnitDevice;
    DoorLock: DoorLockDevice;
    ExtendedColorLight: ExtendedColorLightDevice;
    Fan: FanDevice;
    GenericSwitch: GenericSwitchDevice;
    HumiditySensor: HumiditySensorDevice;
    LeakSensor: WaterLeakDetectorDevice;
    LightSensor: LightSensorDevice;
    MotionSensor: OccupancySensorDevice;
    OnOffLight: OnOffLightDevice;
    OnOffOutlet: OnOffPlugInUnitDevice;
    OnOffSwitch: OnOffLightSwitchDevice;
    Pump: PumpDevice;
    RoboticVacuumCleaner: RoboticVacuumCleanerDevice;
    RoomAirConditioner: RoomAirConditionerDevice;
    SmokeSensor: SmokeCoAlarmDevice;
    TemperatureSensor: TemperatureSensorDevice;
    Thermostat: With<
        For<{}>,
        With<
            {},
            readonly [
                Type<
                    typeof ThermostatServer,
                    WithSupportedFeatures<
                        Thermostat,
                        {
                            autoMode: true;
                            cooling: true;
                            heating: true;
                            localTemperatureNotExposed: false;
                            matterScheduleConfiguration: false;
                            occupancy: true;
                            presets: false;
                            scheduleConfiguration: false;
                            setback: false;
                        },
                    >,
                    Concrete,
                    typeof Internal,
                    "thermostat",
                >,
            ],
        >,
    >;
    WaterValve: With<
        For<{}>,
        With<{} & {}, readonly [typeof ValveConfigurationAndControlServer]>,
    >;
    WindowCovering: WindowCoveringDevice;
}

Matter device types for creating accessories. Maps friendly names to Matter.js device types, including stateless controller types like GenericSwitch.

getAccessoryState

getAccessoryState: {
    <K extends keyof ClusterStateMap>(
        uuid: string,
        cluster: K,
        partId?: string,
    ): Promise<Partial<ClusterStateMap[K]> | undefined>;
    (
        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.value getter.

Type Declaration

- <K extends keyof ClusterStateMap>(
      uuid: string,
      cluster: K,
      partId?: string,
  ): Promise<Partial<ClusterStateMap[K]> | undefined>
- Typed overload for known clusters - returns typed state
  Type Parameters
  - K extends keyof ClusterStateMap
  Parameters
  - uuid: string
  - cluster: K
  - OptionalpartId: string
  Returns Promise<Partial<ClusterStateMap[K]> | undefined>
- (
      uuid: string,
      cluster: string,
      partId?: string,
  ): Promise<Record<string, unknown> | undefined>
- Fallback for unknown/custom clusters
  Parameters
  - uuid: string
  - cluster: string
  - OptionalpartId: string
  Returns Promise<Record<string, unknown> | undefined>

Param: uuid

The UUID of the accessory

Param: cluster

The cluster name (use api.matter?.clusterNames for autocomplete)

Param: 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

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
)

registerPlatformAccessories

registerPlatformAccessories: (
    pluginIdentifier: string,
    platformName: string,
    accessories: MatterAccessory<UnknownContext>[],
) => Promise<void>

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.

Type Declaration

- (
      pluginIdentifier: string,
      platformName: string,
      accessories: MatterAccessory<UnknownContext>[],
  ): Promise<void>
- Parameters
  - pluginIdentifier: string
    The plugin identifier (e.g., 'homebridge-example')
  - platformName: string
    The platform name (e.g., 'ExamplePlatform')
  - accessories: MatterAccessory<UnknownContext>[]
    Array of Matter accessories to register
  Returns Promise<void>

`Readonly`switch

switch: SwitchAPI

Helpers for GenericSwitch accessories (stateless remotes and buttons).

Device-type-specific helpers live under nested namespaces (e.g. api.matter?.switch) to keep the top-level MatterAPI surface focused on the generic, UUID-addressed primitives.

See

SwitchAPI

Example

// Simple single-button press and release
await api.matter?.switch.emit(uuid, 'press')
await api.matter?.switch.emit(uuid, 'release')

`Readonly`types

types: {
    AirQuality: typeof AirQuality;
    BooleanState: typeof BooleanState;
    CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement;
    ColorControl: typeof ColorControl;
    DoorLock: typeof DoorLock;
    FanControl: typeof FanControl;
    LevelControl: typeof LevelControl;
    NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement;
    OnOff: typeof OnOff;
    OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement;
    Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement;
    Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement;
    RvcOperationalState: typeof RvcOperationalState;
    Thermostat: typeof Thermostat;
    ValveConfigurationAndControl: typeof ValveConfigurationAndControl;
    WindowCovering: typeof WindowCovering;
}

Matter types - Access to Matter.js cluster type definitions and enums Use these for type-safe attribute values (modes, states, etc.)

Type Declaration

AirQuality: typeof AirQuality
Definitions for the AirQuality cluster.

This cluster provides an interface to air quality classification using distinct levels with human-readable labels.

See
MatterSpecification.v142.Cluster § 2.9
BooleanState: typeof BooleanState
Definitions for the BooleanState cluster.

This cluster provides an interface to a boolean state.

See
MatterSpecification.v142.Cluster § 1.7
CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement
Definitions for the CarbonMonoxideConcentrationMeasurement cluster.
ColorControl: typeof ColorControl
Definitions for the ColorControl cluster.

This cluster provides an interface for changing the color of a light. Color is specified according to the CIE 1931 Color space. Color control is carried out in terms of x,y values, as defined by this specification.

Additionally, color may optionally be controlled in terms of color temperature, or as hue and saturation values based on optionally variable RGB and W color points. It is recommended that the hue and saturation are interpreted according to the HSV (a.k.a. HSB) color model.

Control over luminance is not included, as this is provided by means of the Level Control for Lighting cluster. It is recommended that the level provided by this cluster be interpreted as representing a proportion of the maximum intensity achievable at the current color.

See
MatterSpecification.v142.Cluster § 3.2
DoorLock: typeof DoorLock
Definitions for the DoorLock cluster.

The door lock cluster provides an interface to a generic way to secure a door. The physical object that provides the locking functionality is abstracted from the cluster. The cluster has a small list of mandatory attributes and functions and a list of optional features.

See
MatterSpecification.v142.Cluster § 5.2
FanControl: typeof FanControl
Definitions for the FanControl cluster.

This cluster specifies an interface to control the speed of a fan.

See
MatterSpecification.v142.Cluster § 4.4
LevelControl: typeof LevelControl
Definitions for the LevelControl cluster.

This cluster provides an interface for controlling a characteristic of a device that can be set to a level, for example the brightness of a light, the degree of closure of a door, or the power output of a heater.

See
MatterSpecification.v142.Cluster § 1.6
NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement
Definitions for the NitrogenDioxideConcentrationMeasurement cluster.
OnOff: typeof OnOff
Definitions for the OnOff cluster.

Attributes and commands for turning devices on and off.

See
MatterSpecification.v142.Cluster § 1.5
OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement
Definitions for the OzoneConcentrationMeasurement cluster.
Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement
Definitions for the Pm10ConcentrationMeasurement cluster.
Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement
Definitions for the Pm25ConcentrationMeasurement cluster.
RvcOperationalState: typeof RvcOperationalState
Definitions for the RvcOperationalState cluster.

This cluster is derived from the Operational State cluster and provides an interface for monitoring the operational state of a robotic vacuum cleaner.

See
MatterSpecification.v142.Cluster § 7.4
Thermostat: typeof Thermostat
Definitions for the Thermostat cluster.

This cluster provides an interface to the functionality of a thermostat.

See
MatterSpecification.v142.Cluster § 4.3
ValveConfigurationAndControl: typeof ValveConfigurationAndControl
Definitions for the ValveConfigurationAndControl cluster.

This cluster is used to configure a valve.

See
MatterSpecification.v142.Cluster § 4.6
WindowCovering: typeof WindowCovering
Definitions for the WindowCovering cluster.

The window covering cluster provides an interface for controlling and adjusting automatic window coverings such as drapery motors, automatic shades, curtains and blinds.

See
MatterSpecification.v142.Cluster § 5.3

Example

Fan mode enum
api.matter?.updateAccessoryState(
  uuid,
  api.matter?.clusterNames.FanControl,
  { fanMode: api.matter?.types.FanControl.FanMode.High }
)

unregisterPlatformAccessories

unregisterPlatformAccessories: (
    pluginIdentifier: string,
    platformName: string,
    accessories: MatterAccessory<UnknownContext>[],
) => Promise<void>

Unregister Matter platform accessories by UUID

Type Declaration

- (
      pluginIdentifier: string,
      platformName: string,
      accessories: MatterAccessory<UnknownContext>[],
  ): Promise<void>
- Parameters
  - pluginIdentifier: string
    The plugin identifier
  - platformName: string
    The platform name
  - accessories: MatterAccessory<UnknownContext>[]
    Array of Matter accessories to unregister (only uuid is required)
  Returns Promise<void>

updateAccessoryState

updateAccessoryState: {
    <K extends keyof ClusterStateMap>(
        uuid: string,
        cluster: K,
        attributes: Partial<ClusterStateMap[K]>,
        partId?: string,
    ): Promise<void>;
    (
        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()

Type Declaration

- <K extends keyof ClusterStateMap>(
      uuid: string,
      cluster: K,
      attributes: Partial<ClusterStateMap[K]>,
      partId?: string,
  ): Promise<void>
- Typed overload for known clusters - provides autocomplete for attribute names
  Type Parameters
  - K extends keyof ClusterStateMap
  Parameters
  - uuid: string
  - cluster: K
  - attributes: Partial<ClusterStateMap[K]>
  - OptionalpartId: string
  Returns Promise<void>
- (
      uuid: string,
      cluster: string,
      attributes: Record<string, unknown>,
      partId?: string,
  ): Promise<void>
- Fallback for unknown/custom clusters
  Parameters
  - uuid: string
  - cluster: string
  - attributes: Record<string, unknown>
  - OptionalpartId: string
  Returns Promise<void>

Param: uuid

The UUID of the accessory

Param: cluster

The cluster name (use api.matter?.clusterNames for autocomplete)

Param: attributes

The attributes to update

Param: partId

Optional: ID of the part to update (for composed devices with multiple endpoints)

Example

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
)

updatePlatformAccessories

updatePlatformAccessories: (
accessories: MatterAccessory<UnknownContext>[],
) => 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.

Type Declaration

- (accessories: MatterAccessory<UnknownContext>[]): Promise<void>
- Parameters
  - accessories: MatterAccessory<UnknownContext>[]
    Array of Matter accessories to update (must include uuid)
  Returns Promise<void>

Example

// Update the display name after it changed in the external system
const accessory = cachedAccessories.find(a => a.uuid === uuid)
if (accessory) {
  accessory.displayName = 'New Name from API'
  await api.matter?.updatePlatformAccessories([accessory])
}

`Readonly`uuid

uuid: __module

UUID generator (alias of api.hap.uuid for convenience) Use this to generate unique identifiers for Matter accessories

Example

const uuid = api.matter?.uuid.generate('my-light-unique-id')
api.matter?.registerAccessory({
  uuid,
  displayName: 'Living Room Light',
  // ...
})

Interface MatterAPI

Example

Example

Index

Properties

Properties

ReadonlyclusterNames

Example

Readonlyclusters

Type Declaration

AirQuality: typeof AirQuality

See

BooleanState: typeof BooleanState

See

CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement

ColorControl: typeof ColorControl

See

DoorLock: typeof DoorLock

See

FanControl: typeof FanControl

See

LevelControl: typeof LevelControl

See

NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement

OnOff: typeof OnOff

See

OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement

Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement

Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement

RvcOperationalState: typeof RvcOperationalState

See

Thermostat: typeof Thermostat

See

ValveConfigurationAndControl: typeof ValveConfigurationAndControl

See

WindowCovering: typeof WindowCovering

See

ReadonlydeviceTypes

getAccessoryState

Type Declaration

Type Parameters

Parameters

Returns Promise<Partial<ClusterStateMap[K]> | undefined>

Parameters

Returns Promise<Record<string, unknown> | undefined>

Param: uuid

Param: cluster

Param: partId

Returns

Example

registerPlatformAccessories

Type Declaration

Parameters

Returns Promise<void>

Readonlyswitch

See

Example

Readonlytypes

Type Declaration

AirQuality: typeof AirQuality

See

BooleanState: typeof BooleanState

See

CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement

ColorControl: typeof ColorControl

See

DoorLock: typeof DoorLock

See

FanControl: typeof FanControl

See

LevelControl: typeof LevelControl

See

NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement

OnOff: typeof OnOff

See

OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement

Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement

Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement

RvcOperationalState: typeof RvcOperationalState

See

`Readonly`clusterNames

`Readonly`clusters

`Readonly`deviceTypes

`Readonly`switch

`Readonly`types

`Readonly`uuid