From c9e6eef5b27208f4a88a72da626a19c4c69a1834 Mon Sep 17 00:00:00 2001
From: Alex Hope-O'Connor <alex.hope.oconnor@pomonaqld.au>
Date: Wed, 22 Apr 2026 12:09:12 +1000
Subject: [PATCH] Add ArduinoHALog helpers, extend ArduinoHADefines, update
 mqtt usage doc

---
 docs/mqtt-usage.md     |  2 +-
 src/ArduinoHADefines.h | 18 +++++++++++++-----
 src/ArduinoHALog.cpp   | 11 +++++++++++
 src/ArduinoHALog.h     | 20 ++++++++++++++++++++
 4 files changed, 45 insertions(+), 6 deletions(-)
 create mode 100644 src/ArduinoHALog.cpp
 create mode 100644 src/ArduinoHALog.h

diff --git a/docs/mqtt-usage.md b/docs/mqtt-usage.md
index 332d10a..6a741ce 100644
--- a/docs/mqtt-usage.md
+++ b/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.:
 
diff --git a/src/ArduinoHADefines.h b/src/ArduinoHADefines.h
index 3f98e9b..686bc94 100644
--- a/src/ArduinoHADefines.h
+++ b/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)
diff --git a/src/ArduinoHALog.cpp b/src/ArduinoHALog.cpp
new file mode 100644
index 0000000..ef7c253
--- /dev/null
+++ b/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;
+}
diff --git a/src/ArduinoHALog.h b/src/ArduinoHALog.h
new file mode 100644
index 0000000..e96b90b
--- /dev/null
+++ b/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