• SwitchAPI

Interface SwitchAPI

Switch helper API for GenericSwitch accessories (stateless remotes and buttons).

Grouped under api.matter?.switch so device-type-specific helpers don't crowd the top-level MatterAPI surface. Built on top of updateAccessoryState for the Switch cluster.

interface SwitchAPI {
emit: (
uuid: string,
action: "press" | "release",
options?: { partId?: string; position?: number },
) => Promise<void>;
emitGesture: (
uuid: string,
gesture: "singlePress" | "doublePress" | "longPress",
options?: {
longPressDelayMs?: number;
multiPressDelayMs?: number;
partId?: string;
position?: number;
},
) => Promise<void>;
}

Index

Properties

emitemitGesture

Properties

emit

emit: (
uuid: string,
action: "press" | "release",
options?: { partId?: string; position?: number },
) => Promise<void>

Emit a switch action for a GenericSwitch accessory.

High-level helper for stateless switches and remotes (e.g. Pico remotes, scene controllers). Sets the Switch cluster's currentPosition attribute, which causes the Matter.js SwitchServer to automatically fire the appropriate cluster events:

shortRelease vs longRelease is determined automatically by the SwitchServer based on how long the button was held (configurable via longPressDelay, default 2 s). Multi-press sequences (multiPressComplete) are generated automatically when press/release cycles occur within the multiPressDelay window (default 300 ms).

Type Declaration

• • (
    uuid: string,
    action: "press" | "release",
    options?: { partId?: string; position?: number },
    ): Promise<void>

Parameters

- uuid: string

UUID of the GenericSwitch accessory

- action: "press" | "release"

'press' to press the button, 'release' to release it

- `Optional`options: { partId?: string; position?: number }

Optional configuration

  - 

OptionalpartId?: string

Part ID for composed devices with GenericSwitch parts.

  - 

Optionalposition?: number

Button position index (1-based). Defaults to 1. Use when the GenericSwitch has multiple positions (e.g. a multi-button remote).

Returns Promise<void>

Example

// Simple single-button press and releaseawait api.matter?.switch.emit(uuid, 'press')await api.matter?.switch.emit(uuid, 'release')// Multi-button remote: button 2 press and releaseawait api.matter?.switch.emit(uuid, 'press', { position: 2 })await api.matter?.switch.emit(uuid, 'release', { position: 2 })// GenericSwitch as a part in a composed deviceawait api.matter?.switch.emit(uuid, 'press', { partId: 'button-top' })await api.matter?.switch.emit(uuid, 'release', { partId: 'button-top' })Copy

emitGesture

emitGesture: (
uuid: string,
gesture: "singlePress" | "doublePress" | "longPress",
options?: {
longPressDelayMs?: number;
multiPressDelayMs?: number;
partId?: string;
position?: number;
},
) => Promise<void>

Emit a high-level gesture for a GenericSwitch accessory.

Convenience helper for integrations that already classify gestures (e.g. remotes that report only single, double, or hold). Translates each gesture into the canonical press / release sequence that Matter.js SwitchServer expects, so the server still determines the correct Switch cluster events (shortRelease, longRelease, multiPressComplete) based on timing.

Default delays:

• longPressDelayMs – 2500 ms (just above the Matter.js longPressDelay default of 2000 ms)
• multiPressDelayMs – 100 ms (well within the Matter.js multiPressDelay window of 300 ms)

Type Declaration

• • (
    uuid: string,
    gesture: "singlePress" | "doublePress" | "longPress",
    options?: {
    longPressDelayMs?: number;
    multiPressDelayMs?: number;
    partId?: string;
    position?: number;
    },
    ): Promise<void>

Parameters

- uuid: string

UUID of the GenericSwitch accessory

- gesture: "singlePress" | "doublePress" | "longPress"

The gesture to emit: 'singlePress', 'doublePress', or 'longPress'

- `Optional`options: {  

longPressDelayMs?: number;
multiPressDelayMs?: number;
partId?: string;
position?: number;
}

Optional configuration

  - 

OptionallongPressDelayMs?: number

How long (ms) to hold the button for a long press. Defaults to 2500. Only relevant for 'longPress'.

  - 

OptionalmultiPressDelayMs?: number

Delay (ms) between the two press cycles of a double press. Defaults to 100. Only relevant for 'doublePress'.

  - 

OptionalpartId?: string

Part ID for composed devices with GenericSwitch parts.

  - 

Optionalposition?: number

Button position index (1-based). Defaults to 1.

Returns Promise<void>

Example

// Single press on a simple remoteawait api.matter?.switch.emitGesture(uuid, 'singlePress')// Double press on button 2 of a multi-button remoteawait api.matter?.switch.emitGesture(uuid, 'doublePress', { position: 2 })// Long press on a composed device partawait api.matter?.switch.emitGesture(uuid, 'longPress', { partId: 'button-top' })Copy

Settings

Member Visibility

• Inherited

ThemeOSLightDark

On This Page

Properties emitemitGesture