> 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/app-builder/build-backend/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.

This connector requires [instance creation](/app-builder/build-backend/functions/connectors.md#instance-creation) before you can scan system ports, configure connection parameters, or manage data streams.

## 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 configured for a specific serial port. The connector preserves these properties but delays opening the physical hardware port until you run `open`.

#### 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 communication channel to the serial port defined in the configuration.

#### Parameters

None.

#### Output

Returns `true` when the connection succeeds. Throws an error on failure.

### `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.

### `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.</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.

### `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 `true` when the observer registers successfully, or nothing if an observer with that name already exists.

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

#### 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 `true` when the observer registers successfully, or nothing if an observer with that name already exists.

#### 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.heisenware.com/app-builder/build-backend/functions/connectors/rs-232-485.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.