This file documents Tap, a program to read data from (and write data to) a serial port.  Amongst other things, it may be used to facilitate the reverse engineering of serial communication protocols.

Copyright © 1999 Jonathan E duSaint jon@mbayweb.com.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled ``Copying'' and ``GNU General Public License'' are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

Tap
***

Tap is a program designed to read data from and write data to the serial port.  As such it has a wide variety of applications.  For example, it can be used to prototype serial hardware, or to read data from a serial line tap, which can facilitate the reverse engineering of serial line communication protocols.

This documentation corresponds with version 1.0 of Tap.

Introduction
************

This chapter serves as an introduction to the manual as well as to Tap, and documents the command line options.

Conventions
===========

The syntax C-whatever means to press the Control key and to simultaneously press the whatever key.  For example, C-P means to hold down the Control key, and then hit the P key.

When the command definitions are presented, the command usage is put first.  Then follows a description of the function.  If there is more than one way to use a function, then each invocation is shown with an explanation after it.

Invocation
==========

To start Tap, merely type tap at the shell prompt.  If it is properly installed, you should be presented with the interface.  If it isn't, then read the file INSTALL for information on how to do so.  Tap can be invoked with several different command line options.

--help
------

--help, -h

Invoking Tap with this option will cause Tap to print a short help message to STDOUT and then exit.

--version
---------

--version, -v

Invoking Tap with this option will cause Tap to print version and copyright information to STDOUT and then exit.

--port
------

--port serial port, -p serial port

With this option, Tap will open serial port at startup. If the serial port can't be opened, Tap will print an error message at startup.

--save-history
--------------

--save-history history filename, -s history filename

This option will cause Tap to read history information at startup from the file specified and to write history information at shutdown to the file.  If the file specified doesn't exist, it will be created, and if no file is specified, the default will be used, which is usually ~/.tap_history.

Overview
========

This overview assumes that tap is already properly installed on your system.  If it isn't, read the file INSTALL for instructions.

To start, invoke tap from the command line by typing tap. Once it is started, you will notice that the screen is divided into two parts, both with headers.  The top part is called the input window and the bottom part is called the output window.  At the bottom of the screen is the status bar.  It should state that no serial port is open on one side, and suggest typing help for help.

As a first experiment, try typing help.  You will be presented with a brief summary of all of the commands available.  To get more specific help information, type help command-name

The Command Line
****************

If you are familiar with Bash or Emacs, then you should already have a good grasp of most of the functionality of the command line interface.  While Tap doesn't actually use the GNU Readline or the GNU History libraries, the interface was designed to be very similar.  All commands are saved in a history list, although if a command is repeated one or more times, only one copy is saved.  Also, while entering text on the command line, a variety of keystrokes are available for command line editing.

History
=======

Every time a command is entered, it is automatically inserted into the internal history list.  However, if the command is identical to the previous command, a list entry is not made.

To access previous entries, press either Up Arrow, or C-P.  To access more recent entries, press either Down Arrow, or C-N.

If a previous entry is edited and Enter is not pressed, the edited copy will be saved in the place of the original.  However, once Enter is pressed, the original copy will once again be available.

When Tap is invoked with the --save-history (see save-history) option, all history entries are read at startup from the file specified, or, if one isn't specified, from the default file.  At shutdown, the current history list is appended onto the file.

If a file is specified that doesn't exist, then one will be created at shutdown.

Editing
=======

Tap contains features for editing the current command line.  The keystrokes are the same as used in Emacs and in the Bash shell's Emacs mode.

Moving Left
-----------

C-B, Left Arrow

Both of these keystrokes will move the point one character to the left, if possible.

Moving Right
------------

C-F, Right Arrow

Both of these keystrokes will move the point one character to the right, if possible.

C-A
---

C-A

This keystroke will move the point to the start of the line.

C-E
---

C-E

This keystroke will move the point to the end of the line.

C-D
---

C-D, Delete

Both of these keystrokes will delete the character under the point.

C-H
---

C-H, Backspace

Both of these keystrokes will delete the character to the left of the point.

C-U
---

C-U

This command prompts for a number.  After the number is entered, press Enter, and then the desired key.  If the key entered was C-Y (see Killing and Yanking Text), then text from the kill ring will be entered.  If Enter was pressed, then it will be just as if Enter had been pressed without the argument (i.e. the command line will be processed).  Any other key will be repeated as many times as was indicated by the number.

For example, type

     C-U 2 0 Enter a

to insert 20 copies of the letter `a', or type

     C-U 5 Enter C-D

to delete the character under the point and four to the right of it.

Killing and Yanking Text
------------------------

C-space  Set the mark.

C-W      Kill the text from the mark to the point.

C-K      Kill the text from the mark to the end of the line.

C-Y      Yank from the kill ring and insert it at the point.

Tap utilizes a kill ring for storage of text which has been killed using the above commands.  The single character delete commands will not store anything to the ring.

The C-Y command will only yank the most recent entry.  In order to yank older entries than that, it must be used in combination with the C-U command (see C-U).  For example, type

     C-U 3 Enter C-Y

to insert the text from the third to last kill.

C-T
---

C-T

This keystroke transposes the character under the point with the character to its left.

C-L
---

C-L

This keystroke clears the screen and redraws the current line.

See clear.

tab
---

tab

Pressing the tab key will complete the token under the point, if at all possible.  If the point is over the first token, then a command completion will be attempted.  If it is over any other token, a completion will be attempted, based on the arguments that the command takes.  If only a partial completion is possible, the token is completed as far as it can be, and all of the matching completions are printed out.  If no completion is possible, the program just beeps.

Command Overview
****************

These are descriptions of all of the commands.  Some commands are documented elsewhere, so for them, there will be only a short description.

alias
=====

alias

Invoking alias with no arguments will print out all of the aliases which have been assigned.

alias ALIAS

The alias command with one argument will print out the alias and the command to which it is aliased.

alias ALIAS COMMAND

With two options, alias will assign ALIAS to COMMAND so that when ALIAS is entered, the program will act as if COMMAND itself had been entered.

This command can be very useful to decrease the amount of typing necessary.  If, for example, the out (see out) command were to be aliased to o, then rather than typing

     out foo bar\n

it would be possible to merely type

     o foo bar\n

which doesn't save that much typing, but does illustrate the point.

However, alias is limited to aliasing commands only, so it is not possible to type something like

     alias bin 'set if bin'

Also see unalias.

capture
=======

capture file filename

When invoked in this manner, capture starts capturing data recieved from the serial port to filename.  Only one file may be open at a time.

capture file off

This causes Tap to stop capturing data and to close the file.

capture register 1--64

capture, when invoked like this, will cause Tap to start capturing data to a register.  Data is captured until it is turned off, as described below, or the register is full.  The size of the registers may be changed by using the command set.

capture register off

This stops the capturing to the register.

See set, and The Set Command.

clear
=====

clear

Invoking clear will clear the input window.

See C-L.

close
=====

close

This command closes the currently open serial port.

help
====

help

When invoked without a command name, help prints a short description of every command.

help command name

This provides help on individual commands.

open
====

open serial port

open opens a serial port and prepares it for communication.  The properties of the serial port may be changed with the command set.

See set.

out
===

out data

The out command writes data to the serial port.

See Input and Output.

print
=====

print file

If a file is currently being captured to, this will print the contents of that file.  If no file is open, then an error will be thrown.

print file filename

This prints the contents of the file specified in filename.

print file filename bytes

This does the same as above, but only prints the first bytes number of bytes.

print register

If a register is currently being captured to, this will print its contents.  If one isn't being used, then an error will be thrown.

print register register number

This will print the contents of the register specified.

print register register number bytes

This will print the first bytes number of bytes of the specified register.

quit
====

quit

This command quits the program, closing any open files and the serial port, if one is open.

set
===

set options

The set command adjusts various run time parameters of Tap.  See The Set Command, for a full explanation.

unalias
=======

unalias alias

The unalias command removes the alias alias from the alias list.

Input and Output
****************

The Set Command
***************

Often, while working with Tap, you will find that you might want to change some of the operational parameters.