Lib.rs

› 硬件支持 › SerialPort
#串口 #串行 #硬件 #系统 #硬件接口 #USB设备

serialport-fix-stop-bits

一个跨平台的底层串口库

由 Bryant Mairs，Jesse Braham 以及 54 位贡献者 贡献。 由 robdobsn 拥有。

1 个稳定版本

4.3.0 2024年6月12日

#129 在 硬件支持


在 raftcli 中使用

MPL-2.0 许可证

155KB
3K SLoC

crates.io version badge Documentation GitHub workflow status Minimum Stable Rust Version

简介

serialport-rs 是一个通用的跨平台串口库，用于 Rust。它为 POSIX 和 Windows 系统提供了阻塞 I/O 接口和端口枚举。

有关异步 I/O 功能，请参阅 mio-serial 和 tokio-serial crate。

加入 Matrix 上的讨论！ #serialport-rs:matrix.org

该项目正在寻找维护者！尤其是 Windows 方面的维护者。如果您对此感兴趣，请在 Matrix 上告知我们，或者通过 创建讨论。

概述

该库通过 SerialPort trait 暴露了跨平台的串口功能。该库旨在使 API 尽可能简单，以鼓励默认情况下进行跨平台开发。因此，建议使用结果的 Box<dyn SerialPort> 类型。要公开额外的平台特定功能，请直接使用平台特定的结构：POSIX 系统上的 TTYPort 和 Windows 上的 COMPort。

大多数平台上都提供了串口枚举。Linux 上的实现使用 glibc，依赖于外部动态库 libudev，该库需要在最终二进制文件运行的系统上可用。即使禁用了此功能，枚举仍然可用，但不会公开太多信息，并可能返回不存在的物理端口。但是，可以通过禁用默认的 libudev 功能来删除此依赖项。

$ cargo build --no-default-features

还应注意的是，在 macOS 上，Callout (/dev/cu.*) 和 Dial-in 端口 (/dev/tty.*) 都会枚举，导致每个连接的串行设备有可用两个端口。

用法

列出可用端口

let ports = serialport::available_ports().expect("No ports found!");
for p in ports {
    println!("{}", p.port_name);
}

打开和配置端口

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

向端口写入

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

从端口读取（默认为带有0ms超时的阻塞模式）

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

某些平台公开了其他功能，这些功能可以通过open_native()方法打开

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

关闭端口

serialport-rs使用资源获取初始化（RAII）范例，因此关闭端口发生在SerialPort对象被隐式或显式使用std::mem::drop（std::mem::drop(port)）释放时。

示例

包含了一些示例，这些示例有助于演示该库的功能，并可以帮助调试软件或硬件错误。

  • clear_input_buffer - 展示查询和清除驱动器输入缓冲区。
  • clear_output_buffer - 展示查询和清除驱动器输出缓冲区。
  • duplex - 测试端口是否可以成功克隆。
  • hardware_check - 检查单个端口或连接到彼此的端口对的功能。
  • list_ports - 列出可用的串行端口。
  • pseudo_terminal - 仅限Unix。测试是否可以创建伪终端对。
  • receive_data - 输出端口接收到的数据。
  • transmit - 在具有不同端口配置的端口上定期传输数据。对调试很有用。

依赖关系

该库本身支持Rust版本1.59.0及更高版本。有一些示例需要Rust的新版本。

对于GNU/Linux，需要pkg-config头文件

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

对于其他发行版，它们可能通过pkgconf包提供pkg-config。

对于GNU/Linux，还需要libudev头文件（除非您禁用了默认的libudev功能）

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

平台支持

CI中运行了针对主要目标的构建和一些测试（不需要实际硬件）。任一失败的测试将阻止新代码的包含。此库应该与以下未列出的其他目标兼容，但不提供保证。如有需要和/或需求，将来可能会添加更多平台。

  • Android
    • arm-linux-androideabi（无串行枚举）
    • armv7-linux-androideabi（无串行枚举）
  • 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（无串行枚举）
  • Windows
    • i686-pc-windows-gnu
    • i686-pc-windows-msvc
    • x86_64-pc-windows-gnu
    • x86_64-pc-windows-msvc

硬件支持

此库的开发是为了支持所有平台上的所有串行端口设备。要确定您的平台支持程度，请运行此库提供的 hardware_check 示例。它将测试驱动程序以确认端口支持所有可能的设置。此外，如果您有两个物理配置为通信的端口，它还将测试这些设置下的数据传输是否正确。如果您在设备上遇到问题，请提交一个错误报告，并识别所使用的硬件、操作系统和驱动程序。

已知问题

硬件 操作系统 驱动程序 问题
FTDI TTL-232R Linux ftdi_sio, Linux 4.14.11 硬件不支持5或6个数据位，但驱动程序谎称支持5。

许可

根据 Mozilla公共许可证，版本2.0 许可。

贡献

请在GitHub上提交一个问题或拉取请求以进行贡献。您提交的代码贡献，根据MPL2.0许可证定义，应按照上述内容许可，无需附加条款或条件。

致谢

这是在 https://gitlab.com/susurrus/serialport-rs 上的开发延续。感谢susurrus以及所有在GitLab上对原始项目做出贡献的其他人员。

特别感谢dcuddeback、willem66745和apoloval，他们编写了原始的serial-rs库，本库大量借鉴了该库。

依赖关系

~1.5–2.6MB
~51K SLoC