Working on better version

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.