Button+ V2 — Home Assistant Integration

Native Home-Assistant-Integration für das Button+ Gerät mit V2-Firmware (2.x/3.x). Alle Komponenten des Geräts als echte HA-Entitäten, robuste Neustart-Behandlung und Button-Aktionen direkt als Device Triggers im Automations-Editor.

Features

• Setup in unter 5 Minuten: IP-Adresse eingeben, fertig — die Integration lädt die Gerätekonfiguration selbst (GET /config)
• Buttons als Event-Entities mit sauber normalisierten Events: press, release, long_press, single_click, double_click (Doppelklick wird aus zwei Kurzklicks im konfigurierbaren Zeitfenster abgeleitet — die Firmware kennt nativ keinen; die Longpress-Eventflut der Firmware (~30/s) wird auf ein einzelnes Event entprellt)
• Device Triggers: „Button 3 → Doppelklick" direkt im Automations-Editor auswählbar, ohne MQTT-Kenntnisse
• LEDs (front/wall je Button) als RGB-Lights, Gesamthelligkeit als Light
• Labels & Display-Items als beschreibbare Text-Entities
• Sensoren (Temperatur, Umgebungslicht) + Diagnose (WLAN-Signal, Chip-Temperatur, freier Speicher, Firmware, IP)
• Neustart-Erkennung ohne LWT: Sensor-Stream als Heartbeat; nach einem Boot werden Config re-synchronisiert und die Display-Werte automatisch re-published (die das Gerät beim Neustart verliert)
• Resilienz: Timeouts/Retries mit Backoff, ConfigEntryNotReady, Reload ohne HA-Neustart, periodischer Config-Sync (Default 15 min)
• Events auf dem HA-Bus (button_plus_v2_event) für Power-User

Installation

HACS (empfohlen)

1. HACS → Integrationen → ⋮ → Benutzerdefinierte Repositories
2. https://github.com/mdellwing/HABP2 als Integration hinzufügen
3. „Button+ V2" installieren, HA neu starten

Manuell

custom_components/button_plus_v2/ in das HA-Config-Verzeichnis unter custom_components/ kopieren und HA neu starten.

Einrichtung

1. Einstellungen → Geräte & Dienste → Integration hinzufügen → „Button+ V2"
2. IP-Adresse des Geräts eingeben — alle Entitäten werden automatisch angelegt
3. Empfohlen: In der WebUI des Geräts (http://<geräte-ip>) unter den Broker-Einstellungen hassdiscovery deaktivieren, sonst legt die HA-MQTT-Integration parallele (doppelte) Entitäten an. Das Default-Schema muss aktiviert bleiben — es liefert die Live-Daten.

Optionen

Option	Default	Beschreibung
MQTT-Topic-Prefix	buttonplus	Basis-Prefix der Geräte-Topics
Doppelklick-Fenster	400 ms	Max. Abstand zweier Klicks für double_click
Sync-Intervall	15 min	Periodischer Abgleich mit GET /config

Hinweis zum Timing: press und release feuern unverzögert. Ein single_click wird erst nach Ablauf des Doppelklick-Fensters gemeldet (Default 400 ms) — nur so ist er sicher von einem Doppelklick unterscheidbar.

Voraussetzungen

• Home Assistant ≥ 2024.6 mit eingerichteter MQTT-Integration
• Button+ Gerät mit V2-Firmware, verbunden mit demselben MQTT-Broker (Default-Schema aktiv)

Entwicklung

Details zur Architektur in docs/ARCHITECTURE.md, das live erfasste MQTT-Schema in docs/MQTT.md.

python3 -m unittest discover tests

Lizenz

MIT