multiple buttons

PKA_SUMMARY.md

@@ -0,0 +1,24 @@
+---
+title: "esp32-debug-dongle"
+source: pka-assess
+---
+
+# esp32-debug-dongle
+
+## Purpose
+
+ESP32 dev-kit firmware turning the chip into a WiFi + Bluetooth serial-terminal dongle. Browser-based terminal uses xterm.js served from the ESP's LittleFS; also exposes a classic Bluetooth SPP port for desktop/mobile terminal apps. Multi-port (internal debug / USB / external Serial1) with on-the-fly baud-rate switching.
+
+## Type
+
+ESP32 PlatformIO firmware. `#embedded`, `#firmware`, `#iot`, `#service`.
+
+## Dependencies
+
+- **External:** PlatformIO `espressif32` + Arduino framework, xterm.js (bundled in LittleFS), Bluetooth SPP stack (classic BT — needs a WROOM-style ESP32, NOT S2/S3/C3).
+- **Internal:** complementary tool to ESP32 Sh3d projects — [[Sh3dNb]], [[Sh3dController]], [[Sh3dStick]], [[Doxy]] — when serial access is awkward.
+
+## Notable
+
+- Uses a `huge_app.csv` partition (3 MB app, 1 MB FS, no OTA) — swap to `min_spiffs.csv` if OTA is needed.
+- Classic Bluetooth requirement is a hard constraint on target hardware.

PLAN.md

@@ -0,0 +1,69 @@
+# esp32-debug-dongle → LilyGo T3-S3 debug bridge
+
+## Why
+USB serial to the trough/solartrack sensors drops on every deep sleep, so we
+can't watch boots/crashes/wakes. This dongle becomes an always-connected box on
+the LAN that bridges a sensor's UART to telnet + a web terminal, controls GPIO
+to reset/wake the target, logs to SD, and (Phase 2) sniffs the MeshCore LoRa
+mesh — so we can debug remotely and stop flying blind.
+
+## Decisions (confirmed with user)
+1. **Board: LilyGo T3-S3** (ESP32-S3 + SX127x LoRa + SSD1306 128×64 OLED + SD).
+   Chosen over TTGO for onboard SD and LoRa (mesh monitoring).
+2. **Extend `esp32-debug-dongle` in place** (not a new Sh3dNb app). Keep the
+   existing `esp32dev` env working; add a `t3s3` env.
+3. **Both telnet (:23) and the WebSocket terminal.** Telnet is the primary
+   remote control path (nc/minicom + an agent driving it); GPIO reset/wake and
+   port/baud are exposed as **both** telnet `~commands` and REST endpoints.
+4. **SD logging in Phase 1, ON by default** once NTP (built-in `configTzTime`)
+   gives today's date — log file named/stamped from real time.
+5. **Power monitoring: out of scope.**
+6. **Phase 2: MeshCore monitor** over the onboard LoRa (passive RX of mesh
+   packets, surfaced on telnet/web/SD).
+
+## Board facts that shape the build
+- ESP32-S3 has **no Bluetooth Classic** → `BluetoothSerial`/SerialBT is guarded
+  behind `HAS_BT_CLASSIC` (esp32dev only). On T3-S3, telnet + WebSocket replace it.
+- USB CDC on boot (`-DARDUINO_USB_CDC_ON_BOOT=1`) → UART0 (GPIO43/44) is free for
+  the target bridge.
+- Pins (from `Sh3dNb/apps_oglas/lilygot3s3_basic`): OLED SDA18/SCL17/RST21@0x3C;
+  LoRa SCK5/MISO3/MOSI6/CS7/RST8/DIO0:9; BTN0.
+
+## Phase 1 (this build) — extend src/main.cpp + platformio.ini
+- **platformio.ini**: keep `[env:esp32dev]` (+ `-DHAS_BT_CLASSIC=1`); add
+  `[env:t3s3]` (esp32-s3-devkitc-1, USB CDC on boot, huge_app, littlefs,
+  Adafruit SSD1306+GFX). All pins via build flags (target UART, GPIO reset/wake,
+  SD, OLED) so they're config, not hardcoded.
+- **Target UART bridge**: Serial1 on `TARGET_RX/TX` pins ↔ fan-out to WebSocket
+  (existing), **telnet clients**, and **SD log**. RX/TX byte+line counters.
+- **Telnet server :23** with line protocol: non-`~` lines forward to the target
+  UART; `~` lines are commands:
+  `~help ~status ~reset [ms] ~wake [ms] ~baud <n> ~port <int|usb|ext> ~log on|off
+   ~gpio <pin> <0|1>`. Lets an operator (or agent via `nc`) drive a remote board.
+- **REST** (mirror of the commands): `/api/status /api/reset /api/wake
+  /api/baud?baud= /api/log?on= /api/gpio?pin=&val= /api/send?data=`.
+- **GPIO control**: configurable `reset`/`wake` pins (active-low option), pulse.
+- **NTP + SD logging**: `configTzTime(<TZ>)`; once time syncs, open
+  `/logs/YYYYMMDD-HHMMSS.log` and append timestamped serial. Logging ON by
+  default; `~log off` / REST toggles. Graceful no-op if SD absent/pins wrong.
+- **OLED**: IP/SSID/RSSI, target pins+baud, RX/TX counts, telnet client count,
+  logging on/off, NTP synced y/n.
+
+## Phase 2 — MeshCore monitor (later)
+- Bring up the T3-S3 LoRa radio (confirm chip: SX1276 vs SX1262 variant) with
+  the mesh's PHY (freq/SF/BW/CR matching the sensors), RX-only.
+- Decode/forward MeshCore channel frames to telnet/web/SD so we see beacons
+  (e.g. count trough beacons to confirm the sleep-crash fix) without a sensor.
+
+## Pins to CONFIRM against the actual board (set as build flags)
+- **SD**: SCK/MISO/MOSI/CS for the T3-S3 SD slot (may share the LoRa SPI bus +
+  own CS — verify). Logging silently disables if wrong.
+- **Target UART bridge** RX/TX (default UART0 43/44, free under USB CDC).
+- **GPIO reset/wake** pins to whatever lines you wire to the sensor's RST/control.
+- **LoRa chip variant** (Phase 2).
+
+## Verify
+- `pio run -e t3s3` compiles; `pio run -e esp32dev` still compiles (BT intact).
+- Flash T3-S3: OLED shows IP; `nc <ip> 23` streams a wired sensor's UART;
+  `~reset` reboots it (seen on the same stream); a dated file appears under
+  `/logs` on the SD and grows.

data/index.html

@@ -109,16 +109,85 @@
             background: #ef4444;
         }
         
+        .main-row {
+            flex: 1;
+            display: flex;
+            min-height: 0;
+        }
+
         .terminal-container {
             flex: 1;
             padding: 10px;
             overflow: hidden;
+            min-width: 0;
         }
-        
+
         #terminal {
             height: 100%;
         }
-        
+
+        /* Right-side comms panel (MeshCore today, more later) */
+        .comms-panel {
+            flex: 0 0 340px;
+            display: flex;
+            flex-direction: column;
+            background: #16213e;
+            border-left: 1px solid #0f3460;
+            padding: 10px 12px;
+            gap: 10px;
+            min-height: 0;
+        }
+        .comms-panel h2 {
+            margin: 0;
+            font-size: 1em;
+            color: #e94560;
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+        }
+        .comms-cfg {
+            display: flex;
+            flex-direction: column;
+            gap: 6px;
+            font-size: 0.85em;
+        }
+        .comms-cfg input {
+            background: #0f3460;
+            color: #fff;
+            border: 1px solid #1a4a7a;
+            padding: 6px 8px;
+            border-radius: 4px;
+            font-size: 0.9em;
+            width: 100%;
+        }
+        .comms-cfg .row { display: flex; gap: 6px; }
+        .comms-cfg .row input { flex: 1; }
+        #meshMessages {
+            flex: 1;
+            overflow-y: auto;
+            background: #0f1a30;
+            border: 1px solid #0f3460;
+            border-radius: 4px;
+            padding: 6px 8px;
+            font-family: Menlo, Monaco, "Courier New", monospace;
+            font-size: 0.8em;
+            line-height: 1.4;
+            min-height: 60px;
+        }
+        .mc-msg { margin-bottom: 4px; word-break: break-word; }
+        .mc-msg .who { color: #60a5fa; }
+        .mc-msg.tx .who { color: #4ade80; }
+        .mc-msg .meta { color: #666; font-size: 0.85em; }
+        .mc-empty { color: #666; }
+        .comms-send { display: flex; gap: 6px; }
+        .comms-send input { flex: 1; }
+        .mesh-dot {
+            width: 8px; height: 8px; border-radius: 50%;
+            background: #666; display: inline-block;
+        }
+        .mesh-dot.up { background: #4ade80; }
+        .mesh-dot.down { background: #ef4444; }
+
         .footer {
             background: #16213e;
             padding: 8px 20px;
@@ -138,6 +207,14 @@
                 display: none;
             }
         }
+        @media (max-width: 900px) {
+            .main-row { flex-direction: column; }
+            .comms-panel {
+                flex: 0 0 45vh;
+                border-left: none;
+                border-top: 1px solid #0f3460;
+            }
+        }
     </style>
 </head>
 <body>
@@ -165,8 +242,13 @@
                     <option value="921600">921600</option>
                 </select>
             </div>
+            <button class="danger" onclick="doReset()" title="Pulse the target reset line">Reset</button>
+            <button onclick="doButton()" title="Momentary press of the target button / wake line">Button</button>
+            <button id="holdBtn" onclick="toggleHold()" title="Latch the button line held down (force-on) / release">Hold: off</button>
             <button onclick="clearTerminal()">Clear</button>
             <button onclick="reconnect()">Reconnect</button>
+            <button id="logBtn" onclick="toggleLog()">Log: --</button>
+            <button onclick="toggleFiles()">Files</button>
         </div>
         <div class="status">
             <div class="status-item">
@@ -184,10 +266,39 @@
         </div>
     </div>
     
-    <div class="terminal-container">
-        <div id="terminal"></div>
+    <div id="filesPanel" style="display:none; background:#16213e; border-bottom:1px solid #0f3460; padding:10px 20px; max-height:40vh; overflow:auto;">
+        <div style="display:flex; justify-content:space-between; align-items:center; margin-bottom:8px;">
+            <strong>SD log files</strong>
+            <span><span id="logState" style="color:#aaa; margin-right:10px;"></span><button onclick="refreshLogs()">Refresh</button></span>
+        </div>
+        <table id="filesTable" style="width:100%; border-collapse:collapse; font-size:0.85em;"></table>
     </div>
-    
+
+    <div class="main-row">
+        <div class="terminal-container">
+            <div id="terminal"></div>
+        </div>
+
+        <div class="comms-panel" id="commsPanel">
+            <h2>
+                <span>📡 MeshCore</span>
+                <span><span class="mesh-dot" id="meshDot"></span> <span id="meshState" style="font-size:0.75em;color:#aaa;">…</span></span>
+            </h2>
+            <div class="comms-cfg">
+                <input type="text" id="meshChan" placeholder="Channel name (e.g. SensorsTest)">
+                <div class="row">
+                    <input type="text" id="meshPsk" placeholder="PSK (base64, 16 or 32-byte key)">
+                    <button onclick="programChannel()">Program</button>
+                </div>
+            </div>
+            <div id="meshMessages"><div class="mc-empty">No messages yet.</div></div>
+            <div class="comms-send">
+                <input type="text" id="meshInput" placeholder="Message…" onkeydown="if(event.key==='Enter')sendMesh()">
+                <button onclick="sendMesh()">Send</button>
+            </div>
+        </div>
+    </div>
+
     <div class="footer">
         <span id="rxCount">RX: 0 bytes</span>
         <span id="txCount">TX: 0 bytes</span>
@@ -198,6 +309,7 @@
         // Terminal setup
         const term = new Terminal({
             cursorBlink: true,
+            convertEol: true,   // target sends bare '\n'; treat it as CRLF so lines don't staircase
             fontSize: 14,
             fontFamily: 'Menlo, Monaco, "Courier New", monospace',
             theme: {
@@ -262,6 +374,7 @@
                 
                 // Request initial status
                 sendCommand({ cmd: 'getStatus' });
+                sendCommand({ cmd: 'meshGet' });
             };
             
             ws.onclose = () => {
@@ -283,6 +396,13 @@
             };
             
             ws.onmessage = (event) => {
+                // Control/mesh events arrive as text frames (0x00-prefixed JSON).
+                if (typeof event.data === 'string') {
+                    let s = event.data;
+                    if (s.charCodeAt(0) === 0) s = s.slice(1);
+                    try { handleResponse(JSON.parse(s)); } catch (e) {}
+                    return;
+                }
                 if (event.data instanceof ArrayBuffer) {
                     const data = new Uint8Array(event.data);
                     
@@ -315,6 +435,8 @@
                     document.getElementById('baudSelect').value = msg.baudSerial1;
                     updateStatus('btStatus', msg.btConnected);
                     document.getElementById('heap').textContent = `Heap: ${msg.freeHeap}`;
+                    updateLogUi(msg);
+                    updateButtonUi(msg);
                     
                     // Show WiFi info
                     const wifiInfo = document.getElementById('wifiInfo');
@@ -333,8 +455,75 @@
                     const portNames = ['Internal', 'USB Serial', 'External'];
                     term.writeln(`\r\n\x1b[33m[Switched to ${portNames[msg.port]}]\x1b[0m\r\n`);
                     break;
+
+                case 'mesh':
+                    appendMeshMsg(msg);
+                    break;
+
+                case 'meshcfg':
+                    updateMeshCfg(msg);
+                    break;
             }
         }
+
+        // ---- MeshCore comms panel ----
+        let meshEnabled = false;
+        function updateMeshCfg(c) {
+            meshEnabled = !!c.enabled;
+            const dot = document.getElementById('meshDot');
+            const state = document.getElementById('meshState');
+            const chan = document.getElementById('meshChan');
+            const psk = document.getElementById('meshPsk');
+            if (!meshEnabled) {
+                dot.className = 'mesh-dot';
+                state.textContent = 'not in build';
+            } else if (c.up) {
+                dot.className = 'mesh-dot up';
+                state.textContent = `up · rx ${c.rx} tx ${c.tx}`;
+            } else {
+                dot.className = 'mesh-dot down';
+                state.textContent = 'radio down';
+            }
+            // Don't clobber a field the user is editing.
+            if (document.activeElement !== chan && typeof c.channel !== 'undefined') chan.value = c.channel;
+            if (document.activeElement !== psk && typeof c.psk !== 'undefined') psk.value = c.psk;
+            const disabled = !meshEnabled;
+            document.getElementById('meshInput').disabled = disabled;
+        }
+        function appendMeshMsg(m) {
+            const box = document.getElementById('meshMessages');
+            const empty = box.querySelector('.mc-empty');
+            if (empty) empty.remove();
+            const div = document.createElement('div');
+            div.className = 'mc-msg' + (m.dir === 'tx' ? ' tx' : '');
+            const t = new Date().toLocaleTimeString();
+            let meta = m.dir === 'tx' ? '↑' : '↓';
+            if (m.channel) meta += ' ' + m.channel;
+            if (typeof m.rssi !== 'undefined' && m.rssi) meta += ` ${m.rssi}dBm`;
+            div.innerHTML = `<span class="meta">[${t}] ${escapeHtml(meta)}</span> ` +
+                            `<span class="who">${escapeHtml(m.sender || '?')}:</span> ` +
+                            escapeHtml(m.text || '');
+            box.appendChild(div);
+            box.scrollTop = box.scrollHeight;
+        }
+        function escapeHtml(s) {
+            return String(s).replace(/[&<>"']/g, c =>
+                ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+        }
+        function programChannel() {
+            const name = document.getElementById('meshChan').value.trim();
+            const psk = document.getElementById('meshPsk').value.trim();
+            if (!psk) { alert('Enter a PSK (base64 16- or 32-byte key)'); return; }
+            sendCommand({ cmd: 'meshPsk', name: name, psk: psk });
+            setTimeout(() => sendCommand({ cmd: 'meshGet' }), 300);
+        }
+        function sendMesh() {
+            const inp = document.getElementById('meshInput');
+            const text = inp.value;
+            if (!text) return;
+            sendCommand({ cmd: 'meshSend', text: text });
+            inp.value = '';
+        }
         
         function sendCommand(cmd) {
             if (ws && ws.readyState === WebSocket.OPEN) {
@@ -406,6 +595,80 @@
             if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
             return (bytes / 1024 / 1024).toFixed(1) + ' MB';
         }
+
+        // ---- Target control lines (reset / button) ----
+        function pulseLine(path, label) {
+            fetch(path + '?ms=200').then(r => r.text())
+                .then(t => term.writeln(`\r\n\x1b[33m[${label}] ${t.trim()}\x1b[0m`))
+                .catch(() => term.writeln(`\r\n\x1b[31m[${label} failed]\x1b[0m`));
+        }
+        function doReset() { pulseLine('/api/reset', 'reset'); }
+        function doButton() {
+            fetch('/api/button?ms=200').then(r => r.json()).then(s => {
+                updateButtonUi(s);
+                term.writeln('\r\n\x1b[33m[button] pulsed\x1b[0m');
+            }).catch(() => term.writeln('\r\n\x1b[31m[button failed]\x1b[0m'));
+        }
+        let holdOn = false;
+        function toggleHold() {
+            fetch('/api/button?latch=' + (holdOn ? 'off' : 'on')).then(r => r.json()).then(s => {
+                updateButtonUi(s);
+                term.writeln(`\r\n\x1b[33m[button] hold ${holdOn ? 'ON' : 'off'}\x1b[0m`);
+            }).catch(() => term.writeln('\r\n\x1b[31m[hold failed]\x1b[0m'));
+        }
+        function updateButtonUi(s) {
+            if (typeof s.buttonLatch === 'undefined') return;
+            holdOn = !!s.buttonLatch;
+            const b = document.getElementById('holdBtn');
+            b.textContent = 'Hold: ' + (holdOn ? 'ON' : 'off');
+            b.classList.toggle('danger', holdOn);
+        }
+
+        // ---- SD logging controls ----
+        let logOn = false;
+        function toggleLog() {
+            fetch('/api/log?on=' + (logOn ? 0 : 1))
+                .then(r => r.json()).then(updateLogUi)
+                .catch(() => term.writeln('\r\n\x1b[31m[log toggle failed]\x1b[0m'));
+        }
+        function updateLogUi(s) {
+            if (typeof s.log === 'undefined') return;
+            logOn = !!s.log;
+            const b = document.getElementById('logBtn');
+            b.textContent = 'Log: ' + (logOn ? 'ON' : 'off');
+            b.classList.toggle('danger', logOn);
+            const st = document.getElementById('logState');
+            if (st) {
+                st.textContent = !s.sd ? 'no SD card'
+                    : s.logfile ? ('file: ' + String(s.logfile).split('/').pop())
+                    : (s.ntp ? 'idle' : 'waiting for NTP date');
+            }
+        }
+        function toggleFiles() {
+            const p = document.getElementById('filesPanel');
+            const show = p.style.display === 'none';
+            p.style.display = show ? 'block' : 'none';
+            if (show) refreshLogs();
+        }
+        function refreshLogs() {
+            fetch('/api/logs').then(r => r.json()).then(list => {
+                const t = document.getElementById('filesTable');
+                if (!list.length) { t.innerHTML = '<tr><td style="color:#666;">(no log files yet)</td></tr>'; return; }
+                t.innerHTML = list.map(f =>
+                    `<tr style="border-bottom:1px solid #0f3460;">
+                       <td style="padding:4px 0;">${f.name}${f.active ? ' <span style="color:#4ade80;">(active)</span>' : ''}</td>
+                       <td style="text-align:right; color:#aaa;">${formatBytes(f.size)}</td>
+                       <td style="text-align:right; padding-left:12px;"><a href="/api/logfile?name=${encodeURIComponent(f.name)}" style="color:#60a5fa;">download</a></td>
+                       <td style="text-align:right; padding-left:12px;">${f.active ? '' : `<a href="#" onclick="deleteLog('${f.name}');return false;" style="color:#e94560;">delete</a>`}</td>
+                     </tr>`).join('');
+            }).catch(() => {
+                document.getElementById('filesTable').innerHTML = '<tr><td style="color:#e94560;">(failed -- SD only on T3-S3 build)</td></tr>';
+            });
+        }
+        function deleteLog(name) {
+            if (!confirm('Delete ' + name + '?')) return;
+            fetch('/api/logdelete?name=' + encodeURIComponent(name)).then(() => refreshLogs());
+        }
         
         // Initial connection
         term.writeln('\x1b[1;36m╔═══════════════════════════════════════╗\x1b[0m');

platformio.ini

@@ -28,6 +28,9 @@ build_flags =
     -DCORE_DEBUG_LEVEL=3
     -DCONFIG_BT_ENABLED=1
     -DCONFIG_BLUEDROID_ENABLED=1
+    -DHAS_BT_CLASSIC=1                 ; classic SPP exists on the original ESP32
+    -DSTA_SSID="${sysenv.STA_SSID}"
+    -DSTA_PASSWORD="${sysenv.STA_PASSWORD}"
 
 ; Libraries
 lib_deps =
@@ -45,3 +48,138 @@ lib_deps =
 ; Extra scripts for LittleFS
 extra_scripts =
     pre:scripts/download_xterm.py
+
+; ============================================================================
+; LilyGo T3-S3 -- ESP32-S3 + SX127x LoRa + SSD1306 128x64 OLED + microSD.
+; The remote debug bridge: UART <-> telnet(:23)/WebSocket, GPIO reset/wake,
+; SD logging (NTP-dated), OLED status. NOTE: ESP32-S3 has NO Bluetooth Classic,
+; so HAS_BT_CLASSIC is NOT set here (telnet + WebSocket replace SerialBT).
+; Pins marked CONFIRM must be checked against your actual board wiring.
+; ============================================================================
+[env:t3s3]
+platform = espressif32
+board = esp32-s3-devkitc-1
+framework = arduino
+monitor_speed = 115200
+monitor_filters = esp32_exception_decoder
+board_build.mcu = esp32s3
+board_build.flash_size = 4MB
+board_upload.flash_size = 4MB
+board_build.filesystem = littlefs
+board_build.partitions = huge_app.csv
+build_flags =
+    -DCORE_DEBUG_LEVEL=3
+    -DARDUINO_USB_CDC_ON_BOOT=1        ; console on USB CDC -> frees UART0 (43/44)
+    ;-DSTA_SSID="${sysenv.STA_SSID}"
+    ;-DSTA_PASSWORD="${sysenv.STA_PASSWORD}"
+    -DSTA_SSID="MeridenRainbow5G"
+    -DSTA_PASSWORD="4z8bcw5vfrs3n7dm"
+    -DBOARD_T3S3=1
+    ; --- OLED (SSD1306 128x64) ---
+    -DT3S3_OLED_SDA=18
+    -DT3S3_OLED_SCL=17
+    -DT3S3_OLED_RST=21
+    -DT3S3_OLED_ADDR=0x3C
+    ; --- target UART bridge (wire to the sensor's debug UART) ---
+    -DTARGET_RX_PIN=44                 ; CONFIRM: dongle RX <- sensor TX
+    -DTARGET_TX_PIN=43                 ; CONFIRM: dongle TX -> sensor RX
+    ; --- GPIO control lines to the target (reset out / button out) ---
+    ; GPIO38 + GPIO39 are free pins on the T3-S3 RIGHT header, right next to the
+    ; UART pins TXD=43/RXD=44 -- so reset/button/TX/RX/GND all come off one row.
+    ; (GPIO2=SD MISO and GPIO1=battery ADC; GPIO4/12 are not broken out at all.)
+    -DGPIO_RESET_PIN=38                ; -> sensor RST (active-low pulse)
+    -DGPIO_WAKE_PIN=39                 ; -> sensor button/wake (active-low pulse)
+    -DGPIO_CTRL_ACTIVE_LOW=1
+    ; --- microSD on FSPI/SPI2 (separate bus from LoRa, which uses HSPI/SPI3) ---
+    -DT3S3_SD_SCK=14
+    -DT3S3_SD_MISO=2
+    -DT3S3_SD_MOSI=11
+    -DT3S3_SD_CS=13
+    -DT3S3_SD_FREQ_HZ=20000000UL
+    ; --- timezone for NTP-dated logs (Australia/Victoria) ---
+    -DNTP_TZ='"AEST-10AEDT,M10.1.0,M4.1.0/3"'
+lib_deps =
+    https://github.com/ESP32Async/ESPAsyncWebServer
+    https://github.com/ESP32Async/AsyncTCP
+    ArduinoJson
+    adafruit/Adafruit SSD1306
+    adafruit/Adafruit GFX Library
+extra_scripts =
+    pre:scripts/download_xterm.py
+
+; ============================================================================
+; LilyGo T3-S3 + MeshCore radio.  Extends env:t3s3 (OLED + SD logging) and
+; adds the SX1276 LoRa link so the web "MeshCore" panel and telnet ~psk/~msg
+; commands work.  Builds on the same hardware; pins match MeshCore's
+; experiment/lilygot3s3logger (the proven T3-S3 SX1276 reference).
+;
+;   pio run -e t3s3_mesh -t upload && pio run -e t3s3_mesh -t uploadfs
+; ============================================================================
+[env:t3s3_mesh]
+extends = env:t3s3
+; ed25519 (MeshCore's bundled identity crypto) lives in MeshCore/lib.
+lib_extra_dirs =
+    /home/scottp/github/MeshCore/lib
+lib_ldf_mode = deep+
+build_unflags =
+    -DBOARD_HAS_PSRAM
+lib_deps =
+    ${env:t3s3.lib_deps}
+    symlink:///home/scottp/github/MeshCore
+    jgromes/RadioLib @ ^7.6.0
+    rweather/Crypto @ ^0.4.0
+    adafruit/RTClib @ ^2.1.3
+    densaugeo/base64 @ ~1.4.0
+    Preferences
+    ed25519
+build_flags =
+    ${env:t3s3.build_flags}
+    -w
+    -DUSE_MESHCORE=1
+    -D ESP32_PLATFORM
+    ; --- pin 21 is the SX1276 RX-enable on the T3-S3, so the OLED can't use it
+    ;     as a reset line here; SSD1306 over I2C runs fine with no reset pin. ---
+    -DT3S3_OLED_RST=-1
+    ; --- RadioLib: lock to the SX127x family ---
+    -D RADIOLIB_STATIC_ONLY=1
+    -D RADIOLIB_GODMODE=1
+    -D RADIOLIB_EXCLUDE_CC1101=1
+    -D RADIOLIB_EXCLUDE_RF69=1
+    -D RADIOLIB_EXCLUDE_SX1231=1
+    -D RADIOLIB_EXCLUDE_SI443X=1
+    -D RADIOLIB_EXCLUDE_RFM2X=1
+    -D RADIOLIB_EXCLUDE_SX128X=1
+    -D RADIOLIB_EXCLUDE_AFSK=1
+    -D RADIOLIB_EXCLUDE_AX25=1
+    -D RADIOLIB_EXCLUDE_HELLSCHREIBER=1
+    -D RADIOLIB_EXCLUDE_MORSE=1
+    -D RADIOLIB_EXCLUDE_APRS=1
+    -D RADIOLIB_EXCLUDE_BELL=1
+    -D RADIOLIB_EXCLUDE_RTTY=1
+    -D RADIOLIB_EXCLUDE_SSTV=1
+    ; --- T3-S3 v1.2 SX1276 pin map (MeshCore variants/lilygo_t3s3_sx1276) ---
+    -D USE_SX1276
+    -D P_LORA_NSS=7
+    -D P_LORA_RESET=8
+    -D P_LORA_DIO_0=9
+    -D P_LORA_DIO_1=33
+    -D P_LORA_SCLK=5
+    -D P_LORA_MISO=3
+    -D P_LORA_MOSI=6
+    -D P_LORA_TX_LED=37
+    -D SX127X_CURRENT_LIMIT=120
+    -D SX176X_RXEN=21
+    -D SX176X_TXEN=10
+    ; --- LoRa PHY: Australia Narrow (match the sensor fleet) ---
+    -D LORA_FREQ=916.575
+    -D LORA_BW=62.5
+    -D LORA_SF=7
+    -D LORA_CR=8
+    -D LORA_TX_POWER=20
+    -D MAX_GROUP_CHANNELS=4
+    -D MAX_CONTACTS=8
+    ; --- channel defaults (runtime-overridable + persisted in NVS) ---
+    -D NODE_NAME='"dongle"'
+    -D SENSORS_CHANNEL_NAME='"SensorsTest"'
+    -D SENSORS_CHANNEL_PSK_B64='"PNtgMxiq9R7eQ3IleHoL3g=="'
+    -D PUBLIC_CHANNEL_PSK_B64='"izOH6cXN6mrJ5e26oRXNcg=="'

src/meshcore_link.cpp

@@ -0,0 +1,296 @@
+/**
+ * meshcore_link.cpp -- see meshcore_link.h.
+ *
+ * Pattern mirrors MeshCore/experiment/lilygot3s3logger (same board: LilyGo
+ * T3-S3, ESP32-S3 + SX1276), trimmed to a single reprogrammable channel.
+ */
+#include "meshcore_link.h"
+
+#if USE_MESHCORE
+
+#include <Arduino.h>
+#include <SPI.h>
+#include <LittleFS.h>
+#include <Preferences.h>
+#include <mbedtls/base64.h>   // ESP-IDF builtin; avoids clashing with MeshCore's base64.hpp
+
+#include <Mesh.h>
+#include <helpers/BaseChatMesh.h>
+#include <helpers/ArduinoHelpers.h>
+#include <helpers/StaticPoolPacketManager.h>
+#include <helpers/SimpleMeshTables.h>
+#include <helpers/IdentityStore.h>
+#include <helpers/ESP32Board.h>
+#include <helpers/AutoDiscoverRTCClock.h>
+#include <helpers/radiolib/CustomSX1276.h>
+#include <helpers/radiolib/CustomSX1276Wrapper.h>
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/queue.h"
+
+// ---- compile-time defaults (override via build flags) ----------------------
+#ifndef NODE_NAME
+#define NODE_NAME "dongle"
+#endif
+#ifndef SENSORS_CHANNEL_NAME
+#define SENSORS_CHANNEL_NAME "SensorsTest"
+#endif
+#ifndef SENSORS_CHANNEL_PSK_B64
+#define SENSORS_CHANNEL_PSK_B64 "PNtgMxiq9R7eQ3IleHoL3g=="
+#endif
+// Standard MeshCore "Public" channel (same key the companion examples use).
+#ifndef PUBLIC_CHANNEL_PSK_B64
+#define PUBLIC_CHANNEL_PSK_B64 "izOH6cXN6mrJ5e26oRXNcg=="
+#endif
+
+namespace {
+
+// ---- radio + mesh support objects (file-scope, mirrors the logger) ---------
+ESP32Board           board;
+// Radio on FSPI (SPI2). The SD card is on HSPI (SPI3, see main.cpp). They MUST
+// be different peripherals -- SPIClass() defaults to HSPI, which would collide
+// with the SD bus and corrupt it the moment the radio re-inits the pins.
+SPIClass             lora_spi(FSPI);
+CustomSX1276         lora(new Module(P_LORA_NSS, P_LORA_DIO_0, P_LORA_RESET, P_LORA_DIO_1, lora_spi));
+CustomSX1276Wrapper  radio_driver(lora, board);
+ESP32RTCClock        fallback_clock;
+AutoDiscoverRTCClock rtc_clock(fallback_clock);
+StdRNG               fast_rng;
+SimpleMeshTables     tables;
+
+mc::RxHandler        s_on_rx     = nullptr;
+bool                 s_up        = false;
+volatile bool        s_cfg_dirty = false;
+QueueHandle_t        s_queue     = nullptr;
+
+// User-channel state (index 1; "Public" sits at index 0).
+const int            USER_IDX = 1;
+char                 s_channel[32] = SENSORS_CHANNEL_NAME;
+char                 s_psk[48]     = SENSORS_CHANNEL_PSK_B64;
+
+// ---- queued action (producer = any task, consumer = loop()) ----------------
+struct McAction {
+    uint8_t kind;          // 0 = send text, 1 = reprogram channel
+    char    name[32];
+    char    text[176];
+};
+
+// Split "<sender>: <payload>" in place; returns sender (or "?") + payload.
+void split_sender(char* buf, const char** sender, const char** payload) {
+    *sender = "?";
+    *payload = buf;
+    char* sep = strstr(buf, ": ");
+    if (sep) { *sep = 0; *sender = buf; *payload = sep + 2; }
+}
+
+// ---- the mesh node ---------------------------------------------------------
+class DongleMesh : public BaseChatMesh {
+    ChannelDetails* _public = nullptr;
+    ChannelDetails* _user   = nullptr;
+    ChannelDetails  _user_view;          // kept in sync for sending
+    uint32_t        _rx = 0, _tx = 0;
+
+protected:
+    // Unused contact-protocol hooks -- this node only does channel chat.
+    void onDiscoveredContact(ContactInfo&, bool, uint8_t, const uint8_t*) override {}
+    void onContactPathUpdated(const ContactInfo&) override {}
+    ContactInfo* processAck(const uint8_t*) override { return nullptr; }
+    void onMessageRecv(const ContactInfo&, mesh::Packet*, uint32_t, const char*) override {}
+    void onCommandDataRecv(const ContactInfo&, mesh::Packet*, uint32_t, const char*) override {}
+    void onSignedMessageRecv(const ContactInfo&, mesh::Packet*, uint32_t, const uint8_t*, const char*) override {}
+    uint8_t onContactRequest(const ContactInfo&, uint32_t, const uint8_t*, uint8_t, uint8_t*) override { return 0; }
+    void onContactResponse(const ContactInfo&, const uint8_t*, uint8_t) override {}
+    void onSendTimeout() override {}
+    uint32_t calcFloodTimeoutMillisFor(uint32_t air) const override { return 500 + 16 * air; }
+    uint32_t calcDirectTimeoutMillisFor(uint32_t air, uint8_t) const override { return 500 + 16 * air; }
+    // Listener only -- do not re-flood other nodes' traffic.
+    bool allowPacketForward(const mesh::Packet*) override { return false; }
+
+    const char* channelName(const mesh::GroupChannel& ch) {
+        int idx = findChannelIdx(ch);
+        if (idx < 0) return "unknown";
+        ChannelDetails cd;
+        if (!getChannel(idx, cd)) return "unknown";
+        return cd.name[0] ? cd.name : "unnamed";
+    }
+
+    void onChannelMessageRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt,
+                              uint32_t, const char* text) override {
+        _rx++;
+        int   rssi = (int)lroundf(radio_driver.getLastRSSI());
+        float snr  = radio_driver.getLastSNR();
+        const char* chan = channelName(channel);
+
+        char buf[200];
+        strlcpy(buf, text, sizeof(buf));
+        const char *sender, *payload;
+        split_sender(buf, &sender, &payload);
+
+        if (s_on_rx) s_on_rx(chan, sender, payload, rssi, snr);
+    }
+
+public:
+    DongleMesh()
+        : BaseChatMesh(radio_driver, *new ArduinoMillis(), fast_rng, rtc_clock,
+                       *new StaticPoolPacketManager(16), tables) {}
+
+    void begin() {
+        BaseChatMesh::begin();
+
+        IdentityStore store(LittleFS, "/identity");
+        if (!store.load("_main", self_id)) {
+            self_id = mesh::LocalIdentity(getRNG());
+            store.save("_main", self_id);
+        }
+
+        _public = addChannel("Public", PUBLIC_CHANNEL_PSK_B64);
+        _user   = addChannel(s_channel, s_psk);     // -> index USER_IDX
+        if (_user) getChannel(USER_IDX, _user_view);
+    }
+
+    // Overwrite the user channel's key (and name) at runtime. Recomputes the
+    // channel hash from the decoded secret via setChannel().
+    bool reprogram(const char* name, const char* psk_b64) {
+        ChannelDetails cd;
+        memset(&cd, 0, sizeof(cd));
+        unsigned char key[32];
+        size_t len = 0;
+        if (mbedtls_base64_decode(key, sizeof(key), &len,
+                                  (const unsigned char*)psk_b64, strlen(psk_b64)) != 0)
+            return false;
+        if (len != 16 && len != 32) return false;   // PSK must be a 16- or 32-byte key
+        memcpy(cd.channel.secret, key, len);
+        strlcpy(cd.name, name, sizeof(cd.name));
+        if (!setChannel(USER_IDX, cd)) return false;
+        getChannel(USER_IDX, _user_view);
+        _user = &_user_view;
+        strlcpy(s_channel, name, sizeof(s_channel));
+        strlcpy(s_psk, psk_b64, sizeof(s_psk));
+        return true;
+    }
+
+    bool send(const char* text) {
+        if (!_user) return false;
+        bool ok = sendGroupMessage(getRTCClock()->getCurrentTime(),
+                                   _user_view.channel, NODE_NAME, text, strlen(text));
+        if (ok) _tx++;
+        return ok;
+    }
+
+    uint32_t rxCount() const { return _rx; }
+    uint32_t txCount() const { return _tx; }
+};
+
+DongleMesh the_mesh;
+
+void persist_cfg() {
+    Preferences p;
+    if (p.begin("mcfg", false)) {
+        p.putString("name", s_channel);
+        p.putString("psk", s_psk);
+        p.end();
+    }
+}
+
+void load_cfg() {
+    Preferences p;
+    if (p.begin("mcfg", true)) {
+        String n = p.getString("name", "");
+        String k = p.getString("psk", "");
+        if (n.length()) strlcpy(s_channel, n.c_str(), sizeof(s_channel));
+        if (k.length()) strlcpy(s_psk, k.c_str(), sizeof(s_psk));
+        p.end();
+    }
+}
+
+}  // namespace
+
+namespace mc {
+
+bool enabled() { return true; }
+
+void begin(RxHandler on_rx) {
+    s_on_rx = on_rx;
+    s_queue = xQueueCreate(8, sizeof(McAction));
+
+    load_cfg();                         // NVS overrides of channel/psk, if any
+
+    board.begin();
+    fallback_clock.begin();
+    if (!lora.std_init(&lora_spi)) {
+        Serial.println("[mesh] radio init FAILED -- mesh disabled");
+        return;
+    }
+    fast_rng.begin(lora.random(0x7FFFFFFF));
+    the_mesh.begin();
+    lora.startReceive();
+    s_up = true;
+    Serial.printf("[mesh] up: freq=%.3f bw=%.1f sf=%d cr=%d  channel='%s'\n",
+                  (float)LORA_FREQ, (float)LORA_BW, (int)LORA_SF, (int)LORA_CR, s_channel);
+}
+
+void loop() {
+    if (s_queue) {
+        McAction a;
+        while (xQueueReceive(s_queue, &a, 0) == pdTRUE) {
+            if (a.kind == 0) {
+                the_mesh.send(a.text);
+            } else {
+                if (the_mesh.reprogram(a.name, a.text)) persist_cfg();
+                s_cfg_dirty = true;
+            }
+        }
+    }
+    if (s_up) the_mesh.loop();
+}
+
+void requestSend(const char* text) {
+    if (!s_queue || !text) return;
+    McAction a; a.kind = 0; a.name[0] = 0;
+    strlcpy(a.text, text, sizeof(a.text));
+    xQueueSend(s_queue, &a, 0);
+}
+
+void requestPsk(const char* name, const char* psk_b64) {
+    if (!s_queue || !psk_b64) return;
+    McAction a; a.kind = 1;
+    strlcpy(a.name, (name && *name) ? name : s_channel, sizeof(a.name));
+    strlcpy(a.text, psk_b64, sizeof(a.text));
+    xQueueSend(s_queue, &a, 0);
+}
+
+bool up() { return s_up; }
+bool consumeCfgChanged() { bool d = s_cfg_dirty; s_cfg_dirty = false; return d; }
+const char* nodeName() { return NODE_NAME; }
+const char* channelName() { return s_channel; }
+const char* pskB64() { return s_psk; }
+const char* radioConfig() {
+    static char buf[80];
+    snprintf(buf, sizeof(buf), "freq=%.3f bw=%.1f sf=%d cr=%d tx=%d",
+             (float)LORA_FREQ, (float)LORA_BW, (int)LORA_SF, (int)LORA_CR, (int)LORA_TX_POWER);
+    return buf;
+}
+uint32_t rxCount() { return the_mesh.rxCount(); }
+uint32_t txCount() { return the_mesh.txCount(); }
+
+}  // namespace mc
+
+#else  // ---- USE_MESHCORE not set: cheap no-op build ----------------------
+
+namespace mc {
+bool enabled() { return false; }
+void begin(RxHandler) {}
+void loop() {}
+void requestSend(const char*) {}
+void requestPsk(const char*, const char*) {}
+bool up() { return false; }
+bool consumeCfgChanged() { return false; }
+const char* nodeName() { return "me"; }
+const char* channelName() { return ""; }
+const char* pskB64() { return ""; }
+const char* radioConfig() { return ""; }
+uint32_t rxCount() { return 0; }
+uint32_t txCount() { return 0; }
+}  // namespace mc
+
+#endif

src/meshcore_link.h

@@ -0,0 +1,43 @@
+/**
+ * meshcore_link -- thin facade over a MeshCore BaseChatMesh node.
+ *
+ * Lets the debug dongle send/receive text on a single PSK-protected group
+ * channel (plus the well-known "Public" channel), and reprogram that channel's
+ * PSK at runtime. All MeshCore + RadioLib headers stay inside meshcore_link.cpp
+ * so the rest of the firmware compiles identically with or without the radio.
+ *
+ * Enabled by the USE_MESHCORE build flag (see env:t3s3_mesh in platformio.ini).
+ * When the flag is absent every function below is a cheap no-op, so callers
+ * need no #if guards.
+ *
+ * Threading: requestSend()/requestPsk() are safe to call from any task (e.g.
+ * the async web-server callback). They enqueue work that is applied inside
+ * loop(), which must be called from the same task that owns the radio.
+ */
+#pragma once
+#include <stdint.h>
+#include <stddef.h>
+
+namespace mc {
+
+// Fired from loop() (radio task context) for each received channel message.
+typedef void (*RxHandler)(const char* channel, const char* sender,
+                          const char* text, int rssi, float snr);
+
+bool enabled();                                  // compile-time: USE_MESHCORE set?
+void begin(RxHandler on_rx);                     // bring up radio + mesh
+void loop();                                     // pump radio, drain action queue
+
+void requestSend(const char* text);              // queue a TX on the user channel
+void requestPsk(const char* name, const char* psk_b64);  // queue a channel reprogram
+
+bool up();                                       // radio initialised OK
+bool consumeCfgChanged();                         // true once after a reprogram
+const char* nodeName();                          // our sender name
+const char* channelName();                       // current user-channel name
+const char* pskB64();                            // current user-channel PSK (base64)
+const char* radioConfig();                       // "freq=.. bw=.. sf=.. cr=.. tx=.." ("" if disabled)
+uint32_t rxCount();
+uint32_t txCount();
+
+}  // namespace mc