Lib.rs

› 硬件支持
#serial #hardware #hardware-devices #rs232 #system #hardware-interface #async-io

serialport

跨平台低级串行端口库

由 Bryant Mairs，Jesse Braham，Christian Meusel 以及 53 位贡献者 共同开发

26个版本 (17个稳定版)

4.5.0 2024年8月5日
4.4.0 2024年6月27日
4.3.0 2023年12月12日
4.2.2 2023年8月5日
0.1.1 2016年12月24日

#2 在 硬件支持

Download history 32845/week @ 2024-05-03 36508/week @ 2024-05-10 36966/week @ 2024-05-17 34352/week @ 2024-05-24 35670/week @ 2024-05-31 33882/week @ 2024-06-07 35667/week @ 2024-06-14 36704/week @ 2024-06-21 35061/week @ 2024-06-28 38882/week @ 2024-07-05 37541/week @ 2024-07-12 43084/week @ 2024-07-19 40069/week @ 2024-07-26 41857/week @ 2024-08-02 44562/week @ 2024-08-09 33229/week @ 2024-08-16

每月167,902次 下载
用于 326 个crate（直接使用195个）

MPL-2.0 许可证

170KB
3.5K 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 特性暴露了跨平台的串行端口功能。该库旨在使 API 尽可能简单，以鼓励默认情况下进行跨平台开发。因此建议使用由此产生的 Box<dyn SerialPort> 类型。要公开额外的平台特定功能，请直接使用平台特定结构体：TTYPort 用于 POSIX 系统，COMPort 用于 Windows。

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

$ cargo build --no-default-features

还应注意的是，在macOS上，呼叫（/dev/cu.*）和拨入端口（/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 Public License，版本2.0许可。

贡献

请在GitHub上打开一个问题或拉取请求来贡献。根据MPL2.0许可，您提交的代码贡献应作为上述内容进行许可，不附加任何额外条款或条件。

致谢

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

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

依赖关系

~1.5–2.1MB
~42K SLoC