#serial #virtual #router

bin+lib vsp-router

Create virtual serial ports, connect them to physical serial ports, and create routes between them all

7 releases (4 stable)

1.0.3 Aug 15, 2024
1.0.1 Aug 2, 2023
0.2.0 Oct 29, 2022
0.1.1 Sep 12, 2022
0.1.0 Sep 11, 2022

#243 in Command line utilities

Download history 192/week @ 2024-08-13 9/week @ 2024-09-10 7/week @ 2024-09-17 31/week @ 2024-09-24 11/week @ 2024-10-01

291 downloads per month

MIT/Apache

25KB
380 lines

Virtual Serial Port Router (vsp-router)

Build status Crates.io

Create virtual serial ports, connect them to physical serial ports, and create routes between them all.

Vsp-router was created to connect two terminal emulators to the same physical RS-232 serial console.

asciicast

Supported Operating Systems

  • Linux: Yes, tested on Red Hat Enterprise Linux 8
  • macOS: Yes, tested on macOS Ventura 13.1
  • Windows: Yes*, tested on Windows 10

*The Windows version does not support creation of virtual serial ports. A third-party tool like com0com can be used instead.

Use Cases

Multiplex two virtual serial ports to a single physical serial port.

vsp-router \
    --create 0 \
    --create 1 \
    --attach 2:/dev/ttyUSB0 \
    --route 0:2 \
    --route 1:2 \
    --route 2:0 \
    --route 2:1

Multiplex two virtual serial ports to a third virtual serial port.

vsp-router \
    --create 0 \
    --create 1 \
    --create 2 \
    --route 0:2 \
    --route 1:2 \
    --route 2:0 \
    --route 2:1

Example

In terminal A

cargo run -- \
    --create 0 \
    --create 1 \
    --create 2 \
    --route 0:2 \
    --route 1:2 \
    --route 2:0 \
    --route 2:1

In terminal 0

picocom 0

In terminal 1

picocom 1

In terminal 2

picocom 2

Characters entered in terminal 0 will be sent to terminal 2 only.
Characters entered in terminal 1 will be sent to terminal 2 only.
Characters entered in terminal 2 will be sent to both terminals 0 and 1.

Connection to a Virtual Serial Port

Virtual serial ports created by vsp-router behave a bit differently from physical serial ports:

  • You can connect to them using any baud rate. You are not forced to use the same baud rate as the physical serial port you are multiplexing.
  • When you don't read from them they accumulate data in a buffer. When this buffer becomes full new data will be discarded and a warning message will be shown in the logs. Any buffered data will get returned when you next read from them.

To avoid reading stale data accumulated in the buffer when you want to read from the virtual serial port it is recommended to flush its input buffer before you first read from it. This can be done using tcflush(fd, TCIFLUSH) (or equivalent on your platform) on the file descriptor of the virtual serial port.

Comparison to TTYBUS

vsp-router is similar to TTYBUS.

The key differences is in how data is written. TTYBUS broadcasts data to all ports. vsp-router routes data to select ports.

The following 3-port configurations are the equivalent.

TTYBUS

tty_bus -d -s bus
tty_fake -d -s bus 0
tty_fake -d -s bus 1
tty_fake -d -s bus 2

vsp-router

vsp-router \
    --create 0 \
    --create 1 \
    --create 2 \
    --route 0:1 \
    --route 0:2 \
    --route 1:0 \
    --route 1:2 \
    --route 2:0 \
    --route 2:1

Comparison to socat

Socat establishes a bidirectional channel between two end points. Vsp-router establishes a multi-directional channel between N end points. Socat supports several different types of end points. Vsp-router supports two: virtual serial ports and physical serial ports.

Vsp-router could be combined with socat to enable interesting use cases. For example, vsp-router could be used to snoop a physical serial port and paired with socat to send the snooped data over UDP.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~9–19MB
~248K SLoC