Tools quickstart

In five minutes you connect two virtual serial ports with a null-modem cable, send bytes across, and inject a fault that the receiving side sees. For the concepts, see How virtual serial ports work.

Before you begin

• You need macOS or Linux and three terminals. This quickstart uses pseudo terminals (pty), so you don’t install a driver.

• The pdcomm-vserial program must be on your PATH. The Linux package installs it as /usr/bin/pdcomm-vserial. Check the version:

  pdcomm-vserial --version

  The program prints its version, for example pdcomm-vserial 0.1.0.

Note

On Windows you use installed COM ports instead of pseudo terminals. Follow the Windows steps in Install virtual serial ports.

Create a virtual pair

1. In terminal 1, start the pair. --link-a and --link-b add a symbolic link at a fixed path for each port.

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

   When the lab is ready, it prints its ports as one JSON line. The path values change from run to run.

   {"ports":[{"backend":"pty","link":"/tmp/pdcomm-a","node":"a","path":"/dev/ttys011"},{"backend":"pty","link":"/tmp/pdcomm-b","node":"b","path":"/dev/ttys016"}],"ready":true}

   The terminal now waits for commands that control the lab. Keep it open.

2. In terminal 2, print what port b receives:

   cat /tmp/pdcomm-b

3. In terminal 3, send a string to port a:

   printf 'hello\n' > /tmp/pdcomm-a

   hello appears in terminal 2. The pair runs at 9600 bit/s 8N1 and, like a real line, delivers one character per character time.

4. In terminal 1, type the following command and press Enter. It flips bit 0x20 in the next character that port b receives.

   {"command":"inject","node":"b","fault":{"xor":32}}

   The lab replies {"ok":true}.

5. In terminal 3, send again:

   printf 'ABC\n' > /tmp/pdcomm-a

   Terminal 2 shows aBC: only the first character changed, from A (0x41) to a (0x61).

6. In terminal 1, stop the lab:

   {"command":"stop"}

   Closing the input with Ctrl+D stops the lab too. The lab removes the /tmp/pdcomm-a and /tmp/pdcomm-b links and exits with code 0. Press Ctrl+C to end cat in terminal 2.

Common errors

Symptom	Fix
pdcomm-vserial: /tmp/pdcomm-a exists and is not a symlink	A regular file is in the way. Delete it or choose another path. The lab replaces symbolic links that an earlier lab left behind.
Nothing appears in terminal 2	Check the link names. The sending port (a) and the receiving port (b) must differ.
A command returns {"ok":false,"error":"unknown node …"}	Use a node name of the lab (a or b) in node.

Next steps

• Put a real protocol on a virtual bus: Test Modbus RTU on a virtual RS-485 bus.
• Look up every command and setting in pdcomm-vserial commands and lab files.
• Do the same from a GUI with the virtual serial manager.