serialport-rs

The library uses the RAII (Resource Acquisition Is Initialization) paradigm. A port is automatically closed when the SerialPort object is dropped. You can close it implicitly by letting it go out of scope or explicitly using std::mem::drop(port).

std::mem::drop(port);

On macOS and iOS, the serialport library supports non-standard baud rates by utilizing the iossiospeed ioctl. This is necessary because the standard POSIX termios implementation does not support custom baud rates directly in the termios struct.

Implementation Detail: To ensure compatibility, the library follows these behaviors:

1. It uses iossiospeed for all baud rate settings.
2. Whenever the termios struct is written back (via tcsetattr), a call to iossiospeed follows it to re-apply the desired baud rate.
3. The termios struct is not cached; it is retrieved from the kernel on every settings adjustment to ensure the kernel's state remains the canonical source.

The library provides a cross-platform interface via the SerialPort trait.

• Recommended approach: Work with Box<dyn SerialPort>. This ensures your code remains cross-platform by default.
• Platform-specific approach: If you need features unique to an OS, use the specific structs directly: TTYPort for POSIX systems and COMPort for Windows.
• Async I/O: This crate provides blocking I/O. For asynchronous functionality, use mio-serial or tokio-serial instead.

To build serialport-rs on GNU/Linux, you need pkg-config and libudev headers.

Ubuntu:

sudo apt install pkg-config libudev-dev

Fedora:

sudo dnf install pkgconf-pkg-config systemd-devel

On Linux, the default enumeration implementation relies on libudev. If you want to remove this dependency (at the cost of less detailed enumeration information), build with:

cargo build --no-default-features

On macOS and iOS, setting arbitrary baud rates is more complex than on other platforms due to driver dependencies. The system uses the IOSSIOSPEED ioctl.

To ensure the baud rate is applied correctly, you must follow these requirements:

1. The port must be set into raw mode using cfmakeraw.
2. The baud rate must be set after every call to tcsetattr, because tcsetattr will reset the baud rate to its previous value.
3. Note that there is no OS-level mechanism to retrieve the currently active baud rate on these platforms.

The preferred way to access a serial port is using the serialport::new(path, baud_rate) function, which returns a SerialPortBuilder. You can chain configuration methods to set up the port before calling .open().

serialport::new("/dev/ttyUSB0", 9600)
    .data_bits(DataBits::Eight)
    .parity(Parity::None)
    .stop_bits(StopBits::One)
    .timeout(Duration::from_millis(10))
    .open()
    .expect("Failed to open port");

serialport::new("/dev/ttyUSB0", 9600).open().expect("Failed to open port");

Use the serialport::new(path, baud_rate) builder pattern to configure and open a port.

Key configuration methods:

• .timeout(Duration): Sets the I/O timeout.
• .dtr_on_open(bool): Automatically sets the DTR (Data Terminal Ready) signal when opening the port.
• .open(): Opens the port as a Box<dyn SerialPort> (recommended for cross-platform use).
• .open_native(): Opens the port using platform-specific structs (TTYPort on POSIX, COMPort on Windows) to expose additional platform-specific functionality.

let port = serialport::new("/dev/ttyUSB0", 115_200)
    .timeout(Duration::from_millis(10))
    .dtr_on_open(true)
    .open()
    .expect("Failed to open port");

The SerialPort trait provides blocking I/O methods. The port operates in blocking mode with a default timeout of 0 ms unless configured otherwise.

• Writing: Use .write(bytes) to send data.
• Reading: Use .read(&mut [u8]) to read data into a buffer.

// Writing
let output = "This is a test. This is only a test.".as_bytes();
port.write(output).expect("Write failed!");

// Reading
let mut serial_buf: Vec<u8> = vec![0; 32];
port.read(serial_buf.as_mut_slice()).expect("Found no data!");