---
title: RS-232 Tools
description: Modem control lines, break signals, and RS-232 specific operations
sidebar:
  order: 2
---

import { Aside } from '@astrojs/starlight/components';

RS-232 is the default mode for all newly opened ports. These five tools provide control over modem signal lines and break conditions -- the hardware handshaking and signaling layer of point-to-point serial communication.

<Aside type="note">
Examples use tool-call notation: `tool_name(param=value)`. These are MCP tool calls made by the assistant, not code you write directly. Boolean values use JSON convention (`true`/`false`).
</Aside>

<Aside type="note" title="RS-232 mode required">
All tools on this page require the port to be in RS-232 mode. Since RS-232 is the default mode when a port is opened, no extra setup is needed unless you previously switched to RS-485 mode. To switch back, call `set_port_mode(port, "rs232")`.
</Aside>

<Aside type="tip" title="Modem control lines explained">
RS-232 defines six signal lines beyond TX/RX data:

**Output lines** (controlled by you):
- **RTS** (Request To Send) -- signals that you are ready to receive data
- **DTR** (Data Terminal Ready) -- signals that your terminal is present and active

**Input lines** (read-only, set by the remote device):
- **CTS** (Clear To Send) -- remote device is ready to receive
- **DSR** (Data Set Ready) -- remote device is present and powered
- **RI** (Ring Indicator) -- incoming call (modem legacy)
- **CD** (Carrier Detect) -- connection is established

In practice, many embedded devices repurpose these lines for reset, bootloader entry, or power control.
</Aside>

---

## get_modem_lines

Read all RS-232 modem control and status line states, including the current break condition.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `port` | `str` | required | Device path of the port to query. |

**Returns:** Dict with `success`, `port`, `input_lines` (object with `cts`, `dsr`, `ri`, `cd`), `output_lines` (object with `rts`, `dtr`), and `break_condition` (bool).

```
get_modem_lines(port="/dev/ttyUSB0")

# Example response:
# {
#   "success": true,
#   "port": "/dev/ttyUSB0",
#   "input_lines": {"cts": true, "dsr": true, "ri": false, "cd": false},
#   "output_lines": {"rts": true, "dtr": true},
#   "break_condition": false
# }
```

---

## set_modem_lines

Set the RS-232 output control lines (RTS and DTR). Only the lines you specify are changed; pass `None` (or omit the parameter) to leave a line unchanged.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `port` | `str` | required | Device path of the port. |
| `rts` | `bool \| None` | `None` | Set RTS (Request To Send) state. `None` = no change. |
| `dtr` | `bool \| None` | `None` | Set DTR (Data Terminal Ready) state. `None` = no change. |

**Returns:** Dict with `success`, `port`, `rts`, and `dtr` (current states after change).

These lines are commonly used for:
- Hardware flow control
- Device reset sequences (many boards use DTR for reset)
- Power control on some devices
- Custom signaling protocols

```
# Assert DTR to signal "terminal ready"
set_modem_lines(port="/dev/ttyUSB0", dtr=true)

# Drop RTS to signal "stop sending"
set_modem_lines(port="/dev/ttyUSB0", rts=false)

# Set both lines at once
set_modem_lines(port="/dev/ttyUSB0", rts=true, dtr=true)
```

---

## pulse_line

Pulse an RS-232 control line high-then-low or low-then-high. Commonly used for device reset sequences.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `port` | `str` | required | Device path of the port. |
| `line` | `Literal["rts", "dtr"]` | required | Which line to pulse. |
| `duration_ms` | `int` | `100` | Pulse duration in milliseconds. Must be 1-5000. |
| `active_low` | `bool` | `True` | If `True`, pulse LOW then HIGH. If `False`, pulse HIGH then LOW. |

**Returns:** Dict with `success`, `port`, `line`, `duration_ms`, and `active_low`.

The line is set to its initial state, held for `duration_ms`, pulsed to the active state for `duration_ms`, then restored to its original value.

Typical reset sequences:
- **Arduino**: DTR pulse triggers auto-reset
- **ESP32/ESP8266**: DTR + RTS sequence enters bootloader
- **Custom hardware**: Various reset/trigger signals

```
# Arduino-style reset (DTR pulse, active low)
pulse_line(port="/dev/ttyUSB0", line="dtr", duration_ms=100)

# Active-high pulse on RTS
pulse_line(port="/dev/ttyUSB0", line="rts", duration_ms=200, active_low=false)

# Short trigger pulse
pulse_line(port="/dev/ttyUSB0", line="dtr", duration_ms=10)
```

---

## send_break

Send a timed serial break signal -- a sustained low state on the TX line longer than a character frame. Used to get the attention of a remote device or trigger special modes.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `port` | `str` | required | Device path of the port. |
| `duration_ms` | `int` | `250` | Break duration in milliseconds. Must be 1-5000. |

**Returns:** Dict with `success`, `port`, and `duration_ms`.

```
# Standard break signal
send_break(port="/dev/ttyUSB0")

# Short break (100ms)
send_break(port="/dev/ttyUSB0", duration_ms=100)

# Long break to force attention
send_break(port="/dev/ttyUSB0", duration_ms=1000)
```

---

## set_break_condition

Set or clear the break condition on a serial port. Unlike `send_break()` which sends a timed pulse, this holds the break condition indefinitely until explicitly cleared. Useful for protocols that require sustained break states.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `port` | `str` | required | Device path of the port. |
| `enabled` | `bool` | required | `True` to assert break (hold TX low), `False` to release. |

**Returns:** Dict with `success`, `port`, and `break_condition`.

<Aside type="caution">
The break condition holds the TX line low continuously. The remote device will not receive valid data while break is asserted. Always clear the condition with `enabled=False` when done.
</Aside>

```
# Assert break condition
set_break_condition(port="/dev/ttyUSB0", enabled=true)

# ... wait for device to respond ...

# Release break
set_break_condition(port="/dev/ttyUSB0", enabled=false)
```
