> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CodeGroup>
  ```bash Linux theme={null}
  wezterm serial /dev/ttyUSB0

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

  ```bash macOS theme={null}
  wezterm serial /dev/cu.usbserial

  # List available serial devices
  ls /dev/cu.*
  ```

  ```bash Windows theme={null}
  wezterm serial COM1

  # Or other COM ports
  wezterm serial COM3
  wezterm serial COM4
  ```
</CodeGroup>

## Specifying Baud Rate

Set the connection speed with the `--baud` flag:

```bash Custom Baud Rate theme={null}
# 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:

```bash Arduino Serial Monitor theme={null}
# 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:**

```cpp Arduino Sketch theme={null}
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

```bash ESP32 Connection theme={null}
# 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:

```bash Server Console theme={null}
# Connect to server serial console
wezterm serial --baud 115200 /dev/ttyS0

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

### Embedded Linux

```bash Embedded Linux Console theme={null}
# 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:

```bash Network Device Console theme={null}
# 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:

<Warning>
  * 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
</Warning>

## Multiple Serial Connections

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

```bash Multiple Devices theme={null}
# 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

<CodeGroup>
  ```bash Linux theme={null}
  # 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/
  ```

  ```bash macOS   theme={null}
  # List serial devices
  ls -l /dev/cu.*
  ls -l /dev/tty.*

  # Look for USB serial devices
  ls -l /dev/cu.usb*
  ```

  ```bash Windows PowerShell theme={null}
  # List COM ports
  [System.IO.Ports.SerialPort]::getportnames()

  # Or use Device Manager
  # devmgmt.msc -> Ports (COM & LPT)
  ```
</CodeGroup>

## Permissions (Linux/macOS)

You may need permissions to access serial devices:

<Steps>
  <Step title="Check current permissions">
    ```bash theme={null}
    ls -l /dev/ttyUSB0
    # Usually owned by group 'dialout' or 'uucp'
    ```
  </Step>

  <Step title="Add user to serial group">
    ```bash theme={null}
    # On most Linux distros
    sudo usermod -a -G dialout $USER

    # On some systems (Arch, etc.)
    sudo usermod -a -G uucp $USER
    ```
  </Step>

  <Step title="Log out and back in">
    Changes take effect after logging out and back in, or run:

    ```bash theme={null}
    newgrp dialout
    ```
  </Step>

  <Step title="Verify access">
    ```bash theme={null}
    groups
    # Should show 'dialout' or 'uucp' in the list
    ```
  </Step>
</Steps>

## Troubleshooting

### Device Not Found

```bash Check Device Existence theme={null}
# 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

```bash Fix Permissions theme={null}
# 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:

```bash Troubleshooting Steps theme={null}
# 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:
   ```bash Shell Aliases theme={null}
   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:
   ```udev /etc/udev/rules.d/99-usb-serial.rules theme={null}
   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

<Steps>
  <Step title="Verify device specs">
    Always check device documentation for correct baud rate and settings.
  </Step>

  <Step title="Set up permissions once">
    Add your user to the appropriate group rather than using sudo repeatedly.
  </Step>

  <Step title="Use stable device names">
    On Linux, use `/dev/serial/by-id/*` for consistent device identification.
  </Step>

  <Step title="Close connections properly">
    Exit WezTerm cleanly to release the serial port for other applications.
  </Step>
</Steps>