Add ArduinoHALog helpers, extend ArduinoHADefines, update mqtt usage doc

docs/mqtt-usage.md

@@ -56,7 +56,7 @@ device.enableLastWill();   // broker publishes offline when TCP drops
 
 Defined in `ArduinoHADefines.h` or via build flags.
 
-- **`ARDUINOHA_DEBUG`** — enables library logging (useful when debugging MQTT).
+- **`ARDUINOHA_DEBUG`** — enables library logging (useful when debugging MQTT). By default lines go to **`Serial`** unless you install a sink with **`arduinoHASetLogSink(ArduinoHALogSink*)`** (for example **DeviceFramework** forwards debug output into its main log stream).
 
 **Exclude unused device types** (saves flash from vtables), e.g.:
 

src/ArduinoHADefines.h

@@ -1,8 +1,10 @@
 // Turns on debug information of the ArduinoHA core.
-// Please note that you need to initialize serial interface manually
-// by calling Serial.begin([baudRate]) before initializing ArduinoHA.
+// Without a log sink (arduinoHASetLogSink), initialize Serial (e.g. Serial.begin(115200)) before ArduinoHA.
+// With a sink installed, the host is responsible for transport setup.
 // #define ARDUINOHA_DEBUG
 
+#include "ArduinoHALog.h"
+
 // These macros allow to exclude some parts of the library to save more resources.
 // #define EX_ARDUINOHA_BINARY_SENSOR
 // #define EX_ARDUINOHA_BUTTON
@@ -35,9 +37,15 @@
 #if defined(ARDUINOHA_DEBUG)
     #include <Arduino.h>
 
-    #define ARDUINOHA_DEBUG_INIT() Serial.begin(115200);
-    #define ARDUINOHA_DEBUG_PRINTLN(x) Serial.println(x);
-    #define ARDUINOHA_DEBUG_PRINT(x) Serial.print(x);
+    #define ARDUINOHA_DEBUG_INIT() do { if (!arduinoHAGetLogSink()) { Serial.begin(115200); } } while(0)
+    #define ARDUINOHA_DEBUG_PRINTLN(x) do { \
+        if (arduinoHAGetLogSink()) { arduinoHAGetLogSink()->println(String(x)); } \
+        else { Serial.println(x); } \
+    } while(0)
+    #define ARDUINOHA_DEBUG_PRINT(x) do { \
+        if (arduinoHAGetLogSink()) { arduinoHAGetLogSink()->print(String(x)); } \
+        else { Serial.print(x); } \
+    } while(0)
 #else
     #define ARDUINOHA_DEBUG_INIT()
     #define ARDUINOHA_DEBUG_PRINTLN(x)

src/ArduinoHALog.cpp

@@ -0,0 +1,11 @@
+#include "ArduinoHALog.h"
+
+static ArduinoHALogSink* g_arduinoHALogSink = nullptr;
+
+void arduinoHASetLogSink(ArduinoHALogSink* sink) {
+    g_arduinoHALogSink = sink;
+}
+
+ArduinoHALogSink* arduinoHAGetLogSink() {
+    return g_arduinoHALogSink;
+}

src/ArduinoHALog.h

@@ -0,0 +1,20 @@
+#ifndef ARDUINOHA_LOG_H
+#define ARDUINOHA_LOG_H
+
+#include <Arduino.h>
+
+/**
+ * Optional sink for ArduinoHA debug output (ARDUINOHA_DEBUG).
+ * When set, ARDUINOHA_DEBUG_* macros route here; otherwise Serial is used.
+ */
+class ArduinoHALogSink {
+public:
+    virtual void print(const String& s) = 0;
+    virtual void println(const String& s) = 0;
+    virtual ~ArduinoHALogSink() = default;
+};
+
+void arduinoHASetLogSink(ArduinoHALogSink* sink);
+ArduinoHALogSink* arduinoHAGetLogSink();
+
+#endif