Usage guide

The Matter firmware intentionally keeps the Generic Switch device type. That is the semantically correct Matter model for this hardware, even though not every ecosystem handles it well. In Home Assistant, the Matter variant is exposed as one Generic Switch device that emits Matter switch events instead of separate per-gesture entities. Unlike the Zigbee variant, Matter also exposes the measured battery voltage as a normal user-visible value in Home Assistant.

Battery Life Estimate

About 2.3 years.*

_{* Assumes a 2200 mAh battery, 10 clicks per day on average, the current 10 second idle timeout after each click, about 40 uA in deep sleep, and about 60 mA average active draw while Matter over Thread is awake. Real battery life varies with RF conditions, retries, recommissioning, and battery self-discharge.}

Supported Platforms

Platform	Status	Notes
Home Assistant		Primary Matter target; requires the Matter integration and a Thread border router
Google Home		Provisioning can succeed, but the device is known to appear permanently offline afterward; automations and usable status reporting are not available
Alexa		Not a supported target for this firmware
Apple Home		Not a supported target for this firmware

Because Google Home, Apple Home, and Alexa are not supported targets for this project, the firmware does not optimize the Matter path for their ecosystem-specific behavior. The battery-first deep sleep policy is therefore preferred over keeping commissioned Matter devices continuously awake.

Color Code

Indicator	Meaning
off	Device is commissioned and idle
pulse	Device is not commissioned and is waiting for initial Matter commissioning
pulse	Matter provisioning phase 1 is active; the device is being paired to Matter/Thread
pulse	Matter provisioning phase 2 is active; the device is commissioned but still waiting to be assigned to the target controller
steady	Matter provisioning flow completed successfully
steady	Device is awake and a button event is queued for delivery
steady	Button event was delivered successfully in normal operation
steady	Matter connection or button delivery failed

Getting Started

1. Confirm that your device is hardware version 2. The version number is printed on the back, under the battery.
2. Install using the web installer or by downloading and flashing the Thread binary from the GitHub Releases section for this repository.
3. Scan the QR code below, or enter the manual pairing code if your controller asks for it.
4. Select Home Assistant in the setup flow and finish commissioning through Home Assistant Matter.

Default commissioning convenience values for the current development setup:

• Manual pairing code: 34970112332
• QR payload: MT:Y.K9042C00KA0648G00

_{QR decoder: project-chip.github.io/connectedhomeip/qrcode.html}

Home Assistant Automation Example

For Matter in Home Assistant, automate on the event.* entity state change itself, not on the event_type attribute. This is important for repeated identical presses such as single -> single, because the event entity state changes every time while event_type may stay the same.

alias: Smart Button Matter
trigger:
  - platform: state
    entity_id:
      - event.smart_button_button
    not_from:
      - unavailable
    not_to:
      - unavailable
      - unknown

action:
  - choose:
      - conditions:
          - condition: template
            value_template: "{{ trigger.to_state.attributes.event_type == 'multi_press_1' }}"
        sequence:
          - service: light.toggle
            target:
              entity_id: light.example

      - conditions:
          - condition: template
            value_template: "{{ trigger.to_state.attributes.event_type == 'multi_press_2' }}"
        sequence:
          - service: scene.turn_on
            target:
              entity_id: scene.example

      - conditions:
          - condition: template
            value_template: "{{ trigger.to_state.attributes.event_type == 'long_press' }}"
        sequence:
          - service: switch.turn_off
            target:
              entity_id: switch.example

The default Matter event entity name is event.smart_button_button.