1[](https://crates.io/crates/serialport) 2[](https://docs.rs/serialport) 3[](https://github.com/serialport/serialport-rs/actions) 4[](https://blog.rust-lang.org/2022/02/24/Rust-1.59.0.html) 5 6# Introduction 7 8`serialport-rs` is a general-purpose cross-platform serial port library for Rust. It provides a 9blocking I/O interface and port enumeration on POSIX and Windows systems. 10 11For async I/O functionality, see the [mio-serial](https://github.com/berkowski/mio-serial) and 12[tokio-serial](https://github.com/berkowski/tokio-serial) crates. 13 14Join the discussion on Matrix! 15[#serialport-rs:matrix.org](https://matrix.to/#/#serialport-rs:matrix.org) 16 17**This project is looking for maintainers! Especially for Windows. If you are interested please let 18us know on Matrix, or by [creating a 19discussion](https://github.com/serialport/serialport-rs/discussions/new).** 20 21# Overview 22 23The library exposes cross-platform serial port functionality through the `SerialPort` trait. This 24library is structured to make this the simplest API to use to encourage cross-platform development 25by default. Working with the resultant `Box<dyn SerialPort>` type is therefore recommended. To 26expose additional platform-specific functionality use the platform-specific structs directly: 27`TTYPort` for POSIX systems and `COMPort` for Windows. 28 29Serial enumeration is provided on most platforms. The implementation on Linux using `glibc` relies 30on `libudev` (unless you disable the default `libudev` feature), an external dynamic library that 31will need to be available on the system the final binary is running on. Enumeration will still be 32available if this feature is disabled, but won't expose as much information and may return ports 33that don't exist physically. However this dependency can be removed by disabling the default 34`libudev` feature: 35 36```shell 37$ cargo build --no-default-features 38``` 39 40It should also be noted that on macOS, both the Callout (`/dev/cu.*`) and Dial-in ports 41(`/dev/tty.*`) ports are enumerated, resulting in two available ports per connected serial device. 42 43# Usage 44 45Listing available ports: 46 47```rust 48let ports = serialport::available_ports().expect("No ports found!"); 49for p in ports { 50 println!("{}", p.port_name); 51} 52 53``` 54 55Opening and configuring a port: 56 57```rust 58let port = serialport::new("/dev/ttyUSB0", 115_200) 59 .timeout(Duration::from_millis(10)) 60 .open().expect("Failed to open port"); 61``` 62 63Writing to a port: 64 65```rust 66let output = "This is a test. This is only a test.".as_bytes(); 67port.write(output).expect("Write failed!"); 68``` 69 70Reading from a port (default is blocking with a 0ms timeout): 71 72```rust 73let mut serial_buf: Vec<u8> = vec![0; 32]; 74port.read(serial_buf.as_mut_slice()).expect("Found no data!"); 75``` 76 77Some platforms expose additional functionality, which is opened using the `open_native()` method: 78 79```rust 80let port = serialport::new("/dev/ttyUSB0", 115_200) 81 .open_native().expect("Failed to open port"); 82``` 83 84Closing a port: 85 86`serialport-rs` uses the Resource Acquisition Is Initialization (RAII) paradigm and so closing a 87port is done when the `SerialPort` object is `Drop`ed either implicitly or explicitly using 88`std::mem::drop` (`std::mem::drop(port)`). 89 90# Examples 91 92There are several included examples, which help demonstrate the functionality of this library and 93can help debug software or hardware errors. 94 95- _clear_input_buffer_ - Demonstrates querying and clearing the driver input buffer. 96- _clear_output_buffer_ - Demonstrates querying and clearing the driver output buffer. 97- _duplex_ - Tests that a port can be successfully cloned. 98- _hardware_check_ - Checks port/driver functionality for a single port or a pair of ports connected 99 to each other. 100- _list_ports_ - Lists available serial ports. 101- _pseudo_terminal_ - Unix only. Tests that a pseudo-terminal pair can be created. 102- _receive_data_ - Output data received on a port. 103- _transmit_ - Transmits data regularly on a port with various port configurations. Useful for 104 debugging. 105 106# Dependencies 107 108Rust versions 1.59.0 and higher are supported by the library itself. There are 109examples requiring newer versions of Rust. 110 111For GNU/Linux `pkg-config` headers are required: 112 113- Ubuntu: `sudo apt install pkg-config` 114- Fedora: `sudo dnf install pkgconf-pkg-config` 115 116For other distros they may provide `pkg-config` through the `pkgconf` package instead. 117 118For GNU/Linux `libudev` headers are required as well (unless you disable the default `libudev` 119feature): 120 121- Ubuntu: `sudo apt install libudev-dev` 122- Fedora: `sudo dnf install systemd-devel` 123 124# Platform Support 125 126Builds and some tests (not requiring actual hardware) for major targets are run 127in CI. Failures of either block the inclusion of new code. This library should 128be compatible with additional targets not listed below, but no guarantees are 129made. Additional platforms may be added in the future if there is a need and/or 130demand. 131 132- Android 133 - `arm-linux-androideabi` (no serial enumeration) 134 - `armv7-linux-androideabi` (no serial enumeration) 135- FreeBSD 136 - `x86_64-unknown-freebsd` 137- Linux 138 - `aarch64-unknown-linux-gnu` 139 - `aarch64-unknown-linux-musl` 140 - `i686-unknown-linux-gnu` 141 - `i686-unknown-linux-musl` 142 - `x86_64-unknown-linux-gnu` 143 - `x86_64-unknown-linux-musl` 144- macOS/iOS 145 - `aarch64-apple-darwin` 146 - `aarch64-apple-ios` 147 - `x86_64-apple-darwin` 148- NetBSD 149 - `x86_64-unknown-netbsd` (no serial enumeration) 150- Windows 151 - `i686-pc-windows-gnu` 152 - `i686-pc-windows-msvc` 153 - `x86_64-pc-windows-gnu` 154 - `x86_64-pc-windows-msvc` 155 156# Hardware Support 157 158This library has been developed to support all serial port devices across all supported platforms. 159To determine how well your platform is supported, please run the `hardware_check` example provided 160with this library. It will test the driver to confirm that all possible settings are supported for a 161port. Additionally, it will test that data transmission is correct for those settings if you have 162two ports physically configured to communicate. If you experience problems with your devices, please 163file a bug and identify the hardware, OS, and driver in use. 164 165Known issues: 166 167| Hardware | OS | Driver | Issues | 168| ------------- | ----- | ----------------------- | ---------------------------------------------------------------------------------- | 169| 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. | 170 171# Licensing 172 173Licensed under the [Mozilla Public License, version 2.0](https://www.mozilla.org/en-US/MPL/2.0/). 174 175# Contributing 176 177Please open an issue or pull request on GitHub to contribute. Code contributions submitted for 178inclusion in the work by you, as defined in the MPL2.0 license, shall be licensed as the above 179without any additional terms or conditions. 180 181# Acknowledgments 182 183This is the continuation of the development at <https://gitlab.com/susurrus/serialport-rs>. Thanks 184to susurrus and all other contributors to the original project on GitLab. 185 186Special thanks to dcuddeback, willem66745, and apoloval who wrote the original serial-rs library 187which this library heavily borrows from. 188
){kind=link}
){kind=link}