{"id":50584633,"url":"https://github.com/zay002/hurry-porter","last_synced_at":"2026-06-05T05:01:51.587Z","repository":{"id":361209137,"uuid":"1253551658","full_name":"zay002/hurry-porter","owner":"zay002","description":"ROS 2 hardware orchestration for WSL2: usbipd-win workflow, serial/gamepad/LAN discovery, diagnostics, and ROS export.","archived":false,"fork":false,"pushed_at":"2026-05-29T17:12:42.000Z","size":61,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T17:15:16.397Z","etag":null,"topics":["colcon","cpp","gamepad","hardware","lan","python","robotics","ros","ros2","serial","usb","usbipd-win","windows","wsl2"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zay002.png","metadata":{"files":{"readme":"README.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":"2026-05-29T15:24:29.000Z","updated_at":"2026-05-29T17:12:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zay002/hurry-porter","commit_stats":null,"previous_names":["zay002/hurry-porter"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zay002/hurry-porter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zay002%2Fhurry-porter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zay002%2Fhurry-porter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zay002%2Fhurry-porter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zay002%2Fhurry-porter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zay002","download_url":"https://codeload.github.com/zay002/hurry-porter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zay002%2Fhurry-porter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33930311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["colcon","cpp","gamepad","hardware","lan","python","robotics","ros","ros2","serial","usb","usbipd-win","windows","wsl2"],"created_at":"2026-06-05T05:01:50.651Z","updated_at":"2026-06-05T05:01:51.573Z","avatar_url":"https://github.com/zay002.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hurry-porter\n\n[![Software checks](https://github.com/zay002/hurry-porter/actions/workflows/software.yml/badge.svg)](https://github.com/zay002/hurry-porter/actions/workflows/software.yml)\n\n面向 **ROS 2 on WSL2** 的硬件接入工具包。`hurry-porter` 负责发现、诊断和连接 Windows 主机上的 USB 串口、USB-CAN、手柄和局域网设备，让 ROS 2 侧拿到可用的端口、`/joy` 输入和 launch 参数。\n\n当前版本：`0.2.1`\n\n## 能力范围\n\n| 场景 | 路径 |\n| --- | --- |\n| USB 串口、USB-CAN、USB 手柄 | 复用 `usbipd-win` attach 到 WSL2 |\n| Waveshare USB-CAN-A | 通过厂商串口协议发送/接收 CAN2.0A/B 帧 |\n| Windows 蓝牙/HID 手柄 | Windows agent -\u003e UDP -\u003e ROS 2 `sensor_msgs/Joy` |\n| LAN 设备 | 按 TCP 端口或 MAC 地址发现机械臂 IP，并导出 endpoint |\n| ROS 集成 | 导出 env、JSON、YAML params、launch-file |\n\n不做的事：\n\n- 不重新实现 USB/IP。\n- 不把 Waveshare USB-CAN-A 伪装成 SocketCAN `can0`。\n- 不接管 Windows 蓝牙配对流程。\n\n## 要求\n\n- Windows 11 + WSL2\n- ROS 2 Jazzy\n- Python `3.12`\n- [`usbipd-win`](https://github.com/dorssel/usbipd-win)\n- `colcon`\n\n安装 `usbipd-win`：\n\n```powershell\nwinget install --interactive --exact dorssel.usbipd-win\n```\n\n## 构建\n\n```bash\ncd ~/hurry-porter\nsource /opt/ros/jazzy/setup.bash\ncolcon build\nsource install/setup.bash\n```\n\n## 快速使用\n\n检查环境和设备：\n\n```bash\nhurry doctor\nhurry scan --json\n```\n\nAttach Windows USB 设备到 WSL2：\n\n```bash\nhurry attach 4-3 --dry-run\nhurry attach 4-3\n```\n\n发送普通串口帧：\n\n```bash\nhurry serial send --port /dev/ttyUSB0 --baud 115200 --hex \"01 02\" --dry-run\nhurry serial send --port /dev/ttyUSB0 --baud 115200 --hex \"01 02\"\n```\n\n使用 Waveshare USB-CAN-A：\n\n```bash\nhurry waveshare-can-a send \\\n  --port /dev/ttyUSB0 \\\n  --can-bitrate 1000000 \\\n  --frame-type standard \\\n  --mode loopback \\\n  --id 0x123 \\\n  --data \"11 22 33 44\"\n```\n\n`standard` 对应 CAN2.0A 11-bit ID，`extended` 对应 CAN2.0B 29-bit ID。USB 串口默认波特率为 `2000000`。\n\n按 MAC 地址查找局域网机械臂：\n\n```bash\nhurry lan scan --cidr 192.168.1.0/24 --mac aa:bb:cc:dd:ee:ff --ports 502,30002 --json\n```\n\n启动 Windows 手柄桥：\n\n```bash\n# 终端 1：WSL / ROS bridge\nsource /opt/ros/jazzy/setup.bash\nsource install/setup.bash\nhurry gamepad bridge --topic /joy\n\n# 终端 2：Windows input agent\nsource install/setup.bash\nhurry gamepad start-agent\n\n# 终端 3：检查 ROS Joy\nsource /opt/ros/jazzy/setup.bash\nsource install/setup.bash\nros2 topic echo /joy sensor_msgs/msg/Joy\n```\n\n导出 ROS 参数：\n\n```bash\nhurry ros export --format json\nhurry ros export --format params --output config/hurry.generated.yaml\nhurry ros export --format launch-file --output launch/hurry.generated.launch.py\n```\n\n## 命令速查\n\n| 命令 | 用途 |\n| --- | --- |\n| `hurry doctor` | 检查 WSL2、ROS、usbipd-win、串口和手柄状态 |\n| `hurry scan --json` | 扫描 Windows USB/COM、WSL serial/input、LAN 设备 |\n| `hurry attach \u003cbusid\u003e` | 通过 usbipd-win attach USB 设备 |\n| `hurry watch` | 周期扫描并按配置自动 attach |\n| `hurry serial send` | 向 WSL 串口写入 text/hex 帧 |\n| `hurry waveshare-can-a` | Waveshare USB-CAN-A 配置、发送、接收、解码 |\n| `hurry lan scan` | 按 TCP 端口或 MAC 地址扫描 LAN 设备 |\n| `hurry gamepad status` | 查看手柄路径：WSL native、usbipd、Windows bridge |\n| `hurry gamepad bridge` | 在 WSL 发布 ROS 2 `/joy` |\n| `hurry gamepad start-agent` | 启动 Windows.Gaming.Input agent |\n| `hurry ros export` | 导出 ROS launch/env/params |\n\n## 配置\n\n生成 `hurry.toml`：\n\n```bash\nhurry init\nhurry init --from-scan --force\n```\n\n示例：\n\n```toml\n[watch]\ninterval_seconds = 2.0\nauto_attach = true\n\n[[devices]]\nrole = \"base_controller\"\nkind = \"serial\"\ndescription_regex = \"CH340|CP210|USB Serial|UART|CDC|FTDI\"\nauto_attach = true\npreferred_transport = \"usbipd\"\n\n[[devices]]\nrole = \"gamepad\"\nkind = \"gamepad\"\ndescription_regex = \"Xbox|Controller|Gamepad|Joystick|DualSense|Pro Controller\"\npreferred_transport = \"usbipd\"\n\n[[devices]]\nrole = \"arm_controller\"\nkind = \"lan_robot\"\nlan_host = \"192.168.1.10\"\nlan_mac = \"aa:bb:cc:dd:ee:ff\"\nlan_cidr = \"192.168.1.0/24\"\nlan_ports = [502, 30002]\npreferred_transport = \"lan\"\n```\n\n## 硬件备注\n\n### USB 串口\n\nCH340/CH341、CP210x、FTDI、PL2303、CDC ACM 通常应先在 Windows 侧安装对应驱动，再通过 `usbipd-win` attach 到 WSL2。WSL 中可见 `/dev/ttyUSB*`、`/dev/ttyACM*` 或 `/dev/serial/by-id/*` 后再由 ROS 使用。\n\n### Waveshare USB-CAN-A\n\nUSB-CAN-A 是 USB-串口-CAN 设备。`hurry waveshare-can-a` 按 Waveshare 串口协议工作，支持 CAN2.0A/B、数据帧、远程帧、variable/fixed 协议和 loopback 模式。\n\n### LAN 机械臂\n\n很多机械臂的 IP 会随路由器变化，但铭牌或网页里会提供 MAC 地址。`hurry-porter` 会读取 WSL 的邻居表，并在指定 CIDR 内做轻量触达来刷新 ARP/neighbor cache；找到 MAC 后输出当前 IP 和已开放端口。\n\n配置里可以只写 `lan_mac` + `lan_cidr`，也可以同时保留一个已知的 `lan_host` 作为兜底。\n\n### Nintendo Switch Pro Controller\n\nWindows 蓝牙下，Pro Controller 有时会保持玩家灯搜索/配对样式，但 PnP 状态仍是 `OK`，`/joy` 也能正常变化。这通常只是 Windows 没有分配玩家 LED，不代表需要重新配对。\n\n检查：\n\n```bash\nhurry gamepad status --json\n```\n\n如果输出里有：\n\n```json\n\"quirks\": [\"windows_pro_controller_led_unassigned\"],\n\"safe_to_keep_paired\": true\n```\n\n就可以继续使用，不需要重新配对。\n\n## 开发\n\n```bash\npython3.12 -m pytest -q\nsource /opt/ros/jazzy/setup.bash\ncolcon build\ncolcon test\nscripts/software_check.sh\n```\n\n## 相关项目\n\n- [`usbipd-win`](https://github.com/dorssel/usbipd-win)\n- [Microsoft WSL USB documentation](https://learn.microsoft.com/windows/wsl/connect-usb)\n- [ROS 2 joy](https://docs.ros.org/)\n- [Waveshare USB-CAN-A](https://www.waveshare.net/wiki/USB-CAN-A)\n\n## License\n\nMIT\n\n---\n\n# English\n\n`hurry-porter` is a ROS 2 on WSL2 hardware porter for USB serial devices, Waveshare USB-CAN-A, Windows gamepads, and LAN endpoints.\n\nIt orchestrates existing system paths instead of replacing them:\n\n- USB forwarding uses `usbipd-win`.\n- Waveshare USB-CAN-A uses its vendor serial protocol, not SocketCAN.\n- Windows Bluetooth/HID gamepads are bridged to ROS 2 `sensor_msgs/Joy`.\n- ROS integration is exported as env, JSON, params, or launch files.\n\nBuild:\n\n```bash\nsource /opt/ros/jazzy/setup.bash\ncolcon build\nsource install/setup.bash\n```\n\nCommon commands:\n\n```bash\nhurry doctor\nhurry scan --json\nhurry attach \u003cbusid\u003e\nhurry serial send --port /dev/ttyUSB0 --baud 115200 --hex \"01 02\"\nhurry waveshare-can-a send --port /dev/ttyUSB0 --frame-type standard --id 0x123 --data \"11 22\"\nhurry lan scan --cidr 192.168.1.0/24 --mac aa:bb:cc:dd:ee:ff --ports 502,30002\nhurry gamepad bridge --topic /joy\nhurry gamepad start-agent\nhurry ros export --format params\n```\n\nRun checks:\n\n```bash\npython3.12 -m pytest -q\nscripts/software_check.sh\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzay002%2Fhurry-porter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzay002%2Fhurry-porter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzay002%2Fhurry-porter/lists"}