70 lines
3.9 KiB
Markdown
70 lines
3.9 KiB
Markdown
# 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.
|