Install virtual serial ports

You can create virtual serial ports in two ways:

• Pseudo terminal (pty) mode needs no installation. All you need on macOS and Linux is the pdcomm-vserial program. Applications open paths such as /dev/ttys… or /dev/pts/….
• Driver mode installs a port driver in the operating system. Applications open ordinary serial port names such as COMn on Windows and /dev/ttyPDVn on Linux. Use it to test applications that can’t change the port name or that look for ports in the device manager.

Operating system	Modes
Windows 10/11 x64	Driver mode: MSI installer (UMDF2 port driver)
Linux (Debian, Ubuntu) amd64 and arm64	Driver mode: DKMS kernel module .deb package; pseudo terminal mode
macOS	Pseudo terminal mode

Windows

Install on Windows

The MSI installer installs:

• C:\Program Files\PDComm\Virtual Serial\bin\pdcomm-vserial.exe, the command-line program that runs labs and manages ports.
• C:\Program Files\PDComm\Virtual Serial\driver\, with the port driver (PDCommVSerial.dll, UMDF2), a kernel filter that passes flush requests to it (PDCommVSerialFlt.sys), and the INF and catalog files.

After it copies the files, the installer creates the COM port devices and installs the driver. It creates two ports by default, named COM201 and COM202 unless Windows assigns other names.

1. Run the MSI file as an administrator. To create a different number of ports, set the PORTS property from an elevated command prompt:

   msiexec /i <path to the MSI file> PORTS=4

2. In Device Manager, under Ports (COM & LPT), look for entries such as PDComm Virtual Serial Port (COM201). You can also list the ports from the command line:

   & "$env:ProgramFiles\PDComm\Virtual Serial\bin\pdcomm-vserial.exe" ports list

   The command prints the device instance, the driver port number (index), and the COM name of each port as JSON.

3. The ports are connected only while a lab runs. This lab file joins driver ports 0 and 1 with a null-modem cable:

   windows-null-modem.json

   {
     "engine": {
       "pacing": "realistic",
       "nodes": [
         {"name": "plc", "port": {"line": {"baud": 19200, "data_bits": 8, "parity": "even", "stop_bits": "1"}}},
         {"name": "hmi", "port": {"line": {"baud": 19200, "data_bits": 8, "parity": "even", "stop_bits": "1"}}}
       ],
       "media": [{"kind": "null_modem", "a": "plc", "b": "hmi"}]
     },
     "ports": [
       {"node": "plc", "backend": {"type": "driver", "index": 0}},
       {"node": "hmi", "backend": {"type": "driver", "index": 1}}
     ]
   }

   & "$env:ProgramFiles\PDComm\Virtual Serial\bin\pdcomm-vserial.exe" run --config windows-null-modem.json

   When the lab is ready, it prints its ports. One program can now open COM201 and another COM202. To stop the lab, type {"command":"stop"} or press Ctrl+Z and then Enter.

Add and remove ports

Run these commands in an elevated PowerShell:

$Bin = "$env:ProgramFiles\PDComm\Virtual Serial"
& "$Bin\bin\pdcomm-vserial.exe" ports install --inf "$Bin\driver\PDCommVSerial.inf" --count 4
& "$Bin\bin\pdcomm-vserial.exe" ports remove

• ports install creates ports until there are --count of them. Each new port gets the lowest free driver port number and the name COM<--first-com + number>; --first-com defaults to 201. The driver supports up to 64 ports.
• ports remove deletes all port devices. ports uninstall also deletes the driver package and the filter service.

Uninstall

Remove PDComm Virtual Serial in Settings > Apps, or run msiexec /x <path to the MSI file>. Before it removes the files, the installer deletes the port devices, the driver package, and the filter service.

Linux

Install on Linux

The .deb package installs:

Path	Contents
/usr/src/pdcomm-vserial-<version>/	Source of the pdcomm_vserial kernel module, which DKMS builds
/usr/bin/pdcomm-vserial	The program that runs labs
/lib/systemd/system/pdcomm-vseriald.service	A service that runs the default lab at boot
/lib/udev/rules.d/60-pdcomm-vserial.rules	Lets members of the dialout group open the ports
/etc/pdcomm-vserial/lab.json	The default lab that the service runs
/etc/modprobe.d/pdcomm-vserial.conf	Module options (ports=4 by default)

1. DKMS needs the headers of the running kernel to build the module. Install them first:

   sudo apt install linux-headers-$(uname -r)

2. Install the package:

   sudo apt install ./pdcomm-vserial_<version>_amd64.deb

   The installation script builds and loads the module and enables the pdcomm-vseriald service. On arm64 systems, use the _arm64.deb file.

3. Check the ports and the service:

   ls -l /dev/ttyPDV*
   systemctl status pdcomm-vseriald

   You see four ports, /dev/ttyPDV0 to /dev/ttyPDV3. The service’s default lab joins ttyPDV0 with ttyPDV1 and ttyPDV2 with ttyPDV3 through null-modem cables.

   /etc/pdcomm-vserial/lab.json

   {
     "engine": {
       "pacing": "realistic",
       "nodes": [{"name": "port0"}, {"name": "port1"}, {"name": "port2"}, {"name": "port3"}],
       "media": [
         {"kind": "null_modem", "a": "port0", "b": "port1"},
         {"kind": "null_modem", "a": "port2", "b": "port3"}
       ]
     },
     "ports": [
       {"node": "port0", "backend": {"type": "driver", "index": 0}},
       {"node": "port1", "backend": {"type": "driver", "index": 1}},
       {"node": "port2", "backend": {"type": "driver", "index": 2}},
       {"node": "port3", "backend": {"type": "driver", "index": 3}}
     ]
   }

4. To open the ports as a regular user, add yourself to the dialout group and sign in again:

   sudo usermod -aG dialout "$USER"

Change the wiring or the number of ports

• To change the wiring, edit /etc/pdcomm-vserial/lab.json and run sudo systemctl restart pdcomm-vseriald. Reinstalling the package keeps your edits.

• To change the number of ports (1 to 64), edit ports in /etc/modprobe.d/pdcomm-vserial.conf and reload the module:

  sudo systemctl stop pdcomm-vseriald
  sudo modprobe -r pdcomm_vserial
  sudo modprobe pdcomm_vserial
  sudo systemctl start pdcomm-vseriald

• To run your own lab instead of the service, stop the service first. Only one lab at a time can open the driver’s control device /dev/pdcomm-vserial, and only root can open it.

  sudo systemctl stop pdcomm-vseriald
  sudo pdcomm-vserial run --config my-lab.json

Caution

With Secure Boot on, the kernel refuses unsigned modules. Enroll a module signing key (MOK) as your distribution’s DKMS documentation describes, and check the state with mokutil --sb-state.

Uninstall

sudo apt remove pdcomm-vserial

The package stops the service, unloads the module, and removes it from DKMS.

macOS

Use on macOS

On macOS you use pseudo terminal mode. Put the pdcomm-vserial program in a folder of your choice and add it to your PATH; that’s the whole installation.

pdcomm-vserial --version
pdcomm-vserial pair --link-a /tmp/pdcomm-a --link-b /tmp/pdcomm-b

Applications open the link path (/tmp/pdcomm-a) or the path that the lab prints (/dev/ttys…). For how pseudo terminals differ from UARTs, see How pseudo terminals behave.

Manager GUI and MCP server

• pdcomm-vserial-manager is a GUI that edits and runs labs. It runs the pdcomm-vserial program in its own folder; to use a program elsewhere, set the PDCOMM_VSERIAL_BIN environment variable to its path. See Virtual serial manager.
• pdcomm-vserial-mcp is an MCP server through which AI tools create and control labs. See Control virtual serial ports over MCP.