ttypatch User Guide

ttypatch is an opensource project hosted at http://ttypatch.sourceforge.net. Feedback and help with improvements
is greatly appreciated.

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.  ttypatch can:

Uses for ttypatch

Installation

ttypatch-1.0 uses a very crude installation. This means that you will probably need to tweak it unless you are running on Linux, and perhaps even then.

pick a directory and move the tarball into it. Then, in a shell, issue the following commands:

tar xzvf ttypatch-1.0.tar.gz
cd ttypatch-1.0
make

If all goes well, your directory will now contain executable files named ttypatch, testty, and aoutesttty. If not, you will need to tweak the makefile and re-run make. If you do not know how to do this, please wait for the next version (which is intended to have a better config), or go to the forum on the ttypatch homepage and post a question.

Testing the Installation

Test the result as follows. First make sure you do not have a config file:
     rm ~/.ttypatch
If you do have a config file, you probably do not need these instructions!
Bring up two separate shells. in the first shell, type
./ttypatch

You should see the ttypatch prompt:
ttypatch>

type
l

(i.e. the lowercase letter L.) this is the "list" command. You should see:
/dev/ptyp0 -> /dev/ptyp1
/dev/ptyp1 -> /dev/ptyp0
STDIN -> <nothing>
ttypatch>

This shows that ttypatch established its default configuration, since you do not have a config file and you did not type in any command line options. The default config has established two ports and connected them to each other.
Now, in the other shell, type the following:
./autotesttty

After a short while, you should see:

sent 255 characters each way with 0 errors


Autotesttty is a very simple program that opens two serial ports check for correct transmission of all characters in each direction.

Overview: Using ttypatch

If you already know why you want to use ttypatch, you can skip this section and go directly to the Configuration section.

Connecting two Serial Port Applications

You can use ttypatch for a variety of functions. Configuration and control is intended to be very simple if you have a simple application, but it can become complicated when your application is complex. As you saw above, to connect a pair of serial applications you need do nothing except run ttypatch. If you need to support more applications, or applications that use more serial ports, configure more. Monitoring is off by default. if you need to see what is being sent from an application on a port, you can configure monitoring on that port.

ttypatch  uses the pseudoterminal masters provided by the operating system to provide its services. These pseudoterminal masters are usually called /dev/ptyp0, etc.  Each pseudoterminal used by patch causes  another virtual serial device to come into existence. The name of a virtual device is related to the name of the corresponding pseudoterminal master: /dev/ptyp0 brings /dev/ttyp0 into existence. A Linux system with a default config has 256 psedoterminal masters named /dev/ptyXY, where X is a letter from 'p' to 'z' or from 'a' to 'e', and Y is a hexidecimal number from '0' to '9' or from 'a' to 'f'.  ttypatch is not the only user of these pseudoterminals. If you have problems with using /dev/pty0, you may have a conflict. In this case, you can configure ttypatch to use a different range of pseudoterminals.  (ttypatch could in theory play by the rules and dynamically pick pseudoterminals rather than using a configured range. However, this is harder to explain to users.) If you need the services of ttypatch all the time, you may want to run ttypatch as a daemon from the sytem init file. (You must be the system administrator to do this, but you would need to be the system administrator to make this decision anyway.) This will ensure that ttypatch always allocates the pseudoterminals it needs before other users start to acquire them.

Virtual Datascope

ttypatch can be used to interpose a datascope between an application and a real serial port. To do this, configure the real serial port on addition to a virtual port, configure a patch between the two, and configure monitoring on both. Now, any traffic from the application or from the outside world will be monitored.

Real Datascope

OK, you've debugged two applications in emulation, downloaded them to two real serial devices, and plugged them into each other, but something is still wrong. Now, you need to monitor the serial interaction between the devices. OK, simply configure two real serial ports on ttypatch and configure a patch and monitoring on them. plug the two devices into the two real ports. Now you have a datascope.

Serial Port Selector

You have several real serial ports, and you want to use a single running instance of an application to speak to then in turn for some reason. (Why? this seems dumb.) No problem. Just configure multiple serial ports and one pseudoterminal. Use the console commands to move the patch.

Application Selector

You have one serial port connected to an external device, but you need to swap among several applications that each wish to communicate with the device, without restarting anything. (This actually happens quite a bit.) Simple. configure multiple pseudoterminals and a single real serial port. Use the console commands to move the patch.

Virtual Patch Panel

All of the above applications are actually specific instances of the generic virtual patch panel. The patch panel has as many pseudoterminals as you need to support local applications, and as many real serial ports as your hardware can support, together with as many datascopes as you care to use.

Configuring ttypatch

You can configure ttypatch three ways: from the commandline, via a config file, and by entering console commands. As you saw while testing, in the absence of a config file and with no commandline options, ttypatch creates a pair of pseudoterminals and patches them to each other.

If there is a config file in the default location, or if a config file is specified on the command line, then the rest of the command line is ignored.

Commandline Options

Usage: ./ttypatch [-v] [-c configfile] [-o output-file] [-p /dev/ptyXY] [-n nbr]
  -v            --Activate verbose mode
  -c configfile --file of initial commands (defaults to ~/.ttypatch)
  -o output-file--Write intercepted data to output-file
  -p /dev/ptyXY --Full path to first pty (defaults to /dev/ptyp0)
  -n nbr        --number of pty devices (defaults to 2)

Config Files

A config file is simply a file containing a set of console commands. If the -c option is present on the commandline, the default file is not read. If the default file is present,  and no -c option is present, then it is read.

Console Commands

The console is usually the shell from which ttypatch is read. All the usual rules apply for console redirection. ttypatch continually monitors the console for new commands. Commands directly from the console are not echoed to the console. commands from a file (including the config file) are echoed to the console.

The commands are all a single letter command, perhaps followed by one or more parameters and terminated by end-of-line. Parameters
are separated by whitespace (tabs or spaces.)

the commands are:

A command is a single command character optionally followed by space-delimited parameters.
In all cases below <dev> is the full pathname of a character file, e.g. /dev/ptyp0

m <dev> [yes|no|toggle]  -- monitor a device (default is toggle)
p <dev> <dev>            -- patch two devices
u <dev>                  -- unpatch. both ends of the patch are unpatched
a <dev> [nbr]            -- add one or more sequential pseudoterminals
                              (automatically patched in pairs)
s <dev>                  -- add a "real" serial port
r <dev> [nbr]            -- remove one or more sequential devices
c <commandfile>          -- execute commands in the named command file
l                        -- list current patches and monitors
q                        -- exit the program
h                        -- print this help text
There are a few quirks here. In the current release (ttypatch-1.0) the <dev> is the master pseudoterminal, not the
user serial terminal. Also, quitting the program is a bad idea unless you first terminate the user applications.

Acknowledgements

While trying to find an existing solution for eliminating the null modem cable, I found a program by Scott W. Gifford called interceptty, with a home page at http://www.suspectclass.com/~sgifford/interceptty.  ttypatch  started as a  modification to  that code. The functionality, and the code, is now so different that I consider ttypatch to be "inspired by" interceptty, but not derived from it. Nevertheless, I really appreciate not having to start from scratch.  Scott has given me some pointers on doing a real config, but I haven't implemented it yet.

I found Dave's name on a message on the pose forum: he was having problems using the pty directly. I contacted him, and he offered to test ttypatch. [Dave: if you prefer to have your full name in the acknowledgement, let me know.]

Hosted at:  SourceForge.net Logo