serialport-rs is a general-purpose cross-platform serial port library for Rust. It provides a
simple blocking I/O interface and port enumeration on POSIX and Windows systems.
The canonical repository for this crate is on GitLab, but it is mirrored on GitHub purely for testing via Travis CI. To report any issues or contribute code, please do so using through the GitLab repository.
The library has been organized such that there is a high-level
SerialPort trait that provides
a cross-platform API for accessing serial ports. This is the preferred method of interacting
with ports and as such is part of the
in the root are also cross-platform.
For platform-specific functionality, this crate is split into a
windows API with
COMPort structs, both of which implement the
SerialPort trait. Using
open*() functions will return the platform-specific port object which
allows access to platform-specific functionality.
Serial enumeration on Linux is provided by
libudev, an external dynamic library that
is linked against. This dependency can be removed by disabling the
There are several included examples, which both demonstrate the functionality of this library and serve to 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.
- heartbeat - Transmits data regularly on a port.
- list_ports - Lists available serial ports.
- pseudo_terminal - Unix only. Tests that a pseudo-terminal pair can be created.
- receive_data - Print data received on a port.
Rust versions 1.31.1 and higher are supported.
For GNU Linux
libudev headers are required (
libudev-dev on Ubuntu respectively).
Platform support is broken into three tiers:
- Tier 1 - Builds and tests for this target are run in CI. Failures of either block the inclusion of new code.
- Tier 2 - Builds for this target are run in CI. Failures during the build blocks the inclusion of new code. Tests may be run, but failures in tests don't block the inclusion of new code.
- Tier 3 - Builds for this target are run in CI. Failures during the build do not block the inclusion of new code. Testing may be run, but failures in tests don't block the inclusion of new code.
This library has been developed to support all serial port devices across all
supported platforms. To determine how well your platform is supported, please
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 merge request on GitLab to contibute. 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.