Repository files navigation

serialport-rs is a general-purpose cross-platform serial port library for Rust. It provides ablocking I/O interface and port enumeration on POSIX and Windows systems.

For async I/O functionality, see themio-serial andtokio-serial crates.

Join the discussion on Matrix!#serialport-rs:matrix.org

This project is looking for maintainers! Especially for Windows. If you are interested please letus know on Matrix, or bycreating adiscussion.

The library exposes cross-platform serial port functionality through theSerialPort trait. Thislibrary is structured to make this the simplest API to use to encourage cross-platform developmentby default. Working with the resultantBox<dyn SerialPort> type is therefore recommended. Toexpose additional platform-specific functionality use the platform-specific structs directly:TTYPort for POSIX systems andCOMPort for Windows.

Serial enumeration is provided on most platforms. The implementation on Linux usingglibc reliesonlibudev (unless you disable the defaultlibudev feature), an external dynamic library thatwill need to be available on the system the final binary is running on. Enumeration will still beavailable if this feature is disabled, but won't expose as much information and may return portsthat don't exist physically. However this dependency can be removed by disabling the defaultlibudev feature:

$ 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 = serialport::available_ports().expect("No ports found!");for pin ports{println!("{}", p.port_name);}

Opening and configuring a port:

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

Writing to a port:

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

Reading from a port (default is blocking with a 0ms timeout):

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

Some platforms expose additional functionality, which is opened using theopen_native() method:

let port = serialport::new("/dev/ttyUSB0",115_200).open_native().expect("Failed to open port");

Closing a port:

serialport-rs uses the Resource Acquisition Is Initialization (RAII) paradigm and so closing aport is done when theSerialPort object isDroped either implicitly or explicitly usingstd::mem::drop (std::mem::drop(port)).

There are several included examples, which help demonstrate the functionality of this library andcan 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 connectedto 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 fordebugging.

Rust versions 1.59.0 and higher are supported by the library itself. There areexamples requiring newer versions of Rust.

For GNU/Linuxpkg-config headers are required:

• Ubuntu:sudo apt install pkg-config
• Fedora:sudo dnf install pkgconf-pkg-config

For other distros they may providepkg-config through thepkgconf package instead.

For GNU/Linuxlibudev headers are required as well (unless you disable the defaultlibudevfeature):

• Ubuntu:sudo apt install libudev-dev
• Fedora:sudo dnf install systemd-devel

Builds and some tests (not requiring actual hardware) for major targets are runin CI. Failures of either block the inclusion of new code. This library shouldbe compatible with additional targets not listed below, but no guarantees aremade. Additional platforms may be added in the future if there is a need and/ordemand.

• Android
  • arm-linux-androideabi (no serial enumeration)
  • armv7-linux-androideabi (no serial enumeration)
• FreeBSD
  • x86_64-unknown-freebsd
• Linux
  • aarch64-unknown-linux-gnu
  • aarch64-unknown-linux-musl
  • i686-unknown-linux-gnu
  • i686-unknown-linux-musl
  • x86_64-unknown-linux-gnu
  • x86_64-unknown-linux-musl
• macOS/iOS
  • aarch64-apple-darwin
  • aarch64-apple-ios
  • x86_64-apple-darwin
• NetBSD
  • x86_64-unknown-netbsd (no serial enumeration)
• Windows
  • i686-pc-windows-msvc
  • x86_64-pc-windows-gnu
  • x86_64-pc-windows-msvc

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 thehardware_check example providedwith this library. It will test the driver to confirm that all possible settings are supported for aport. Additionally, it will test that data transmission is correct for those settings if you havetwo ports physically configured to communicate. If you experience problems with your devices, pleasefile a bug and identify the hardware, OS, and driver in use.

Known issues:

Licensed under theMozilla Public License, version 2.0.

Please open an issue or pull request on GitHub to contribute. Code contributions submitted forinclusion in the work by you, as defined in the MPL2.0 license, shall be licensed as the abovewithout any additional terms or conditions.

This is the continuation of the development athttps://gitlab.com/susurrus/serialport-rs. Thanksto susurrus and all other contributors to the original project on GitLab.

Special thanks to dcuddeback, willem66745, and apoloval who wrote the original serial-rs librarywhich this library heavily borrows from.