简介

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

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

此 crate 的规范仓库位于 GitLab 上，但它是通过 Travis CI 进行测试的 GitHub 上的镜像。如需报告问题或贡献代码，请通过 GitLab 进行。

概述

该库通过 SerialPort 特性暴露跨平台的串口功能。该库旨在使 API 使用起来尽可能简单，以鼓励默认的跨平台开发。因此，建议使用派生的 Box<dyn SerialPort> 类型。为了暴露附加的平台特定功能，直接使用平台特定的结构：POSIX 系统上的 TTYPort 和 Windows 上的 COMPort。

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

$ cargo build --no-default-features

使用方法

列出可用端口

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 对象被 Drop（显式或隐式地使用 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.36.0 及更高版本。

对于 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 中运行针对此目标构建和测试。任一失败都会阻止新代码的加入。
• 第二级 - 在 CI 中运行针对此目标的构建。CI 中不运行测试。

第一级

• Linux
  • i586-unknown-linux-musl
  • i686-unknown-linux-gnu
  • i686-unknown-linux-musl
  • x86_64-unknown-linux-gnu
  • x86_64-unknown-linux-musl
• MacOS/iOS
  • x86_64-apple-darwin
• Windows
  • i686-pc-windows-gnu
  • i686-pc-windows-msvc
  • x86_64-pc-windows-gnu
  • x86_64-pc-windows-msvc

第二级

• Android
  • aarch64-linux-android（无串行枚举）
  • arm-linux-androideabi（无串行枚举）
  • armv7-linux-androideabi（无串行枚举）
  • i686-linux-android（无串行枚举）
  • x86_64-linux-android（无串行枚举）
• FreeBSD
  • i686-unknown-freebsd
  • x86_64-unknown-freebsd
• Linux
  • aarch64-unknown-linux-gnu
  • aarch64-unknown-linux-musl
  • arm-unknown-linux-gnueabi
  • arm-unknown-linux-musleabi
  • armv5te-unknown-linux-gnueabi
  • armv5te-unknown-linux-musleabi
  • armv7-unknown-linux-gnueabihf
  • armv7-unknown-linux-musleabihf
  • i586-unknown-linux-gnu
  • mips-unknown-linux-gnu
  • mips-unknown-linux-musl
  • mips64-unknown-linux-gnuabi64
  • mips64el-unknown-linux-gnuabi64
  • mipsel-unknown-linux-gnu
  • mipsel-unknown-linux-musl
  • powerpc-unknown-linux-gnu
  • powerpc64-unknown-linux-gnu
  • powerpc64le-unknown-linux-gnu
  • s390x-unknown-linux-gnu
  • sparc64-unknown-linux-gnu
• MacOS/iOS
  • aarch64-apple-ios
  • x86_64-apple-ios
• NetBSD
  • x86_64-unknown-netbsd (无串行枚举)

硬件支持

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

已知问题

许可

本库采用Mozilla公共许可证，版本2.0授权。

贡献

请打开GitLab上的问题或合并请求以进行贡献。根据MPL2.0许可证定义，您提交的代码贡献应授权为上述内容，无任何附加条款或条件。

致谢

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