Serial Port Support

Connect to serial devices for embedded development, Arduino projects, and server console access

WezTerm can connect directly to serial ports, making it an ideal tool for embedded systems development, Arduino programming, and accessing server console ports.

Basic Usage

Connect to a serial port from the command line:

Linux

wezterm serial /dev/ttyUSB0

# Or other common Linux serial devices
wezterm serial /dev/ttyACM0
wezterm serial /dev/ttyS0

Specifying Baud Rate

Set the connection speed with the --baud flag:

Custom Baud Rate

# Common baud rates
wezterm serial --baud 9600 /dev/ttyUSB0
wezterm serial --baud 115200 /dev/ttyUSB0
wezterm serial --baud 38400 COM3

Common Baud Rates

Baud Rate	Typical Use Case
9600	Older devices, GPS modules
19200	Legacy equipment
38400	Some industrial devices
57600	Bluetooth modules
115200	Arduino, ESP32, modern devices
230400	High-speed microcontrollers
460800	Very high-speed serial
921600	Maximum speed for some devices

Use Cases

Arduino Development

Connect to Arduino boards for serial monitor functionality:

Arduino Serial Monitor

# Upload your sketch with Arduino IDE
# Then connect to serial port
wezterm serial --baud 115200 /dev/ttyACM0

# Now you can see Serial.print() output
# and send data to Serial.read()

Arduino sketch example:

Arduino Sketch

void setup() {
  Serial.begin(115200);
  Serial.println("Arduino Ready!");
}

void loop() {
  if (Serial.available() > 0) {
    char c = Serial.read();
    Serial.print("Received: ");
    Serial.println(c);
  }
  
  delay(1000);
  Serial.println("Heartbeat");
}

ESP32/ESP8266 Development

ESP32 Connection

# ESP32 typically uses 115200 baud
wezterm serial --baud 115200 /dev/ttyUSB0

# You'll see boot messages and serial output

Server Console Access

Connect to server console ports for out-of-band management:

Server Console

# Connect to server serial console
wezterm serial --baud 115200 /dev/ttyS0

# Common for:
# - Headless servers
# - BIOS/UEFI access
# - Emergency system recovery

Embedded Linux

Embedded Linux Console

# Connect to embedded Linux device
wezterm serial --baud 115200 /dev/ttyUSB0

# Access bootloader, kernel messages, and shell

Networking Equipment

Access Cisco, Juniper, and other network device consoles:

Network Device Console

# Cisco devices typically use 9600 baud
wezterm serial --baud 9600 /dev/ttyUSB0

# Some newer devices use 115200
wezterm serial --baud 115200 /dev/ttyUSB0

Limitations

When operating in serial mode:

• You cannot create new tabs in a serial connection window
• Serial mode is dedicated to the single serial port connection
• To use multiple serial ports, open separate WezTerm windows

Multiple Serial Connections

To work with multiple serial devices simultaneously, use separate terminal windows:

Multiple Devices

# Terminal 1: Arduino
wezterm serial --baud 115200 /dev/ttyACM0

# Terminal 2: ESP32
wezterm serial --baud 115200 /dev/ttyUSB0

# Terminal 3: GPS Module  
wezterm serial --baud 9600 /dev/ttyUSB1

Finding Serial Devices

Linux

# List USB serial devices
ls -l /dev/ttyUSB*
ls -l /dev/ttyACM*

# Or use dmesg to see newly connected devices
dmesg | grep tty

# More detailed information
ls -l /dev/serial/by-id/

Permissions (Linux/macOS)

You may need permissions to access serial devices:

1. Check current permissions

   ls -l /dev/ttyUSB0
   # Usually owned by group 'dialout' or 'uucp'
   
2. Add user to serial group

   # On most Linux distros
   sudo usermod -a -G dialout $USER
   
   # On some systems (Arch, etc.)
   sudo usermod -a -G uucp $USER
   
3. Log out and back in

   Changes take effect after logging out and back in, or run:

   newgrp dialout
   
4. Verify access

   groups
   # Should show 'dialout' or 'uucp' in the list
   

Troubleshooting

Device Not Found

Check Device Existence

# Verify device exists
ls -l /dev/ttyUSB0

# Check if device is in use
lsof /dev/ttyUSB0

# Disconnect and reconnect USB device
# Watch kernel messages
sudo dmesg -w

Permission Denied

Fix Permissions

# Temporary fix (until reboot)
sudo chmod 666 /dev/ttyUSB0

# Permanent fix: add user to group (see Permissions section)
sudo usermod -a -G dialout $USER

Wrong Baud Rate

If you see garbled characters:

1. Verify the device’s baud rate in documentation
2. Try common rates: 9600, 115200, 38400
3. Check device settings (Arduino sketch, firmware config)

No Output

If connected but seeing no data:

Troubleshooting Steps

# 1. Verify device is transmitting
#    - Check device power/activity LEDs
#    - Confirm device is running

# 2. Try sending data to device
#    - Type in WezTerm serial window
#    - See if device responds

# 3. Check physical connections
#    - Reseat USB cable
#    - Try different USB port
#    - Test with different cable

# 4. Verify with another tool
screen /dev/ttyUSB0 115200
# or
minicom -D /dev/ttyUSB0 -b 115200

Comparison to Other Serial Tools

Feature	WezTerm	screen	minicom	PuTTY
Cross-platform	✓	Linux/Mac	Linux/Mac	✓
GPU acceleration	✓	✗	✗	✗
Modern UI	✓	✗	✗	✓
Simple usage	✓	✓	✗	✓
Scrollback	✓	✓	✓	✓
Configuration	Lua	.screenrc	Complex	GUI

Tips and Tricks

1. Create shell aliases for frequently used devices:

   Shell Aliases

   alias arduino="wezterm serial --baud 115200 /dev/ttyACM0"
   alias esp32="wezterm serial --baud 115200 /dev/ttyUSB0"
   

2. Use udev rules (Linux) to create stable device names:

   /etc/udev/rules.d/99-usb-serial.rules

   SUBSYSTEM=="tty", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0043", SYMLINK+="arduino"
   

3. Monitor connection state with device LEDs or system logs

4. Save important output using WezTerm’s scrollback feature

5. Use search (Ctrl+Shift+F) to find specific messages in serial output

Best Practices

1. Verify device specs

   Always check device documentation for correct baud rate and settings.

2. Set up permissions once

   Add your user to the appropriate group rather than using sudo repeatedly.

3. Use stable device names

   On Linux, use /dev/serial/by-id/* for consistent device identification.

4. Close connections properly

   Exit WezTerm cleanly to release the serial port for other applications.