List all available serial ports on the system.

Returns device path, description, hardware ID, and USB metadata (vendor/product IDs, manufacturer, serial number) when available. Use this to discover which TTL adapters or serial devices are connected.

Kill the process holding a serial port so it can be opened.

Uses lsof to find the process holding the port, then sends SIGTERM (escalating to SIGKILL if needed). This is a destructive operation — it will terminate the process holding the port.

Args: port: Serial port device path (e.g. /dev/ttyUSB0, /dev/cu.usbserial-1420)

Open a serial connection to the specified port.

If port is omitted, automatically discovers available ports. When only one port is found it is used directly; when multiple are found, elicitation is used to let the user pick one.

IMPORTANT: Always call serial_close() when you are finished with the port. Leaving a port open prevents other processes from accessing the device. The session will be automatically closed after inactivity_timeout seconds of no activity.

Common configurations:

• Most devices: 115200 baud, 8N1 (the defaults)

• Older equipment: 9600 baud, 8N1

• Use serial_detect_baud() first if unsure of the baud rate.

Args: port: Serial port device path (e.g. /dev/ttyUSB0, COM3). Optional — omit to auto-discover. baud_rate: Baud rate for the connection data_bits: Number of data bits (5, 6, 7, or 8) stop_bits: Number of stop bits (1, 1.5, or 2) parity: Parity checking ("none", "even", "odd", "mark", "space") timeout: Read timeout in seconds inactivity_timeout: Seconds of inactivity before the session is auto-closed (default 900 = 15 min)

Close a serial connection and release the port.

Always call this when you are done interacting with a device. Leaving a port open blocks other tools and processes from accessing the device.

Args: session_id: Port name of the session to close. Optional if only one session is open.

Change serial port settings on an open connection without closing it.

Useful when a device changes baud rate mid-session (e.g. bootloader hands off to OS at a different speed) or during manual baud detection.

Args: session_id: Port name of the session. Optional if only one session is open. baud_rate: New baud rate (e.g. 9600, 115200). None to keep current. data_bits: New data bits (5, 6, 7, or 8). None to keep current. stop_bits: New stop bits (1, 1.5, or 2). None to keep current. parity: New parity ("none", "even", "odd", "mark", "space"). None to keep current.

Send a command and wait for the response. This is the primary tool for interacting with serial devices — it combines write + read into a single atomic operation.

If expect is provided, waits until that regex pattern appears in the response. Without expect, waits for the device to stop sending (300ms of silence after last received byte).

If respond or respond_hex is provided along with expect, the response is sent immediately when the pattern matches — before this tool returns. This enables sub-millisecond triggered responses for time-sensitive sequences. The respond string is sent as-is (no newline appended).

Examples: - Linux shell: serial_command(data="ls -la", expect="\$") - AT modem: serial_command(data="AT", expect="OK|ERROR") - Router CLI: serial_command(data="show version", expect="#") - Simple ping: serial_command(data="hello", timeout=2) - Reboot + catch bootloader: serial_command(data="reboot", expect="Hit any key", respond=" ")

Args: data: Text to send to the device expect: Regex pattern to wait for in the response (e.g. "\$", "OK", ">") timeout: Max seconds to wait for response (default 5) session_id: Port name of the session. Optional if only one session is open. encoding: Character encoding (default utf-8) append_newline: Whether to append \r\n to the data (default True) respond: Text to send immediately when expect pattern matches (sent as-is, no newline) respond_hex: Hex bytes to send when expect pattern matches (e.g. "7F", "AA 55")

Wait for a specific pattern to appear in the serial output. Blocks until the regex pattern matches in incoming data, or until timeout.

If respond or respond_hex is provided, that data is sent immediately when the pattern matches — before this tool returns. This enables sub-millisecond triggered responses for time-sensitive sequences like interrupting a bootloader autoboot. The respond string is sent as-is (no newline appended).

Useful for waiting for boot messages, login prompts, or specific device states before interacting.

Examples: - Wait for login: serial_wait_for(pattern="login:") - Wait for U-Boot: serial_wait_for(pattern="U-Boot", timeout=30) - Wait for prompt: serial_wait_for(pattern="[$#>]\s*$") - Wait for ready: serial_wait_for(pattern="System ready", timeout=60) - Interrupt autoboot: serial_wait_for(pattern="Hit any key to stop autoboot", respond=" ", timeout=60) - Bootloader handshake: serial_wait_for(pattern="Bootloader v", respond_hex="7F")

Args: pattern: Regex pattern to wait for timeout: Max seconds to wait (default 10) session_id: Port name of the session. Optional if only one session is open. encoding: Character encoding (default utf-8) respond: Text to send immediately when pattern matches (sent as-is, no newline) respond_hex: Hex bytes to send when pattern matches (e.g. "7F", "AA 55")

Write data to the open serial port.

For most interactions, prefer serial_command() which writes and waits for the response in one step. Use serial_write() for fire-and-forget or when you need manual timing control.

Args: data: Text to send over serial session_id: Port name of the session to write to. Optional if only one session is open. encoding: Character encoding to use append_newline: Whether to append \r\n to the data

Read all buffered data from the serial port.

Returns everything received since the last read, then advances the cursor. If no new data is available, waits up to timeout seconds for data to arrive.

For most interactions, prefer serial_command() which writes and reads in one step. Use serial_read() when passively monitoring or after a manual serial_write().

Args: session_id: Port name of the session to read from. Optional if only one session is open. timeout: Seconds to wait for data if buffer is empty encoding: Character encoding for decoding the data

Read historical data received since a given timestamp (non-destructive).

Unlike serial_read(), this does NOT advance the read cursor — calling serial_read_since will not affect what serial_read() returns next. If since is omitted, returns all data received since the session was opened.

Args: session_id: Port name of the session. Optional if only one session is open. since: Unix timestamp. If omitted, returns all data since session start. encoding: Character encoding for decoding the data

Write raw bytes (specified as hex) to the serial port.

Use this for binary protocols (Modbus, bootloader commands, firmware upload, raw UART framing) where you need exact byte-level control. No newline is appended.

Examples: - Send Modbus query: serial_write_hex(hex_string="01 03 00 00 00 0A C5 CD") - Send break byte: serial_write_hex(hex_string="FF") - STM32 bootloader: serial_write_hex(hex_string="7F")

Args: hex_string: Hex-encoded bytes separated by spaces (e.g. "AA 55 01 03 FF") session_id: Port name of the session. Optional if only one session is open.

Read buffered data as hex-encoded bytes (for binary protocols).

Like serial_read() but returns data as a hex string instead of decoded text. Advances the read cursor.

Args: session_id: Port name of the session to read from. Optional if only one session is open. timeout: Seconds to wait for data if buffer is empty

Control DTR and RTS hardware signals on the serial port.

These pins are commonly used to:

• Reset microcontrollers (DTR on Arduino, DTR+RTS on ESP32)

• Enter bootloader/programming mode

• Control power to peripherals via transistor switches

• Implement hardware flow control

Examples: - Reset Arduino: serial_set_signals(dtr=False); serial_set_signals(dtr=True) - ESP32 bootloader: serial_set_signals(dtr=False, rts=True) then serial_set_signals(dtr=True, rts=False)

Args: dtr: Set DTR signal high (True) or low (False). None leaves it unchanged. rts: Set RTS signal high (True) or low (False). None leaves it unchanged. session_id: Port name of the session. Optional if only one session is open.

Read the current state of all serial control signals.

Returns: DTR, RTS (output signals you control) and CTS, DSR, RI, CD (input signals from the remote device). Useful for checking hardware flow control state or verifying device presence.

Args: session_id: Port name of the session. Optional if only one session is open.

Send a serial break signal.

A break signal holds the TX line low for longer than a character frame, which many devices interpret as a special command:

• U-Boot: interrupt autoboot to get a shell

• Cisco IOS: break into ROMMON

• Sun/Oracle ILOM: enter diagnostics

• Linux SysRq: trigger magic SysRq if configured

Args: duration: Break duration in seconds (default 0.25, most devices need 0.1-0.5) session_id: Port name of the session. Optional if only one session is open.

Auto-detect the baud rate on a serial port by trying common rates and checking which one produces readable ASCII output.

Opens and closes the port internally — the port must NOT have an active session. After detection, use serial_open() with the recommended baud rate.

If probe is True (default), sends \r\n at each baud rate to elicit a response. Set to False for passive listening (e.g. if the device sends data continuously).

Args: port: Serial port device path (e.g. /dev/ttyUSB0, COM3) probe: Whether to send \r\n to prompt a response (default True)

Clear the receive history buffer for a session.

Resets the read cursor and frees memory. Useful for long-running sessions on chatty devices, or to get a clean slate before a new interaction.

Args: session_id: Port name of the session. Optional if only one session is open.

Start logging all received serial data to a file.

Creates a timestamped log file capturing everything the device sends. Similar to minicom's capture feature. Only one log file per session.

Args: file_path: Path to the log file to create/write session_id: Port name of the session. Optional if only one session is open. append: If True, append to existing file instead of overwriting

Stop logging serial data and close the log file.

Returns the log file path, total bytes logged, and duration.

Args: session_id: Port name of the session. Optional if only one session is open.

Send a file to the device using XMODEM protocol.

The device must already be waiting to receive (e.g. after a "rx" command or entering a bootloader's receive mode). Supports standard XMODEM (checksum) and XMODEM-CRC (CRC-16) modes.

Args: file_path: Path to the file to send session_id: Port name of the session. Optional if only one session is open. mode: "xmodem" for checksum mode, "xmodem-crc" for CRC-16 mode

Receive a file from the device using XMODEM protocol.

The device must already be sending (e.g. after a "sx filename" command). The received file is written to file_path.

Args: file_path: Path where the received file will be saved timeout: Max seconds to wait for transfer to complete session_id: Port name of the session. Optional if only one session is open. mode: "xmodem" for checksum mode, "xmodem-crc" for CRC-16 mode

List all open serial sessions with connection details.

Get the current serial session status including connection health.

Reports whether the device is still connected, bytes buffered, total bytes received, connection parameters, and health status. If the USB adapter has been physically disconnected, the health field will indicate the problem.

Args: session_id: Port name of the session. Optional if only one session is open. If omitted with multiple sessions open, returns a summary of all.