feat: improve MQTT discovery publishing and examples

examples/02-switch-callback/README.md

@@ -0,0 +1,9 @@
+# Switch Callback
+
+This example creates one writable Home Assistant switch. When Home Assistant sends a command, `onOutputCommand()` changes the local output and immediately reports the resulting state back through the supplied `HASwitch`.
+
+The ESP8266 build uses `LED_BUILTIN`; the ESP32 build uses GPIO 2. Confirm your board’s LED polarity before treating that output as a real load.
+
+Set the Wi-Fi and MQTT placeholders in `include/ExampleNetwork.h`, flash the board, then toggle **Example output** in Home Assistant.
+
+See [MQTT usage](../../docs/mqtt-usage.md) and the shared [examples guide](../README.md).

examples/02-switch-callback/include/ExampleNetwork.h

@@ -0,0 +1,37 @@
+#pragma once
+#if defined(ESP32)
+#include <Network.h>
+#include <WiFi.h>
+#else
+#include <ESP8266WiFi.h>
+#endif
+
+#ifndef EXAMPLE_WIFI_SSID
+#define EXAMPLE_WIFI_SSID "replace-with-wifi-name"
+#endif
+#ifndef EXAMPLE_WIFI_PASSWORD
+#define EXAMPLE_WIFI_PASSWORD "replace-with-wifi-password"
+#endif
+#ifndef EXAMPLE_MQTT_HOST
+#define EXAMPLE_MQTT_HOST "replace-with-mqtt-host"
+#endif
+#ifndef EXAMPLE_MQTT_USER
+#define EXAMPLE_MQTT_USER ""
+#endif
+#ifndef EXAMPLE_MQTT_PASSWORD
+#define EXAMPLE_MQTT_PASSWORD ""
+#endif
+
+inline void connectExampleWiFi() {
+    WiFi.mode(WIFI_STA);
+    WiFi.begin(EXAMPLE_WIFI_SSID, EXAMPLE_WIFI_PASSWORD);
+    while (WiFi.status() != WL_CONNECTED) {
+        delay(250);
+    }
+}
+
+inline void setExampleUniqueId(HADevice& device) {
+    uint8_t mac[6];
+    WiFi.macAddress(mac);
+    device.setUniqueId(mac, sizeof(mac));
+}

examples/02-switch-callback/platformio.ini

@@ -0,0 +1,24 @@
+[platformio]
+default_envs = esp8266
+
+[common]
+framework = arduino
+lib_ldf_mode = deep+
+lib_deps =
+    home-assistant-integration=symlink://../..
+
+[env:esp8266]
+extends = common
+platform = espressif8266
+board = d1_mini
+platform_packages =
+    platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git#521ae60a89e64bb0d1eb7a0b7addf620ced5cad3
+
+[env:esp32]
+extends = common
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip
+board = esp32dev
+build_unflags = -std=gnu++11
+build_flags =
+    -std=gnu++14
+    -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src

examples/02-switch-callback/src/main.cpp

@@ -0,0 +1,36 @@
+#include <Arduino.h>
+#include <ArduinoHA.h>
+#include "ExampleNetwork.h"
+
+#if defined(ESP32)
+constexpr uint8_t kOutputPin = 2;
+#else
+constexpr uint8_t kOutputPin = LED_BUILTIN;
+#endif
+
+WiFiClient client;
+HADevice device;
+HAMqtt mqtt(client, device);
+HASwitch output("output");
+
+void onOutputCommand(bool state, HASwitch* sender) {
+    digitalWrite(kOutputPin, state ? HIGH : LOW);
+    sender->setState(state);
+}
+
+void setup() {
+    Serial.begin(115200);
+    pinMode(kOutputPin, OUTPUT);
+    digitalWrite(kOutputPin, LOW);
+    connectExampleWiFi();
+    setExampleUniqueId(device);
+
+    device.setName("ArduinoHA switch example");
+    output.setName("Example output");
+    output.onCommand(onOutputCommand);
+    mqtt.begin(EXAMPLE_MQTT_HOST, EXAMPLE_MQTT_USER, EXAMPLE_MQTT_PASSWORD);
+}
+
+void loop() {
+    mqtt.loop();
+}