Switch Cluster

Cluster ID: 0x003B  |  Endpoint: Typically on Endpoint 1 (application endpoint)

The Switch Cluster describes physical input devices — wall-mounted toggle switches, doorbell buttons, dimmer knobs, and so on. It does not control any outputs (turning a light on or off is the job of the OnOff Cluster); instead, it converts the user's physical actions into events, and the bound target devices or automation rules decide the actual actions.

Switch ≠ OnOff

Two easily confused Clusters: Switch (0x003B) is a physical input device, responsible for reporting "what the user pressed"; OnOff (0x0006) is an output control, responsible for executing "whether the device is on or off". A wall switch panel typically includes both — Switch detects press actions, OnOff executes on/off control. However, the Switch Cluster itself has no commands; it is purely an event source.

Event-Driven Model

The Switch Cluster is the most typical event-driven Cluster in Matter. It has no commands (does not accept external instructions); all information is reported through events. Controllers (phones, hubs) need to subscribe to events to detect user actions, rather than polling attribute changes.

Feature Bitmap

The Switch Cluster's Feature Map is very important — it determines what type of switch the device is and which events it will report. The device must declare either LS (Latching Switch) or MS (Momentary Switch), and the two are mutually exclusive.

Bit 0
LS (Latching Switch) Latching switch — stays in position after being toggled (e.g., a traditional wall toggle switch). Mutually exclusive with MS
Bit 1
MS (Momentary Switch) Momentary switch — springs back automatically after being pressed (e.g., a pushbutton, doorbell). Mutually exclusive with LS
Bit 2
MSR (Momentary Switch Release) Release detection — supports detecting button release actions. Depends on MS
Bit 3
MSL (Momentary Switch Long Press) Long press detection — supports distinguishing short press and long press. Depends on MS + MSR
Bit 4
MSM (Momentary Switch Multi Press) Multi-press — supports detecting consecutive presses such as double-tap, triple-tap. Depends on MS + MSR
Feature Dependencies

LS and MS are mutually exclusive; both cannot be declared simultaneously.
MSR depends on MS (only momentary switches have a "release" concept).
MSL and MSM both depend on MS + MSR (precise press/release timing is needed to determine long press or multi-press).

Feature Combination Examples

Device Type Feature Value Enabled Features Supported Events
Traditional wall toggle switch 0x01 LS SwitchLatched
Simple pushbutton 0x06 MS + MSR InitialPress, ShortRelease
Button with long press support 0x0E MS + MSR + MSL InitialPress, ShortRelease, LongPress, LongRelease
Full-featured button (long press + multi-press) 0x1E MS + MSR + MSL + MSM All momentary events

Attributes

The Switch Cluster has only 3 attributes, all read-only. The switch's core information is reported through events; attributes mainly describe device capabilities.

ID Name Type Required Description
0x0000 NumberOfPositions uint8 Yes Total number of switch positions. Minimum value is 2. A regular switch has 2 (on/off); a multi-position knob can have more
0x0001 CurrentPosition uint8 Yes Current position, range 0 to NumberOfPositions - 1. For a latching switch, this value persists after toggling; for a momentary switch, it changes on press and may return to 0 on release
0x0002 MultiPressMax uint8 MSM Maximum number of consecutive presses the device can recognize. For example, a value of 3 means it can recognize up to a triple-tap. Only present when the MSM Feature is enabled
Positions Are Zero-Indexed

Position numbering starts from 0. A two-position toggle switch has positions 0 and 1, not 1 and 2. A 4-position knob has positions 0, 1, 2, 3.

Event Details

Events are the core of the Switch Cluster. All user actions are reported to controllers through events. Different Feature combinations determine which events the device will report. Click an event ID in the table below to jump to its detailed description.

ID Name Required Feature Description
0x00 SwitchLatched LS Latching switch toggled to a new position
0x01 InitialPress MS Momentary button pressed
0x02 LongPress MS + MSL Button held past the long-press threshold
0x03 ShortRelease MS + MSR Button released after a short press
0x04 LongRelease MS + MSL Button released after a long press
0x05 MultiPressOngoing MS + MSM Multi-press in progress (reported on each press)
0x06 MultiPressComplete MS + MSM Multi-press completed (reports total count)

SwitchLatched — Latching Switch Toggled (0x00)

Triggered when a latching switch is toggled to a new position. This is the only event reported by LS-type devices — simple and straightforward: toggle and report.

FieldTypeDescription
NewPosition uint8 The new position the switch was toggled to
Typical Scenario

Traditional wall toggle switch: the user flips the switch from "down" to "up", and the device reports SwitchLatched {'{ NewPosition: 1 }'}. The controller then sends an On command to the bound light via the binding relationship.

↑ Back to Events

InitialPress — Button Pressed (0x01)

Triggered the instant a momentary button is pressed. This is the starting point for all momentary switch (MS) action sequences — regardless of whether a short press, long press, or multi-press follows, it all begins with InitialPress.

FieldTypeDescription
NewPosition uint8 Position after pressing (typically 1)
Typical Scenario

The user presses a doorbell button, and the device immediately reports InitialPress {'{ NewPosition: 1 }'}. The controller can trigger the doorbell chime at this moment, without waiting for release.

↑ Back to Events

LongPress — Long Press (0x02)

Triggered when a button is held continuously past the device's internal long-press threshold. Reported after InitialPress and before release. Requires the MSL Feature.

FieldTypeDescription
NewPosition uint8 Position while held (same as InitialPress NewPosition)
Typical Scenario

Dimmer button: short press toggles on/off, long press starts brightness adjustment. The user holds the button, and upon receiving LongPress, the controller begins continuously adjusting the light's brightness (via LevelControl Cluster's MoveWithOnOff command), until it receives LongRelease, at which point it stops.

↑ Back to Events

ShortRelease — Short Press Release (0x03)

Triggered when a button is released before the LongPress threshold is reached (i.e., this was a short press). Requires the MSR Feature.

FieldTypeDescription
PreviousPosition uint8 Position while pressed (i.e., position before release)
Note the Field Name

ShortRelease and LongRelease use PreviousPosition (position before release), while InitialPress and LongPress use NewPosition (position after pressing). Although the values are usually the same, the semantics differ — one describes "where it went when pressed", the other describes "where it was released from".

Typical Scenario

Smart button: upon receiving ShortRelease, confirm this was a short press and execute the corresponding short-press action (e.g., Toggle light on/off). If the MSM Feature is enabled, the device waits to determine if there are subsequent presses (multi-press), so ShortRelease may not fire immediately.

↑ Back to Events

LongRelease — Long Press Release (0x04)

Triggered when the button is released after LongPress has fired (i.e., the long press ends). Requires the MSL Feature.

FieldTypeDescription
PreviousPosition uint8 Position during the long press (i.e., position before release)
Typical Scenario

Dimmer button long-press release: upon receiving LongRelease, the controller stops brightness adjustment (sends StopWithOnOff command), and the light stays at the current brightness.

↑ Back to Events

MultiPressOngoing — Multi-Press In Progress (0x05)

During a rapid consecutive press sequence, this event is triggered on each press, carrying the cumulative press count so far. Requires the MSM Feature.

FieldTypeDescription
NewPosition uint8 Position after pressing
CurrentNumberOfPressesCounted uint8 Cumulative press count so far (starts from 2, since the first press is InitialPress)
Typical Scenario

User rapidly triple-taps a button. Event sequence:

  1. InitialPress {'{ NewPosition: 1 }'} — first press
  2. MultiPressOngoing {'{ NewPosition: 1, CurrentNumberOfPressesCounted: 2 }'} — second press
  3. MultiPressOngoing {'{ NewPosition: 1, CurrentNumberOfPressesCounted: 3 }'} — third press
  4. MultiPressComplete {'{ PreviousPosition: 1, TotalNumberOfPressesCounted: 3 }'} — multi-press complete

Controllers typically wait for MultiPressComplete before executing an action, rather than responding to each Ongoing event.

↑ Back to Events

MultiPressComplete — Multi-Press Complete (0x06)

Triggered after a consecutive press sequence ends, carrying the final total press count. This is the key event for the controller to determine user intent — based on the total count, it decides which action to execute (single-tap, double-tap, triple-tap, etc.). Requires the MSM Feature.

FieldTypeDescription
PreviousPosition uint8 Position during the presses
TotalNumberOfPressesCounted uint8 Total press count. A value of 1 indicates a single-tap, 2 indicates a double-tap, and so on. Maximum value does not exceed MultiPressMax
Special Meaning of TotalNumberOfPressesCounted = 0

If TotalNumberOfPressesCounted is 0, it means this multi-press sequence was invalid (e.g., the press count exceeded MultiPressMax, or the device determined it was an accidental touch). Controllers should not execute any action when receiving 0.

Typical Scenario

Aqara wireless button: single-tap turns on the light, double-tap switches scenes, triple-tap turns off all lights. The controller waits for MultiPressComplete, then dispatches different automation actions based on the TotalNumberOfPressesCounted value.

↑ Back to Events

Event Sequence Comparison

Event reporting order for different operation types:

Operation Event Sequence
Toggle (LS) SwitchLatched
Short press (MS+MSR) InitialPress → ShortRelease
Long press (MS+MSR+MSL) InitialPress → LongPress → LongRelease
Double-tap (MS+MSR+MSM) InitialPress → MultiPressOngoing(2) → MultiPressComplete(2)
Single-tap (MS+MSR+MSM, confirmed after timeout) InitialPress → MultiPressComplete(1)

Example Data

Attribute read result from a smart button supporting long press and double-tap (Features: MS+MSR+MSL+MSM):

{
  // --- Switch Position ---
  "0x0000": 2,              // NumberOfPositions = 2 (two positions, e.g., a common up/down toggle switch)
  "0x0001": 0,              // CurrentPosition = 0 (currently at position 0)

  // --- Multi-Press ---
  "0x0002": 3               // MultiPressMax = 3 (recognizes up to 3 consecutive presses)
}

Event Subscription and Reception Example

Subscribing to Switch Cluster events and the data format when receiving events:

// Event subscription example — subscribe to all events of the Switch Cluster
{
  "subscribeRequest": {
    "eventRequests": [{
      "endpoint": 1,
      "cluster": "0x003B"    // Switch Cluster
    }],
    "minInterval": 0,
    "maxInterval": 60
  }
}

// Received InitialPress event
{
  "eventPath": {
    "endpoint": 1,
    "cluster": "0x003B",
    "event": "0x01"          // InitialPress
  },
  "eventData": {
    "NewPosition": 1         // Position after pressing
  }
}

// Received MultiPressComplete event
{
  "eventPath": {
    "endpoint": 1,
    "cluster": "0x003B",
    "event": "0x06"          // MultiPressComplete
  },
  "eventData": {
    "PreviousPosition": 1,
    "TotalNumberOfPressesCounted": 2  // Total 2 presses (double-tap)
  }
}
Developer Tip

The Switch Cluster has few attributes; its core value is in events. Key points during development:

  • First read FeatureMap (0xFFFC) to determine which operation modes the device supports
  • Subscribe to events rather than polling CurrentPosition
  • If MSM is supported, read MultiPressMax to know the maximum multi-press count
  • For buttons that support multiple operation types, consider providing a UI for users to configure actions for single-tap/double-tap/long-press

Common Scenarios

Scenario 1: Wall Toggle Switch (Latching Switch)

Device: Traditional up/down wall toggle switch, Feature = LS (0x01)

  1. Device declares NumberOfPositions = 2 (up/down, two positions)
  2. User flips the switch from down to up, device reports SwitchLatched {'{ NewPosition: 1 }'}
  3. Controller finds the corresponding light via binding relationship and sends the On command
  4. User flips the switch from up to down, device reports SwitchLatched {'{ NewPosition: 0 }'}
  5. Controller sends the Off command, light turns off

This type of switch is the simplest — one event, one action, with no concept of long press or multi-press. The switch position and light state have a direct physical correspondence.

Scenario 2: Dimmer Knob / Dimmer Button

Device: A knob with press capability or a dimmer button, Feature = MS + MSR + MSL (0x0E)

  1. User short presses: receives InitialPress → ShortRelease, controller executes Toggle (switch on/off)
  2. User long presses:
    • Receives InitialPress — do not act yet, wait for subsequent events
    • Receives LongPress — begin continuous brightness adjustment (send MoveWithOnOff command)
    • Receives LongRelease — stop brightness adjustment (send StopWithOnOff command)

Key design point: do not execute Toggle on InitialPress, otherwise a long press would also trigger an on/off toggle first. The correct approach is to wait for ShortRelease or LongPress before deciding on the action.

Scenario 3: Multi-Function Wireless Button (Multi Press)

Device: Aqara / Eve wireless smart button, Feature = MS + MSR + MSL + MSM (0x1E), MultiPressMax = 3

  1. Single-tap (confirmed after timeout): InitialPress → MultiPressComplete(1) → Execute action A (e.g., turn on light)
  2. Double-tap: InitialPress → MultiPressOngoing(2) → MultiPressComplete(2) → Execute action B (e.g., switch scene)
  3. Triple-tap: InitialPress → MultiPressOngoing(2) → MultiPressOngoing(3) → MultiPressComplete(3) → Execute action C (e.g., turn off all lights)
  4. Long press: InitialPress → LongPress → LongRelease → Execute action D (e.g., enter pairing mode)

In the app, you can let users customize the automation action for each operation type, similar to Apple HomeKit's button configuration interface.

Note: Single-tap confirmation has a delay — the device waits a brief period to confirm there are no subsequent presses before reporting MultiPressComplete(1). This is to distinguish a single-tap from the first press of a double-tap; users may notice a slight response delay.