Serial Terminal

Serial Terminal Skill

Safely interact with serial ports without directly reading /dev/tty* devices (which would crash Claude Code).

CRITICAL SAFETY RULES

1. NEVER read from /dev/tty* devices directly using cat, head, tail, or any other command
2. NEVER use the Read tool on /dev/tty* files
3. ALWAYS use the Python wrapper script for ALL serial operations

Device Identification

IMPORTANT: Always use /dev/serial/by-id/ paths when available!

When multiple devices are connected, raw paths like /dev/ttyACM0 can change between reboots or when devices are reconnected. The /dev/serial/by-id/ directory provides stable, descriptive paths that include the device serial number.

Example /dev/serial/by-id/ entries:

/dev/serial/by-id/usb-SEGGER_J-Link_001057754341-if00 -> ../../ttyACM2
/dev/serial/by-id/usb-SEGGER_J-Link_001057754341-if02 -> ../../ttyACM3

When the user asks to connect to a device:

1. First run list to show available devices with their serial numbers
2. Ask the user which device/serial number they want to use if multiple are present
3. Use the /dev/serial/by-id/ path for the connection

Available Commands

The script is located at ~/.claude/skills/serial-terminal/scripts/serial_terminal.py

List Available Ports

python3 ~/.claude/skills/serial-terminal/scripts/serial_terminal.py list

This will show devices from /dev/serial/by-id/ with their serial numbers, making it easy to identify which device is which.

Send Data

python3 ~/.claude/skills/serial-terminal/scripts/serial_terminal.py send <port> "<message>" [options]

Options:

• --baud <rate>: Baud rate (default: 115200)
• --newline: Append newline to message (useful for command-line interfaces)

Example:

python3 ~/.claude/skills/serial-terminal/scripts/serial_terminal.py send "/dev/serial/by-id/usb-SEGGER_J-Link_001057754341-if02" "AT" --newline --baud 9600

Receive Data

python3 ~/.claude/skills/serial-terminal/scripts/serial_terminal.py receive <port> [options]

Options:

• --baud <rate>: Baud rate (default: 115200)
• --timeout <secs>: How long to wait for data (default: 2.0)
• --bytes <n>: Max bytes to read (default: 4096)
• --hex: Display data as hex dump

Example:

python3 ~/.claude/skills/serial-terminal/scripts/serial_terminal.py receive "/dev/serial/by-id/usb-SEGGER_J-Link_001057754341-if02" --timeout 5 --baud 115200

Send and Receive (most common)

Send a command and wait for response in one operation:

python3 ~/.claude/skills/serial-terminal/scripts/serial_terminal.py sendrecv <port> "<message>" [options]

Example:

python3 ~/.claude/skills/serial-terminal/scripts/serial_terminal.py sendrecv "/dev/serial/by-id/usb-SEGGER_J-Link_001057754341-if02" "help" --newline --timeout 3

Troubleshooting

Permission denied

The user may need to add themselves to the dialout group:

sudo usermod -a -G dialout $USER
# Then logout and login again

Or use sudo for a quick test:

sudo python3 ~/.claude/skills/serial-terminal/scripts/serial_terminal.py list

No response received

• Check baud rate matches the device
• Increase timeout with --timeout
• Verify the device is connected with list
• Try adding --newline if the device expects CR/LF

Device busy

Another program may have the port open. Close any serial monitors or other tools.

Script Details

The Python script uses only standard library modules:

• os - Low-level file operations
• termios - Serial port configuration
• select - Non-blocking I/O (safe timeout handling)
• fcntl - File descriptor control

It safely handles serial I/O by:

1. Using select() to wait for data with timeout (never blocks indefinitely)
2. Setting non-blocking mode to prevent hangs
3. Properly restoring terminal settings on exit