Commander1024
c257158ada
Align component groups, repair affected routing, and add preservation audits. Assign the confirmed U2 footprint and update pull-ups to 2 kΩ across design files. Document user acceptance, switch to an A3 worksheet, and refresh PCB exports.
ESP32 Serial Swiss Army Knife
ESP32-S3 firmware for a secure, multi-transport RS-232 adapter. It operates one MAX3243-backed UART1 serial port and safely shares it between native USB CDC-ACM, an HTTPS/WebSocket browser terminal, and SSH: one connected client can write while others observe. The firmware also provides persistent serial and Wi-Fi configuration, a UART0 recovery console, and hardware diagnostics; it is not a general-purpose router, captive portal, or unauthenticated TCP serial server.
Supported hardware
- ESP32-S3-DevKitC-1-compatible development board
- ESP32-S3-WROOM-1-N16R8 module
- 16 MB flash
- 8 MB octal PSRAM
- Adafruit MAX3243 full-pinout RS-232 breakout; the male connector version is preferred (see Hardware wiring for supported connector variants)
- Optional 128×64 I²C OLED and three buttons, as described in the wiring guide
Documentation
Start with Getting started for installation, first-time configuration, and USB or network access.
- Hardware wiring: GPIO assignments, power safety, cables, USB connectors, OLED, and buttons.
- Electrical tests: safe hardware bring-up, loopback, flow control, and shared-serial checks.
- Command reference: administration, serial, USB, Wi-Fi, discovery, SSH, and diagnostics.
- Web administration: browser Serial, Admin, Settings, writer control, and reconnecting after changes.
- User administration: accounts, passwords, SSH client keys, and local recovery.
- Firmware update: application upload through the browser, update precautions, and wired recovery.
- Security operations: trusted-network use, identity verification, credentials, shutdown, and recovery.
Build
Install PlatformIO Core and run from the project root:
pio run
The getting-started guide covers prerequisites and first installation. The configured target is esp32-s3-devkitc-1-n16r8.
Upload and monitor
Connect the board's USB-to-UART port for firmware upload and the UART0 recovery console:
pio run --target upload
pio device monitor -b 115200
If necessary, add --upload-port with your actual bridge device path. The bridge normally appears as /dev/ttyUSB*; it is separate from native USB CDC (/dev/ttyACM*), which carries UART1 data. At serial-tool>, press Enter and run help.
Do not erase for routine updates. Erasing destroys all persisted configuration and credentials. Migration from the former default/factory layout to the custom OTA layout is a separate destructive step; see partition migration. Subsequent application-only updates can use the web updater.
Before using network access
Create the first administrator on trusted UART0 with user add <username> admin; there is no default shared login. Use a separate user account for SSH serial access: SSH admin opens device administration instead. Verify HTTPS and SSH fingerprints locally before trusting a new or changed identity.
Serial, Wi-Fi, mDNS hostname, and display edits need their explicit Save commands to survive reboot. Account and device-identity changes persist immediately. USB host baud/framing choices do not change physical UART1 settings.
Use a trusted LAN or the password-protected device AP, not Internet exposure. HTTPS uses a device-specific self-signed certificate and password login; SSH accepts passwords and supported public keys. Browser logins expire after one hour, even during active use. Disconnect is not sign-out: use Sign out when finished.
The firmware is not resistant to physical flash or RAM extraction. Passwords are stored as salted PBKDF2-HMAC-SHA256 verifiers, but Wi-Fi secrets and private device keys remain recoverable from unencrypted NVS; offline password guessing and old flash copies also remain possible. Keep local ports physically controlled. Read Security operations before deployment.
Development documentation
Developer index · Roadmap and acceptance history · Current development state
Implementation contracts, regression procedures, PCB research, and the flash layout live under docs/devel/. Agent working memory lives under docs/agent/. Historical acceptance records are not claims that every fault or hardware test has passed; the carrier PCB remains a draft, not fabrication-ready.
License
This project is licensed under the GNU General Public License version 3 only (GPL-3.0-only). Third-party components remain subject to their respective licenses. The integration baseline uses Espressif registry components espressif/mdns 1.12.0, wolfssl/wolfssl 5.8.2~1, and wolfssl/wolfssh 1.4.20; review upstream security releases before production use.