【python】pyserial 在windows 下卡住的bug
使用当前pyserial 在Windwos 下做的项目，移交到客户案场后， 客户发现程序会卡住，经过最终调查，是卡在了pyserial 的write 方法中了。
具体现象：
程序卡在write 方法中，长时间无法返回，即使设置了write_timeout 也无法返回。
分析
下来我们将Send 方法的代码切出来：
def write(self, data):"""Output the given byte string over the serial port."""if not self.is_open:raise PortNotOpenError()#~ if not isinstance(data, (bytes, bytearray)):#~ raise TypeError('expected %s or bytearray, got %s' % (bytes, type(data)))# convert data (needed in case of memoryview instance: Py 3.1 io lib), ctypes doesn't like memoryviewdata = to_bytes(data)if data:#~ win32event.ResetEvent(self._overlapped_write.hEvent)n = win32.DWORD()success = win32.WriteFile(self._port_handle, data, len(data), ctypes.byref(n), self._overlapped_write)if self._write_timeout != 0: # if blocking (None) or w/ write timeout (>0)if not success and win32.GetLastError() not in (win32.ERROR_SUCCESS, win32.ERROR_IO_PENDING):raise SerialException("WriteFile failed ({!r})".format(ctypes.WinError()))# Wait for the write to complete.#~ win32.WaitForSingleObject(self._overlapped_write.hEvent, win32.INFINITE)win32.GetOverlappedResult(self._port_handle, self._overlapped_write, ctypes.byref(n), True)if win32.GetLastError() == win32.ERROR_OPERATION_ABORTED:return n.value # canceled IO is no errorif n.value != len(data):raise SerialTimeoutException('Write timeout')return n.valueelse:errorcode = win32.ERROR_SUCCESS if success else win32.GetLastError()if errorcode in (win32.ERROR_INVALID_USER_BUFFER, win32.ERROR_NOT_ENOUGH_MEMORY,win32.ERROR_OPERATION_ABORTED):return 0elif errorcode in (win32.ERROR_SUCCESS, win32.ERROR_IO_PENDING):# no info on true length provided by OS function in async modereturn len(data)else:raise SerialException("WriteFile failed ({!r})".format(ctypes.WinError()))else:return 0
这里有一个 Windows 串口编程的“坑”：即使你设置了 write_timeout，某些情况下，WriteFile + GetOverlappedResult() 仍可能卡住不返回。下面我从操作系统底层机制解释这个行为。
在 PySerial 的 Windows 实现中，串口写操作等价于如下 WinAPI 调用流程：
OVERLAPPED ov = {...}; // 重叠结构体（异步IO用）
DWORD written = 0;
BOOL success = WriteFile(hSerial, buffer, len, &written, &ov);if (!success && GetLastError() == ERROR_IO_PENDING) {// 等待异步写完成GetOverlappedResult(hSerial, &ov, &written, TRUE); // TRUE = 阻塞等待
}
问题发生点：GetOverlappedResult(…, TRUE)
这个调用是阻塞等待写完成。理论上，当写操作超过 WriteTotalTimeoutConstant + len * WriteTotalTimeoutMultiplier 时，系统应返回 SerialTimeoutException，但实际并不总是这样。
| 原因 | 解释 |
|---|---|
| ✅ 驱动未正确处理超时 | 某些串口驱动（尤其是 USB 转串口）忽略了 SetCommTimeouts 中的写超时设置。 |
| ✅ 缓冲区已满 | 写缓冲区写不进去，但驱动仍让 WriteFile 挂起等待，超时机制失效。 |
| ✅ GetOverlappedResult 不检查超时 | 它本身不带超时参数，除非你用 WaitForSingleObject 另设超时，pyserial 没这么做。 |
| ✅ 虚拟串口/硬件死锁 | 某些虚拟串口设备（如蓝牙串口、USB转串口）会因设备掉线导致永远不返回。 |
举个例子：
ser.write_timeout = 2.0
ser.write(b'X' * 102400) # 写一个很大的包
如果目标串口设备已断开/没响应：
- WriteFile() 会返回 ERROR_IO_PENDING
- 然后 GetOverlappedResult(…, TRUE) 就会 永久阻塞
- 此时 write_timeout 设置毫无作用
如果串口写缓冲区已满，驱动并不会立即失败， 而是等待硬件清空缓冲区（例如对端设备接受）， 如果硬件永远不读（比如死机了），那它就永远挂住了。
WriteFile() 是异步的，但 GetOverlappedResult(…, TRUE) 是阻塞的。它等的是 overlapped 事件完成，但串口驱动只有在写成功/失败时才触发事件。
当使用 OVERLAPPED 结构进行串口异步写时，WriteFile() 返回后，并不会立刻知道是否成功，而是通过一个事件句柄 hEvent 在未来某个时间点通知“写操作完成”。
所以我们给出最终解决方案如下：
def write(self, data):"""Output the given byte string over the serial port."""if not self.is_open:raise PortNotOpenError()#~ if not isinstance(data, (bytes, bytearray)):#~ raise TypeError('expected %s or bytearray, got %s' % (bytes, type(data)))# convert data (needed in case of memoryview instance: Py 3.1 io lib), ctypes doesn't like memoryviewdata = to_bytes(data)if data:#~ win32event.ResetEvent(self._overlapped_write.hEvent)n = win32.DWORD()success = win32.WriteFile(self._port_handle, data, len(data), ctypes.byref(n), self._overlapped_write)if self._write_timeout != 0: # if blocking (None) or w/ write timeout (>0)if not success and win32.GetLastError() not in (win32.ERROR_SUCCESS, win32.ERROR_IO_PENDING):raise SerialException("WriteFile failed ({!r})".format(ctypes.WinError()))# Wait for the write to complete.WAIT_TIMEOUT = 0x00000102if self._write_timeout is None:timeout_ms = win32.INFINITEelse:timeout_ms = int(self._write_timeout * 1000)rc = win32.WaitForSingleObject(self._overlapped_write.hEvent, timeout_ms)if rc == WAIT_TIMEOUT:self.cancel_write()raise SerialTimeoutException('Write timeout due to device blocking.')win32.GetOverlappedResult(self._port_handle, self._overlapped_write, ctypes.byref(n), False)if win32.GetLastError() == win32.ERROR_OPERATION_ABORTED:return n.value # canceled IO is no errorif n.value != len(data):raise SerialTimeoutException('Write timeout')return n.valueelse:errorcode = win32.ERROR_SUCCESS if success else win32.GetLastError()if errorcode in (win32.ERROR_INVALID_USER_BUFFER, win32.ERROR_NOT_ENOUGH_MEMORY,win32.ERROR_OPERATION_ABORTED):return 0elif errorcode in (win32.ERROR_SUCCESS, win32.ERROR_IO_PENDING):# no info on true length provided by OS function in async modereturn len(data)else:raise SerialException("WriteFile failed ({!r})".format(ctypes.WinError()))else:return 0
使用WaitForSingleObject：
- 等待 overlapped 写事件完成
- 最多等待 timeout_in_ms 毫秒
- 返回值 rc 用于判断是成功、超时，还是其他错误
- 如果超时，调用cancel_write() 掉取消一个挂起的 I/O 操作（如 ReadFile、WriteFile 等）（特别是在使用 重叠（Overlapped）I/O 时非常有用。）
如此，就完美的解决掉pyserial 在windows 下卡住的现象了。