# 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.