From 824b9e392b252415c5e8fe289714449b6318bdda Mon Sep 17 00:00:00 2001
From: Scott Penrose <scooter.me@gmail.com>
Date: Mon, 8 Jun 2026 02:42:43 +1000
Subject: [PATCH] local example

---
 examples/echo/platformio.ini | 18 +++++++++++
 examples/echo/src/main.cpp   | 62 ++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)
 create mode 100644 examples/echo/platformio.ini
 create mode 100644 examples/echo/src/main.cpp

diff --git a/examples/echo/platformio.ini b/examples/echo/platformio.ini
new file mode 100644
index 0000000..7766709
--- /dev/null
+++ b/examples/echo/platformio.ini
@@ -0,0 +1,18 @@
+; Self-contained PlatformIO project for the "echo" example.
+;
+; Unlike `pio ci`, this is a normal project you can build, upload and monitor
+; right here. It pulls in the library from the repo root (two levels up) via a
+; relative symlink dependency, so there is no copy of the source -- the library's
+; library.json compiles src/meshcore_companion.c + src/MeshCoreCompanion.cpp.
+;
+;     cd examples/echo
+;     pio run                 # compile
+;     pio run -t upload       # flash over USB
+;     pio device monitor      # serial console (115200)
+
+[env:esp32-s3]
+platform = espressif32
+board = esp32-s3-devkitc-1
+framework = arduino
+monitor_speed = 115200
+lib_deps = symlink://../..
diff --git a/examples/echo/src/main.cpp b/examples/echo/src/main.cpp
new file mode 100644
index 0000000..71c10e8
--- /dev/null
+++ b/examples/echo/src/main.cpp
@@ -0,0 +1,62 @@
+/*
+ * echo example -- decode a MeshCore channel to the USB serial console.
+ *
+ * Listens to a companion radio on a hardware UART (Serial1) and echoes every
+ * decoded channel message and data frame to the USB serial monitor (Serial).
+ * A read-only "what's on the mesh" window: no sending, no heartbeat.
+ *
+ * Built as a self-contained PlatformIO project (see platformio.ini next to this
+ * file) that depends on the library at the repo root via a relative symlink.
+ *
+ *   cd examples/echo && pio run -t upload && pio device monitor
+ *
+ * SPDX-License-Identifier: MIT
+ * Author: Scott Penrose / Digital Dimensions.
+ */
+#include <Arduino.h>
+#include "MeshCoreCompanion.h"
+
+// --- UART to the companion radio (CHANGE to free GPIOs on your S3 board) ---
+static const int      UART_RX_PIN = 16;   // host RX <- companion TX
+static const int      UART_TX_PIN = 17;   // host TX -> companion RX
+static const uint32_t UART_BAUD   = 115200;
+
+// Channel to listen on. The radio decodes channel traffic, so it needs the PSK;
+// we program it on connect. Replace with your real 16-byte PSK (32 hex chars).
+static const uint8_t  CHANNEL_IDX      = 2;
+static const char*    CHANNEL_NAME     = "sensors";
+static const char*    CHANNEL_PSK_HEX  = "000102030405060708090a0b0c0d0e0f";
+
+MeshCoreCompanion mc(Serial1);
+
+void setup() {
+    Serial.begin(115200);
+    Serial1.begin(UART_BAUD, SERIAL_8N1, UART_RX_PIN, UART_TX_PIN);
+
+    mc.onDeviceInfo([](const mc_device_info_t& d) {
+        Serial.printf("[radio] %s  fw=%d  channels=%u  build=%s\n",
+                      d.model, d.fw_ver, d.max_channels, d.build_date);
+        // Make sure the radio is on the channel we want to echo.
+        mc.setChannelHexSecret(CHANNEL_IDX, CHANNEL_NAME, CHANNEL_PSK_HEX);
+    });
+
+    // Decoded channel TEXT -> serial. Body is "SenderName: message".
+    mc.onChannelMessage([](const mc_channel_msg_t& m) {
+        Serial.printf("[ch %d] %s\n", m.channel_idx, m.text);
+    });
+
+    // Decoded channel DATA -> serial, with link metadata.
+    mc.onChannelData([](const mc_channel_data_t& d) {
+        Serial.printf("[ch %d] %u bytes  type=0x%04X  snr=%.1f dB  %s\n",
+                      d.channel_idx, d.data_len, d.data_type,
+                      MC_SNR_DB(d.snr_q4),
+                      d.path_len == MC_PATH_DIRECT ? "direct" : "flood");
+    });
+
+    mc.begin();   // resets RX, sends AppStart + DeviceQuery
+    Serial.println("echo: listening...");
+}
+
+void loop() {
+    mc.loop();    // pump serial; auto-drains the radio queue on MsgWaiting
+}