{"id":48874079,"url":"https://github.com/yunsmall/usbipdcpp","last_synced_at":"2026-04-15T23:34:25.192Z","repository":{"id":305757855,"uuid":"1023850867","full_name":"yunsmall/usbipdcpp","owner":"yunsmall","description":"A C++ library for creating usbip server.","archived":false,"fork":false,"pushed_at":"2026-04-14T18:17:22.000Z","size":322,"stargazers_count":19,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-14T20:18:26.665Z","etag":null,"topics":["android","asio","libusb","remote-control","termux","usb","usb-device","usbip","usbipd","virtual","virtual-keyboard","virtual-mouse","virtualization"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yunsmall.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-21T19:46:29.000Z","updated_at":"2026-04-14T18:17:26.000Z","dependencies_parsed_at":"2025-08-19T21:32:59.817Z","dependency_job_id":"1fe3ab2a-ce6a-47a4-8804-aee22e8f528e","html_url":"https://github.com/yunsmall/usbipdcpp","commit_stats":null,"previous_names":["yunsmall/usbipcpp","yunsmall/usbipdcpp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/yunsmall/usbipdcpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunsmall%2Fusbipdcpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunsmall%2Fusbipdcpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunsmall%2Fusbipdcpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunsmall%2Fusbipdcpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yunsmall","download_url":"https://codeload.github.com/yunsmall/usbipdcpp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunsmall%2Fusbipdcpp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31865071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","asio","libusb","remote-control","termux","usb","usb-device","usbip","usbipd","virtual","virtual-keyboard","virtual-mouse","virtualization"],"created_at":"2026-04-15T23:34:24.485Z","updated_at":"2026-04-15T23:34:25.181Z","avatar_url":"https://github.com/yunsmall.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# usbipdcpp\n\n一个用于创建 usbip 服务器的 C++ 库\n\n## 功能特性\n\n- ✅ **USBIP 服务器**: 基于 libusb 实现，支持所有 libusb 兼容平台\n- ✅ **虚拟 HID 设备**: 跨平台虚拟 USB 设备支持（无需 libusb），详见 `examples` 目录\n- 🔌 **热插拔支持**: 自动检测设备插入/拔出（LibusbServer）\n- 🚀 **异步架构**: 使用 C++20 协程和 asio 实现高效 I/O\n- 🧩 **可扩展设计**: 提供完善的抽象接口供开发者扩展\n\n欢迎贡献代码！🚀\n\n\u003e 💡 **提示**: 如果这个项目对你有用，请考虑给它一个 ⭐，这能帮助更多人发现它。\n\n---\n\n## 架构设计\n\nUSB 通信和网络通信都是 I/O 密集型任务，本项目采用全异步架构：\n\n- 使用 C++20 协程处理网络通信\n- 使用 asio 异步通信\n- 使用 libusb 异步接口处理 USB 通信\n\n### 依赖项\n\n| 依赖 | 是否必需 | 说明 |\n|------|----------|------|\n| asio | ✅ 必需 | 异步I/O库 |\n| spdlog | ✅ 必需 | 日志库 |\n| libusb-1.0 | 可选 | 用于物理USB设备转发 |\n| libevdev | 可选 (仅Linux) | 用于evdev输入设备转发 |\n| GTest | 可选 | 用于编译测试 |\n\n### 平台支持\n\n| 平台 | 虚拟设备 | 物理设备 (libusb) | 备注 |\n|------|----------|-------------------|------|\n| Windows | ✅ | ⚠️ 需安装WinUSB驱动 | 适合虚拟HID设备 |\n| Linux | ✅ | ✅ | 完全支持 |\n| macOS | ✅ | ✅ | 完全支持 |\n| Android (Termux) | ✅ | ✅ 通过termux-usb | 支持非root访问 |\n| ESP32 | ✅ | ✅ | 使用ESP-IDF和asio组件 |\n\n### 核心类\n\n| 类 | 说明 |\n|----|------|\n| `Server` | 主服务器类，管理设备列表并接受连接 |\n| `Session` | 表示客户端连接，处理USBIP协议 |\n| `UsbDevice` | USB设备描述符和配置 |\n| `LibusbServer` | 物理USB设备转发服务器封装（基于libusb） |\n| `AbstDeviceHandler` | 所有设备处理器的抽象基类。提供 `is_device_removed()`、`on_device_removed()`、`trigger_session_stop()` 用于设备生命周期管理 |\n| `DeviceHandlerBase` | 提供通用功能的设备处理器中间基类 |\n| `VirtualDeviceHandler` | 虚拟USB设备的基类 |\n| `LibusbDeviceHandler` | 基于libusb的物理设备处理器 |\n| `VirtualInterfaceHandler` | 实现虚拟USB接口的基类 |\n| `HidVirtualInterfaceHandler` | HID设备基类（鼠标、键盘等） |\n| `SimpleVirtualDeviceHandler` | 简单设备处理器，提供标准请求的空实现 |\n| `StringPool` | 管理USB字符串描述符（最多255个） |\n\n### 工具类\n\n| 类 | 说明 |\n|----|------|\n| `ObjectPool\u003cT, PoolSize, ThreadSafe\u003e` | 固定大小对象池，用于高效内存分配。支持指针验证和重复释放检测。alloc O(1)，free O(log n)。 |\n| `ConcurrentTransferTracker\u003cTransferPtr, SegmentCount\u003e` | 基于分段锁的传输追踪器，用于高效管理并发传输。使用原子计数器实现快速路径操作。 |\n\n### 类继承关系\n\n```\nAbstDeviceHandler\n└── DeviceHandlerBase\n    ├── LibusbDeviceHandler    (通过libusb的物理设备)\n    └── VirtualDeviceHandler   (虚拟设备)\n        └── SimpleVirtualDeviceHandler\n```\n\n### 线程模型\n\n系统包含三个核心线程：\n\n1. **网络 I/O 线程**: 运行 `asio::io_context::run()`等待客户端连接\n2. **USB 传输线程**: 处理 `libusb_handle_events()`\n3. **主线程**: 控制服务器的行为，以及用于启动服务器\n\n每个连接会启动一个单独线程，防止某些设备的一些特殊同步操作阻塞所有设备。\n\n如果此时又启动一个线程会感觉多此一举。\n鉴于本身单个服务器的usb设备不会特别多，这种设计也是可行的。\n\n数据传输流程：\n\n```\n网络线程 → libusb_submit_transfer → USB线程 → 回调 → 网络线程\n```\n\n该架构通过最小化线程竞争实现高 CPU 效率\n\n### 虚拟设备实现\n\n开发虚拟设备时需注意：\n\n- 避免阻塞网络线程\n- 在工作线程中处理请求\n- 通过回调提交响应数据\n\n---\n\n## 使用指南\n\n### 代码说明\n\n\u003e 📝 注释和日志主要使用中文，代码结构清晰易读  \n\u003e 欢迎提交英文翻译的 PR！\n\n### 扩展功能\n\n实现自定义 USB 设备：\n\n1. 使用 `usbipdcpp::UsbDevice` 定义设备描述符\n2. 继承 `AbstDeviceHandler` 实现设备逻辑\n3. 使用 `VirtualInterfaceHandler` 处理接口操作，同时实现接口内的端点的逻辑\n\n简单设备可直接使用 `SimpleVirtualDeviceHandler`，它为标准请求提供了空实现\n\n\u003e ⚠️ **重要提示**：重写 `VirtualInterfaceHandler::on_new_connection()` 和 `on_disconnection()` 时，**必须**调用父类实现。父类会设置/清除 `session` 指针，该指针用于提交响应数据。\n\n---\n\n## ⚠️ Windows 使用提示\n\n在 Windows 使用 libusb 服务器需要替换驱动：\n\n1. 使用 [Zadig](https://zadig.akeo.ie/) 安装 WinUSB 驱动\n    - 选择目标设备（找不到设备时启用\"列出所有设备\"）\n    - **警告**：替换鼠标/键盘驱动会导致输入失效\n2. 使用后通过设备管理器回滚驱动：\n    - `Win+X` → 设备管理器 → 选择设备 → 回滚驱动程序\n\n对于物理设备，推荐使用 [usbipd-win](https://github.com/dorssel/usbipd-win) ，\n该项目使用VBoxUSB从驱动层面实现上述功能\n本项目更适合在 Windows 实现**虚拟 USB 设备**\n\n---\n\n## 例子介绍\n\n1. libevdev_mouse\n\n   使用libevdev库，在支持evdev的系统上，通过读取`/dev/input/event*`，模拟一个usbip的鼠标，实现转发本地的鼠标信号\n2. mock_mouse\n\n   一个每隔一秒就切换鼠标左键状态的鼠标示例。用以介绍虚拟HID设备的写法\n3. mock_keyboard\n\n   一个键盘示例，每秒模拟按下和释放'A'键。展示了如何实现标准键盘报告描述符的虚拟HID键盘。\n4. multi_devices\n\n   包含10个虚拟HID设备的示例。展示了如何使用工厂模式创建多个设备。\n5. empty_server\n\n   一个只有一个设备的usbip服务器。设备无任何功能，不会对数据做相应。\n6. libusb_server\n\n   转发本机的usb设备，带一个非常简陋的命令行，输入`h`查看用法，可自行选择转发哪些设备。\n   通过添加虚拟usb设备可实现和真实设备共享同一个usbip server\n7. termux_libusb_server\n\n   可在非root安卓设备的termux中使用的libusb server，通过\n   `termux-usb -e /path/to/termux_libusb_server /dev/bus/usb/xxx/xxx`启动。\n\n   由于termux-usb只支持传入一个fd，因此可使用不同端口启动多个服务器以支持多个设备。\n   使用`USBIPDCPP_LISTEN_PORT`环境变量来指定监听端口\n\n   termux-usb的使用可查看termux官方的相关文档\n---\n\n## 编译安装\n\n若使用gcc编译，最低gcc版本为**gcc13**。**gcc14**之下的C++23标准支持都是残的，\n不是`std::println`不支持就是`std::format`不支持，用得一点也不舒服。\n为了兼容性只能放弃编程体验。所以我选择了支持`std::format`但仍不支持`std::println`的gcc13\n\n有多个CMake选项用于控制相应模块是否编译：\n\n| 选项 | 默认值 | 说明 |\n|------|--------|------|\n| `USBIPDCPP_USE_COROUTINE` | ON | 使用C++20协程实现 |\n| `USBIPDCPP_ENABLE_BUSY_WAIT` | ON | 启用busy-wait模式以降低延时（仅在非协程模式下有效） |\n| `USBIPDCPP_BUILD_LIBUSB_COMPONENTS` | ON | 编译基于libusb的服务器组件 |\n| `USBIPDCPP_BUILD_EXAMPLES` | ON (顶级项目) | 编译所有示例程序 |\n| `USBIPDCPP_BUILD_TESTS` | ON (顶级项目) | 编译测试套件 |\n\n更多选项详见 `CMakeLists.txt`\n\n### 完整编译命令：\n\n#### 使用vcpkg包管理器\n请提前装好asio libusb libevdev spdlog等库\n```bash\ncmake -B build \\\n-DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake\ncmake --build build\ncmake --install build\n```\n\n#### 使用conan作为包管理器：\n```bash\nconan install . --build=missing -s build_type=Release\ncmake --preset conan-release\ncmake --build build/Release\ncmake --install build/Release\n```\n\n---\n\n## 使用\n\n```cmake\nfind_package(usbipdcpp CONFIG REQUIRED)\ntarget_link_libraries(main PRIVATE usbipdcpp::usbipdcpp)\n\n# 或者想使用libusb功能\n\nfind_package(usbipdcpp CONFIG REQUIRED COMPONENTS libusb)\ntarget_link_libraries(main PRIVATE usbipdcpp::usbipdcpp usbipdcpp::usbipdcpp_libusb)\n```\n\n---\n\n## 致谢\n\n本项目受益于以下开源项目：\n\n- [usbipd-libusb](https://github.com/raydudu/usbipd-libusb)\n- [usbip](https://github.com/jiegec/usbip)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyunsmall%2Fusbipdcpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyunsmall%2Fusbipdcpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyunsmall%2Fusbipdcpp/lists"}