List every serial port the computer can currently see.

Call this FIRST whenever the user wants to connect to a device but hasn't given an exact port name, or when a connection fails. Returns each port's system name (what you pass to connect), a human description, and the USB hardware id, so you can guess which one is the user's gear.

Open a serial port and start the background reader.

The defaults are 9600 baud, 8 data bits, no parity, 1 stop bit, no flow control ("9600 8N1"), which is what most console/craft ports and much radio gear expect. Every setting can be overridden when the user says so, e.g. "38400 with XON/XOFF" -> baud=38400, xonxoff=True.

Args: port: System port name, e.g. "COM4" (Windows), "/dev/cu.usbserial-10" (macOS), or "/dev/ttyUSB0" (Linux). Get exact names from list_serial_ports. baud: Baud rate. Common values: 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200. Check the device's console/CAT menu if unsure. bytesize: Data bits: 5, 6, 7, or 8. Almost always 8. parity: "N" none, "E" even, "O" odd. Almost always "N". stopbits: 1, 1.5, or 2. Almost always 1. rtscts: Hardware (RTS/CTS) flow control. Off by default; only turn on if the device's manual says so and the cable carries those lines. xonxoff: Software (XON/XOFF) flow control. Off by default. Do not use for binary protocols (it swallows 0x11 / 0x13 bytes). timeout: Reserved for compatibility; the reader thread polls the port on a fixed short interval regardless, so reads never block Claude.

Reconnect to the most recently used port/settings from a previous session.

Handy at the start of a chat so the user doesn't have to repeat the port and baud rate. If nothing is remembered, tells you to use connect instead.

Send an ASCII command to the device. Writes to TX only; does NOT read.

On an interactive console the device will ECHO this text back and then print its output; call read_until_prompt (or read_available) afterward to see it. Use clear_buffer_first=True to discard any stale/unsolicited output so the next read starts clean.

Args: data: The command text, e.g. "show version", "FA014250000", or "ID". Non-ASCII characters are sent as "?"; use send_hex for raw bytes. line_ending: What to append — "CR" (\r, most rigs), "CRLF" (\r\n), "LF" (\n, most Unix-style consoles), or "NONE". clear_buffer_first: Discard buffered RX before sending.

Send raw bytes given as hex. Writes to TX only; does NOT read.

Use for binary protocols — notably Icom CI-V, which is all hex (e.g. "FE FE 94 E0 03 FD"). Spaces in the hex string are ignored. To see a binary reply, call read_available afterward (binary replies rarely have a text prompt, so read_until_prompt usually isn't the right tool for these).

Args: hex_bytes: Bytes as hex, e.g. "FE FE 94 E0 03 FD". clear_buffer_first: Discard buffered RX before sending.

Read accumulated output until a prompt appears, or until timeout.

This is the right tool for interactive CLI sessions (routers, switches, shells). It reads from the background buffer until prompt is seen, then returns everything up to and including it, leaving anything after the prompt in the buffer for the next read. Because the reader runs continuously, large multi-page outputs are captured in full rather than being cut off by a fixed delay.

Typical flow: send_text("show version", line_ending="LF", clear_buffer_first=True) read_until_prompt(prompt="# ")

Args: prompt: The text that marks the end of output. Literal by default, e.g. "# ", "> ", "login: ", "$ ", "Password:". Common device prompts end in "# " (enable) or "> " (user). Note the match is searched in everything received, including the echo of your own command, so prefer a prompt with its trailing space over a bare "#" or ">" when the command text itself could contain that character. timeout: Max seconds to wait for the prompt to appear. regex: Treat prompt as a Python regular expression instead of literal text (e.g. r"[\w.-]+[#>] ?$" to match a hostname-style prompt).

Drain and return whatever the device has sent, without transmitting anything.

Use for unsolicited/streaming output (syslog on a console, GPS, a sensor, a rig in auto-info mode), or to grab a binary reply after send_hex. Waits up to read_timeout for the first bytes, then briefly settles so a full chunk is captured, then returns everything buffered.

Convenience: clear the buffer, send an ASCII command, and read the reply.

For the common "ask the device something and read its answer" case. If prompt is given, reads until that prompt appears (best for interactive CLIs). If prompt is empty, reads until the device goes idle for a short beat (best for line-based rigs/CAT that reply with a terminated string and no shell prompt).

Args: data: Command text, e.g. "show version" or "ID". line_ending: "CR", "CRLF", "LF", or "NONE" (see send_text). prompt: Optional literal prompt to read until, e.g. "# ". Empty = read until idle. read_timeout: How long to wait overall, in seconds.

Discard any buffered received data. Handy right before sending a command so the next read starts clean (drops old echo, prior output, or syslog noise).

Report whether a port is open, with what settings, and how much RX is buffered.

Close the serial port and free it for other programs.