homebridge
    Preparing search index...

    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

    emit emitGesture

    Properties

    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:

    Action When to use Events fired by Matter.js
    press Physical button pressed / contact closed initialPress
    release Physical button released / contact opened shortRelease or longRelease*

    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

        • Optionaloptions: { 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>

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

    // Multi-button remote: button 2 press and release
    await api.matter?.switch.emit(uuid, 'press', { position: 2 })
    await api.matter?.switch.emit(uuid, 'release', { position: 2 })

    // GenericSwitch as a part in a composed device
    await api.matter?.switch.emit(uuid, 'press', { partId: 'button-top' })
    await api.matter?.switch.emit(uuid, 'release', { partId: 'button-top' })
    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.

    Gesture Translated sequence
    singlePress press → release
    doublePress press → release → (multiPressDelayMs) → press → release
    longPress press → (longPressDelayMs) → release

    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'

        • Optionaloptions: {
              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>

    // Single press on a simple remote
    await api.matter?.switch.emitGesture(uuid, 'singlePress')

    // Double press on button 2 of a multi-button remote
    await api.matter?.switch.emitGesture(uuid, 'doublePress', { position: 2 })

    // Long press on a composed device part
    await api.matter?.switch.emitGesture(uuid, 'longPress', { partId: 'button-top' })

    Settings

    Member Visibility

    On This Page

    Properties