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";
        ClosureControl: "closureControl";
        ColorControl: "colorControl";
        DeviceEnergyManagement: "deviceEnergyManagement";
        DeviceEnergyManagementMode: "deviceEnergyManagementMode";
        DoorLock: "doorLock";
        ElectricalEnergyMeasurement: "electricalEnergyMeasurement";
        ElectricalPowerMeasurement: "electricalPowerMeasurement";
        EnergyEvse: "energyEvse";
        EnergyEvseMode: "energyEvseMode";
        FanControl: "fanControl";
        Identify: "identify";
        IlluminanceMeasurement: "illuminanceMeasurement";
        KeypadInput: "keypadInput";
        LevelControl: "levelControl";
        MediaPlayback: "mediaPlayback";
        MeterIdentification: "meterIdentification";
        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";
        WaterHeaterManagement: "waterHeaterManagement";
        WaterHeaterMode: "waterHeaterMode";
        WindowCovering: "windowCovering";
    };
    clusters: {
        AirQuality: typeof AirQuality;
        BooleanState: typeof BooleanState;
        CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement;
        ClosureControl: typeof ClosureControl;
        ColorControl: typeof ColorControl;
        DeviceEnergyManagement: typeof DeviceEnergyManagement;
        DoorLock: typeof DoorLock;
        ElectricalEnergyMeasurement: typeof ElectricalEnergyMeasurement;
        ElectricalPowerMeasurement: typeof ElectricalPowerMeasurement;
        EnergyEvse: typeof EnergyEvse;
        FanControl: typeof FanControl;
        KeypadInput: typeof KeypadInput;
        LevelControl: typeof LevelControl;
        MediaPlayback: typeof MediaPlayback;
        NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement;
        OnOff: typeof OnOff;
        OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement;
        Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement;
        Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement;
        PowerTopology: typeof PowerTopology;
        RvcOperationalState: typeof RvcOperationalState;
        Thermostat: typeof Thermostat;
        ValveConfigurationAndControl: typeof ValveConfigurationAndControl;
        WindowCovering: typeof WindowCovering;
    };
    deviceRequirements: {
        Closure: typeof ClosureRequirements;
        DeviceEnergyManagement: typeof DeviceEnergyManagementRequirements;
        ElectricalEnergyTariff: typeof ElectricalEnergyTariffRequirements;
        ElectricalMeter: typeof ElectricalMeterRequirements;
        ElectricalSensor: typeof ElectricalSensorRequirements;
        ElectricalUtilityMeter: typeof ElectricalUtilityMeterRequirements;
        EnergyEvse: typeof EnergyEvseRequirements;
        GenericSwitch: typeof GenericSwitchRequirements;
        MotionSensor: typeof OccupancySensorRequirements;
        PowerSource: typeof PowerSourceRequirements;
        Pump: typeof PumpRequirements;
        RoboticVacuumCleaner: typeof RoboticVacuumCleanerRequirements;
        RoomAirConditioner: typeof RoomAirConditionerRequirements;
        SmokeSensor: typeof SmokeCoAlarmRequirements;
        Thermostat: typeof ThermostatRequirements;
        WaterHeater: typeof WaterHeaterRequirements;
        WaterValve: typeof WaterValveRequirements;
        WindowCovering: typeof WindowCoveringRequirements;
    };
    deviceTypes: {
        AirQualitySensor: With<
            For<{}>,
            With<
                {} & {},
                readonly [
                    Type<
                        typeof AirQualityServer,
                        WithSupportedFeatures<
                            AirQuality,
                            { extremelyPoor: true; fair: true; moderate: true; veryPoor: true },
                        >,
                        Concrete,
                        new () => {},
                        "airQuality",
                    >,
                ],
            >,
            {},
        >;
        BatteryStorage: BatteryStorageDevice;
        BridgedNode: BridgedNodeEndpoint;
        Closure: With<
            For<{}>,
            With<
                {} & {},
                readonly [
                    Type<
                        typeof DefaultClosureControlServer,
                        WithSupportedFeatures<
                            ClosureControl,
                            {
                                calibration: false;
                                instantaneous: false;
                                manuallyOperable: false;
                                motionLatching: false;
                                pedestrian: false;
                                positioning: true;
                                protection: false;
                                speed: false;
                                ventilation: false;
                            },
                        >,
                        Concrete,
                        new () => {},
                        "closureControl",
                    >,
                ],
            >,
            {},
        >;
        ColorTemperatureLight: ColorTemperatureLightDevice;
        ContactSensor: ContactSensorDevice;
        DeviceEnergyManagement: With<
            For<{}>,
            With<
                {},
                readonly [
                    Type<
                        typeof DefaultDeviceEnergyManagementServer,
                        WithSupportedFeatures<
                            WithSupportedFeatures<
                                DeviceEnergyManagement,
                                {
                                    constraintBasedAdjustment: true;
                                    forecastAdjustment: true;
                                    pausable: true;
                                    powerAdjustment: true;
                                    powerForecastReporting: true;
                                    startTimeAdjustment: true;
                                    stateForecastReporting: false;
                                },
                            >,
                            {
                                constraintBasedAdjustment: false;
                                forecastAdjustment: false;
                                pausable: false;
                                powerAdjustment: false;
                                powerForecastReporting: false;
                                startTimeAdjustment: false;
                                stateForecastReporting: false;
                            },
                        >,
                        Concrete,
                        new () => {},
                        "deviceEnergyManagement",
                    >,
                ],
            >,
            {},
        >;
        DimmableLight: DimmableLightDevice;
        DimmableOutlet: DimmablePlugInUnitDevice;
        DoorLock: DoorLockDevice;
        ElectricalEnergyTariff: ElectricalEnergyTariffDevice;
        ElectricalMeter: ElectricalMeterDevice;
        ElectricalSensor: ElectricalSensorEndpoint;
        ElectricalUtilityMeter: ElectricalUtilityMeterDevice;
        EnergyEvse: With<
            For<{}>,
            With<
                {} & {},
                readonly [
                    Type<
                        typeof DefaultEnergyEvseServer,
                        WithSupportedFeatures<
                            WithSupportedFeatures<
                                EnergyEvse,
                                {
                                    chargingPreferences: true;
                                    plugAndCharge: true;
                                    rfid: true;
                                    soCReporting: true;
                                    v2X: true;
                                },
                            >,
                            {
                                chargingPreferences: false;
                                plugAndCharge: false;
                                rfid: false;
                                soCReporting: false;
                                v2X: false;
                            },
                        >,
                        Concrete,
                        new () => {},
                        "energyEvse",
                    >,
                ],
            >,
            {},
        >;
        ExtendedColorLight: ExtendedColorLightDevice;
        Fan: FanDevice;
        GenericSwitch: With<
            For<{}>,
            With<
                {},
                readonly [
                    Type<
                        typeof SwitchServer,
                        WithSupportedFeatures<
                            WithSupportedFeatures<WithSupportedFeatures<Switch, {}>, {}>,
                            {
                                actionSwitch: false;
                                latchingSwitch: false;
                                momentarySwitch: true;
                                momentarySwitchLongPress: true;
                                momentarySwitchMultiPress: true;
                                momentarySwitchRelease: true;
                            },
                        >,
                        Concrete,
                        typeof Internal,
                        "switch",
                    >,
                ],
            >,
            {},
        >;
        HumiditySensor: HumiditySensorDevice;
        LeakSensor: WaterLeakDetectorDevice;
        LightSensor: LightSensorDevice;
        MediaPlayer: With<
            For<{}>,
            With<
                {} & {} & {},
                readonly [
                    typeof DefaultMediaPlaybackServer,
                    typeof DefaultKeypadInputServer,
                ],
            >,
            {},
        >;
        MotionSensor: With<
            For<{}>,
            With<
                {},
                readonly [
                    Type<
                        typeof OccupancySensingServer,
                        WithSupportedFeatures<
                            OccupancySensing,
                            {
                                activeInfrared: false;
                                occupancyEvent: true;
                                other: false;
                                passiveInfrared: true;
                                physicalContact: false;
                                radar: false;
                                rfSensing: false;
                                ultrasonic: false;
                                vision: false;
                            },
                        >,
                        Concrete,
                        new () => {},
                        "occupancySensing",
                    >,
                ],
            >,
            {},
        >;
        OnOffLight: OnOffLightDevice;
        OnOffOutlet: OnOffPlugInUnitDevice;
        OnOffSwitch: OnOffLightSwitchDevice;
        PowerSource: PowerSourceEndpoint;
        Pump: With<
            For<{}>,
            With<
                {} & {},
                readonly [
                    Type<
                        typeof PumpConfigurationAndControlServer,
                        WithSupportedFeatures<
                            PumpConfigurationAndControl,
                            {
                                automatic: false;
                                compensatedPressure: false;
                                constantFlow: false;
                                constantPressure: false;
                                constantSpeed: true;
                                constantTemperature: false;
                                localOperation: false;
                            },
                        >,
                        Concrete,
                        new () => {},
                        "pumpConfigurationAndControl",
                    >,
                ],
            >,
            {},
        >;
        RoboticVacuumCleaner: RoboticVacuumCleanerDevice;
        RoomAirConditioner: With<
            For<{}>,
            With<
                {} & {},
                readonly [
                    Type<
                        typeof ThermostatServer,
                        WithSupportedFeatures<
                            WithSupportedFeatures<WithSupportedFeatures<Thermostat, {}>, {}>,
                            {
                                autoMode: false;
                                cooling: true;
                                events: false;
                                heating: true;
                                localTemperatureNotExposed: false;
                                matterScheduleConfiguration: false;
                                occupancy: false;
                                presets: false;
                                setback: false;
                                thermostatSuggestions: false;
                            },
                        >,
                        Concrete,
                        typeof Internal,
                        "thermostat",
                    >,
                ],
            >,
            {},
        >;
        SmokeSensor: SmokeCoAlarmDevice;
        SolarPower: SolarPowerDevice;
        Speaker: SpeakerDevice;
        TemperatureSensor: TemperatureSensorDevice;
        Thermostat: ThermostatDevice;
        WaterHeater: With<
            For<{}>,
            With<
                {} & {} & {},
                readonly [
                    Type<
                        Type<
                            typeof ThermostatServer,
                            WithSupportedFeatures<
                                WithSupportedFeatures<WithSupportedFeatures<Thermostat, {}>, {}>,
                                {},
                            >,
                            Concrete,
                            typeof Internal,
                            "thermostat",
                        >,
                        WithSupportedFeatures<
                            WithSupportedFeatures<
                                WithSupportedFeatures<WithSupportedFeatures<Thermostat, {}>, {}>,
                                {},
                            >,
                            {
                                autoMode: false;
                                cooling: false;
                                events: false;
                                heating: true;
                                localTemperatureNotExposed: false;
                                matterScheduleConfiguration: false;
                                occupancy: false;
                                presets: false;
                                setback: false;
                                thermostatSuggestions: false;
                            },
                        >,
                        Concrete,
                        typeof Internal,
                        "thermostat",
                    >,
                    typeof DefaultWaterHeaterManagementServer,
                ],
            >,
            {},
        >;
        WaterValve: With<
            For<{}>,
            With<
                {} & {},
                readonly [typeof DefaultValveConfigurationAndControlServer],
            >,
            {},
        >;
        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>;
    status: {
        Busy: typeof Busy;
        ConstraintError: typeof ConstraintError;
        Failure: typeof Failure;
        InvalidAction: typeof InvalidAction;
        InvalidInState: typeof InvalidInState;
        isMatterProtocolError: (error: unknown) => error is MatterProtocolError;
        MatterProtocolError: typeof MatterProtocolError;
        NotFound: typeof NotFound;
        PermissionDenied: typeof PermissionDenied;
        ResourceExhausted: typeof ResourceExhausted;
        Timeout: typeof Timeout;
    };
    switch: SwitchAPI;
    types: {
        AirQuality: typeof AirQuality;
        BooleanState: typeof BooleanState;
        CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement;
        ClosureControl: typeof ClosureControl;
        ColorControl: typeof ColorControl;
        DeviceEnergyManagement: typeof DeviceEnergyManagement;
        DoorLock: typeof DoorLock;
        ElectricalEnergyMeasurement: typeof ElectricalEnergyMeasurement;
        ElectricalPowerMeasurement: typeof ElectricalPowerMeasurement;
        EnergyEvse: typeof EnergyEvse;
        FanControl: typeof FanControl;
        KeypadInput: typeof KeypadInput;
        LevelControl: typeof LevelControl;
        MediaPlayback: typeof MediaPlayback;
        NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement;
        OnOff: typeof OnOff;
        OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement;
        Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement;
        Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement;
        PowerTopology: typeof PowerTopology;
        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 deviceRequirements deviceTypes getAccessoryState registerPlatformAccessories status switch types unregisterPlatformAccessories updateAccessoryState updatePlatformAccessories uuid

Properties

`Readonly`clusterNames

clusterNames: {
    AirQuality: "airQuality";
    BasicInformation: "basicInformation";
    BooleanState: "booleanState";
    BridgedDeviceBasicInformation: "bridgedDeviceBasicInformation";
    CarbonMonoxideConcentrationMeasurement: "carbonMonoxideConcentrationMeasurement";
    ClosureControl: "closureControl";
    ColorControl: "colorControl";
    DeviceEnergyManagement: "deviceEnergyManagement";
    DeviceEnergyManagementMode: "deviceEnergyManagementMode";
    DoorLock: "doorLock";
    ElectricalEnergyMeasurement: "electricalEnergyMeasurement";
    ElectricalPowerMeasurement: "electricalPowerMeasurement";
    EnergyEvse: "energyEvse";
    EnergyEvseMode: "energyEvseMode";
    FanControl: "fanControl";
    Identify: "identify";
    IlluminanceMeasurement: "illuminanceMeasurement";
    KeypadInput: "keypadInput";
    LevelControl: "levelControl";
    MediaPlayback: "mediaPlayback";
    MeterIdentification: "meterIdentification";
    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";
    WaterHeaterManagement: "waterHeaterManagement";
    WaterHeaterMode: "waterHeaterMode";
    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;
    ClosureControl: typeof ClosureControl;
    ColorControl: typeof ColorControl;
    DeviceEnergyManagement: typeof DeviceEnergyManagement;
    DoorLock: typeof DoorLock;
    ElectricalEnergyMeasurement: typeof ElectricalEnergyMeasurement;
    ElectricalPowerMeasurement: typeof ElectricalPowerMeasurement;
    EnergyEvse: typeof EnergyEvse;
    FanControl: typeof FanControl;
    KeypadInput: typeof KeypadInput;
    LevelControl: typeof LevelControl;
    MediaPlayback: typeof MediaPlayback;
    NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement;
    OnOff: typeof OnOff;
    OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement;
    Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement;
    Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement;
    PowerTopology: typeof PowerTopology;
    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.v161.Cluster § 2.9
BooleanState: typeof BooleanState

Definitions for the BooleanState cluster.

This cluster provides an interface to a boolean state.

See
MatterSpecification.v161.Cluster § 1.7
CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement

Definitions for the CarbonMonoxideConcentrationMeasurement cluster.
ClosureControl: typeof ClosureControl

Definitions for the ClosureControl cluster.

This cluster provides an interface for controlling a Closure.

See
MatterSpecification.v161.Cluster § 5.4
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.v161.Cluster § 3.2
DeviceEnergyManagement: typeof DeviceEnergyManagement
Definitions for the DeviceEnergyManagement cluster.

This cluster allows a client to manage the power draw of a device. An example of such a client could be an Energy Management System (EMS) which controls an Energy Smart Appliance (ESA).

In most deployments the EMS will be the client, and the ESA will host the Device Energy Management Cluster server.

This cluster is intended to be generic in nature and could apply to any electrical load or generator (e.g. a Battery Electric Storage System - BESS, solar PV inverter, EVSE, HVAC, heat pump, hot water heater, white goods appliances etc).

It consists of the following areas which shall be supported by all devices implementing this cluster:
- Description of ESA and its capabilities & power limits (sometimes referred to as a nameplate)
- Current state of operation (including user opt-out, safety limitations / alarms)
There are some optional capabilities that some ESAs may be able to offer:
- Ability to control the load or generation
- Forecast data, including when it can be flexible (i.e. modify the power or time period)
- The ability to have their power profile adjusted by an EMS, and to provide an updated Forecast back to the EMS.
This allows the EMS to manage multiple home loads and where ESAs can be flexible, continuously optimizing the home energy to minimize cost, reduce CO2 impact, maximize self-consumption of solar PV and provide Demand Side Response (DSR) Grid services.

It is likely that the ESA may also use the Pricing Cluster to obtain incentive signals such as 'grid carbon intensity', 'time of use' or 'type of use' tariffs to schedule its operation to run at the cheapest and greenest times.

Note

NOTE: Grid Services are market dependent and will use other protocols ([OpenADR] / [IEEE2030.5]) to communicate grid events to the EMS. These are outside the scope of Matter.

Note

NOTE: Different markets may follow different approaches, but the UK [PAS1878] and [EUCodeOfConduct] give examples of how ESAs may be mandated to support these features in the future.
See
MatterSpecification.v161.Cluster § 9.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.v161.Cluster § 5.2
ElectricalEnergyMeasurement: typeof ElectricalEnergyMeasurement

Definitions for the ElectricalEnergyMeasurement cluster.

This cluster provides a mechanism for querying data about the electrical energy imported or provided by the server.

See
MatterSpecification.v161.Cluster § 2.12
ElectricalPowerMeasurement: typeof ElectricalPowerMeasurement

Definitions for the ElectricalPowerMeasurement cluster.

This cluster provides a mechanism for querying data about electrical power as measured by the server.

See
MatterSpecification.v161.Cluster § 2.13
EnergyEvse: typeof EnergyEvse

Definitions for the EnergyEvse cluster.

Electric Vehicle Supply Equipment (EVSE) is equipment used to charge an Electric Vehicle (EV) or Plug-In Hybrid Electric Vehicle. This cluster provides an interface to the functionality of Electric Vehicle Supply Equipment (EVSE) management.

Devices targeted by this cluster include Electric Vehicle Supply Equipment (EVSE). The cluster generically assumes a signaling protocol (J1772 in NA and IEC61851 in Europe and Asia) between the EVSE and Electric Vehicle (EV) that utilizes a pilot signal to manage the states of the charging process. [SAE J2847/3_202311] version and IEC61841 define Pilot signal as a modulated DC voltage on a single wire.

Power Line Communication (PLC) is supported by some EVSEs (e.g. for support of ISO 15118 in Europe and SAE J2931/4 in NA) and may enable features such as Vehicle to Grid (V2G) or Vehicle to Home (V2H) that allows for bi-directional charging/discharging of electric vehicles.

More modern EVSE devices may optionally support ISO 15118-20 in Europe and SAE J2836/3 for NA to support bi-directional charging (Vehicle to Grid - V2G) and Plug and Charge capabilities.

This cluster definition assumes AC charging only. DC charging options may be added in future revisions of this cluster.

This cluster supports a safety mechanism that may lockout remote operation until the initial latching conditions have been met. Some of the fault conditions defined in SAE J1772, such as Ground-Fault Circuit Interrupter (GFCI) or Charging Circuit Interrupting Device (CCID), may require clearing by an operator by, for example, pressing a button on the equipment or breaker panel.

This EVSE cluster is written around support of a single EVSE. Having multiple EVSEs at home or a business is managed by backend system and outside scope of this cluster.

Note that in many deployments the EVSE may be outside the home and may suffer from intermittent network connections (e.g. a weak Wi-Fi signal). It also allows for a charging profile to be pre-configured, in case there is a temporary communications loss during a charging session.

See
MatterSpecification.v161.Cluster § 9.3
FanControl: typeof FanControl

Definitions for the FanControl cluster.

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

See
MatterSpecification.v161.Cluster § 4.4
KeypadInput: typeof KeypadInput

Definitions for the KeypadInput cluster.

This cluster provides an interface for key code based input and control on a device like a Video Player or an endpoint like a Content App. This may include text or action commands such as UP, DOWN, and SELECT.

This cluster would be supported on Video Player devices as well as devices that support remote control input from a keypad or remote. This cluster provides the list of supported keypad inputs and provides a command for sending them.

The cluster server for Keypad Input is implemented by a device that can receive keypad input, such as a Video Player, or an endpoint that can receive keypad input, such as a Content App.

The key codes used are those defined in the HDMI CEC specification (see HDMI).

Devices may understand a subset of these key codes. Feature flags are used to indicate a specific subset that is supported. Device may support additional codes beyond what is indicated in feature flags.

See
MatterSpecification.v161.Cluster § 6.8
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 or lamp, a pump's flow rate setpoint, etc.

See
MatterSpecification.v161.Cluster § 1.6
MediaPlayback: typeof MediaPlayback

Definitions for the MediaPlayback cluster.

This cluster provides an interface for controlling Media Playback (PLAY, PAUSE, etc) on a media device such as a TV, Set-top Box, or Smart Speaker.

This cluster server would be supported on Video Player devices or endpoints that provide media playback, such as a Content App. This cluster provides an interface for controlling Media Playback.

See
MatterSpecification.v161.Cluster § 6.10
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.v161.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.
PowerTopology: typeof PowerTopology

Definitions for the PowerTopology cluster.

The Power Topology Cluster provides a mechanism for expressing how power is flowing between endpoints.

See
MatterSpecification.v161.Core § 11.8
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.v161.Cluster § 7.4
Thermostat: typeof Thermostat

Definitions for the Thermostat cluster.

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

See
MatterSpecification.v161.Cluster § 4.3
ValveConfigurationAndControl: typeof ValveConfigurationAndControl

Definitions for the ValveConfigurationAndControl cluster.

This cluster is used to configure a valve.

See
MatterSpecification.v161.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.v161.Cluster § 5.3

`Readonly`deviceRequirements

deviceRequirements: {
    Closure: typeof ClosureRequirements;
    DeviceEnergyManagement: typeof DeviceEnergyManagementRequirements;
    ElectricalEnergyTariff: typeof ElectricalEnergyTariffRequirements;
    ElectricalMeter: typeof ElectricalMeterRequirements;
    ElectricalSensor: typeof ElectricalSensorRequirements;
    ElectricalUtilityMeter: typeof ElectricalUtilityMeterRequirements;
    EnergyEvse: typeof EnergyEvseRequirements;
    GenericSwitch: typeof GenericSwitchRequirements;
    MotionSensor: typeof OccupancySensorRequirements;
    PowerSource: typeof PowerSourceRequirements;
    Pump: typeof PumpRequirements;
    RoboticVacuumCleaner: typeof RoboticVacuumCleanerRequirements;
    RoomAirConditioner: typeof RoomAirConditionerRequirements;
    SmokeSensor: typeof SmokeCoAlarmRequirements;
    Thermostat: typeof ThermostatRequirements;
    WaterHeater: typeof WaterHeaterRequirements;
    WaterValve: typeof WaterValveRequirements;
    WindowCovering: typeof WindowCoveringRequirements;
}

The matter.js requirements behind the feature-gated device types, keyed to match deviceTypes.

Homebridge picks a feature set from the state an accessory declares, which suits almost every device. Use these when it cannot: a thermostat that declares both a heating and a cooling setpoint is given AutoMode too, so a device that heats and cools but has no auto mode has to compose the cluster itself. Homebridge leaves an already-composed cluster alone.

Example

deviceType: api.matter.deviceTypes.Thermostat.with(
  api.matter.deviceRequirements.Thermostat.ThermostatServer.with('Heating', 'Cooling'),
)

`Readonly`deviceTypes

deviceTypes: {
    AirQualitySensor: With<
        For<{}>,
        With<
            {} & {},
            readonly [
                Type<
                    typeof AirQualityServer,
                    WithSupportedFeatures<
                        AirQuality,
                        { extremelyPoor: true; fair: true; moderate: true; veryPoor: true },
                    >,
                    Concrete,
                    new () => {},
                    "airQuality",
                >,
            ],
        >,
        {},
    >;
    BatteryStorage: BatteryStorageDevice;
    BridgedNode: BridgedNodeEndpoint;
    Closure: With<
        For<{}>,
        With<
            {} & {},
            readonly [
                Type<
                    typeof DefaultClosureControlServer,
                    WithSupportedFeatures<
                        ClosureControl,
                        {
                            calibration: false;
                            instantaneous: false;
                            manuallyOperable: false;
                            motionLatching: false;
                            pedestrian: false;
                            positioning: true;
                            protection: false;
                            speed: false;
                            ventilation: false;
                        },
                    >,
                    Concrete,
                    new () => {},
                    "closureControl",
                >,
            ],
        >,
        {},
    >;
    ColorTemperatureLight: ColorTemperatureLightDevice;
    ContactSensor: ContactSensorDevice;
    DeviceEnergyManagement: With<
        For<{}>,
        With<
            {},
            readonly [
                Type<
                    typeof DefaultDeviceEnergyManagementServer,
                    WithSupportedFeatures<
                        WithSupportedFeatures<
                            DeviceEnergyManagement,
                            {
                                constraintBasedAdjustment: true;
                                forecastAdjustment: true;
                                pausable: true;
                                powerAdjustment: true;
                                powerForecastReporting: true;
                                startTimeAdjustment: true;
                                stateForecastReporting: false;
                            },
                        >,
                        {
                            constraintBasedAdjustment: false;
                            forecastAdjustment: false;
                            pausable: false;
                            powerAdjustment: false;
                            powerForecastReporting: false;
                            startTimeAdjustment: false;
                            stateForecastReporting: false;
                        },
                    >,
                    Concrete,
                    new () => {},
                    "deviceEnergyManagement",
                >,
            ],
        >,
        {},
    >;
    DimmableLight: DimmableLightDevice;
    DimmableOutlet: DimmablePlugInUnitDevice;
    DoorLock: DoorLockDevice;
    ElectricalEnergyTariff: ElectricalEnergyTariffDevice;
    ElectricalMeter: ElectricalMeterDevice;
    ElectricalSensor: ElectricalSensorEndpoint;
    ElectricalUtilityMeter: ElectricalUtilityMeterDevice;
    EnergyEvse: With<
        For<{}>,
        With<
            {} & {},
            readonly [
                Type<
                    typeof DefaultEnergyEvseServer,
                    WithSupportedFeatures<
                        WithSupportedFeatures<
                            EnergyEvse,
                            {
                                chargingPreferences: true;
                                plugAndCharge: true;
                                rfid: true;
                                soCReporting: true;
                                v2X: true;
                            },
                        >,
                        {
                            chargingPreferences: false;
                            plugAndCharge: false;
                            rfid: false;
                            soCReporting: false;
                            v2X: false;
                        },
                    >,
                    Concrete,
                    new () => {},
                    "energyEvse",
                >,
            ],
        >,
        {},
    >;
    ExtendedColorLight: ExtendedColorLightDevice;
    Fan: FanDevice;
    GenericSwitch: With<
        For<{}>,
        With<
            {},
            readonly [
                Type<
                    typeof SwitchServer,
                    WithSupportedFeatures<
                        WithSupportedFeatures<WithSupportedFeatures<Switch, {}>, {}>,
                        {
                            actionSwitch: false;
                            latchingSwitch: false;
                            momentarySwitch: true;
                            momentarySwitchLongPress: true;
                            momentarySwitchMultiPress: true;
                            momentarySwitchRelease: true;
                        },
                    >,
                    Concrete,
                    typeof Internal,
                    "switch",
                >,
            ],
        >,
        {},
    >;
    HumiditySensor: HumiditySensorDevice;
    LeakSensor: WaterLeakDetectorDevice;
    LightSensor: LightSensorDevice;
    MediaPlayer: With<
        For<{}>,
        With<
            {} & {} & {},
            readonly [
                typeof DefaultMediaPlaybackServer,
                typeof DefaultKeypadInputServer,
            ],
        >,
        {},
    >;
    MotionSensor: With<
        For<{}>,
        With<
            {},
            readonly [
                Type<
                    typeof OccupancySensingServer,
                    WithSupportedFeatures<
                        OccupancySensing,
                        {
                            activeInfrared: false;
                            occupancyEvent: true;
                            other: false;
                            passiveInfrared: true;
                            physicalContact: false;
                            radar: false;
                            rfSensing: false;
                            ultrasonic: false;
                            vision: false;
                        },
                    >,
                    Concrete,
                    new () => {},
                    "occupancySensing",
                >,
            ],
        >,
        {},
    >;
    OnOffLight: OnOffLightDevice;
    OnOffOutlet: OnOffPlugInUnitDevice;
    OnOffSwitch: OnOffLightSwitchDevice;
    PowerSource: PowerSourceEndpoint;
    Pump: With<
        For<{}>,
        With<
            {} & {},
            readonly [
                Type<
                    typeof PumpConfigurationAndControlServer,
                    WithSupportedFeatures<
                        PumpConfigurationAndControl,
                        {
                            automatic: false;
                            compensatedPressure: false;
                            constantFlow: false;
                            constantPressure: false;
                            constantSpeed: true;
                            constantTemperature: false;
                            localOperation: false;
                        },
                    >,
                    Concrete,
                    new () => {},
                    "pumpConfigurationAndControl",
                >,
            ],
        >,
        {},
    >;
    RoboticVacuumCleaner: RoboticVacuumCleanerDevice;
    RoomAirConditioner: With<
        For<{}>,
        With<
            {} & {},
            readonly [
                Type<
                    typeof ThermostatServer,
                    WithSupportedFeatures<
                        WithSupportedFeatures<WithSupportedFeatures<Thermostat, {}>, {}>,
                        {
                            autoMode: false;
                            cooling: true;
                            events: false;
                            heating: true;
                            localTemperatureNotExposed: false;
                            matterScheduleConfiguration: false;
                            occupancy: false;
                            presets: false;
                            setback: false;
                            thermostatSuggestions: false;
                        },
                    >,
                    Concrete,
                    typeof Internal,
                    "thermostat",
                >,
            ],
        >,
        {},
    >;
    SmokeSensor: SmokeCoAlarmDevice;
    SolarPower: SolarPowerDevice;
    Speaker: SpeakerDevice;
    TemperatureSensor: TemperatureSensorDevice;
    Thermostat: ThermostatDevice;
    WaterHeater: With<
        For<{}>,
        With<
            {} & {} & {},
            readonly [
                Type<
                    Type<
                        typeof ThermostatServer,
                        WithSupportedFeatures<
                            WithSupportedFeatures<WithSupportedFeatures<Thermostat, {}>, {}>,
                            {},
                        >,
                        Concrete,
                        typeof Internal,
                        "thermostat",
                    >,
                    WithSupportedFeatures<
                        WithSupportedFeatures<
                            WithSupportedFeatures<WithSupportedFeatures<Thermostat, {}>, {}>,
                            {},
                        >,
                        {
                            autoMode: false;
                            cooling: false;
                            events: false;
                            heating: true;
                            localTemperatureNotExposed: false;
                            matterScheduleConfiguration: false;
                            occupancy: false;
                            presets: false;
                            setback: false;
                            thermostatSuggestions: false;
                        },
                    >,
                    Concrete,
                    typeof Internal,
                    "thermostat",
                >,
                typeof DefaultWaterHeaterManagementServer,
            ],
        >,
        {},
    >;
    WaterValve: With<
        For<{}>,
        With<{} & {}, readonly [typeof DefaultValveConfigurationAndControlServer]>,
        {},
    >;
    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.

Unlike HAP, register every accessory on every start, including the ones handed to configureMatterAccessory() from the cache. Handlers are functions and cannot be cached, so a restored accessory answers every command with a failure until it is registered again.

When an accessory is restored from the cache, its cached state is kept: the clusters values passed here are the starting state for a new accessory only. To set the current state of a restored accessory, call updateAccessoryState() once this promise resolves (#4015).

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`status

status: {
    Busy: typeof Busy;
    ConstraintError: typeof ConstraintError;
    Failure: typeof Failure;
    InvalidAction: typeof InvalidAction;
    InvalidInState: typeof InvalidInState;
    isMatterProtocolError: (error: unknown) => error is MatterProtocolError;
    MatterProtocolError: typeof MatterProtocolError;
    NotFound: typeof NotFound;
    PermissionDenied: typeof PermissionDenied;
    ResourceExhausted: typeof ResourceExhausted;
    Timeout: typeof Timeout;
}

Matter protocol status errors for handlers.

Throw one of these from a handler to send a specific Matter status code to the controller instead of failing the endpoint. Prefer this over importing MatterStatus from the homebridge package: a value import resolves the package when the plugin file is loaded, which fails on installs that keep Homebridge in a separate node_modules tree, taking the whole plugin down with it. The api object a plugin already holds has no such problem.

Type Declaration

Busy: typeof Busy
ConstraintError: typeof ConstraintError
Failure: typeof Failure
InvalidAction: typeof InvalidAction
InvalidInState: typeof InvalidInState
isMatterProtocolError: (error: unknown) => error is MatterProtocolError
MatterProtocolError: typeof MatterProtocolError
NotFound: typeof NotFound
PermissionDenied: typeof PermissionDenied
ResourceExhausted: typeof ResourceExhausted
Timeout: typeof Timeout

Example

handlers: {
  onOff: {
    on: async () => {
      if (deviceIsBusy) {
        throw new api.matter!.status.Busy('Device is processing another command')
      }
      // ... control device
    }
  }
}

`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;
    ClosureControl: typeof ClosureControl;
    ColorControl: typeof ColorControl;
    DeviceEnergyManagement: typeof DeviceEnergyManagement;
    DoorLock: typeof DoorLock;
    ElectricalEnergyMeasurement: typeof ElectricalEnergyMeasurement;
    ElectricalPowerMeasurement: typeof ElectricalPowerMeasurement;
    EnergyEvse: typeof EnergyEvse;
    FanControl: typeof FanControl;
    KeypadInput: typeof KeypadInput;
    LevelControl: typeof LevelControl;
    MediaPlayback: typeof MediaPlayback;
    NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement;
    OnOff: typeof OnOff;
    OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement;
    Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement;
    Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement;
    PowerTopology: typeof PowerTopology;
    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.v161.Cluster § 2.9
BooleanState: typeof BooleanState

Definitions for the BooleanState cluster.

This cluster provides an interface to a boolean state.

See
MatterSpecification.v161.Cluster § 1.7
CarbonMonoxideConcentrationMeasurement: typeof CarbonMonoxideConcentrationMeasurement

Definitions for the CarbonMonoxideConcentrationMeasurement cluster.
ClosureControl: typeof ClosureControl

Definitions for the ClosureControl cluster.

This cluster provides an interface for controlling a Closure.

See
MatterSpecification.v161.Cluster § 5.4
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.v161.Cluster § 3.2
DeviceEnergyManagement: typeof DeviceEnergyManagement
Definitions for the DeviceEnergyManagement cluster.

This cluster allows a client to manage the power draw of a device. An example of such a client could be an Energy Management System (EMS) which controls an Energy Smart Appliance (ESA).

In most deployments the EMS will be the client, and the ESA will host the Device Energy Management Cluster server.

This cluster is intended to be generic in nature and could apply to any electrical load or generator (e.g. a Battery Electric Storage System - BESS, solar PV inverter, EVSE, HVAC, heat pump, hot water heater, white goods appliances etc).

It consists of the following areas which shall be supported by all devices implementing this cluster:
- Description of ESA and its capabilities & power limits (sometimes referred to as a nameplate)
- Current state of operation (including user opt-out, safety limitations / alarms)
There are some optional capabilities that some ESAs may be able to offer:
- Ability to control the load or generation
- Forecast data, including when it can be flexible (i.e. modify the power or time period)
- The ability to have their power profile adjusted by an EMS, and to provide an updated Forecast back to the EMS.
This allows the EMS to manage multiple home loads and where ESAs can be flexible, continuously optimizing the home energy to minimize cost, reduce CO2 impact, maximize self-consumption of solar PV and provide Demand Side Response (DSR) Grid services.

It is likely that the ESA may also use the Pricing Cluster to obtain incentive signals such as 'grid carbon intensity', 'time of use' or 'type of use' tariffs to schedule its operation to run at the cheapest and greenest times.

Note

NOTE: Grid Services are market dependent and will use other protocols ([OpenADR] / [IEEE2030.5]) to communicate grid events to the EMS. These are outside the scope of Matter.

Note

NOTE: Different markets may follow different approaches, but the UK [PAS1878] and [EUCodeOfConduct] give examples of how ESAs may be mandated to support these features in the future.
See
MatterSpecification.v161.Cluster § 9.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.v161.Cluster § 5.2
ElectricalEnergyMeasurement: typeof ElectricalEnergyMeasurement

Definitions for the ElectricalEnergyMeasurement cluster.

This cluster provides a mechanism for querying data about the electrical energy imported or provided by the server.

See
MatterSpecification.v161.Cluster § 2.12
ElectricalPowerMeasurement: typeof ElectricalPowerMeasurement

Definitions for the ElectricalPowerMeasurement cluster.

This cluster provides a mechanism for querying data about electrical power as measured by the server.

See
MatterSpecification.v161.Cluster § 2.13
EnergyEvse: typeof EnergyEvse

Definitions for the EnergyEvse cluster.

Electric Vehicle Supply Equipment (EVSE) is equipment used to charge an Electric Vehicle (EV) or Plug-In Hybrid Electric Vehicle. This cluster provides an interface to the functionality of Electric Vehicle Supply Equipment (EVSE) management.

Devices targeted by this cluster include Electric Vehicle Supply Equipment (EVSE). The cluster generically assumes a signaling protocol (J1772 in NA and IEC61851 in Europe and Asia) between the EVSE and Electric Vehicle (EV) that utilizes a pilot signal to manage the states of the charging process. [SAE J2847/3_202311] version and IEC61841 define Pilot signal as a modulated DC voltage on a single wire.

Power Line Communication (PLC) is supported by some EVSEs (e.g. for support of ISO 15118 in Europe and SAE J2931/4 in NA) and may enable features such as Vehicle to Grid (V2G) or Vehicle to Home (V2H) that allows for bi-directional charging/discharging of electric vehicles.

More modern EVSE devices may optionally support ISO 15118-20 in Europe and SAE J2836/3 for NA to support bi-directional charging (Vehicle to Grid - V2G) and Plug and Charge capabilities.

This cluster definition assumes AC charging only. DC charging options may be added in future revisions of this cluster.

This cluster supports a safety mechanism that may lockout remote operation until the initial latching conditions have been met. Some of the fault conditions defined in SAE J1772, such as Ground-Fault Circuit Interrupter (GFCI) or Charging Circuit Interrupting Device (CCID), may require clearing by an operator by, for example, pressing a button on the equipment or breaker panel.

This EVSE cluster is written around support of a single EVSE. Having multiple EVSEs at home or a business is managed by backend system and outside scope of this cluster.

Note that in many deployments the EVSE may be outside the home and may suffer from intermittent network connections (e.g. a weak Wi-Fi signal). It also allows for a charging profile to be pre-configured, in case there is a temporary communications loss during a charging session.

See
MatterSpecification.v161.Cluster § 9.3
FanControl: typeof FanControl

Definitions for the FanControl cluster.

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

See
MatterSpecification.v161.Cluster § 4.4
KeypadInput: typeof KeypadInput

Definitions for the KeypadInput cluster.

This cluster provides an interface for key code based input and control on a device like a Video Player or an endpoint like a Content App. This may include text or action commands such as UP, DOWN, and SELECT.

This cluster would be supported on Video Player devices as well as devices that support remote control input from a keypad or remote. This cluster provides the list of supported keypad inputs and provides a command for sending them.

The cluster server for Keypad Input is implemented by a device that can receive keypad input, such as a Video Player, or an endpoint that can receive keypad input, such as a Content App.

The key codes used are those defined in the HDMI CEC specification (see HDMI).

Devices may understand a subset of these key codes. Feature flags are used to indicate a specific subset that is supported. Device may support additional codes beyond what is indicated in feature flags.

See
MatterSpecification.v161.Cluster § 6.8
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 or lamp, a pump's flow rate setpoint, etc.

See
MatterSpecification.v161.Cluster § 1.6
MediaPlayback: typeof MediaPlayback

Definitions for the MediaPlayback cluster.

This cluster provides an interface for controlling Media Playback (PLAY, PAUSE, etc) on a media device such as a TV, Set-top Box, or Smart Speaker.

This cluster server would be supported on Video Player devices or endpoints that provide media playback, such as a Content App. This cluster provides an interface for controlling Media Playback.

See
MatterSpecification.v161.Cluster § 6.10
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.v161.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.
PowerTopology: typeof PowerTopology

Definitions for the PowerTopology cluster.

The Power Topology Cluster provides a mechanism for expressing how power is flowing between endpoints.

See
MatterSpecification.v161.Core § 11.8
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.v161.Cluster § 7.4
Thermostat: typeof Thermostat

Definitions for the Thermostat cluster.

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

See
MatterSpecification.v161.Cluster § 4.3
ValveConfigurationAndControl: typeof ValveConfigurationAndControl

Definitions for the ValveConfigurationAndControl cluster.

This cluster is used to configure a valve.

See
MatterSpecification.v161.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.v161.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

ClosureControl: typeof ClosureControl

See

ColorControl: typeof ColorControl

See

DeviceEnergyManagement: typeof DeviceEnergyManagement

See

DoorLock: typeof DoorLock

See

ElectricalEnergyMeasurement: typeof ElectricalEnergyMeasurement

See

ElectricalPowerMeasurement: typeof ElectricalPowerMeasurement

See

EnergyEvse: typeof EnergyEvse

See

FanControl: typeof FanControl

See

KeypadInput: typeof KeypadInput

See

LevelControl: typeof LevelControl

See

MediaPlayback: typeof MediaPlayback

See

NitrogenDioxideConcentrationMeasurement: typeof NitrogenDioxideConcentrationMeasurement

OnOff: typeof OnOff

See

OzoneConcentrationMeasurement: typeof OzoneConcentrationMeasurement

Pm10ConcentrationMeasurement: typeof Pm10ConcentrationMeasurement

Pm25ConcentrationMeasurement: typeof Pm25ConcentrationMeasurement

PowerTopology: typeof PowerTopology

See

RvcOperationalState: typeof RvcOperationalState

See

Thermostat: typeof Thermostat

See

ValveConfigurationAndControl: typeof ValveConfigurationAndControl

See

WindowCovering: typeof WindowCovering

See

ReadonlydeviceRequirements

Example

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>

Readonlystatus

Type Declaration

Busy: typeof Busy

ConstraintError: typeof ConstraintError

Failure: typeof Failure

InvalidAction: typeof InvalidAction

InvalidInState: typeof InvalidInState

isMatterProtocolError: (error: unknown) => error is MatterProtocolError

`Readonly`clusterNames

`Readonly`clusters

`Readonly`deviceRequirements

`Readonly`deviceTypes

`Readonly`status

`Readonly`switch

`Readonly`types