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. Ports already open here are marked.

Show the device presets connect(preset=...) understands, with their settings.

A preset supplies baud, data bits, parity, stop bits, flow control, the line ending the device expects, and the prompt that ends a reply. Anything you pass explicitly to connect overrides the preset. Families: network consoles (Cisco, Juniper, Linux), text CAT radios (Kenwood, Elecraft, Yaesu), Icom CI-V, rotators, Arduino, NMEA GPS.

Open a serial port and start its background reader.

Defaults are 9600 baud, 8 data bits, no parity, 1 stop bit, no flow control ("9600 8N1"), CR line ending, which is what most console/craft ports expect. Give preset (see list_presets) to load a device family's usual settings, and override any field explicitly, e.g. "38400 with XON/XOFF" -> baud=38400, xonxoff=True. Several ports can be open at once; each gets a name and later tools default to the most recently used one. Nothing is specific to telecom gear: any device on a serial port works, including IoT gateways, alarm and control panels, UPS and PDU menus and lab instruments; choose terminal by what the device prints.

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. preset: Device preset name such as "cisco-console", "juniper-craft", "kenwood-cat", "icom-civ", "yaesu-rotator", "arduino", "nmea-gps". name: Nickname for this connection ("rig", "rotator"). Defaults to the port's short name. Use it in other tools' connection argument. baud: Baud rate. Common values: 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200. Unknown? Use detect_baud first. 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 unless the manual says so and the cable carries those lines. xonxoff: Software (XON/XOFF) flow control. Off by default. Never for binary protocols (it swallows 0x11 / 0x13 bytes). line_ending: Default line ending for send_text/query_text on this connection: "CR" (most rigs, consoles), "LF" (Unix, Arduino), "CRLF", or "NONE" (Kenwood-style CAT ending in ';'). prompt: Default prompt for read_until_prompt/query_text on this connection, e.g. "# ", "> ", ";" (CAT replies). Say what the device shows, with its trailing space. prompt_regex: Treat prompt as a regular expression. terminal: How to interpret what the device sends. "dumb" (default): raw bytes, right for CAT, CI-V, rotators and most CLIs. "ansi": strip colour/escape sequences and apply CR/backspace overwrites so shells and coloured prompts read cleanly (the console presets use it); prompts are also matched on the last line as displayed, so a line redrawn with spaces and backspaces (Junos after ? or Ctrl-U) still ends in its prompt. "vt100"/"xterm": additionally keep a real screen for full-screen menus, BIOS/BMC consoles, vi/top; read it with the screen tool, navigate with send_keys. cols: Screen width for vt100/xterm (default 80). rows: Screen height for vt100/xterm (default 24).

Reconnect to a remembered port with the same settings as last time.

Every successful connect is remembered by name across sessions (port, baud, flow control, line ending, prompt, preset). With no name, reopens the most recently used one. Handy at the start of a chat so the user doesn't repeat the port and baud rate. If nothing is remembered, says to use connect instead.

Close a serial port and free it for other programs.

Args: connection: Which connection to close (name from connect). Default: the current one. all_connections: Close every open port.

Report every open port: settings, reader state, buffered bytes, control-line states, capture, and which connection is current. With nothing open, lists what reconnect_last remembers.

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". Default: the connection's line ending (from connect or its preset). clear_buffer_first: Discard buffered RX before sending. connection: Which open connection (name). Default: the current one.

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"; civ_build makes these). Spaces in the hex string are ignored. To see a binary reply, call read_available afterward and hand the hex to civ_parse (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. connection: Which open connection (name). Default: the current one.

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", 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:". Prefer a prompt with its trailing space over a bare "#": the match is searched in everything received, including the echo of your own command. Default: the connection's prompt (from connect/preset), else "ends with #, >, $ or %". timeout: Max seconds to wait for the prompt to appear. regex: Treat prompt as a Python regular expression (e.g. r"[\w.-]+[#>] ?$" for a hostname-style prompt). auto_reply: Text to send automatically when a trigger shows up while waiting, e.g. {"--More--": " "} to page through long output, or {"[confirm]": "\r"}. Each occurrence is answered once. connection: Which open connection (name). Default: the current one.

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, as text and as hex.

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

For the common "ask the device something and read its answer" case. Reads until prompt (or the connection's prompt) appears; with no prompt anywhere, or prompt="", 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). Default: the connection's line ending. prompt: Literal prompt to read until, e.g. "# " or ";". "" forces an idle-terminated read even if the connection has a prompt. read_timeout: How long to wait overall, in seconds. connection: Which open connection (name). Default: the current one.

Run a scripted sequence of send-and-wait steps in one call, like expect.

Use it for login flows and multi-step commands instead of one tool call per line: [{send: "", expect: "login: "}, {send: "admin", expect: "Password:"}, {send: "", expect: "> "}, {send: "show version", expect: "> "}]. Each step's output is returned. A step with no send just waits; one with no expect just sends.

Args: steps: The steps, in order. auto_reply: Triggers answered automatically while waiting, e.g. {"--More--": " "}. stop_on_timeout: Stop at the first step whose expect isn't seen. connection: Which open connection (name). Default: the current one.

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).

Press keys by name, encoded the way a VT100/xterm terminal sends them.

Use it for what send_text can't type: Ctrl-C to interrupt a running command (ping, monitor, a stuck process), Ctrl-Z, Esc, Tab (completion), arrows (history, menus), Enter alone, function keys, Page Up/Down. Each item is a key name ("ctrl-c", "esc", "tab", "enter", "up", "down", "left", "right", "home", "end", "pgup", "pgdn", "backspace", "delete", "f1".."f12", "space"), a single character, or "text:..." for a literal run. Nothing is read; follow with read_until_prompt, read_available, or screen.

Show the current terminal screen of a vt100/xterm connection: what a person at a real terminal would see right now, as rows of text, plus the cursor position. This is how to read full-screen interfaces (BIOS setup, RAID/BMC consoles, menu-driven switches, vi, top): press keys with send_keys, then look at the screen again.

Args: reset: Clear the screen model first (after garbage, or a resize). connection: Which open connection (name). Default: the current one.

Set the DTR and/or RTS output lines and hold them.

Uses: key a transmitter whose PTT is wired to RTS or DTR (set it True to transmit, False to stop; pulse_line is safer for that), hold an Arduino in reset (DTR False), or tell a modem you're present. Leave a line at None to keep it unchanged. Refused in read-only mode.

Drive DTR or RTS to level for ms milliseconds, then restore it.

Uses: reset an Arduino (DTR, 100 ms), enter a bootloader, or key a rig's PTT for a timed transmission (RTS or DTR per the interface's wiring). The line is always restored, even if the wait is interrupted. Refused in read-only mode.

Send a BREAK condition (TX held low) for ms milliseconds.

Some consoles use BREAK to enter ROMMON or interrupt boot; some serial devices use it as an attention signal. Refused in read-only mode.

Start writing this connection's traffic to a file until capture_stop.

Args: path: File to write. Empty = an auto-named file in the app's captures folder. A bare name goes in that folder; an absolute path is used as is. Existing files are appended to. format: "raw" writes received bytes exactly as they arrive (a terminal log; echo included). "annotated" writes timestamped lines marked TX or RX, which is better for protocol debugging. connection: Which open connection (name). Default: the current one.

Stop the capture started by capture_start and report the file and size.

Return the tail of everything received on a connection since it was opened.

This is a rolling record (last 256 KB) kept regardless of what the read tools consumed, so you can re-read output that an earlier call already returned or that arrived between calls. Also available as the MCP resource serial://transcript/{name}.

Report which program currently holds a serial port (macOS/Linux, via lsof).

Use when connect says the port is in use, or before asking the user to close something. On Windows the OS doesn't expose this; the usual suspects are a terminal (PuTTY), WSJT-X, a logger, or the Arduino Serial Monitor.

Try common baud rates on a closed port and rank them by how readable the reply is. Use when the user doesn't know the device's rate.

Each candidate is opened briefly, probe (default: a bare return) is sent, and whatever comes back is scored by its share of printable text. The right rate yields clean text; wrong rates yield garbage or nothing. Note: opening a port resets many Arduinos (DTR), and some devices (Kenwood CAT) only answer a real command, so pass e.g. probe="ID;" with probe_line_ending="NONE".

Args: port: The port to probe (must not be open here). probe: Text to send at each rate. Empty sends only the line ending. probe_line_ending: Line ending appended to the probe ("NONE" for CAT). candidates: Rates to try. Default: 9600, 115200, 19200, 38400, 57600, 4800, 2400, 1200, 230400. settle: Seconds to wait for a reply at each rate.

Build an Icom CI-V frame as hex, ready for send_hex.

Args: command: Command byte(s) as hex, e.g. "03" read frequency, "04" read mode, "05" set frequency, "06" set mode, "1C 00" PTT, "19 00" read rig address. data: Data bytes as hex. For frequencies use civ_freq: set 14.070 MHz is command "05" with data "00 00 07 14 00" (BCD, low byte first). rig: The rig's CI-V address (IC-7300 94, IC-7610 98, IC-9700 A2, IC-705 A4). controller: Our address, conventionally E0.

Decode Icom CI-V frames from hex (as returned by read_available).

Splits the bytes into frames, tells our own echoed command apart from the rig's reply, and decodes frequencies (BCD), modes, OK/NG and PTT state.

Convert between a frequency in MHz and CI-V BCD data bytes.

Give mhz to get the 5 data bytes for a set-frequency command (05), or bcd_hex (5 bytes from a reply) to get the frequency.

Build a ';'-terminated text CAT command (Kenwood, Elecraft, Yaesu) for query_text or send_text with line_ending="NONE".

Common commands: ID (rig id), FA/FB (VFO A/B frequency; empty value = read), MD (mode; read, or set with the family's code), IF (full status), PS (power), TX/RX, AI0 (silence auto-info), SM0 (S-meter), PC (output power).

Args: command: Two letters, e.g. "FA". value: Digits/letters to append for a set, e.g. "2" for MD2 (USB). Empty = read. frequency_mhz: For FA/FB sets: the frequency; formatted as 11 digits of Hz (Kenwood/Elecraft) or 9 (Yaesu). flavor: Which family's conventions: "kenwood" (default), "elecraft", "yaesu".

Decode ';'-terminated text CAT replies: rig id to model, FA/FB to MHz, MD to mode name, IF to frequency/mode/VFO/split/TX state, and the ?; E; O; error answers. Pass the text returned by query_text.

Build a Yaesu GS-232A/B rotator command for send_text (CR) or query_text.

Actions: "azimuth" (C, read), "position" (C2, read az+el), "elevation" (B), "move" (M), "move_azel" (W ), "stop"/"stop_azimuth"/ "stop_elevation", "left"/"right"/"up"/"down" (run until stop), "speed" (X1..X4), "help". Reads reply immediately; moves reply nothing, so read the position afterwards to confirm.

Decode a GS-232 reply into azimuth/elevation degrees ("+0180", "+0180+0045", "AZ=180 EL=045") or the ?> rejection.