MatterGenericSwitch

About

The MatterGenericSwitch class provides a generic switch endpoint for Matter networks. It implements the Matter Switch cluster as a momentary smart button that reports press gestures to the Matter controller.

Features:

  • Configurable Switch cluster features (short click, long press, multi-press)

  • Individual event methods matching the Matter specification

  • click() convenience helper for simple automations

  • Automation trigger support for Home Assistant, Apple Home, Amazon Alexa, and Google Home

  • Matter standard compliance

Use Cases:

  • Smart buttons and scene triggers

  • Remote controls with single, double, or long press

  • Event generators for smart home automation

Switch Cluster Features

The Matter Switch cluster exposes optional FeatureMap bits. This class provides constants that match the specification:

Constant

Bit

Events enabled

FEATURE_MOMENTARY

0x02

InitialPress

FEATURE_RELEASE

0x04

ShortRelease

FEATURE_LONG_PRESS

0x08

LongPress, LongRelease

FEATURE_MULTI_PRESS

0x10

MultiPressOngoing, MultiPressComplete

Preset combinations:

  • FEATURE_SIMPLE (default) — FEATURE_MOMENTARY | FEATURE_RELEASE for a single short click

  • FEATURE_ALL — all momentary gesture features above

Dependencies:

  • FEATURE_LONG_PRESS requires FEATURE_RELEASE

  • FEATURE_MULTI_PRESS requires FEATURE_RELEASE

API Reference

Constructor

MatterGenericSwitch

Creates a new Matter generic switch endpoint.

MatterGenericSwitch();

Feature Constants

static constexpr uint32_t FEATURE_MOMENTARY;
static constexpr uint32_t FEATURE_RELEASE;
static constexpr uint32_t FEATURE_LONG_PRESS;
static constexpr uint32_t FEATURE_MULTI_PRESS;
static constexpr uint32_t FEATURE_SIMPLE;   // short click
static constexpr uint32_t FEATURE_ALL;      // all gestures

Initialization

begin

Initializes the Matter generic switch endpoint.

bool begin(uint32_t featureFlags = FEATURE_SIMPLE, uint8_t multiPressMax = 5);

  • featureFlags — Switch cluster features to enable at endpoint creation. Defaults to FEATURE_SIMPLE.

  • multiPressMax — Maximum press count for multi-press (2–255). Used only when FEATURE_MULTI_PRESS is set.

Returns true on success, false otherwise.

Examples:

// Simple short-click button (default)
mySwitch.begin();

// Full gesture support (long press + multi-press up to 5 clicks)
mySwitch.begin(MatterGenericSwitch::FEATURE_ALL, 5);

end

Stops processing Matter switch events.

void end();

hasFeature

Returns true if the given feature bit is enabled.

bool hasFeature(uint32_t feature) const;

Event Generation

Call these from your button driver when the corresponding physical action occurs.

press

Sends InitialPress (button pressed down).

void press();

release

Sends ShortRelease (button released after a short press).

void release();

longPress

Sends LongPress (button held past the long-press threshold).

void longPress();

longRelease

Sends LongRelease (button released after a long press).

void longRelease();

multiPressOngoing

Sends MultiPressOngoing when an additional press starts within the multi-press window.

void multiPressOngoing(uint8_t count);

multiPressComplete

Sends MultiPressComplete when the multi-press window expires after the last release.

void multiPressComplete(uint8_t count);

click

Convenience helper: sends InitialPress followed by ShortRelease when the release feature is enabled. Both events run in one Matter-task lambda so ShortRelease cannot be processed before InitialPress.

void click();

Gesture Event Flow

A correct short click sends two events:

  1. InitialPress on button down

  2. ShortRelease on button up

Long press adds LongPress while held and LongRelease on release.

Multi-press (double/triple click) follows the ESP-Matter generic switch pattern:

  1. First press down → InitialPress

  2. First release → ShortRelease

  3. Second press down (within window) → MultiPressOngoing (count = 2)

  4. Second release → ShortRelease

  5. Window expires → MultiPressComplete (total count)

Semantic Tags

Sibling Generic Switch endpoints share the same Matter device type, so a controller cannot tell them apart from device type alone. Use MatterEndPoint::setTagList() after begin() and before Matter.begin() to write the Descriptor cluster TagList attribute.

Named presets are in MatterTags::Switches (On, Off, Toggle, Up, Down, Next, Previous, Select). For a user-visible custom label, use MatterTags::Switches::createCustomTag("Scene 1"). See MatterEndPoint for the full TagList API.

Examples

Simple Smart Button

Minimal short-click implementation using press() on down and release() on up.

View Matter Smart Button example on GitHub

Enhanced Smart Button

Same single BOOT button as the simple example. begin(FEATURE_ALL) enables long-press and multi-press. Serial names the gestures: single click, double click, triple click, and long press. For several buttons with names, use the TagList example below.

View Matter Enhanced Smart Button example on GitHub

Tagged Smart Buttons

Three Generic Switch endpoints — On, Off, and a custom “Scene 1” button. Each tagged via the Descriptor TagList attribute so a Matter controller can display a meaningful name for each button instead of a generic “Switch 1 / Switch 2 / Switch 3”.

View Matter Smart Buttons TagList example on GitHub