# bp974/xiao-nrf52840-zigbee-button architecture

> Architecture diagram of the GitHub repository bp974/xiao-nrf52840-zigbee-button, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bp974/xiao-nrf52840-zigbee-button
- Repository: https://github.com/bp974/xiao-nrf52840-zigbee-button

## Overview

This repository is firmware for a battery-powered, sleepy Zigbee button remote, with companion Zigbee2MQTT and Home Assistant integrations. The main workflow is physical button input → asynchronous gesture recognition → Zigbee command transmission → coordinator-side action conversion. A separate battery workflow samples voltage, updates Zigbee attributes, and exposes exact voltage in Zigbee2MQTT. The graph also preserves the documented single/three-button variants and automation blueprints. Source excerpts establish firmware calls; README statements support integration links where the companion runtime is external or unsampled.

Main entry points: [`src/main.c`](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/main.c) (Application startup), [`src/zigbee_actions.c`](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/zigbee_actions.c) (Zigbee actions), [`src/buttons.c`](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/buttons.c) (Gesture detection), [`include/zb_button_remote.h`](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/include/zb_button_remote.h) (Zigbee endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Button firmware"]
  node_gpio["Button GPIO<br/>[buttons.c]"]
  node_gestures["Gesture detection<br/>[buttons.c]"]
end

subgraph group_zigbee["Zigbee device"]
  node_app["Application startup<br/>[main.c]"]
  node_actions["Zigbee actions<br/>[zigbee_actions.c]"]
  node_device["Zigbee endpoints<br/>[zb_button_remote.h]"]
  node_network["Zigbee stack"]
end

subgraph group_battery["Battery reporting"]
  node_battery_sample["Voltage sampling<br/>[battery.c]"]
  node_battery_attrs[("Battery attributes<br/>[battery.c]")]
end

subgraph group_integrations["Home integrations"]
  node_converter["Zigbee2MQTT converter"]
  node_blueprint_single["Single-button blueprint"]
  node_blueprint_three["Three-button blueprint"]
end

node_person(("Button user"))
node_coordinator(("Zigbee coordinator"))
node_z2m["Zigbee2MQTT"]
node_ha["Home Assistant"]

node_person -->|"presses"| node_gpio
node_gpio -->|"signals changes"| node_gestures
node_app -->|"initializes"| node_gestures
node_gestures -->|"dispatches gestures"| node_actions
node_actions -->|"schedules commands"| node_network
node_actions -->|"sends cluster commands"| node_coordinator
node_app -->|"registers endpoints"| node_device
node_app -->|"enables sleepy operation"| node_network
node_network -.->|"joins network"| node_coordinator
node_app -->|"initializes and starts"| node_battery_sample
node_battery_sample -->|"updates attributes"| node_battery_attrs
node_battery_attrs -->|"publishes voltage"| node_device
node_device -->|"reports Zigbee attributes"| node_converter
node_coordinator -.->|"delivers commands"| node_z2m
node_z2m -->|"loads converter"| node_converter
node_converter -->|"exposes actions and voltage"| node_ha
node_blueprint_single -->|"configures automation"| node_ha
node_blueprint_three -->|"configures automation"| node_ha

click node_gpio "https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/buttons.c"
click node_gestures "https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/buttons.c"
click node_app "https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/main.c"
click node_actions "https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/zigbee_actions.c"
click node_device "https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/include/zb_button_remote.h"
click node_battery_sample "https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/battery.c"
click node_battery_attrs "https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/battery.c"
click node_converter "https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/zigbee2mqtt/broskie_zigbee_button.mjs"
click node_blueprint_single "https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/home-assistant/blueprints/broskie-zigbee-button.yaml"
click node_blueprint_three "https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/home-assistant/blueprints/broskie-zigbee-3button.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gpio,node_gestures,node_person toneBlue
class node_app,node_actions,node_device,node_network toneAmber
class node_battery_sample,node_battery_attrs toneMint
class node_converter,node_blueprint_single,node_blueprint_three toneRose
class node_coordinator,node_z2m,node_ha toneIndigo
```

## Components

### Button firmware

- [Button GPIO](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/buttons.c): `src/buttons.c`
- [Gesture detection](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/buttons.c): `src/buttons.c`

### Zigbee device

- [Application startup](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/main.c): `src/main.c`
- [Zigbee actions](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/zigbee_actions.c): `src/zigbee_actions.c`
- [Zigbee endpoints](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/include/zb_button_remote.h): `include/zb_button_remote.h`
- **Zigbee stack**

### Battery reporting

- [Voltage sampling](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/battery.c): `src/battery.c`
- [Battery attributes](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/src/battery.c): `src/battery.c`

### Home integrations

- [Zigbee2MQTT converter](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/zigbee2mqtt/broskie_zigbee_button.mjs): `zigbee2mqtt/broskie_zigbee_button.mjs`
- [Single-button blueprint](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/home-assistant/blueprints/broskie-zigbee-button.yaml): `home-assistant/blueprints/broskie-zigbee-button.yaml`
- [Three-button blueprint](https://github.com/bp974/xiao-nrf52840-zigbee-button/blob/main/home-assistant/blueprints/broskie-zigbee-3button.yaml): `home-assistant/blueprints/broskie-zigbee-3button.yaml`

### Other components

- **Button user**
- **Zigbee coordinator**
- **Zigbee2MQTT**
- **Home Assistant**

## Connections

- Button user → Button GPIO: presses (evidence: `README.md`)
- Button GPIO → Gesture detection: signals changes (evidence: `src/buttons.c`)
- Application startup → Gesture detection: initializes (evidence: `src/main.c`)
- Gesture detection → Zigbee actions: dispatches gestures
- Zigbee actions → Zigbee stack: schedules commands (evidence: `src/zigbee_actions.c`)
- Zigbee actions → Zigbee coordinator: sends cluster commands (evidence: `src/zigbee_actions.c`)
- Application startup → Zigbee endpoints: registers endpoints (evidence: `src/main.c`)
- Application startup → Zigbee stack: enables sleepy operation (evidence: `src/main.c`)
- Zigbee stack → Zigbee coordinator: joins network (evidence: `README.md`)
- Application startup → Voltage sampling: initializes and starts (evidence: `src/main.c`)
- Voltage sampling → Battery attributes: updates attributes (evidence: `src/battery.c`)
- Battery attributes → Zigbee endpoints: publishes voltage (evidence: `src/battery.c`)
- Zigbee endpoints → Zigbee2MQTT converter: reports Zigbee attributes (evidence: `README.md`)
- Zigbee coordinator → Zigbee2MQTT: delivers commands (evidence: `README.md`)
- Zigbee2MQTT → Zigbee2MQTT converter: loads converter (evidence: `README.md`)
- Zigbee2MQTT converter → Home Assistant: exposes actions and voltage (evidence: `zigbee2mqtt/broskie_zigbee_button.mjs`)
- Single-button blueprint → Home Assistant: configures automation (evidence: `README.md`)
- Three-button blueprint → Home Assistant: configures automation (evidence: `README.md`)