ttypatch Project Home

ttypatch is an opensource project hosted at Sourceforge.net.
Click Here for downloads, forums, bug reports, and news.
Click Here for the user's guide.

ttypatch functionality

ttypatch allows programs that expect to use serial ports to communicate with each other without the use of real serial ports. The program brings serial port device files into existence and "patches" them together. User programs can then open these serial ports and read, write, and control them exactly like "real" serial ports. ttypatch is controlled by the command line, config files, and the console. The functionality includes:

Bring a number of pseudo serial devices into existence
Open real serial devices
Connect, disconnect, and rearrange pairs of devices
monitor or cease monitoring any number of connections

Why ttypatch?

It started with a simple problem. I wanted to develop an application for my Palm M100 to allow it to control a TINI via a serial port connection. The Palm development environment includes POSE, an emulator running on Linux that can control a real PC serial port as part of emulating the Palm. Similarly, the TINI development environment can control a real PC serial port. Unfortunately, I do not have two spare serial ports and a null-modem cable. Furthermore, I would like to be able to monitor the serial connection as part of debugging. I searched the Web in vain for a solution, and finally gave up and wrote ttypatch. If you know a better way to do this, please let me know. As it happens, FreeBSD can almost do this with the "null modem device."

Uses for ttypatch

Connect serial applications without a null modem cable.
Switch a single serial port among multiple applications without restarting them
Switch an application among several serial ports
Virtual datascope
Real datascope

Just Pseudoterminals? Almost, but not quite

There is in fact a simpler way: simply tell one of your applications to use a pseudoterminal master as its serial device (e.g. use /dev/ptyqe,) while the other application uses the corresponding pseudoterminal slave (e.g., /dev/ttyqe.) This is a kludge. It might work if the first application uses only a subset of the serial API, and that subset is also a subset of the master API. However, there are dozens of things that can go wrong with this, and most of them do. The result is likely to fail in ways that ruin your whole day, or at least take all the fun out of debugging. The FreeBSD "null modem device driver" solves some but not all of these problems, but I'm a Linux person.

By contrast, the connection via ttypatch should be at least as robust as a null modem connection, and monitoring and control should make debugging a great deal easier.

Background

Many Unix application programs are written to use a serial port. These programs can e.g. open the character device file /dev/ttyS0 and control the flow of data to and from a particular RS-232 connector on the back panel of a PC running Linux. These programs use the POSIX tty API. They expect the OS to support the semantics of this API for the device file they open. Linux provides a number of such devices (e.g., /dev/ttyS0) associated with actual serial ports. Linux can also provide a number of such device files (e.g. /dev/ttyp0) which are the user side of a software construct known as a pseudoterminal. Thus any program such as pose that can open a serial port, can open the user side of a pseudoterminal instead.

On a Linux system each user-side pseudoterminal device is brought into existence by the OS when a specialized program opens the corresponding master-side pseudoterminal device. The master side has different semantics, as defined by the pty API. A program that is properly written to use the pty API and semantics can open a master-side port. When such a program opens the master-side and a "normal" program opens the user side, the pty driver in the kernel sends data and signals back and forth between the programs. A master-side program is typically a specialized program that is specifically written to "pretend" it is at the far end of a wire connected via a real local serial port. An example is telnetd, which pretends it is a terminal.

ttypatch Design

ttypatch is a console program. If I decide a GUI is useful, I'll write a GUI wrapper for it later. Based on the command line or on a config file, the program opens a number of master pseudoterminal ports. This will cause Linux to bring the associated slave "serial ports" into existence. Based on the configuration, ttypatch will "patch" the ports together in pairs. When a pair is patched, input received on one port of the pair will be sent to the other port of the pair. ttypatch can also act as a datascope. Each port can be configured to be monitored. When a port is monitored, any character received from the port will be written to the monitor file together with the time and input port. Finally, ttypatch can use real serial ports in addition to pseudoterminals. This makes ttypatch a functional superset of interceptty.

ttypatch looks for a config file named ~/.ttypatch, unless the commandline specifies a different file or no file. If there is no config file and no commandline options, ttypatch will try to establish /dev/ptyp0 and /dev/ptyp1, and patch them to each other. There is a command line option for the first pty (defaults to p0) and for the number of ptys (defaults to 2) and for patching (defaults to patching in pairs) and for monitoring (defaults to no monitoring.)

When the program runs, it will accept commands from the console to initiate and terminate patches, ports, and monitoring.

The program works by listening for input on any port. When input is detected, the program writes to the the patched port and to the monitor, as appropriate. The prpgram uss the POSIX "select" function to efficiently listen to multiple ports at the same time.

ttypatch Development Status

ttypatch-1.0.1 implements the functionality described above, except for "real" serial ports. However, it is rough around the edges. It is not yet a proper Linux "install package." Rather, it is delivered as a tarball that contains C files, a makefile, the GPL, and some HTML documents. It has been built and tested on exactly one system, a pentium-based system running Mandrake Linux 9.0.

Successes

Simple Pairwise Connection of a pair of applications using pseudoterminals:

Reporter	program 1	program 2	application
Dan Clemmensen	POSE	palm-link	hotsync
Dan Clemmensen	vt100 on POSE	minicom	two-way ASCII terminal
Dan Clemmensen	testty	testty	two-way ASCII terminal
Dan Clemmensen	autotesttty	autotesttty	binary tester for ttypatch

TO DO

Add support for real serial ports
Create a proper install package
Place project into CVS on sourceforge
Test on many platforms.
Add support for forwarding serial port <break>
Add support for forwarding other serial port events (are there any?)
Add GUI wrapper