Serial Support on the Windows Subsystem for Linux

This is part of a series of blog posts on the Windows Subsystem for Linux (WSL). For background information you may want to read the architectural overview, introduction to pico processes, WSL system calls, and WSL file system blog posts.

Posted on behalf of Stephen Hufnagel

Summary

In Windows Insider build #16176 WSL now allows access to serial devices (COM ports).

This blog post will describe how to use this feature and the work that was involved in exposing this functionality within WSL.

On Windows, COM ports are named COM1 through COM256. On Linux, serial devices can have arbitrary names but are typically character devices with a major number of 4 and a minor number from 64 to 256 represented by /dev/ttyS0 through /dev/ttyS191.  By default init will populate this mapping using the mknod system call.  Alternate mknod mappings can be created at runtime if needed.

In WSL, the lxcore driver maps COM ports to Linux devices by the COM port number so /dev/ttyS<N> is tied to COM<N>.  More specifically, the mapping is on the minor number, so minor number 65 (/dev/ttyS1) is COM1, 66 (/dev/ttyS2) is COM2, and so forth.  Since pty, tty, and ttyS share a terminal library code base, ttyS will behave similarly but also support the following termios settings which are simply mapped to Windows serial driver ioctls:

  • Standard baud rates - B*
  • Stop bits - CSTOPB
  • Word length - CSIZE
  • Parity checking - PARENB, PARODD, CMSPAR, INPCK
  • Software flow control - IXON, IXOFF
  • Hardware flow control - CRTSCTS, CLOCAL
  • Control characters - VSTART, VSTOP, VEOF

To use your favorite serial tool\library in WSL, just map from the COM port of the device using device manager or the SERIALCOMM registry key (HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP\SERIALCOMM).

serial

Figure 1. This diagram shows the basic architecture of WSL exposes Windows COM ports as serial devices in WSL.

Scenarios

The following scenarios were tested and confirmed to be working:

  1. Programming pixhawk light controller - Thanks @lovettchris!
  2. Connecting to Raspberry Pi 2 serial terminal using the cu tool
  3. Transferring data on various serial configurations:
    1. Hyper-V virtual COM port
    2. FTDI USB to serial converter
    3. Prolific USB to serial converter
    4. Physical COM port

Please note that some serial drivers have known bugs. These issues exist on both native Windows and within WSL.

The following areas are known to not work. We are tracking updates to future Windows Insider builds to address them.

  1. Using legacy raw ioctls instead TCGETS or TCSETS* to configure and query the serial device
  2. Screen and minicom depend on the above so they do not currently work as a serial terminal, but cu is an alternative.

Example

On a Windows 10 machine where a Raspberry Pi is connected on COM5 connect using the following steps:

  1. sudo chmod 666 /dev/ttyS5 - This is required since cu changes it's uid which drops capabilities even when running as root. Not all serial programs have the same behavior.
  2. stty -F /dev/ttyS5 -a . Optionally check your current serial settings before updating.
  3. Set your serial settings, depending on your application this usually will be raw or sane. Either one seems to work fine with cu:
    1. stty -F /dev/ttyS5 sane 9600
    2. stty -F /dev/ttyS5 raw 9600 -echo -echoe -echok -echoctl -echoke -iexten -onlcr cs8 crtscts
  4. cu -l /dev/ttyS5 -s 9600
  5. Hit enter to refresh the cu console

Feedback

Please let us know on our Github about the specific serial scenarios that you are trying. Your feedback helps us prioritize what we should focus on next.