Chime

Device Type
Matter smart chime / doorbell sounder. Indoors, permanently powered from USB-C, sits near the front door in place of (or alongside) a wired electromechanical chime. It is the SOUND PRODUCER, not the doorbell: it does not sense the door, does not stream audio or video, and has no camera. Its job is to ring — audibly and selectively — whenever any Matter device or automation tells it to, from anywhere in the home.

Hardware
chip: esp32 — board: m5-atom-echo — gpios: GPIO27 — on-board SK6812 RGB status LED (data out) · GPIO39 — on-board user button (input-only pad, active low; short press = test ring, 10 s hold = factory reset) · GPIO19 — I2S bit clock to the on-board NS4168 amplifier · GPIO22 — I2S data out to the on-board NS4168 amplifier · GPIO33 — I2S word select / LRCK to the on-board NS4168 amplifier · GPIO21, GPIO25, GPIO26, GPIO32 — free and deliberately unclaimed, reserved for a future wired doorbell contact input — peripherals: On-board speaker via NS4168 I2S amplifier (GPIO 19/22/33) — audio output · On-board SK6812 RGB LED (GPIO 27) — status indicator and Identify · On-board user button (GPIO 39) — local test ring + factory reset · USB-C port — power only (5 V, no data) — bom: No external parts. Everything the product needs is already on the M5Stack Atom Echo (24x24x17 mm). — notes: The ESP32-PICO-D4 has no native USB; flashing is over UART. The end product never requires a wired connection — power only.

Inputs
kind: button — label: Test ring — hardware: On-board user button, GPIO 39, active low — behavior: Short press plays the selected melody immediately, exactly as a remote trigger would (the retrigger guard still applies). Works with no controller, no Wi-Fi and no fabric — this is how the chime is verified while being placed in a room. · kind: button — label: Factory reset — hardware: On-board user button, GPIO 39 — continuous 10 s hold — behavior: At 5 s of holding, the LED turns red as a warning. Releasing before 10 s aborts and nothing is erased. Completing the hold wipes all settings and credentials and reboots into commissioning mode. · kind: matter_command — label: Play chime sound — hardware: Matter Chime cluster (server), over Wi-Fi — behavior: PlayChimeSound with an optional ChimeID. With an ID, that melody plays regardless of the selected default; with no ID, the currently selected melody plays. · kind: matter_attribute — label: Select melody — hardware: Matter Chime cluster — SelectedChime, write from the controller — behavior: Sets which of the three melodies the device uses as its default. Persisted to NVS immediately and reflected in the controller. · kind: matter_attribute — label: Mute / unmute — hardware: Matter Chime cluster — Enabled, write from the controller — behavior: Enabled = false suppresses playback without removing the device from the fabric or losing its settings. Persisted to NVS. Usable from schedules and scenes. · kind: matter_command — label: Identify — hardware: Matter Identify cluster (server), over Wi-Fi — behavior: Pulses the RGB LED for the requested duration so the user can identify which physical chime they are looking at in the app. Interrupts the idle LED animation, then returns to it.

Outputs
kind: speaker — label: Chime melody — hardware: On-board NS4168 I2S amplifier + speaker, GPIO 19/22/33 — behavior: Plays the requested or selected melody at a fixed loudness set by the melody itself. Exactly three built-in melodies, exposed as installed sounds: Classic Ding-Dong (default, IDs 1), Soft Beep (deliberately gentle, for daytime/nighttime use), Doorbell Chime. No volume parameter — mute is the only acoustic control. · kind: led — label: Status LED — hardware: On-board SK6812 RGB LED, GPIO 27 — behavior: Blue breathe = uncommissioned, advertising over BLE. Blue fast blink = commissioning in progress. Amber breathe = commissioned but Wi-Fi/fabric session re-establishing. Solid green = on the fabric and connected. Solid red (steady) = speaker/amplifier failed to initialise. Red slow blink = 5 s reached in a factory-reset hold (warning). White pulse = a chime is sounding. White double-flash = a trigger arrived but playback was suppressed by mute. Dim/pulse for the requested duration = Identify.

Connectivity
stack: matter — transport: wifi — purpose: 2.4 GHz Wi-Fi carries the commissioned Matter session — remote triggers, melody selection, mute and Identify all arrive over it. Wi-Fi only; the device does not use Thread. · stack: ble — transport: ble — purpose: Commissioning only. BLE advertising carries the out-of-the-box pairing advertisement; once commissioning completes, the device hands off to Wi-Fi and stops advertising.

Commissioning
method: Matter standard commissioning — QR code or manual pairing code on the device label, scanned/typed in the controller app, over BLE, then Wi-Fi handoff. — payload: Standard Matter onboarding payload (QR code + 11-digit manual pairing code), provided by this firmware build. — instructions: Plug the chime into a USB-C outlet. Its LED breathes blue, meaning it is advertising and unpaired. In the Matter controller app (Apple Home, Google Home, SmartThings, Alexa, Home Assistant), choose Add device and scan the QR code on the Atom Echo or type the manual pairing code. The LED blinks quickly blue while commissioning, then turns solid green once the device is on the fabric and connected. No app of our own is required. Afterwards, bind your doorbell or a smart button to the chime in the controller (see automationRules).

Business Logic
powerOnBehavior: On power-up the device reads the selected melody and mute state from NVS, initialises the LED and the I2S speaker path, then starts Matter. Never commissioned (or just reset) -> LED breathes blue and BLE advertising is active. Already commissioned -> LED breathes amber while Wi-Fi connects and the fabric session re-establishes, then solid green. The device is silent at boot: it never plays a chime on its own to announce a power cycle. If the amplifier fails to initialise, the LED goes solid red so the fault is visible rather than looking like a working-but-silent device. — automationRules: In the Matter controller, bind a Matter doorbell, smart button, security panel or any device acting as a Chime client to this chime. A press on the source issues PlayChimeSound and the chime rings. · Controller-side automations also work: e.g. 'when the doorbell detects a person, play melody 3', or 'when a door contact opens after 22:00, mute the chime'. · Multiple sources may point at one chime — a front doorbell and a back-door button can share it, with the melody chosen per source via the command's ChimeID. · Because mute is an ordinary Matter attribute, schedules and scenes can arm and disarm it (mute overnight, unmute at breakfast) without touching the device. — dayToDayOperation: The chime sits plugged into a USB-C outlet near the front door, powered and always on. Someone presses the doorbell; the chime plays the selected melody within a fraction of a second and its LED pulses white. Household members change the melody from their phone; a guest can press the button on the device for a test ring while it is being placed. Muting for a nap is a toggle in the same controller app. Nothing else needs doing — there is no maintenance, no battery, no firmware button to press.

Factory Reset
trigger: Hold the on-board button continuously for 10 s. The LED turns red at 5 s as a warning; releasing before 10 s aborts the reset. — effect: Wipes NVS — selected melody, mute state, stored Wi-Fi credentials and all Matter fabric credentials — then reboots immediately into BLE commissioning mode, ready to be added to a new ecosystem. The melody returns to the default (Classic Ding-Dong), mute to off, and the LED returns to blue breathe for the next owner.

Failure Modes
scenario: Wi-Fi down or router rebooted — behavior: Remote triggers stop arriving but nothing else breaks. The LED goes to amber breathe and the device retries in the background indefinitely, reconnecting on its own when the network returns. The physical button still plays a local test ring throughout, so the chime can always be verified. · scenario: Matter controller, hub or cloud unreachable — behavior: The chime keeps its last melody and mute settings and stays responsive to its own button. Automations hosted in the controller simply do not fire; nothing is queued or replayed later, so there are no surprise rings after an outage clears. · scenario: Power blip, or unplugged and replugged — behavior: Reboots silently in under 10 s and rejoins Wi-Fi and the fabric using persisted credentials — no re-commissioning. Melody selection and mute state are restored, so a chime muted before the outage stays muted. It never rings on boot. · scenario: Speaker or amplifier fails to initialise — behavior: The LED shows a solid red fault indication instead of the normal animation, so the fault is visible rather than looking like a working-but-silent device. Button presses and Matter commands are still accepted and still flash the LED, distinguishing 'silent hardware' from 'no trigger received'. · scenario: Trigger received while muted — behavior: Playback is suppressed and the LED double-flashes white, so the user can see the doorbell did fire and can choose to unmute. No audio, ever, while muted. · scenario: Rapid or simultaneous triggers (doorbell pressed repeatedly, or two sources at once) — behavior: The first trigger plays the melody. Triggers arriving within ~2 s of playback starting are dropped, so the melody is never stacked over itself, distorted or restarted mid-phrase. Because nothing is queued, a burst of presses produces exactly one ring rather than a delayed train of rings.

Power Management
batteryPowered: false — note: Mains-powered over USB-C 5 V, always on. No battery, no sleep modes, no wake sources — the radio must stay live to hear fabric commands instantly. Any low-power behaviour would add latency to a doorbell ring, which is the one thing this product must not do.

Custom Behavior
decisionsSettledInConversation: Board confirmed as the M5Stack Atom Echo (ESP32-PICO-D4) — NOT the ESP32-C3 devkit with external piezo buzzer, button and LED that the original notes described. Recorded in artifacts/board.yaml as selected: m5-atom-echo, chip: esp32. Consequence: the product uses the board's own speaker, button and RGB LED, so there is no external BOM. · Melody count settled at THREE (the description said 'at least 3', later notes said four): Classic Ding-Dong (default), Soft Beep, Doorbell Chime. · Matter device type = Chime (0x0146) with the Chime cluster (0x0556) as a server, plus the optional Identify cluster. Chosen over the Doorbell (0x0148) / Audio Doorbell (0x0141) types, which would make the device the doorbell rather than the sound producer and would carry a Chime CLIENT instead of a server. · Controller-visible surface kept to Chime + Identify only — the clean standard accessory (mute toggle + sound picker), with no On/Off endpoint added for generic scenes. · Volume control re-examined and declined a second time, now on the Atom Echo's real amplifier rather than a piezo: mute plus a deliberately gentle Soft Beep covers the household need, and a volume parameter would mean a vendor-specific control rendered inconsistently across ecosystems. · Retrigger policy: one melody per trigger with a ~2 s ignore window; nothing queued. · Selected melody and mute state persist in NVS across reboot and power loss. — matterDeviceType: Chime device type (0x0146) with the Chime cluster (0x0556) as a server. Chosen over the generic On/Off or Level Control clusters because it gives controllers the right vocabulary out of the box: an Enabled attribute as the mute switch, a SelectedChime attribute to pick the sound, an InstalledChimeSounds list reporting exactly what the device can play, and a PlayChimeSound command that names a sound explicitly. In controllers that render a chime as a first-class accessory, the user gets a mute toggle and a sound picker with no custom app. — installedSounds: InstalledChimeSounds reports exactly three entries (IDs 1-3), so a controller's sound picker automatically lists the three melodies and nothing else: 1 = Classic Ding-Dong (default), 2 = Soft Beep, 3 = Doorbell Chime. — identifyCluster: The optional Identify cluster is implemented — sending Identify pulses the LED for the requested duration so a user with several chimes can tell which physical unit they are looking at while binding it in the app. — volumeConsideredAndDeclined: Per-user volume control was considered twice and deliberately dropped both times. The Chime device type defines no volume parameter, so volume would have meant either a non-standard vendor attribute or a second custom cluster: extra surface for every ecosystem to render inconsistently, in exchange for a control almost nobody touches. Mute (the standard Enabled attribute) plus a deliberately gentle Soft Beep melody covers the real household need, which is ringing quietly or not at all. — futureHardwareProvision: GPIO 21, 25, 26 and 32 are deliberately left free and unclaimed so a wired doorbell contact can be added later as a local trigger without re-laying out the board.