Ssh bridge for raspberrypi

ssh-serial-bridge - SSH-to-Serial Bridge for Raspberry Pi, USB CDC and UART

Firmware for the ESP32-S3 that bridges an SSH connection (over Wi-Fi) to UART and USB CDC serial ports. Written in Rust (esp-idf-hal / esp-idf-svc) with a C component (wolfSSH) for the SSH server.

Features

Release History

v0.1.2

• Fixed the OTA update completion message so it is displayed to the SSH client.
• Fixed the Web UI terminal freezing while a serial target is booting.
• Improved setup script compatibility across Linux distributions and made Xtensa toolchain setup more robust.
• Split large USB CDC writes into multiple bulk transfers.
• Fixed device reboot failures.
• Fixed the custom partition table path used by the build.

Architecture

SSH client ──[TCP:22]──► ssh_bridge.c (wolfSSH)
                               │
        per-session ring buffers (PSRAM)
                               │
Rust usb_host.rs ◄─────────────┘
 ├── COM1 (UART1)
 ├── COM2 (UART2)
 └── USB CDC (USB Host: PL2303 / FTDI / etc.)

Browser ──[HTTP/WS]──► httpserver.rs
 ├── /terminal  (xterm.js + WebSocket /ws/serial)
 ├── /          (configuration page)
 └── /gpio      (GPIO/PWM control page)

Directory Layout

ssh-serial-bridge/
├── src/
│   ├── main.rs           # Entry point, peripheral initialisation
│   ├── usb_host.rs       # USB Host (PL2303 etc.) + UART + SSH bridge control
│   ├── httpserver.rs     # HTTP/WebSocket server, NVS config management
│   ├── wifi.rs           # Wi-Fi STA connection (DHCP / static IP)
│   ├── syslogger.rs      # UDP Syslog logger (RFC 5424)
│   ├── serial_display.rs # ST7789V SPI display rendering
│   ├── gpio_ctrl.rs      # Shared GPIO / PWM state
│   ├── btn_ctrl.rs       # GPIO0 button (short press: page cycle; long press: factory reset)
│   └── boot_log.rs       # NVS boot counter and rolling reset-reason log (last 10 entries)
├── components/
│   ├── ssh_bridge/       # SSH server C component (wolfSSH wrapper)
│   ├── wolfssh/          # wolfSSH (github.com/wolfSSL/wolfssh, commit 157cb01f)
│   └── wolfssl/          # wolfSSL/wolfCrypt (github.com/wolfSSL/wolfssl, commit b7e7e755)
├── static/               # Embedded static files (xterm.js / css / fit addon)
├── cfg.toml              # Build-time default configuration (gitignored — contains credentials)
├── cfg.toml.<board>      # Board-specific templates (e.g. ssh-bridge-board / xiao-esp32s3)
├── sdkconfig.defaults    # ESP-IDF build settings
├── partitions.csv        # Flash partition table
├── build-flash-images.sh # Build merged flash + app-only OTA images per board
├── setup_components.sh   # Initial setup script for components/
└── setup_env.sh          # One-shot environment setup (Rust, espup, udev)

Pin Assignment

UART Serial

GPIO / PWM Output

SPI Display (ST7789V)

Button

• 6–10 seconds (button held): Display shows "FACTORY RESET" with countdown "Resetting to defaults in X seconds..."
• 10 seconds (trigger): Display shows "FACTORY RESET" / "Erasing NVS... Please wait..." and device reboots

Configuration

Board-specific cfg.toml (build-time defaults)

Before building, choose a board config and copy it to cfg.toml.

• ssh-bridge-board: Board with a 2.0-inch TFT display for serial data output
• mini-ssh-bridge-board: Small-display board using SSD1306
• xiao-esp32s3: XIAO ESP32S3 board

# 2.0-inch TFT display board
cp cfg.toml.ssh-bridge-board cfg.toml

# SSD1306 mini display board
cp cfg.toml.mini-ssh-bridge-board cfg.toml

# XIAO ESP32S3 board
cp cfg.toml.xiao-esp32s3 cfg.toml

After copying, edit cfg.toml for your environment (Wi-Fi credentials, IP, etc.) if needed.

[ssh-serial-bridge]
wifi_ssid      = "your-ssid"
wifi_psk       = "your-password"
ip_mode        = "dhcp"           # "dhcp" or "static"
ip_address     = "192.168.2.200"
subnet_mask    = "255.255.255.0"
gateway        = "192.168.2.1"
dns            = "1.1.1.1"

syslog_server    = "192.168.2.140:514"
syslog_enable    = "false"
syslog_host_name = "esp32s3"
syslog_app_name  = "ssh-bridge"

ssh_user     = "admin"
ssh_password = "sshpass"

com1_tx_pin = "17"    # XIAO-ESP32S3: 43
com1_rx_pin = "18"    # XIAO-ESP32S3: 44
com1_baud   = "115200"
com2_tx_pin = "41"
com2_rx_pin = "42"
com2_baud   = "115200"

Values in cfg.toml are compiled into the firmware as defaults.
After boot they can be overridden via the Web UI or direct NVS writes; NVS values take priority.

Wi-Fi Setup with WPS

WPS (Wi-Fi Protected Setup) allows you to connect to a Wi-Fi network without manually entering the SSID and password. This device supports WPS Push Button Configuration (PBC) mode.

Method 1: Using cfg.toml and Factory Reset (Recommended for initial setup)

If you don't have Wi-Fi credentials yet or want to reconfigure via WPS without Web UI access:

1. Edit cfg.toml before building (or rebuild the firmware):

   wifi_ssid      = ""           # Set to empty string
   wps_enable     = "true"       # Enable WPS mode on boot

2. Flash the firmware to the device

3. On boot, the device will automatically enter WPS mode and wait for you to press the WPS button on your Wi-Fi router (timeout: 2 minutes)

4. Upon successful WPS connection, the credentials are saved to NVS and the device reboots

Alternative: Trigger WPS via Factory Reset

If the device is already running with Wi-Fi configured but you want to switch to WPS:

1. Edit cfg.toml to set wps_enable = "true" and wifi_ssid = ""
2. Rebuild and flash the firmware
3. Perform a Factory Reset: Press and hold the BOOT button (GPIO 0) for ≥10 seconds
4. The device will erase NVS, restore cfg.toml defaults, and reboot into WPS mode
5. Press the WPS button on your Wi-Fi router within 2 minutes

Note: Web UI is not accessible until Wi-Fi is connected, so this method is essential for initial setup or when you lose Wi-Fi access.

Method 2: Using the Web UI (when already connected to Wi-Fi)

1. Navigate to the configuration page at http://<device_ip>/
2. Find the WPS section
3. Click the "Start WPS" button
4. Press the WPS button on your Wi-Fi router within 2 minutes
5. The device will automatically receive and save the Wi-Fi credentials and reboot

WPS Status Indicators

When WPS is active:

• Display (if enabled): Shows "WPS MODE" with countdown timer (120 seconds)
  • "Press WPS button on your router within 120 seconds"
  • Countdown updates every 10 seconds
  • On success: "WPS SUCCESS" → "Connecting to {SSID}" → "CONNECTED"
• Syslog (if enabled): Logs WPS start, success, or failure events
• Web UI: Shows WPS status during the connection process

WPS Fallback

If WPS fails or times out, the device will revert to the previously configured Wi-Fi credentials (from cfg.toml or NVS).

Notes

• WPS PBC mode is the only supported WPS method (PIN mode is not supported)
• After successful WPS configuration, the new credentials are saved to NVS and persist across reboots
• You can still manually configure Wi-Fi credentials via cfg.toml or the Web UI if WPS is not available on your router

Environment Setup

Run setup_env.sh once on a fresh Ubuntu / Debian machine (or WSL2) before building. The script performs all steps below automatically.

bash setup_env.sh

After the script finishes, open a new terminal (or reload your shell config) so the environment variables take effect:

source "$HOME/.cargo/env"
source ~/export-esp.sh

What the script does

If you prefer to run the steps manually, expand each step below.

# 1. System packages
sudo apt update && sudo apt -y install \
    git python3 python3-pip gcc build-essential curl \
    pkg-config libudev-dev libtinfo5 clang libclang-dev \
    llvm-dev udev libssl-dev python3.10-venv

# 2. Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Select option 1 (default install), then:
source "$HOME/.cargo/env"

# 3. Cargo tools
cargo install ldproxy
cargo install espup
cargo install cargo-espflash

# 4. ESP32-S3 toolchain
espup install
espup update

# 5. Activate ESP environment (add to ~/.bashrc / ~/.zshrc for persistence)
. ~/export-esp.sh

# 6. udev rules

Build and Flash

Prerequisites

• Rust toolchain: esp channel (selected automatically via rust-toolchain.toml)
• espup — ESP32-S3 Xtensa toolchain
• espflash

Initial component setup

Run once after cloning, or after a clean wipe of components/:

cd esp32-s3/ssh-serial-bridge
bash setup_components.sh

This clones wolfssh and wolfssl at the verified commits and places the ESP-IDF-specific CMakeLists.txt and include/user_settings.h on top.

Build

cargo build --release

Flash and monitor

espflash flash --release --monitor

Creating a complete flash binary image

To create a single binary file that includes all partitions (bootloader, partition table, data partitions, and the currently built app image) for distribution or web-based flashing:

cargo espflash save-image --release --merge --chip esp32s3 complete_flash.bin

This creates a complete 8 MB flash image starting from offset 0x0.

Creating board images for both USB flashing and OTA

The helper script builds all board configs and produces both image types:

• flash_images/flash_<board>.bin (merged full-flash image, write at 0x0)
• flash_images/app_<board>.bin (app-only image for ssh ... update OTA)

bash build-flash-images.sh

Important: When flashing this image, always write it to offset 0x0, not 0x9000. Writing to 0x9000 will result in a boot failure with "invalid header: 0xffffffff" error.

Flash the complete binary

# Using esptool.py
esptool.py --chip esp32s3 --port /dev/ttyUSB0 write_flash 0x0 complete_flash.bin

# Using espflash
espflash write-bin 0x0 complete_flash.bin

Web-based flashing (no command line required)

You can also flash the binary via a web browser using the ESP Web Flasher:

1. Open https://thelastoutpostworkshop.github.io/ESPConnect/ in Chrome, Edge, or Opera (Web Serial API required)
2. Click "Connect" and select your ESP32-S3 device from the serial port list
3. Click "Choose File" and select complete_flash.bin
4. Set the flash address to 0x0 (very important!)
5. Click "Program" to start flashing
6. Wait for the process to complete and click "Reset Device"

This method is ideal for:

• Users without command-line tools installed
• Quick firmware updates without installing the Rust/ESP toolchain
• Distribution of pre-built binaries

Flash layout

Flash: 8 MB, DIO mode, 40 MHz.

Web UI Endpoints

Web UI Snapshots

SSH Connection

Authentication

Security note: Change the default password before deploying the device on a shared network.

Commands

The SSH server dispatches on the command passed after the host.
If no command is given, a usage summary is printed and the connection closes.

1. Serial console bridge

Connects the SSH session as a transparent terminal to a serial port.

ssh -tt <user>@<device_ip> console (usb0|usb1|usb2|usb3|com1|com2)

• The -tt flag forces pseudo-TTY allocation, which is required for correct terminal behaviour.
• A welcome banner is printed on connect:

  Connected to ESP32-S3 SSH-Serial-Bridge v0.1.1 [com1].
  Disconnect: Enter then ~.

• The same serial target can be shared by multiple SSH clients. When another session is already connected to that target, the banner also shows:

  Note: N other session(s) are also connected to this device — input/output is shared.

• Shared-session behaviour on the same target:
  • RX from device is broadcast to all connected SSH sessions on that target.
  • TX from each SSH session is sent to the same physical serial line, so input from multiple users can interleave.
• Capacity limits:
  • Max 4 console sessions per target (com1, com2, usb0-usb3).
  • Max 6 total SSH sessions across the system.
• If a target already has 4 console sessions, new attempts are rejected with:

  Error: too many sessions already connected to this device (max 4).

• Serial data received before the first keystroke from the SSH client is discarded to prevent stale output flooding the terminal on login.
• Disconnect with the standard OpenSSH escape sequence: press Enter, then type ~.

Examples:

# Connect to the first USB CDC device
ssh -tt admin@192.168.2.200 console usb0

# Connect to the second USB CDC device
ssh -tt admin@192.168.2.200 console usb1

# Connect to COM1 (UART1)
ssh -tt admin@192.168.2.200 console com1

# Connect to COM2 (UART2)
ssh -tt admin@192.168.2.200 console com2

2. GPIO digital output control

Controls GPIO4–GPIO9 output pins (mapped as power outlets 1–6).

ssh <user>@<device_ip> power <1-6> (on|off)

Examples:

ssh admin@192.168.2.200 power 1 on    # GPIO4 → HIGH
ssh admin@192.168.2.200 power 3 off   # GPIO6 → LOW

3. DC Power output control (GPIO12)

Controls the dedicated DC Power output on GPIO12.

ssh <user>@<device_ip> dcpower (on|off)

Examples:

ssh admin@192.168.2.200 dcpower on
ssh admin@192.168.2.200 dcpower off

4. DC Power power-cycle (GPIO12)

Turns the DC Power output off, waits briefly, then turns it back on — in a single SSH call.

ssh <user>@<device_ip> powercycle

Example:

ssh admin@192.168.2.200 powercycle

5. PWM duty cycle control

Sets the PWM duty cycle on GPIO10 or GPIO11 (LEDC, 1 kHz, 14-bit).

ssh <user>@<device_ip> pwm <1|2> <0-100>

Examples:

ssh admin@192.168.2.200 pwm 1 50    # GPIO10 → 50 %
ssh admin@192.168.2.200 pwm 2 0     # GPIO11 → off
ssh admin@192.168.2.200 pwm 1 100   # GPIO10 → full on

6. Reboot the device

Reboots the ESP32-S3 (equivalent to a power-on reset).

ssh <user>@<device_ip> reboot

Example:

ssh admin@192.168.2.200 reboot

7. OTA firmware update

Streams a new app image over SSH directly into the inactive OTA partition, then reboots into it. No filesystem, SCP, or SFTP support is required — the exec channel's stdin is piped straight into flash.

ssh <user>@<device_ip> update < firmware.bin

Example:

cat flash_images/app_ssh-bridge-board.bin | ssh admin@192.168.2.200 update

Important:

• Use the app-only image (flash_images/app_<board>.bin, produced by build-flash-images.sh), not the merged full-flash image (flash_images/flash_<board>.bin). The merged image includes the bootloader and partition table baked in at offset 0 and will corrupt the OTA partition if written this way.
• The device has two OTA app slots (ota_0/ota_1). The update is written to whichever slot isn't currently running, so the previous firmware is left untouched until the new image is fully received and verified.
• Rollback safety: the new image boots in a "pending verify" state. Once the SSH bridge starts successfully it is marked valid automatically. If the new firmware crashes or fails to boot before that point, the bootloader automatically reverts to the previous working firmware on the next reset.
• This requires the partition table to include ota_0/ota_1/otadata (see partitions.csv). Boards flashed with an older single-partition image must be reflashed once via USB/serial (cargo espflash flash or the merged flash_<board>.bin image) before OTA updates over SSH will work.

Usage summary (printed on unknown command)

ESP32-S3 SSH-Serial-Bridge
Usage:
  ssh -tt admin@host console (usb0|usb1|usb2|usb3|com1|com2)  -- Serial console bridge
  ssh    admin@host power   (1-6) (on|off)    -- GPIO4-9 output control
  ssh    admin@host dcpower (on|off)          -- DC Power output (GPIO12)
  ssh    admin@host powercycle                -- DC Power off->on (GPIO12)
  ssh    admin@host pwm   (1|2) (0-100)       -- PWM GPIO10-11 duty %
  ssh    admin@host reboot                    -- Reboot the ESP32-S3
  ssh    admin@host update < firmware.bin      -- OTA firmware update

Supported USB CDC Devices

The USB Host driver auto-detects the connected adapter by VID/PID and applies the appropriate initialisation sequence. The baud rate is set by cdc_baud in cfg.toml (default: 115200).

Note: cdc_enable must be set to "true" in cfg.toml (or via Web UI) to activate the USB Host driver. When disabled, usb0–usb3 are unavailable as SSH console targets.

Vendor-class adapters

Linux USB Gadget (Raspberry Pi)

This firmware supports Raspberry Pi USB Gadget mode for direct serial access over USB:

Raspberry Pi Configuration

To use your Raspberry Pi as a USB serial gadget with this ESP32-S3 bridge:

1. Enable USB gadget mode on your Raspberry Pi:

   # Add to /boot/config.txt (or /boot/firmware/config.txt on Ubuntu)
   dtoverlay=dwc2

2. Load the g_cdc module (recommended over g_serial):

   Method A: Using cmdline.txt (Recommended)

   # Edit /boot/cmdline.txt (or /boot/firmware/cmdline.txt on Ubuntu)
   # Add modules-load=dwc2,g_cdc to the kernel command line
   # Example:
   console=serial0,115200 ... modules-load=dwc2,g_cdc ...

   Method B: Using /etc/modules

   # Add to /etc/modules
   dwc2
   g_cdc

3. Enable serial-getty service (required for the CDC device to respond):

   sudo systemctl enable serial-getty@ttyGS0
   sudo systemctl start serial-getty@ttyGS0

4. Reboot your Raspberry Pi:

   sudo reboot

5. Connect the Pi to the ESP32-S3 USB port using a USB cable

Important: Use g_cdc instead of g_serial. The g_serial module has compatibility issues with the ESP-IDF USB Host stack and may not work reliably. g_cdc provides better standards compliance and works seamlessly with this firmware.

After configuration, the Pi will appear as a CDC-ACM device and you can access its serial console via SSH to the ESP32-S3 bridge (target: usb0).

Port mapping

Multi-port FTDI adapters expose multiple ports, mapped to SSH console targets in channel order:

Dependencies

Note on wolfSSH / wolfSSL licensing:
Both wolfSSH and wolfSSL are dual-licensed under GPLv3 (open source) or a commercial license (for use in proprietary products).