Back to Homebridge

Interface MatterAPI

docs/interfaces/MatterAPI.html

2.0.230.2 KB
Original Source
  • MatterAPI

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 externallyawait api.matter?.updateAccessoryState(uuid, 'onOff', { onOff: true })// Read current stateconst state = await api.matter?.getAccessoryState(uuid, 'onOff')Copy

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

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

clusterNamesclustersdeviceTypesgetAccessoryStateregisterPlatformAccessoriesswitchtypesunregisterPlatformAccessoriesupdateAccessoryStateupdatePlatformAccessoriesuuid

Properties

ReadonlyclusterNames

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

Readonlyclusters

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

ReadonlydeviceTypes

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

Typed overload for known clusters - returns typed state

Type Parameters

- K extends keyof [ClusterStateMap](ClusterStateMap.html)

Parameters

- uuid: string
- cluster: K
- `Optional`partId: 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
- `Optional`partId: 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)Copy

registerPlatformAccessories

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

Register Matter platform accessories (works exactly like HAP's registerPlatformAccessories)

Returns a promise that resolves when all accessories are fully registered and ready for state updates. This is especially important for external accessories (like robot vacuums) which require additional setup time.

Type Declaration

Parameters

- pluginIdentifier: string

The plugin identifier (e.g., 'homebridge-example')

- platformName: string

The platform name (e.g., 'ExamplePlatform')

- accessories: [MatterAccessory](MatterAccessory.html)\<[UnknownContext](../types/UnknownContext.html)\>[]

Array of Matter accessories to register

Returns Promise<void>

Readonlyswitch

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 releaseawait api.matter?.switch.emit(uuid, 'press')await api.matter?.switch.emit(uuid, 'release')Copy

Readonlytypes

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 enumapi.matter?.updateAccessoryState( uuid, api.matter?.clusterNames.FanControl, { fanMode: api.matter?.types.FanControl.FanMode.High })Copy

unregisterPlatformAccessories

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

Unregister Matter platform accessories by UUID

Type Declaration

Parameters

- pluginIdentifier: string

The plugin identifier

- platformName: string

The platform name

- accessories: [MatterAccessory](MatterAccessory.html)\<[UnknownContext](../types/UnknownContext.html)\>[]

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

Typed overload for known clusters - provides autocomplete for attribute names

Type Parameters

- K extends keyof [ClusterStateMap](ClusterStateMap.html)

Parameters

- uuid: string
- cluster: K
- attributes: Partial\<[ClusterStateMap](ClusterStateMap.html)[K]\>
- `Optional`partId: 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\>
- `Optional`partId: 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)Copy

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

Parameters

- accessories: [MatterAccessory](MatterAccessory.html)\<[UnknownContext](../types/UnknownContext.html)\>[]

Array of Matter accessories to update (must include uuid)

Returns Promise<void>

Example

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

Readonlyuuid

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', // ...})Copy

Settings

Member Visibility

  • Inherited

ThemeOSLightDark

On This Page

Properties clusterNamesclustersdeviceTypesgetAccessoryStateregisterPlatformAccessoriesswitchtypesunregisterPlatformAccessoriesupdateAccessoryStateupdatePlatformAccessoriesuuid