GdSerial

https://github.com/sujithchristopher/gdserial
Admin
A high-performance Rust-based serial communication library for Godot 4 that enables direct hardware...
Tokens:34,686
Snippets:285
Trust Score:8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### GdSerial Quick Start Example

Source: https://github.com/sujithchristopher/gdserial/blob/main/RELEASE_NOTES.md

Shows basic usage of GdSerial: create a serial object, set port and baud rate, open the connection, write a line, read a response, and close. Requires Godot 4.2+ and appropriate system permissions.

```gdscript
var serial = GdSerial.new()
serial.set_port("COM3")
serial.set_baud_rate(9600)

if serial.open():
    serial.writeline("Hello Arduino!")
    var response = serial.readline()
    print("Response: ", response)
    serial.close()
```

--------------------------------

### Open serial port and handle result in GDScript

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Two GDScript examples showing how to call open() and handle its boolean result. The first prints a success or failure message; the second sets a port name, attempts to open it, and pushes an error and returns if it fails.

```gdscript
if serial.open():
    print("Connected to ", port_name)
else:
    print("Open failed — check device, permissions, and port name")
```

```gdscript
var port_name := "COM3"
serial.set_port(port_name)
if not serial.open():
    push_error("Could not open %s (busy? permissions? unplugged?)" % port_name)
    return
```

--------------------------------

### Open Serial Port with Buffering Mode

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Example of using the MODE_LINE_BUFFERED constant as an argument for the open method.

```gdscript
manager.open("COM3", 9600, 1000, GdSerialManager.MODE_LINE_BUFFERED)
```

--------------------------------

### Connect and Handle Serial Signals

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Example of connecting to data_received and port_disconnected signals in GDScript.

```gdscript
func _ready():
    manager.data_received.connect(_on_data)
    manager.port_disconnected.connect(_on_lost)

func _on_data(port: String, data: PackedByteArray) -> void:
    print(port, ": ", data.get_string_from_utf8())

func _on_lost(port: String) -> void:
    print("Lost connection to ", port)
```

--------------------------------

### GdSerialManager.list_ports

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Gets all available serial ports as a dictionary, same as GdSerial.list_ports().

```APIDOC
## [GET] GdSerialManager.list_ports

### Description
Returns a dictionary of available serial ports, identical to GdSerial.list_ports().

### Method
GET

### Endpoint
GdSerialManager.list_ports

### Parameters
None

### Response
#### Success Response (200)
- **Dictionary** - Index to info dict mapping.

#### Response Example
{"0": {"port_name": "COM3"}}
```

--------------------------------

### GdSerial.list_ports

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Gets all available serial ports as a dictionary mapping index to port information dict.

```APIDOC
## [GET] GdSerial.list_ports

### Description
Returns a dictionary where keys are indices and values are info dicts for each available serial port.

### Method
GET

### Endpoint
GdSerial.list_ports

### Parameters
None

### Response
#### Success Response (200)
- **Dictionary** - A mapping of index to port info dict (e.g., {"port_name": "COM3", "device_name": "..."})

#### Response Example
{
  "0": {"port_name": "COM3", "device_name": "..."}
}
```

--------------------------------

### bytes_available GDScript usage

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

GDScript usage example for bytes_available(). It checks if there are available bytes and reads them as a string. The method returns an integer count of available bytes.

```gdscript
if serial.bytes_available() > 0:
    print(serial.read_string(serial.bytes_available()))
```

--------------------------------

### Check connection with is_open() in GDScript

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Two GDScript examples using is_open() to check the connection. The first sends a PING if open; the second shows reconnecting after an unplug, noting that is_open() clears the port state on failure.

```gdscript
if serial.is_open():
    serial.writeline("PING")
```

```gdscript
# After an unplug, is_open() self-heals the internal state
if not serial.is_open():
    # port handle is already cleared; safe to re-open
    if serial.open():
        print("Reconnected")
```

--------------------------------

### clear_buffer GDScript usage

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

GDScript usage example for clear_buffer(). It resets protocol state before a fresh exchange by clearing the buffer and sending a RESET command. The method returns a boolean indicating success.

```gdscript
# Reset protocol state before a fresh exchange
serial.clear_buffer()
serial.writeline("RESET")
```

--------------------------------

### GdSerialManager GDScript Usage

Source: https://github.com/sujithchristopher/gdserial/blob/main/CLAUDE.md

Example of polling events from the GdSerialManager in a Godot _process loop.

```gdscript
func _process(_delta):
    for event in serial_manager.poll_events():
        if event.get("disconnected"):
            print("Lost: ", event["port"])
        else:
            print("Data from ", event["port"], ": ", event["data"])
```

--------------------------------

### Processing poll_events Loop

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/types.md

Example of iterating through events returned by poll_events and handling disconnect markers versus data payloads.

```gdscript
for event: Dictionary in manager.poll_events():
    if event.has("disconnected"):
        pass
    else:
        var data: PackedByteArray = event["data"]
```

--------------------------------

### bytes_available Rust signature

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Rust source signature for the bytes_available method. It returns bytes_to_read() from the underlying port. Any error inside bytes_to_read marks the port disconnected, logs "Failed to get available bytes: {} - marking port as disconnected", clears state, and returns 0. Connection test failure also returns 0.

```rust
#[func]
pub fn bytes_available(&mut self) -> u32
```

--------------------------------

### GdSerial.bytes_available

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Gets the number of bytes waiting to be read.

```APIDOC
## [GET] GdSerial.bytes_available

### Description
Returns the count of bytes currently in the input buffer.

### Method
GET

### Endpoint
GdSerial.bytes_available

### Parameters
None

### Response
#### Success Response (200)
- **int** - Number of bytes available to read.

#### Response Example
10
```

--------------------------------

### Build Commands for GdSerial

Source: https://github.com/sujithchristopher/gdserial/blob/main/CLAUDE.md

Standard commands for checking, building, and deploying the GdSerial library.

```bash
# Check for compilation errors (fastest feedback)
cargo check

# Build for development
cargo build

# Build optimized release (auto-detects platform/arch, copies to addons/)
./build_release.sh

# Build release binary manually (Windows)
cargo build --release
# Then copy: target/release/gdserial.dll → addons/gdserial/bin/windows-x86_64/
```

--------------------------------

### Build the gdserial library

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Builds the gdserial library for the current platform. Use the appropriate script for your operating system: ./build_release.sh for Linux/macOS and build_release.bat for Windows.

```bash
# Linux/Mac
./build_release.sh
```

```bash
# Windows
build_release.bat
```

--------------------------------

### open(port_name: String, baud_rate: int, timeout_ms: int, mode: int = 0) -> bool

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Opens a serial port with the specified configuration. Returns true on success, false on failure.

```APIDOC
## open(port_name: String, baud_rate: int, timeout_ms: int, mode: int = 0) -> bool

### Description
Opens a serial port with the specified configuration. If the port is already open, it is closed first. The mode parameter determines the reading mode. Returns true on success, false on failure.

### Parameters
- **port_name** (String) - Required - OS port name (e.g., "COM3", "/dev/ttyUSB0").
- **baud_rate** (int) - Required - Communication speed.
- **timeout_ms** (int) - Required - Read timeout for the reader thread.
- **mode** (int) - Optional - Default: 0 (MODE_RAW). One of the MODE_* constants; any value outside 1/2 maps to RAW.

### Returns
- **bool** - true if the port was opened successfully, false otherwise.

### Example
```gdscript
if manager.open("COM3", 9600, 1000):
    print("Opened in RAW mode (default)")
manager.open("COM3", 9600, 1000, GdSerialManager.MODE_LINE_BUFFERED)
manager.open("COM3", 9600, 1000, GdSerialManager.MODE_CUSTOM_DELIMITER)
```

### Error Handling
Open can fail (busy port, permissions) - never throws. Check the return value.
```gdscript
if not manager.open("/dev/ttyUSB0", 115200, 500, GdSerialManager.MODE_RAW):
    push_error("Failed to open port — see Godot console for the OS-level reason")
    return
```
```

--------------------------------

### Basic usage (GdSerial)

Source: https://github.com/sujithchristopher/gdserial/blob/main/addons/gdserial/README.md

Basic synchronous usage of GdSerial. Creates a GdSerial instance, sets the port and baud rate, opens the connection, writes a line, and closes it.

```gdscript
extends Node

var serial: GdSerial

func _ready():
    serial = GdSerial.new()
    serial.set_port("COM3")
    serial.set_baud_rate(9600)
    
    if serial.open():
        serial.writeline("Hello!")
        serial.close()
```

--------------------------------

### Clone the gdserial repository

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Clones the gdserial repository and navigates into the project directory. This is the first step in building the plugin from source.

```bash
git clone https://github.com/SujithChristopher/gdserial.git
cd gdserial
```

--------------------------------

### Configure all serial settings before opening

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Configures all serial port settings before opening. Each set_* method stores the value, and the settings take effect on the next open() call. The comments show the valid ranges for data bits, parity, stop bits, and flow control.

```gdscript
# Full configuration before opening (covers all set_* methods)
serial.set_port("COM3")
serial.set_baud_rate(115200)
serial.set_data_bits(8)      # 6, 7, or 8
serial.set_parity(0)         # 0: None, 1: Odd, 2: Even
serial.set_stop_bits(1)      # 1 or 2
serial.set_flow_control(0)   # 0: None, 1: Software, 2: Hardware
serial.set_timeout(1000)
```

--------------------------------

### Arduino Communication - Synchronous Read

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Synchronous, blocking serial communication example for reading a sensor value. Sends a command and waits for a line response.

```gdscript
serial.writeline("GET_SENSOR")
var reading = serial.readline()
print("Sensor value: ", reading)
```

--------------------------------

### GdSerial.open

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Opens the serial port and returns true on success, false otherwise.

```APIDOC
## [POST] GdSerial.open

### Description
Opens the serial port with the current configuration. Returns a boolean indicating success.

### Method
POST

### Endpoint
GdSerial.open

### Parameters
None

### Response
#### Success Response (200)
- **bool** - True if the port was opened successfully, false otherwise.

#### Response Example
true
```

--------------------------------

### open() -> bool

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Opens the configured serial port with current settings. Returns true on success and sets is_connected to true. Returns false and logs errors if the port name is empty or the underlying open operation fails.

```APIDOC
## open() -> bool

### Description
Opens the configured port with all current settings (data bits, parity, stop bits, flow control, baud rate, timeout). Returns `true` and sets `is_connected = true` on success.

### Method
open

### Parameters
None

### Returns
- **bool** - `true` on success, `false` on failure

### Error Handling
- Returns `false` (never throws) if `port_name` is empty, logging `"Port name not set"`
- Returns `false` if the underlying `serialport::new(...).open()` fails (e.g., port not found, busy, permission denied), logging `"Failed to open port {}: {}"` and setting `is_connected = false`

### Example
```gdscript
if serial.open():
    print("Connected to ", port_name)
else:
    print("Open failed — check device, permissions, and port name")
```

```gdscript
var port_name := "COM3"
serial.set_port(port_name)
if not serial.open():
    push_error("Could not open %s (busy? permissions? unplugged?)" % port_name)
    return
```
```

--------------------------------

### GdSerial .gdextension configuration

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/configuration.md

Configures the GDExtension entry symbol, the minimum Godot version (4.4), library paths for all supported platforms, and documentation locale directories. Debug and release build paths point to the same compiled library.

```ini
[configuration]

entry_symbol = "gdext_rust_init"
compatibility_minimum = 4.4

[libraries]

linux.debug.x86_64 =     "res://addons/gdserial/bin/linux-x86_64/libgdserial.so"
linux.release.x86_64 =   "res://addons/gdserial/bin/linux-x86_64/libgdserial.so"
linux.debug.arm64 =      "res://addons/gdserial/bin/linux-arm64/libgdserial.so"
linux.release.arm64 =    "res://addons/gdserial/bin/linux-arm64/libgdserial.so"
windows.debug.x86_64 =   "res://addons/gdserial/bin/windows-x86_64/gdserial.dll"
windows.release.x86_64 = "res://addons/gdserial/bin/windows-x86_64/gdserial.dll"
windows.debug.arm64 =    "res://addons/gdserial/bin/windows-arm64/gdserial.dll"
windows.release.arm64 =  "res://addons/gdserial/bin/windows-arm64/gdserial.dll"
macos.debug.x86_64 =     "res://addons/gdserial/bin/macos-x86_64/libgdserial.dylib"
macos.release.x86_64 =   "res://addons/gdserial/bin/macos-x86_64/libgdserial.dylib"
macos.debug.arm64 =      "res://addons/gdserial/bin/macos-arm64/libgdserial.dylib"
macos.release.arm64 =    "res://addons/gdserial/bin/macos-arm64/libgdserial.dylib"

[documentation]
en =    "res://addons/gdserial/doc/en/"
zh_CN = "res://addons/gdserial/doc/zh_CN/"
pt_BR = "res://addons/gdserial/doc/pt_BR/"

```

--------------------------------

### GdSerial plugin.cfg configuration

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/configuration.md

Defines plugin metadata for the Godot plugin manager, including name, description, author, version, and the bootstrap script 'plugin.gd'. The version must be kept in sync with Cargo.toml on release.

```ini
[plugin]

name="GdSerial - Serial Communication Library"
description="A Rust-based serial communication library for Godot 4 ..."
author="Sujith Christopher"
version="0.3.4"
script="plugin.gd"

```

--------------------------------

### Cargo.toml configuration for cdylib and dependencies

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/configuration.md

Specifies the crate-type as cdylib to produce a shared library loadable by Godot. Pins Godot gdext bindings to API 4-4 and uses serialport 4.7.2 for serial communication. The release profile enables high optimization and panic abort.

```toml
[lib]
crate-type = ["cdylib"]

[dependencies]
godot = { version = "0.5.3", features = ["api-4-4"] }
serialport = "4.7.2"

[profile.release]
opt-level = 3
lto = "fat"
strip = true
panic = "abort"
```

--------------------------------

### is_open(port_name: String) -> bool

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Checks if a port is open. Passive membership check of the ports map.

```APIDOC
## is_open(port_name: String) -> bool

### Description
Checks if a port is open. Passive membership check of the ports map (unlike GdSerial.is_open, no active device probe).

### Parameters
- **port_name** (String) - Required - Port to query.

### Returns
- **bool** - true if the port is open, false otherwise.

### Example
```gdscript
if manager.is_open("COM3"):
    manager.write("COM3", PackedByteArray([0x01]))
```
```

--------------------------------

### Instantiate GdSerial

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Create a new instance of the GdSerial class using the default constructor.

```gdscript
var serial := GdSerial.new()
```

--------------------------------

### Reconfigure settings by reopening the port

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Shows that set_* methods only take effect on the next open() call. Changing the baud rate while the port is open does not affect the live connection; you must close and reopen to apply the new setting.

```gdscript
# Settings only apply on the NEXT open(); use reconfigure-like flow by reopening
serial.set_baud_rate(9600)
serial.open()
serial.set_baud_rate(19200)  # does not affect the live connection
serial.close()
serial.open()                # now uses 19200
```

--------------------------------

### open_buffered(port_name: String, baud_rate: int, timeout_ms: int, mode: int) -> bool

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Deprecated alias for open(). Kept for backward compatibility.

```APIDOC
## open_buffered(port_name: String, baud_rate: int, timeout_ms: int, mode: int) -> bool

### Description
Deprecated: use open(port, baud, timeout, mode) instead. Kept for backward compatibility. Thin alias for open with a mandatory mode. Identical semantics.

### Parameters
- **port_name** (String) - Required - OS port name.
- **baud_rate** (int) - Required - Communication speed.
- **timeout_ms** (int) - Required - Read timeout for the reader thread.
- **mode** (int) - Required - One of the MODE_* constants.

### Returns
- **bool** - true if the port was opened successfully, false otherwise.

### Example
```gdscript
# Legacy call sites still work:
manager.open_buffered("COM3", 9600, 1000, 1)
```
```

--------------------------------

### Instantiate GdSerialManager

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Create a new instance of the GdSerialManager class. No ports are opened upon initialization.

```gdscript
var manager := GdSerialManager.new()
```

--------------------------------

### AT Commands - Send and Read Response

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Sends an AT command to a modem or WiFi module and reads the response line.

```gdscript
serial.writeline("AT+VERSION?")
var version = serial.readline()
print("Module version: ", version)
```

--------------------------------

### gdserial plugin directory structure

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Shows the directory layout of the gdserial Godot plugin, including configuration files, the GDExtension loader, and compiled libraries for Windows, Linux, and macOS.

```text
addons/gdserial/
├── plugin.cfg              # Plugin configuration
├── plugin.gd               # Plugin activation script
├── gdserial.gdextension    # Extension loader
├── bin/                    # Compiled libraries
│   ├── windows/            
│   │   └── gdserial.dll    # Windows x64
│   ├── linux/              
│   │   └── libgdserial.so  # Linux x64
│   └── macos/              
│       └── libgdserial.dylib # macOS x64
└── README.md              # Plugin documentation
```

--------------------------------

### list_ports() -> Dictionary

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Lists available serial ports. Returns an integer-indexed dictionary of port information, or an empty dictionary on failure.

```APIDOC
## list_ports() -> Dictionary

### Description
Lists available serial ports. Returns an integer-indexed dictionary of {port_name, port_type, device_name}. On enumeration failure, logs an error and returns an empty Dictionary.

### Method
list_ports

### Parameters
None

### Returns
- **Dictionary** - Integer-indexed dictionary of port information. Each entry contains:
  - **port_name** (String) - The OS port name.
  - **port_type** (String) - The type of the port.
  - **device_name** (String) - The device name.

### Example
```gdscript
for i in manager.list_ports():
    print(manager.list_ports()[i]["port_name"])
```
```

--------------------------------

### GdSerialManager.new()

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Constructor for creating a new GdSerialManager instance. Initializes internal channel and bookkeeping maps. No ports are open until open() is called.

```APIDOC
## GdSerialManager.new()

### Description
Creates a new GdSerialManager instance. Initializes internal channel and bookkeeping maps. No ports are open until open() is called.

### Method
Constructor

### Signature
GdSerialManager.new()

### Parameters
None

### Returns
GdSerialManager - A new instance of GdSerialManager.

### Example
```gdscript
var manager := GdSerialManager.new()
```
```

--------------------------------

### GdSerialManager.open

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Opens a serial port with the given name, baud rate, timeout, and optional mode. Returns true on success.

```APIDOC
## [POST] GdSerialManager.open

### Description
Opens a serial port for asynchronous communication. The `mode` parameter defaults to 0 (raw), with 1 for line-buffered and 2 for custom delimiter.

### Method
POST

### Endpoint
GdSerialManager.open

### Parameters
#### Path Parameters
- **name** (String) - Required - The port name (e.g., "COM3").
- **baud** (int) - Required - Baud rate.
- **timeout** (int) - Required - Read timeout in milliseconds.
- **mode** (int) - Optional (default 0) - Operation mode: 0 raw, 1 line-buffered, 2 custom delimiter.

### Request Example
GdSerialManager.open("COM3", 9600, 1000)

### Response
#### Success Response (200)
- **bool** - True if opened successfully, false otherwise.

#### Response Example
true
```

--------------------------------

### Simple blocking serial API with GdSerial

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Use GdSerial for simple, synchronous serial communication. List ports, set port and baud rate, open the port, write a line, wait briefly, read the response, and close. The GdSerial class is available automatically once the plugin is enabled; no imports are needed.

```gdscript
extends Node

var serial: GdSerial

func _ready():
    serial = GdSerial.new()
    
    # List available ports
    var ports: Dictionary = serial.list_ports()
    for i in ports:
        var info = ports[i]
        print("- ", info["port_name"], " (", info["device_name"], ")")
    
    serial.set_port("COM3")
    serial.set_baud_rate(115200)
    
    if serial.open():
        serial.writeline("Hello!")
        await get_tree().create_timer(0.1).timeout
        if serial.bytes_available() > 0:
            print("Response: ", serial.readline())
        serial.close()
```

--------------------------------

### GdSerialManager.reconfigure_port

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Updates settings on an already open port.

```APIDOC
## [POST] GdSerialManager.reconfigure_port

### Description
Updates parameters such as baud rate, data bits, etc., on an open port. Returns true on success.

### Method
POST

### Endpoint
GdSerialManager.reconfigure_port

### Parameters
#### Path Parameters
- **(unspecified parameters)** - Required - Settings to be reconfigured on the port.

### Request Example
GdSerialManager.reconfigure_port(...)

### Response
#### Success Response (200)
- **bool** - True if reconfigured successfully, false otherwise.

#### Response Example
true
```

--------------------------------

### reconfigure_port basic usage

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Updates port settings like baud rate and parity on a live connection without needing to reopen the port.

```gdscript
# Change speed and parity on a live connection without reopening
manager.reconfigure_port("COM3", 115200, 8, 0, 1, 0, 500)
```

--------------------------------

### Configure GdSerial with setters

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/configuration.md

Sets serial parameters (port, baud rate, timeout) on a GdSerial instance before calling open(). All settings apply to the next open() call.

```GDScript
serial.set_port("/dev/ttyUSB0")
serial.set_baud_rate(115200)
serial.set_timeout(500)
serial.open()
```

--------------------------------

### Async usage (GdSerialManager)

Source: https://github.com/sujithchristopher/gdserial/blob/main/addons/gdserial/README.md

Async usage with GdSerialManager. Connects to the data_received signal, opens a port with a timeout, and polls events in _process.

```gdscript
extends Node

var manager: GdSerialManager

func _ready():
    manager = GdSerialManager.new()
    manager.data_received.connect(func(port, data): 
        print("Data: ", data.get_string_from_utf8())
    )
    manager.open_port("COM3", 9600, 1000)

func _process(_delta):
    manager.poll_events()
```

--------------------------------

### write

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Thread-safe write of bytes to a port. Performs write_all and flush. Returns true on success, false on failure.

```APIDOC
## write

### Description
Thread-safe write of bytes to a port. Performs write_all and flush. Returns true on success, false on failure.

### Method
N/A (GDScript method)

### Endpoint
N/A (GDScript method)

### Parameters
#### Parameters
- **port_name** (String) - Required - Target port
- **data** (PackedByteArray) - Required - Bytes to transmit

### Request Example
```gdscript
manager.write("COM3", "PING".to_utf8_buffer())
```

### Response
#### Success Response (bool)
- **bool** - Returns true on success, false on failure.

#### Response Example
```gdscript
if not manager.write("COM3", PackedByteArray([0x02, 0x00])):
    push_error("Write failed — is the port open?")
```
```

--------------------------------

### is_open() -> bool

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Actively probes the port connection status via test_connection(), which calls bytes_to_read(). Returns false if no handle exists or if the probe errors, clearing the port state in the error case.

```APIDOC
## is_open() -> bool

### Description
Not a passive flag check: actively probes the port via `test_connection()` (`src/lib.rs:631`), calling `bytes_to_read()`. Returns `false` if no handle exists; if the probe errors, logs `"Connection test failed: {} - marking as disconnected"` and clears the port state before returning `false`.

### Method
is_open

### Parameters
None

### Returns
- **bool** - `true` if the port is open and responsive, `false` otherwise

### Example
```gdscript
if serial.is_open():
    serial.writeline("PING")
```

```gdscript
# After an unplug, is_open() self-heals the internal state
if not serial.is_open():
    # port handle is already cleared; safe to re-open
    if serial.open():
        print("Reconnected")
```
```

--------------------------------

### set_delimiter

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Switches a port to custom-delimiter mode at runtime. Returns true on success, false if the port is not found.

```APIDOC
## set_delimiter

### Description
Switches the port to BufferingMode::CustomDelimiter(delimiter as u8) at runtime. The reader thread picks it up on the next chunk, so no reopen is needed. Only valid for ports opened with MODE_CUSTOM_DELIMITER.

### Method
N/A (GDScript method)

### Endpoint
N/A (GDScript method)

### Parameters
#### Parameters
- **port_name** (String) - Required - Port whose delimiter to change
- **delimiter** (int) - Required - Delimiter byte (0–255, truncated to u8)

### Request Example
```gdscript
manager.open("COM3", 9600, 1000, GdSerialManager.MODE_CUSTOM_DELIMITER)
manager.set_delimiter("COM3", 0xFF)   # binary end marker
```

### Response
#### Success Response (bool)
- **bool** - Returns true on success, false if port not found.

#### Response Example
```gdscript
if not manager.set_delimiter("COM3", 13):  # '\r'
    push_error("Cannot set delimiter: port not open")
```
```

--------------------------------

### Open port with GdSerialManager and set delimiter

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/configuration.md

Opens a serial port with the manager using custom delimiter mode and re-targets the delimiter at runtime to 0xFF.

```GDScript
manager.open("COM3", 9600, 1000, GdSerialManager.MODE_CUSTOM_DELIMITER)
manager.set_delimiter("COM3", 0xFF)
```

--------------------------------

### List available serial ports

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Enumerates available serial ports and returns a dictionary containing port details. On failure, it logs an error and returns an empty dictionary.

```gdscript
for i in manager.list_ports():
    print(manager.list_ports()[i]["port_name"])
```

--------------------------------

### Iterate over ports from list_ports()

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Iterates over the dictionary returned by list_ports(), printing each port's name, device name, and type. The dictionary is indexed by integer port index, and each value contains port_name, port_type, and device_name keys.

```gdscript
var ports: Dictionary = serial.list_ports()
for i in ports:
    var info: Dictionary = ports[i]
    print(info["port_name"], " - ", info["device_name"], " (", info["port_type"], ")")
```

--------------------------------

### reconfigure_port

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Reconfigures an open port's settings. Applies each setting individually; all settings are attempted even if one fails. Returns true if all settings applied successfully, false otherwise.

```APIDOC
## reconfigure_port

### Description
Reconfigures an open port's settings. Applies each setting individually; all settings are attempted even if one fails. Returns true if all settings applied successfully, false otherwise.

### Method
N/A (GDScript method)

### Endpoint
N/A (GDScript method)

### Parameters
#### Parameters
- **port_name** (String) - Required - Open port to reconfigure
- **baud_rate** (int) - Required - New baud rate
- **data_bits** (int) - Required - 6→Six, 7→Seven, anything else→Eight
- **parity** (int) - Required - 1→Odd, 2→Even, anything else→None
- **stop_bits** (int) - Required - 2→Two, anything else→One
- **flow_control** (int) - Required - 1→Software, 2→Hardware, anything else→None
- **timeout_ms** (int) - Required - New read timeout

### Request Example
```gdscript
# Change speed and parity on a live connection without reopening
manager.reconfigure_port("COM3", 115200, 8, 0, 1, 0, 500)
```

### Response
#### Success Response (bool)
- **bool** - Returns true if all settings applied successfully, false otherwise.

#### Response Example
```gdscript
var ok := manager.reconfigure_port("COM3", 9600, 8, 1, 1, 0, 1000)
if not ok:
    push_error("One or more settings failed to apply — check console logs")
```
```

--------------------------------

### write_string(data: String) -> bool

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Convenience wrapper that converts a string to UTF-8 bytes and delegates to the write method. It has the same return and failure semantics as write, and does not append a newline.

```APIDOC
## write_string(data: String) -> bool

### Description
Convenience wrapper converting the string to UTF-8 and delegating to write. Same return/failure semantics as write (no newline is appended).

### Method
write_string

### Parameters
#### Parameters
- **data** (String) - Required - Text to send as UTF-8 bytes

### Returns
- **bool** - true if write and flush succeed, false otherwise

### Request Example
```gdscript
serial.write_string("Hello Arduino")
```
```

--------------------------------

### Open a serial port connection

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Opens a serial port with specified parameters. Returns true on success and false on failure, such as busy ports or permission issues.

```gdscript
if manager.open("COM3", 9600, 1000):
    print("Opened in RAW mode (default)")
manager.open("COM3", 9600, 1000, GdSerialManager.MODE_LINE_BUFFERED)
manager.open("COM3", 9600, 1000, GdSerialManager.MODE_CUSTOM_DELIMITER)
```

```gdscript
# Error handling: open can fail (busy port, permissions) — never throws
if not manager.open("/dev/ttyUSB0", 115200, 500, GdSerialManager.MODE_RAW):
    push_error("Failed to open port — see Godot console for the OS-level reason")
    return
```

--------------------------------

### Open a serial port using open_buffered

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

A deprecated alias for the open method, kept for backward compatibility.

```gdscript
# Legacy call sites still work:
manager.open_buffered("COM3", 9600, 1000, 1)
```

--------------------------------

### set_delimiter usage

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Switches the port to custom delimiter mode at runtime. Only valid for ports opened with MODE_CUSTOM_DELIMITER.

```gdscript
manager.open("COM3", 9600, 1000, GdSerialManager.MODE_CUSTOM_DELIMITER)
manager.set_delimiter("COM3", 0xFF)   # binary end marker
```

--------------------------------

### reconfigure_port error handling

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Checks the return value of reconfigure_port to verify if settings were applied successfully.

```gdscript
var ok := manager.reconfigure_port("COM3", 9600, 8, 1, 1, 0, 1000)
if not ok:
    push_error("One or more settings failed to apply — check console logs")
```

--------------------------------

### set_port(port_name: String)

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Stores the port name to be used on the next open() call. No validation is performed; an invalid name fails at open().

```APIDOC
## set_port(port_name: String)

### Description
Stores the port name; takes effect on the next open() call. No validation is performed — an invalid name fails at open().

### Method
GDScript function

### Endpoint
set_port(port_name)

### Parameters
#### Parameters
- **port_name** (String) - Required - OS port name, e.g. "COM3" (Windows), "/dev/ttyUSB0" (Linux), "/dev/tty.usbserial-*" (macOS)

### Request Example
```gdscript
serial.set_port("COM3")
```

### Response
No return value.
```

--------------------------------

### Handle empty result from list_ports()

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Checks if list_ports() returned an empty dictionary, which indicates either no ports found or an enumeration failure. In that case, a warning is pushed to the Godot console.

```gdscript
# Error handling: enumeration failure yields an empty dict, never a crash
var ports: Dictionary = serial.list_ports()
if ports.is_empty():
    push_warning("No ports found or enumeration failed — see Godot console")
```

--------------------------------

### GdSerialManager - Async Binary Modes

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Opens a serial port in raw or custom-delimiter mode for async binary protocols. Raw mode emits all chunks immediately; custom-delimiter mode waits for a delimiter byte set via set_delimiter.

```gdscript
manager.open("COM3", 9600, 1000)  # MODE_RAW (default): emit all chunks immediately
# or
manager.open("COM3", 9600, 1000, GdSerialManager.MODE_CUSTOM_DELIMITER)  # wait for delimiter byte
manager.set_delimiter("COM3", 0xFF)  # Set custom end marker
```

--------------------------------

### GdSerialManager.write

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Writes raw bytes to a specific open port.

```APIDOC
## [POST] GdSerialManager.write

### Description
Writes the provided PackedByteArray to the specified port. Returns true on success.

### Method
POST

### Endpoint
GdSerialManager.write

### Parameters
#### Path Parameters
- **name** (String) - Required - The port name.
- **data** (PackedByteArray) - Required - The raw bytes to write.

### Request Example
GdSerialManager.write("COM3", PackedByteArray([72, 105]))

### Response
#### Success Response (200)
- **bool** - True if write succeeded, false otherwise.

#### Response Example
true
```

--------------------------------

### Read bytes with read

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Reads up to 10 bytes non-blocking; returns what is available immediately.

```gdscript
var response := serial.read(10)   # non-blocking; returns what's available now
```

--------------------------------

### read_string(size: int) -> String

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Reads up to the specified number of bytes and decodes them as UTF-8. Returns an empty String on invalid UTF-8 or if the underlying read fails.

```APIDOC
## read_string(size: int) -> String

### Description
Calls read(size) and decodes as UTF-8. On invalid UTF-8 logs "Failed to convert bytes to string: {}" and returns an empty String.

### Method
read_string

### Parameters
#### Parameters
- **size** (int) - Required - Maximum number of bytes to read

### Returns
- **String** - Decoded UTF-8 string; empty String on invalid UTF-8 or read failure

### Request Example
```gdscript
if serial.bytes_available() > 0:
    print("Received: ", serial.read_string(100))
```
```

--------------------------------

### Read line with timeout handling

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Sets a 2-second timeout and reads a line; if the timeout occurs mid-line, the partial line is returned instead of failing.

```gdscript
# Timeout mid-line returns the partial line instead of failing
serial.set_timeout(2000)
var line := serial.readline()
if line.is_empty():
    print("No line received within timeout")
else:
    print("Got (possibly partial): ", line)
```

--------------------------------

### Handle write failure

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Checks the return value of write and pushes an error if it fails. The port state is already cleaned up on disconnection, so the user can be prompted to reconnect.

```gdscript
if not serial.write(PackedByteArray([0xDE, 0xAD])):
    push_error("Write failed — device may have been unplugged")
    # state is already cleaned up; prompt the user to reconnect
```

--------------------------------

### GdSerial.write

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Writes raw bytes to the serial port. Returns true on success.

```APIDOC
## [POST] GdSerial.write

### Description
Writes a PackedByteArray of raw bytes to the serial port. Returns true if write succeeded.

### Method
POST

### Endpoint
GdSerial.write

### Parameters
#### Path Parameters
- **data** (PackedByteArray) - Required - The raw bytes to write.

### Request Example
GdSerial.write(PackedByteArray([72, 105]))

### Response
#### Success Response (200)
- **bool** - True if the write succeeded, false otherwise.

#### Response Example
true
```

--------------------------------

### GdSerialManager.is_open

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Checks if a specific port is open.

```APIDOC
## [GET] GdSerialManager.is_open

### Description
Returns whether the given port is currently open.

### Method
GET

### Endpoint
GdSerialManager.is_open

### Parameters
#### Path Parameters
- **name** (String) - Required - The port name to check.

### Request Example
GdSerialManager.is_open("COM3")

### Response
#### Success Response (200)
- **bool** - True if the port is open, false otherwise.

#### Response Example
true
```

--------------------------------

### set_parity(parity: int)

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Sets the parity mode. Valid values are 0 (None), 1 (Odd), 2 (Even). Any other value silently maps to Parity::None.

```APIDOC
## set_parity(parity: int)

### Description
Sets the parity mode. Valid values are 0 (None), 1 (Odd), 2 (Even). Any other value silently maps to Parity::None.

### Method
GDScript function

### Endpoint
set_parity(parity)

### Parameters
#### Parameters
- **parity** (int) - Required - 0→None, 1→Odd, 2→Even. Default is 0.

### Request Example
```gdscript
serial.set_parity(0)
```

### Response
No return value.
```

--------------------------------

### GdSerial.is_open

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Checks if the port is open with an active connection test.

```APIDOC
## [GET] GdSerial.is_open

### Description
Returns whether the port is currently open, performing an active connection test.

### Method
GET

### Endpoint
GdSerial.is_open

### Parameters
None

### Response
#### Success Response (200)
- **bool** - True if open and connection test passes, false otherwise.

#### Response Example
true
```

--------------------------------

### close() -> void

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Closes the serial port by dropping the port handle and setting is_connected to false. Safe to call multiple times or when already closed.

```APIDOC
## close() -> void

### Description
Drops the port handle (`self.port = None`) and sets `is_connected = false`. Safe to call multiple times or when already closed — the `if self.port.is_some()` guard makes it a no-op otherwise.

### Method
close

### Parameters
None

### Returns
None

### Example
```gdscript
serial.close()
```
```

--------------------------------

### Handle serial errors with bool checks, is_open(), and manager signals

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/errors.md

Shows three error-handling patterns for the GdSerial library: checking boolean returns from open() and write(), detecting disconnection with is_open() and reconnecting, and handling disconnection signals in GdSerialManager. After a detected disconnection, both classes clear their port handle, so is_open() returns false and open() can be called again immediately. GdSerial.read/readline never throw on timeout; they return empty/partial data, so polling loops are safe. GdSerialManager never blocks the Godot thread; all hardware errors surface later via poll_events() in _process.

```gdscript
# 1. Check bool returns
if not serial.open():
    return
if not serial.write(data):
    return

# 2. Detect disconnection on the simple API — is_open() self-heals state
if not serial.is_open():
    # port handle cleared; reconnect flow
    if serial.open():
        serial.writeline("PING")

# 3. Manager async path — signal-driven
func _on_disconnect(port: String) -> void:
    # port was auto-closed; open(port, ...) again to reconnect
    manager.open(port, 9600, 1000)
```

--------------------------------

### write_string method signature

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Signature for the write_string method. Converts the string to UTF-8 and delegates to write; same return/failure semantics as write, no newline appended.

```rust
#[func]
pub fn write_string(&mut self, data: GString) -> bool
```

--------------------------------

### Constants (Buffering Modes)

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial-manager.md

Constants that define the buffering behavior for serial data reception. Used as the optional mode argument in open() and open_buffered().

```APIDOC
## Constants (Buffering Modes)

### Description
These constants define how incoming serial data is buffered and emitted. They are used as the optional `mode` argument in `open()` / `open_buffered()`.

### Constants
- **MODE_RAW** (i64) - Value: 0 - Emit every data chunk immediately as it arrives (default).
- **MODE_LINE_BUFFERED** (i64) - Value: 1 - Buffer until `\n` (0x0A), then emit the complete line (newline included).
- **MODE_CUSTOM_DELIMITER** (i64) - Value: 2 - Buffer until a custom delimiter byte; default delimiter `\n` (0x0A), changeable via `set_delimiter`.

### Usage Example
```gdscript
manager.open("COM3", 9600, 1000, GdSerialManager.MODE_LINE_BUFFERED)
```
```

--------------------------------

### Linux - Add User to dialout Group

Source: https://github.com/sujithchristopher/gdserial/blob/main/README.md

Adds the current user to the dialout group on Linux to grant access to serial ports.

```bash
sudo usermod -a -G dialout $USER
```

--------------------------------

### Read line with readline

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Reads a line and prints it if non-empty.

```gdscript
var cmd := serial.readline()
if cmd != "":
    print("Command: ", cmd)
```

--------------------------------

### Port info dictionary structure

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/types.md

The structure returned by GdSerial.list_ports() and GdSerialManager.list_ports(). Keys are integer indices and the dictionary is unordered.

```gdscript
{
  0: {
    "port_name": "COM3",              # String
    "port_type": "USB - VID: 2341, PID: 0043",  # String
    "device_name": "Arduino Uno"      # String
  },
  1: { ... }
}
```

--------------------------------

### write method signature

Source: https://github.com/sujithchristopher/gdserial/blob/main/_autodocs/api-reference/gdserial.md

Signature for the write method. Returns true after write_all and flush succeed; returns false on connection test failure, missing port handle, write/flush errors, or a poisoned mutex, logging the corresponding error message.

```rust
#[func]
pub fn write(&mut self, data: PackedByteArray) -> bool
```
Tokens:
Raw