Lib.rs

› 硬件支持
#串口 #串行 #硬件 #系统 #硬件接口 #读写

serialport5

跨平台的低级串口库

所有者 thewh1teagle.

3个稳定版本

5.0.2 2024年2月24日
5.0.0 2024年1月3日

218 在 硬件支持

Download history 29/week @ 2024-04-27 6/week @ 2024-05-04 73/week @ 2024-05-11 60/week @ 2024-05-18 20/week @ 2024-05-25 23/week @ 2024-06-01 13/week @ 2024-06-08 11/week @ 2024-06-15 20/week @ 2024-06-22 75/week @ 2024-06-29 104/week @ 2024-07-06 71/week @ 2024-07-13 56/week @ 2024-07-20 69/week @ 2024-07-27 35/week @ 2024-08-03 15/week @ 2024-08-10

185 每月下载量
在 2 crates 中使用

MPL-2.0 许可协议

150KB
3K SLoC

crates.io version badge Documentation GitHub Workflow Status

注意： 这是从GitLab上的原始serialport-rs项目的一个分支。请注意，支持的目标和某些目标所在的级别都发生了一些变化，并且可能会进一步更改。此外，所有相关的问题都已迁移到这个仓库。

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

简介

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

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

概述

该库通过 SerialPort 结构体公开跨平台串口功能。可以通过导入特定平台的 SerialPortExt traits 启用平台特定的附加功能。SerialPort 实现了标准 Read 和 Write traits。

大多数平台上都提供了串口枚举。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::builder()
    .baud_rate(115_200)
    .read_timeout(Duration::from_millis(10))
    .open("/dev/ttyUSB0")
    .expect("Failed to open port");

写入端口

use std::io::Write;

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

从端口读取

use std::io::Read;

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

某些平台公开了其他功能，这些功能可以通过导入特定平台的扩展trait来访问。

let port = SerialPort::builder()
    .baud_rate(115_200)
    .read_timeout(Duration::from_millis(10))
    .open("/dev/ttyUSB0")
    .expect("Failed to open port");

#[cfg(windows)]
use serialport::windows::SerialPortExt;

#[cfg(unix)]
use serialport::posix::SerialPortExt;

关闭端口

serialport-rs 使用资源获取即初始化（RAII）范式，因此关闭端口是在 SerialPort 对象被 Drop 时完成的，无论是隐式还是显式地使用 std::mem::drop （std::mem::drop(port)）。

迁移到版本 5

在此库的版本 5 之前，SerialPort 类型是一个特质，跨平台功能是通过使用 Box<dyn SerialPort> 提供的。平台特定功能需要使用特定平台的结构体，如 COMPort 和 TTYPort。

在版本 5 中，这些类型已经统一，只有一个 SerialPort 结构体作为库公开的唯一的串行端口类型。平台特定功能通过扩展特质实现，可以在特定平台需要时导入，以便您可以在 SerialPort 结构体上调用额外的函数。使用结构体而不是特质意味着您不再需要 Box SerialPort 实例，扩展特质应该会更容易编写只偶尔需要访问平台特定功能的跨平台代码。

例如，要在 TTY 端口上发送中断，在版本 4 及更早版本中，您必须使用 TTYPort 结构体而不是跨平台的 dyn SerialPort。

use serialport::BreakDuration;

let port = serialport::new("/dev/ttyUSB0", 9600).open_native()?;
port.send_break(BreakDuration::Short)?;

在版本 5 中，现在您可以在任何地方使用常见的 SerialPort 类型，并且为了访问平台特定的 send_break 方法，您只需导入平台特定的特质。

use serialport::posix::{SerialPortExt, BreakDuration};
use serialport::SerialPort;

let port = SerialPort::builder().open("/dev/ttyUSB0")?;
port.send_break(BreakDuration::Short)?;

将 SerialPort 作为结构体而不是特质切换的另一个后果是，您现在需要显式导入 std::io::Read 和 std::io::Write 特质。以前，SerialPort 特质从 Read 和 Write 继承，因此当 SerialPort 特质在作用域内时，可以调用读取和写入而不需要导入它们。现在，将 SerialPort 作为结构体，您现在需要显式导入 Read 和 Write。

示例

包含几个示例，有助于展示此库的功能，并可以帮助调试软件或硬件错误。

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

依赖关系

支持 Rust 版本 1.46.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
    • i686-unknown-linux-gnu
    • i686-unknown-linux-musl
    • x86_64-unknown-linux-gnu
    • x86_64-unknown-linux-musl
  • MacOS/iOS
    • aarch64-apple-darwin
    • 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-gnueabihf
    • arm-unknown-linux-musleabi
    • armv5te-unknown-linux-gnueabi
    • armv5te-unknown-linux-musleabi
    • armv7-unknown-linux-gnueabihf
    • armv7-unknown-linux-musleabihf
    • i586-unknown-linux-gnu
    • i586-unknown-linux-musl
    • 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 示例。它将测试驱动程序以确认端口支持所有可能的设置。此外，如果您有两个物理配置为通信的端口，它还将测试这些设置的数据传输是否正确。如果您遇到设备问题，请提交错误报告并识别所使用的硬件、操作系统和驱动程序。

已知问题

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

许可

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

贡献

请在GitLab上打开一个问题或合并请求以进行贡献。根据MPL2.0许可证定义，您提交的代码贡献应按照上述方式许可，不附加任何额外条款或条件。

致谢

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

感谢 GitLab 上 original serialport-rs 项目中的 susurrus 以及所有其他贡献者。

依赖关系

~1.6–2.4MB
~46K SLoC