> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/reference/functions/connectors/rs-232-485.md).

# RS-232/485

The RS-232/485 connector provides a unified interface to communicate with devices connected over a serial port, such as physical RS-232 and RS-485 interfaces, or USB-to-serial adapters. It scans system ports, configures connection parameters, and manages incoming and outgoing data streams.

`list` finds the ports of the host without an instance. Everything else works on an [instance](https://docs.heisenware.com/reference/functions/connectors.md#instance-creation) that stands for one open port.

## Connection management

### `list`

Scans the host system and returns an array of all detected serial ports. Use this to locate valid port paths before creating an instance.

#### Parameters

None.

#### Output

Returns an array of objects containing detailed platform hardware information for each detected serial port.

#### Example

```json
[
  {
    "path": "COM3",
    "manufacturer": "Arduino LLC",
    "serialNumber": "12345",
    "pnpId": "USB\\VID_2341&PID_0043\\12345",
    "locationId": "Port_#0003.Hub_#0001",
    "productId": "0043",
    "vendorId": "2341"
  }
]
```

### `create`

Creates an instance for one serial port and opens it right away, locking it against other processes. The instance outlives the App and the agent's restarts: whenever the agent comes up it is created again and the port opens again.

If the device is not there, the open fails, the instance lives on and `lastError` says why. Trigger `open` once the device is plugged in.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>path</code></td><td>The file system path of the target serial port (such as <code>/dev/ttyUSB0</code> on Linux or <code>COM3</code> on Windows).</td><td>string</td></tr><tr><td></td><td><code>baudRate</code></td><td>The serial communication speed in bits per second. Supported standard values include 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, or 115200. Default 9600.</td><td>integer</td></tr><tr><td></td><td><code>dataBits</code></td><td>The number of data bits per character frame (5, 6, 7, or 8). Default 8.</td><td>integer</td></tr><tr><td></td><td><code>stopBits</code></td><td>The number of stop bits to signal the end of a character frame (1, 1.5, or 2). Default 1.</td><td>number</td></tr><tr><td></td><td><code>parity</code></td><td>The parity error-checking mode (<code>none</code>, <code>even</code>, <code>mark</code>, <code>odd</code>, or <code>space</code>). Default 'none'.</td><td>string</td></tr><tr><td></td><td><code>lock</code></td><td>Prevents other system processes from gaining control of the port. Windows does not support disabling this. Default true.</td><td>boolean</td></tr><tr><td></td><td><code>rtscts</code></td><td>Enables Ready to Send / Clear to Send (RTS/CTS) hardware handshaking flow control. Default false.</td><td>boolean</td></tr><tr><td></td><td><code>xon</code></td><td>Enables XON software flow control. Default false.</td><td>boolean</td></tr><tr><td></td><td><code>xoff</code></td><td>Enables XOFF software flow control. Default false.</td><td>boolean</td></tr><tr><td></td><td><code>xany</code></td><td>Enables XANY software flow control, which allows any received character to restart transmission. Default false.</td><td>boolean</td></tr><tr><td></td><td><code>hupcl</code></td><td>Drops the Data Terminal Ready (DTR) hardware line when closing the connection. Default true.</td><td>boolean</td></tr></tbody></table>

#### Output

Returns the name of the created instance.

#### Example

```yaml
# options
path: COM3
baudRate: 9600
dataBits: 8
parity: none
stopBits: 1
```

### `open`

Opens the port the instance was created for. `create` already opened it, so this is how you get a port back that failed to open or that you closed: after plugging the device in, or after `close`.

#### Parameters

None.

#### Output

Returns `true` when the port is open. Throws on failure, and on a port that is open already (`Port is already open`), so ask `isOpen` first when a flow may run `open` twice.

### `isOpen`

Checks whether the communication channel to the serial port is open.

#### Parameters

None.

#### Output

Returns `true` if the channel is open, or `false` if it is not.

### `lastError`

Tells the last error of the port, for example why `open` failed or why the device dropped the line. A successful `open` clears it. The port reports a failed open as an error even when nothing listens yet, so this function answers after an `open` that threw and gives a page or a log the reason in plain words.

#### Parameters

None.

#### Output

Returns the message of the last error, or `null` when there was none.

### `changeBaudRate`

Updates the communication speed dynamically for an active, open serial connection.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>baudRate</code></td><td>The new baud rate (such as 19200 or 115200).</td><td>integer</td></tr></tbody></table>

#### Output

Returns `true` if the baud rate updates successfully. Throws an error on failure.

#### Example

```yaml
# baudRate
115200
```

### `close`

Closes the active serial connection.

#### Parameters

None.

#### Output

Returns `true` on successful disconnection. Ongoing write operations automatically fail if the connection drops before they finish.

### `delete`

Removes the instance and its configuration.

{% hint style="danger" %}

#### Irreversible action

Deleting an instance removes its configuration. To communicate with the device again, you must create a new instance.
{% endhint %}

#### Parameters

None.

#### Output

Returns `true` upon removal.

## Data operations

### `write`

Transmits a text string across the active serial interface and pauses execution until the port transmits all data. To insert control characters, use `<CR>` for carriage return (`\r`), `<LF>` for line feed (`\n`), and `<CRLF>` for both (`\r\n`).

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>data</code></td><td>The text string to transmit. Supports control tokens like <code>&#x3C;CRLF></code>.</td><td>string</td></tr><tr><td><code>suffix</code></td><td>An optional string appended automatically to the end of the text. Default empty string.</td><td>string</td></tr></tbody></table>

#### Output

Returns `true` when all data transmits completely. Throws an error on failure.

#### Example

```yaml
# data
GET_DATA
# suffix
<CRLF>
```

### `read`

Retrieves a specific number of raw bytes from the incoming receive buffer. To monitor incoming traffic asynchronously, use `onData` instead of polling with this function.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>size</code></td><td>The number of bytes to retrieve from the receive buffer. Optional: everything the buffer holds when left out.</td><td>integer</td></tr></tbody></table>

#### Output

Returns a decoded string containing the retrieved bytes, or `null` if the buffer does not contain the requested number of bytes. What is read is taken out of the buffer.

## Events

`onData` and `onError` are event functions. Triggering an event executor subscribes it; the data and the errors arrive on the executor's event outputs, not on its return. A subscription follows the executor's inputs and address, pauses while the App is stopped and ends with its scope: a user's with the user's last connection, a shared one never by itself. To end it by hand, choose **Stop listening** in the menu of the executor's event input; the next trigger subscribes again. See [Backend events](https://docs.heisenware.com/concepts/backend-events.md).

Both take a `name` that must be free on the instance. A second handler under a name that is taken fails with an error, so give each executor its own name.

### `onData`

Registers a named observer that parses the incoming serial data stream and triggers a callback when a complete message arrives. Use only one of the three parsing strategies. If several are set, `timeout` takes precedence over `byteLength` over `delimiter`.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>name</code></td><td></td><td>A unique label to identify this stream parser.</td><td>string</td></tr><tr><td><code>handler</code></td><td></td><td>The callback evaluated on payload match. Receives the parsed string payload.</td><td>callback</td></tr><tr><td><code>parserOptions</code></td><td><code>delimiter</code></td><td>Emits the accumulated stream immediately when encountering this character sequence. Recognizes control tokens like <code>&#x3C;LF></code> or <code>&#x3C;CRLF></code>. Default <code>&#x3C;LF></code>.</td><td>string</td></tr><tr><td></td><td><code>timeout</code></td><td>Emits the accumulated data after detecting a communication silence of this duration in milliseconds.</td><td>integer</td></tr><tr><td></td><td><code>byteLength</code></td><td>Emits the data block when the incoming stream reaches this fixed size in bytes.</td><td>integer</td></tr></tbody></table>

#### Output

Returns the handler's registration, which only says that the executor is listening. The parsed messages arrive on the event output. Releasing it takes the parser off the port and frees the name.

#### Examples

**Example 1: Delimiter text parsing**

```yaml
# name
line_handler
# handler
<callback>
# parserOptions
delimiter: <LF>
```

**Example 2: Inter-byte timeout burst parsing**

```yaml
# name
burst_handler
# handler
<callback>
# parserOptions
timeout: 50
```

**Example 3: Fixed byte length parsing**

```yaml
# name
packet_handler
# handler
<callback>
# parserOptions
byteLength: 16
```

### `onError`

Registers an observer that triggers whenever the serial channel encounters a hardware or connection error. An error that happened before any handler listened, a port that could not be opened for one, is handed to the first handler that listens after it, once.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>name</code></td><td>A unique identification label for this error observer.</td><td>string</td></tr><tr><td><code>handler</code></td><td>The callback triggered when a connector exception occurs. Receives the error object.</td><td>callback</td></tr></tbody></table>

#### Output

Returns the handler's registration, which only says that the executor is listening. The errors arrive on the event output. Releasing it frees the name.

#### Example

```yaml
# name
my_error_handler
# handler
<callback>
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.heisenware.com/reference/functions/connectors/rs-232-485.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
