Note: This is a fork of the original serialport-rs project on GitLab. Please note there have been some changes to both the supported targets and which tier some targets are in, and there may be further changes to this made. Additionally, all relevant issues have been migrated to this repository.
Join the discussion on Matrix! #serialport-rs:matrix.org
This project is looking for maintainers! If you are interested please let us know on Matrix, or by creating a discussion.
serialport-rs is a general-purpose cross-platform serial port library for Rust. It provides a
blocking I/O interface and port enumeration on POSIX and Windows systems.
The library exposes cross-platform serial port functionality through the
SerialPort trait. This
library is structured to make this the simplest API to use to encourage cross-platform development
by default. Working with the resultant
Box<dyn SerialPort> type is therefore recommended. To
expose additional platform-specific functionality use the platform-specific structs directly:
TTYPort for POSIX systems and
COMPort for Windows.
Serial enumeration is provided on most platforms. The implementation on Linux using
libudev, an external dynamic library that will need to be available on the system the final
binary is running on. Enumeration will still be available if this feature is disabled, but won't
expose as much information and may return ports that don't exist physically. However this dependency
can be removed by disabling the default
$ cargo build --no-default-features
It should also be noted that on macOS, both the Callout (
/dev/cu.*) and Dial-in ports
/dev/tty.*) ports are enumerated, resulting in two available ports per connected serial device.
Listing available ports:
let ports = available_ports.expect; for p in ports
Opening and configuring a port:
let port = new .timeout .open.expect;
Writing to a port:
let output = "This is a test. This is only a test.".as_bytes; port.write.expect;
Reading from a port (default is blocking with a 0ms timeout):
let mut serial_buf: = vec!; port.read.expect;
Some platforms expose additional functionality, which is opened using the
let port = new .open_native.expect;
Closing a port:
serialport-rs uses the Resource Acquisition Is Initialization (RAII) paradigm and so closing a
port is done when the
SerialPort object is
Droped either implicitly or explicitly using
There are several included examples, which help demonstrate the functionality of this library and can help debug software or hardware errors.
- clear_input_buffer - Demonstrates querying and clearing the driver input buffer.
- clear_output_buffer - Demonstrates querying and clearing the driver output buffer.
- duplex - Tests that a port can be successfully cloned.
- hardware_check - Checks port/driver functionality for a single port or a pair of ports connected to each other.
- list_ports - Lists available serial ports.
- pseudo_terminal - Unix only. Tests that a pseudo-terminal pair can be created.
- receive_data - Output data received on a port.
- transmit - Transmits data regularly on a port with various port configurations. Useful for debugging.
Rust versions 1.56.1 and higher are supported.
pkg-config headers are required:
sudo apt install pkg-config
sudo dnf install pkgconf-pkg-config
For other distros they may provide
pkg-config through the
pkgconf package instead.
libudev headers are required as well (unless you disable the default
sudo apt install libudev-dev
sudo dnf install systemd-devel
Builds and tests for all supported targets are run in CI. Failures of either block the inclusion of new code. This library should be compatible with additional targets not listed below, but no guarantees are made. Additional platforms may be added in the future if there is a need and/or demand.
arm-linux-androideabi(no serial enumeration)
armv7-linux-androideabi(no serial enumeration)
x86_64-unknown-netbsd(no serial enumeration)
This library has been developed to support all serial port devices across all supported platforms.
To determine how well your platform is supported, please run the
hardware_check example provided
with this library. It will test the driver to confirm that all possible settings are supported for a
port. Additionally, it will test that data transmission is correct for those settings if you have
two ports physically configured to communicate. If you experience problems with your devices, please
file a bug and identify the hardware, OS, and driver in use.
|FTDI TTL-232R||Linux||ftdi_sio, Linux 4.14.11||Hardware doesn't support 5 or 6 data bits, but the driver lies about supporting 5.|
Licensed under the Mozilla Public License, version 2.0.
Please open an issue or pull request on GitHub to contribute. Code contributions submitted for inclusion in the work by you, as defined in the MPL2.0 license, shall be licensed as the above without any additional terms or conditions.
Special thanks to dcuddeback, willem66745, and apoloval who wrote the original serial-rs library which this library heavily borrows from.
Additional thanks to susurrus and all other contributors to the original serialport-rs project on GitLab.