o
      o   /---o
     /---/---o
o---/
     \---\---o
      o   \---o
            o

Cyme

列出系统 USB 总线和设备；一个库和现代的跨平台 lsusb，试图保持与它的兼容性，同时增加新功能。包括 macOS 的 system_profiler SPUSBDataType 解析模块和非 macOS 系统的 libusb 分析器，以收集更详细的信息。

该项目最初是一个快速替换几乎不工作的 lsusb 脚本 和一个 Rust 项目来保持我的知识更新！像大多数有趣的项目一样，我很快就把它开发成了一个跨平台的 lsusb 替代品。

作为嵌入式设备的开发者，我经常使用 USB 列表工具，我开发了它来满足我认为 lsusb 的不足：详细输出太详细，树形图没有包含有用的数据，它在非 Linux 平台上几乎无法工作，而现代终端支持使查看数据更容易的功能。

它并不完美，因为它是作为 Rust 复习开始的，但我开发它的时候非常开心，希望其他人也会觉得它有用并愿意贡献。阅读 lsusb 源代码、USB-IF 和一般 USB 信息也是一个很好的知识构建过程。

这个名字来源于苹果树上花朵的技术术语： cyme - 它与苹果有关，也像 USB 设备树 😃🌸。

功能

• 通过使用 --lsusb 参数与 lsusb 兼容。支持所有参数，包括使用 libusb 的 --verbose 输出。输出与无参数（列表）使用时相同，与树形图（不包括驱动器端口号）几乎匹配，与详细输出（缺少完整的扩展描述符转储）近似匹配。
• 与 lsusb 类似的过滤器，但也能在打印时工作 --tree。增加了 --filter_name、--filter_serial、--filter_class 以及隐藏空数据 --hide-buses/--hide-hubs 的选项。
• 改进了 --tree 模式；根据 --verbose 的级别，以树形结构显示设备、配置、接口和端点。
• 可以控制设备、总线、配置、接口和端点的数据块，如 lsd --blocks。默认使用 --more 来查看更多。
• 现代终端特性，包括彩色输出、utf-8 字符和基于设备数据的图标查找。可以关闭和自定义。查看 --encoding（默认为符号、utf8 和 ascii），它可以在一定编码内保持图标/树，--color（默认为自动，总是和从不）以及 --icon（默认为自动，总是和从不）。自动 --icon 仅在所有要显示的图标都受 --encoding 支持时显示图标。
• 可以作为库使用，包括 system_profiler 解析模块、使用 libusb 的 lsusb 模块以及用于打印的 display 模块等。
• 支持过滤器和 --tree 的 --json 输出。
• 使用 --headers 仅在请求时显示元数据，否则不占用空间。
• 使用 --mask_serials 将序列号替换为 '*' 或随机化序列字符串，以共享包含敏感序列号的转储。
• 自动缩放到终端宽度。变量长度字符串（如描述符）将被省略号 '...' 截断以表示。可以通过配置选项 'no-auto-width' 和 'max-variable-string-len' 定义的最大长度来禁用。
• 支持 Linux、macOS 和 Windows。

演示

安装

要求

• Linux/Windows 和预编译目标需要 libusb 1.0.0：在 macOS 上使用 brew install libusb，在 Linux 上使用 sudo apt install libusb-1.0-0-dev 或使用您选择的包管理器。

有关预编译的二进制文件，请参阅 发布。

在安装了 Rust 工具链的情况下，从 crates.io 安装： cargo install cyme。在本地克隆中执行： cargo install --path .。

如果只想使用 macOS system_profiler 而不获取更详细的信息，请使用 cargo install --no-default-features cyme 删除 'libusb' 功能。

包管理器

• Homebrew 'cyme'，它还会安装 man 页、补全和 'libusb' 依赖项

brew install cyme

• Arch AUR 'cyme-bin'
• 作为发布的一部分的 Debian 软件包 - 需要一个 Debian 维护者。

将提供更多包管理器和包分发，如果您想在此处提供帮助，请随时创建一个 PR。

Linux udev

[!NOTE] 仅在 Linux 目标上受支持。

为了获取Linux上使用的设备和管理接口驱动，例如 lsusb，在构建时可以使用 --features udev 功能 - 这是一个默认功能。该功能使用Rust crate udevrs 来获取信息。要使用C FFI libudev库，请使用 --no-default-features --features udevlib，这将使用 'libudev' crate。注意，这需要在主机机器上安装 'libudev-dev'。

要像 lsusb 一样从udev hwdb中查找USB ID（例如），请使用 --features udev_hwdb。如果没有hwdb，cyme 将使用 'usb-ids' crate，它与hwdb二进制数据的来源相同，但由于定制或最后更新（'usb-ids' 将是最新的）而捆绑的hwdb可能不同。

别名 lsusb

如果想要创建lsusb的macOS版本或只是用它代替，请使用 --lsusb 兼容标志在自己的环境中创建别名

alias lsusb='cyme --lsusb'

使用方法

随着其发展，将对此进行更多介绍。使用 cyme --help 进行基本使用或 man ./doc/cyme.1。此外，'./doc' 中还有自动完成功能。

crate

作为系统USB设备的库进行使用时，crate有100%的文档，请查看 docs.rs。主要的有用模块是 system_profiler、lsusb::profiler 和 usb

在 'examples/' 中也有一些示例，可以使用 cargo run --example filter_devices 运行。

配置

cyme 将在以下位置检查 'cyme.json' 配置文件：

• Linux: "$XDG_CONFIG_HOME/cyme 或 $HOME/.config/cyme"
• macOS: "$HOME/Library/Application Support/cyme"
• Windows: "{FOLDERID_RoamingAppData}/cyme"

还可以使用 --config 供应。复制或参考 './doc/cyme_example_config.json' 以获取可配置项。该文件基本上是默认参数；提供的参数将覆盖这些。使用 --debug 查看其位置或是否未加载。

自定义图标和颜色

有关如何定义图标以及文档的示例，请参阅 './doc/cyme_example_config.json'。如果不想定义任何新的图标/颜色，则可以配置排除 "user"/"colours" 键。

图标的搜索顺序为用户 -> 默认。对于设备：VidPid -> VidPidMsb -> Vid -> UnknownVendor -> get_default_vidpid_icon，类别：ClassifierSubProtocol -> Classifier -> UndefinedClassifier -> get_default_classifier_icon。用户提供的颜色将覆盖所有内部颜色；如果键缺失，则将其设置为 None。

图标未显示/带有问号的框

从 lsd 复制：为了让 cyme 能够显示图标，字体必须包含特殊的字体符号。这可能不是大多数你下载的字体的情况。幸运的是，你可以使用 NerdFont 来修补大多数字体并添加这些图标。或者，你也可以从 NerdFont 字体下载页面 下载已经修补的字体版本。以下是如何在 macOS 和 Android 上设置字体的指南。

要检查你使用的字体是否设置正确，尝试在 shell 中运行以下片段，看看是否打印出 文件夹图标。如果打印出方框、问号或其他内容，那么你可能在设置字体或终端模拟器渲染字体方面存在问题。

echo $'\uf115'

如果不希望使用图标，请提供不包含任何 'icon*' 块的自定义配置文件 - 请参阅示例配置。或者，为了只使用所有字体都支持的标准的 UTF-8 字符（没有私有使用区域），请传递 --encoding utf8 和 --icon auto（默认）。--icon auto 将在匹配的字符不受 --encoding 支持时删除图标块。

对于完全不使用图标，请使用隐藏的 --no-icons 或 --icon never 参数。

已知问题

• sudo 是打开和读取 Linux root_hub 字符串描述符所需的。然而，程序无需这些也能正常工作，因为它会像 lsusb 一样使用 sysfs/hwdb/'usb-ids'。可以使用调试 -z 来查看哪些设备读取失败。可以使用环境变量 CYME_PRINT_NON_CRITICAL_PROFILER_STDERR 或 'print-non-critical-profiler-stderr' 配置键将这些打印到 stderr。使用 --lsusb --verbose 总是打印消息到 stderr，以匹配 'lsusb' 的行为。
• libusb 与 macOS system_profiler 之间的主要版本 BCD 设备差异：如果主要版本很大，libusb 似乎读取了与 macOS 不同的值。我不认为这是一个解析错误，但愿意接受建议。
• libusb 无法读取特殊的非用户 Apple 总线；例如 T2 芯片。这些仍将由 system_profiler 列出。结果是，在合并详细数据时，这些将不会打印详细信息。使用 --force-libusb 来忽略它们。
• 与 macOS 13 -> 测试。我不确定 -json 标志是什么时候添加到 system_profiler 的；它是否存在于所有 macOS 版本上。