ESP32SerialSSHProxy

This project aims to make a serial console connected to the ESP32 accessible using SSH.

This way the ESP32 will act like an USB-UART-Converter, but over the network.

Setup

1. Wire up your ESP32 to the serial console of the target:

   TARGET	ESP32 (UART2)
   RX	TX2 (GPIO 17)
   TX	RX2 (GPIO 16)
   GND	GND
   3.3V	3.3V (optional)

   Remember that the ESP32 is using 3.3V logic levels. Connecting it to 5V logic level serial consoles might damage your ESP32.
   You can also connect the 3.3V pins to power the ESP32 from the target.

2. Create the file src/credentials.hpp:

   #define WIFISSID "WIFI SSID"
   #define WIFIPASS "WIFI Password"
   #define SSHUSER "user"
   #define SSHPASS "user"

3. Generate RSA hostkeys for the SSH server:

   mkdir data
   ssh-keygen -t rsa -f data/hostkey_rsa

4. Upload the filesystem image to the ESP32

5. Compile and upload the project to the ESP32

6. Access the device using:

   ssh -t user@esp32sshserial

   and log in using the credentials.
   If esp32sshserial doesn't work, you can try appending your networks suffix, or just use the IP-Address of the ESP32, which you may find in the USB Serial Console of the ESP32 during boot, or in your routers webinterface.

7. Your SSH session is now directly connected with Serial2 of the ESP32.

8. Use Ctrl-G (Bell) to terminate the SSH connection.
   Context: Since Ctrl-C is directly forwarded to the serial console, and there is no equivalent for it on serial consoles, the connection effectively cannot terminate ever. Ctrl-G is captured by the ESP32 before relaying to Serial and will do nothing else than terminate the connection. You can then anytime reconnect and continue where you left of.
   Remember: Disconnecting from the SSH session will not log you out of the connected serial console.

Terminal configuration

If you have a working connection with a linux machine, you can do these additional steps to enhance the serial experience almost to a native SSH-like level.

Terminal Size

Import the resizeserial function:

resizeserial() {
  local old=$(stty -g)
  stty raw -echo min 0 time 5
  printf '\033[18t' > /dev/tty
  local rows
  local cols
  IFS=';t' read -r _ rows cols _ < /dev/tty
  stty "$old"
  stty cols "$cols" rows "$rows"
}

Then run resizeserial anytime to resize the terminal.

Source

Colors

Run

export TERM=xterm-256color

to enable colored output.

Automatic configuration in .bashrc

Both above mentioned mechanisms can be automated very easily.

Create a file named .serialrc:

#!/bin/bash

# if not accessing from serial console, stop futher execution
[ "$TERM" != "vt220" ] && return 0

resizeserial() {
  local old=$(stty -g)
  stty raw -echo min 0 time 5
  printf '\033[18t' > /dev/tty
  local rows
  local cols
  IFS=';t' read -r _ rows cols _ < /dev/tty
  stty "$old"
  stty cols "$cols" rows "$rows"
}

# force enable color
export TERM=xterm-256color

# run resizeserial everytime before command execution
#trap resizeserial DEBUG
PROMPT_COMMAND='_trace=yes'
trap '[[ "$_trace" == "yes" ]] && resizeserial; _trace=no' DEBUG

Then in .bashrc directly after the interactive terminal check insert

[ -f .serialrc ] && source .serialrc

It needs to be in the beginning, for the color settings to apply properly.

Credits

Huge thanks to LibSSH-ESP32 for making this possible.