将串口数据给进WSL再给进Docker——一次成功流水账（优化稿）

将串口数据给进WSL再给进Docker——一次成功流水账（优化稿）

⚙️ 本文是一次实操记录：把物理串口设备的数据，先接入 Windows，再转发进 WSL，最后映射进 Docker 容器。以乐动单线激光雷达LD14P（串口芯片 CH9102）为例，每一步都带验证。

背景与整体思路

平时主力是 Windows 电脑，偶尔需要 Linux 环境。Win11 可以安装 WSL，自带图形界面服务（WSLg），显示窗口没有问题；进一步在 WSL 中配置 Docker，就能直接在容器镜像里用 ROS 等工具。难点在于要同时读取串口数据——数据要穿过三层驱动：

1. Windows 串口驱动：让 Windows 认到 USB 转串口设备（COM 口）。
2. USB/IP 转发：用usbipd把 USB 设备从 Windows 转发进 WSL。
3. 容器映射：把 WSL 里的串口设备（如/dev/ttyACM0）映射进 Docker。

下面按这三层顺序推进，每一层都先配置、再验证。

一、Windows 侧：安装串口驱动并验证

1.1 安装 Windows 串口驱动

安装 CH9102 对应的 Windows 驱动（CH343SER）：

C:\Users\HongwuZhu\Downloads\激光雷达资料\串口驱动\CH9102\CH343SER（CH9102的windows驱动）\CH343SER\Driver

1.2 确认 COM 口

插入设备，在设备管理器查看是否新增 COM 口。

插入 USB 前：

插入 USB 后：

1.3 在 Windows 中测试雷达端口

运行 CLI 测试脚本，看是否有数据输出。如果有数据，说明连接和 Windows 驱动都没问题：

cd D:\Project\turtlebot3_training\LD14P python ld14p_cli.py COM5

如果有多个端口，分别测试一下。有数据输出，就说明 Windows 串口正常、雷达硬件没问题。

💡 如果usbipd已经把 USB 设备"独占"转发给了 WSL，此时要在 Windows 测试，得先归还：

# PowerShell 管理员 usbipd detach --busid 1-4

等几秒 Windows 会重新识别，COM 口就回来了。测完再挂回去：

usbipd attach --busid 1-4 --wsl

二、把 USB 设备转发给 WSL（usbipd）

usbipd是一个基于 USB/IP 协议的服务端程序（守护进程），核心作用是把一台电脑上连接的物理 USB 设备，通过网络共享给其他系统使用——这里就是共享给 WSL。

2.1 查看设备的 BUSID

# (base) PS C:\Users\HongwuZhu> usbipd list Connected: BUSID VID:PID DEVICE STATE 1-4 1a86:55d4 USB-Enhanced-SERIAL CH9102 (COM3) Not shared

由此得到对应的BUSID = 1-4。1a86:55d4是设备的 VID:PID（厂商号/产品号），在不同系统中不会变化。如果状态已是Shared，直接在 WSL 中重新触发一下即可。

说明：设备管理器里看到的是 COM 口，而usbipd list里不显示 COM——这是正常的。COM 端口号对usbipd转发完全没有影响，它走的是 USB 总线，不经过 COM 端口。核心数据 BUSID=1-4、VID:PID=1a86:55d4 都对，就说明设备被正确识别了。

2.2 绑定并挂载到 WSL

# 假设 BUSID 是 1-4，绑定并转发到 WSL usbipd bind --busid 1-4 --force usbipd attach --busid 1-4 --wsl

• usbipd bind --busid 1-4 --force：将主机上指定总线ID（1-4）的USB设备强制绑定到usbipd服务，使其可以被后续重定向。
• usbipd attach --busid 1-4 --wsl：将已绑定的USB设备挂载到WSL中，让WSL能够像使用本地设备一样访问该串口。

三、在 WSL 中验证 USB 接口

进入 WSL 后，能否认到设备取决于加载了哪个驱动。下面两种情况按优先级尝试。

情况一（推荐，本例成功）：cdc-acm 直接认到 CH9102

只加载cdc-acm，不去碰ch341，让内核自动匹配：

# 只加载 cdc-acm，不要 echo new_id（让内核自动匹配） sudo modprobe cdc-acm # 看看设备是否已自动绑定 dmesg | tail -10 ls -la /dev/ttyACM* /dev/ttyUSB* 2>/dev/null

cdc-acm是 Linux 内核的 USB 串口驱动模块，负责将符合 CDC ACM 协议（如 Arduino、3G 模块、部分 FTDI 设备）的 USB 设备映射为/dev/ttyACM*虚拟串口，让用户空间程序像操作普通串口一样读写。

如果cdc-acm认到了 CH9102，会出现/dev/ttyACM0，这就是最理想的情况。测试：

sudo chmod 666 /dev/ttyACM0 cd /mnt/d/Project/turtlebot3_training/LD14P python3 ld14p_win_wsl_cli.py /dev/ttyACM0

看到数据流，就说明 WSL 中雷达完全正常了。

情况二：给 ch341-uart 打补丁（new_id）

如果走的是ch341驱动，需要手动把设备的 VID:PID 喂给ch341-uart，让它接管：

echo "1a86 55d4" | sudo tee /sys/bus/usb-serial/drivers/ch341-uart/new_id sudo chmod 666 /dev/ttyUSB0 /dev/ttyUSB1 cd /mnt/d/Project/turtlebot3_training/LD14P python3 ld14p_cli.py /dev/ttyUSB0

这条命令的作用，是强制让 Linux 内核的ch341-uart驱动去识别并接管一个它默认不支持的 USB 转串口设备——相当于给驱动"打补丁"，让系统把设备认作串口（如/dev/ttyUSB0），以识别市面上那些非标准 PID 的 CH341 芯片。

• ch341-uart是 Linux 内核里用于支持 CH341/CH340 系列 USB‑串口转换芯片的内核驱动模块（.ko文件）。它包含在主线内核的drivers/usb/serial/ch341.c中，属于“USB 串口转换器驱动”的子系统。当插入 CH341 芯片的 USB 串口线时，系统会自动加载这个内核模块，生成/dev/ttyUSB0等设备节点。
• tee指令是一个 Linux/Unix 命令，作用是从标准输入读取数据，并同时将数据写入一个或多个文件以及输出到标准输出（通常是终端）。典型的用法是command | tee output.txt，这样command的输出既会显示在屏幕上，也会被保存到output.txt。常用于需要同时“看一眼结果”和“留一份记录”的场景。

⚠️ 局限：ch341驱动对 CH9102不完全兼容。常见症状是/dev/ttyUSB0能打开但收到 0 帧数据，换/dev/ttyUSB1则直接 I/O 错误。遇到这种情况，说明这条路走不通，优先回到"情况一"用cdc-acm。

情况三：安装 Linux 专用串口驱动（源码编译）

编译厂商提供的 Linux 驱动源码）。
有尝试这个方法，但是在make的时候报错，感觉很难解决

• 常见排查步骤：
  1. 在 WSL 里执行uname -r获取内核版本，然后安装对应的头文件：sudo apt install linux-headers-$(uname -r)。
  2. 检查驱动源码里的Makefile是否硬编码了内核路径，若用KERNELDIR变量，需确认它指向/lib/modules/$(uname -r)/build。
  3. 如果源码是针对较老内核（如 4.x）写的，而 WSL 是 5.10+，可能需要手动修改Kconfig或补丁，或者考虑在 Docker 容器里编译（但要保证容器内核与 WSL 一致）。
• 实在无法编译的替代方案：
  • 如果只是需要串口 USB 转接（如 CH340、CP2102），WSL 内通常已自带ch341、cp210x等内核模块，无需额外编译。检查lsmod | grep usb是否已加载。如果lsmod | grep usb的输出中已经包含ch341、cp210x等模块，那么插上对应的 USB 串口设备后，WSL 内核会自动加载驱动并创建/dev/ttyUSB0（或类似名称）节点，你可以直接通过该设备名访问。

如果模块未加载，先确认模块名（例如ch341或cp210x），然后手动加载：

sudomodprobe ch341# 若为 CH340/CH341 芯片sudomodprobe cp210x# 若为 CP2102 芯片

加载后再次运行lsmod | grep usb确认，再插拔设备即可。若提示modprobe: FATAL: Module not found，说明 WSL 内核未包含该模块，此时需要重新编译带有该驱动模块的内核（参考 WSL 自定义内核文档），但一般常见模块都已内置。

cdc-acm与ch341/cp210x是不同类别的USB串口驱动，不是“一起”的：

• cdc-acm是 Linux 内核内置的通用驱动，遵循 USB CDC ACM 协议，常用于 Arduino Uno、STM32 虚拟串口、某些 FTDI 芯片等设备。
• ch341和cp210x是特定芯片（CH340/CH341、CP2102）的专用驱动，属于内核中的独立模块，不归入 cdc-acm 体系。
• 你的设备应由芯片决定加载哪个模块：CH341 芯片 →ch341；CP2102 →cp210x；若设备是 CDC ACM 兼容 →cdc-acm。
• 原文只列出了 CH341 和 CP210x 的加载命令，因为它们常见且用户可能主动需要。cdc-acm通常已内置在 WSL 内核中，无需手动modprobe，所以原文未提及。若要确认，可用lsmod | grep acm查看是否已自动加载。
  流程是：usbipd 在 Windows 侧将 USB 设备打包成 TCP 数据流，WSL 内核的 usbip-host 模块负责解包并重新模拟出一个 USB 设备。这个“模拟出的设备”对 WSL 内核而言就是一块新挂载的 USB 硬件，和物理插入 U 盘没有区别——因此 WSL 内核仍然需要对应设备的 Linux 驱动（例如ch341、cp210x、ftdi_sio等串口驱动）才能识别设备并创建/dev/ttyUSB0节点。
  如果 WSL 默认内核已包含该驱动（大多数常见 USB 串口芯片都已内置为模块或编译进内核），那就无需自己编译；但如果遇到厂商独有、内核未收录的驱动，你仍然需要编译内核模块并加载。

四、启动 Docker，把串口映射进容器

4.1 先检查设备权限（在 WSL 中）

ls -la /dev/ttyACM0 # 应显示: crw-rw---- 1 root dialout 166, 0 ... /dev/ttyACM0 # 如果是 crw------- 没有 dialout 组，需要: sudo chmod 666 /dev/ttyACM0

4.2 启动容器

方式 A：用封装脚本（推荐）

bash docker_run_wsl.sh --port /dev/ttyACM0 -e

• --port /dev/ttyACM0：指定要映射进容器的串口设备（已确认在 WSL 中是ttyACM0）。
• -e：脚本里写的 enter 参数，启动后直接进入容器命令行。

方式 B：直接用原始docker run命令

适用于 Win11 + WSLg 环境（直接复制整行到 WSL 终端粘贴）：
在docker run命令的--name tb3_training后面（或任意-v之前的位置）插入--device=/dev/ttyACM0:/dev/ttyACM0即可

dockerrm-ftb3_training2>/dev/null;dockerrun-it-d--nametb3_training--device=/dev/ttyACM0:/dev/ttyACM0--networkhost-eDISPLAY=:0-eLIBGL_ALWAYS_SOFTWARE=1-eTURTLEBOT3_MODEL=burger-v/tmp/.X11-unix:/tmp/.X11-unix-v/mnt/wslg:/mnt/wslg-v"/mnt/d/Project/turtlebot3_training:/workspace"-w/workspace tb3-training:latestbash

如果串口设备名不固定（如ttyACM1、ttyUSB0），可将/dev/ttyACM0替换为实际路径；也可用--privileged映射全部设备（不推荐，安全性低）：
--privileged -v /dev:/dev。
若串口在 WSL 中已通过usbipd挂载且显示为/dev/ttyACM0，上述命令即可在容器内通过/dev/ttyACM0访问。

五、重开终端后如何重新进入环境

关闭所有终端后想重新进入 Docker 环境，按容器状态分两种情况。

5.1 容器仍在运行（最常见）

容器第一次启动后通常一直在后台运行，只需两步：

# [PowerShell] 第一步：进入 WSLwsl

# [WSL] 第二步：进入容器dockerexec-ittb3_trainingbash

进入后提示符变为root@...:/workspace#，即可正常使用ros2、python等命令。

💡 小技巧：可以开多个 PowerShell 窗口，每个都执行上面两步，实现多终端同时操作同一个容器。

5.2 容器已停止（如电脑重启后）

Docker Desktop 会自动启动，但容器需手动拉起：

# [WSL] 先启动容器，再进入dockerstart tb3_trainingdockerexec-ittb3_trainingbash

若Docker 容器启动时配置了设备映射--device /dev/ttyACM0，但USB 串口设备未插入或未挂载到 WSL。docker start tb3_training会提示无法启动。

• WSL 默认不自动挂载 Windows 的 COM 端口，需要手动通过usbipd-win或wsl --mount的方式将物理串口映射到 WSL 的/dev/ttyACM0。

解决步骤：

1. 若设备已连接，使用usbipd attach将 USB 设备绑定到 WSL（需安装 usbipd-win，参考 官方文档）。
2. 若不想挂载物理设备，可临时修改容器配置：移除--device参数，若容器已停止你需要不加载 USB 设备重新启动容器，保留其他挂载/参数。同样容器 ID 不许重复创建，可先docker start试试——如果原容器是docker run -d --device=/dev/ttyUSB0 ...启动的，现在设备不存在，docker start会失败（设备不存在）。
   此时应创建一个新容器（不绑定 --device），比如：

   dockerrun-it--rm\--namemy_container_no_usb\-v/some/path:/some/path\your_imagebash

3. 若想修改已有容器的配置（不重新创建）：
   Docker 不支持运行时变更--device参数。你只能 commit 镜像后基于新镜像创建新容器，或直接创建新容器（推荐）。

5.3 常用容器管理命令

dockerexec-ittb3_trainingbash# 进入容器dockerstop tb3_training# 停止容器dockerstart tb3_training# 启动容器dockerrm-ftb3_training# 强制删除容器

六、常见问题