SERIALSPY

NAME

serialspy — a tool to examine and interact with the serial protocol used by RS-232 based I/O devices.  

SYNOPSIS

serialspy [-l <line>] [-b <baud>] [-f <frequency>] [-mb <max bytes>] [-1] [-pseudo] [-pt] [-flag <byte>] [-asc|-noasc] [-bin|-nobin] [-hex|-nohex]  

DESCRIPTION

The serialspy program is a tool for determining interface protocols between devices and software over serial lines. It can either work as a direct interface to a device, or as a man-in-the-middle interceptor. In either case it outputs data to a terminal or a file while at the same time passing data back and forth with the device. For some devices it is possible to determine the interface protocol merely by typing in commands (often starting with '?' or 'help'), sending them to the device and then viewing the response — many devices have a help message that they will output. For other devices, a working connection with a known driver or software that understands the protocol is the best way to learn what the communications look like.

Lines are preceded with the number of bytes on that line. NOTE: Unlike with socketspy, there is no directional indicator for the data, as it has generally been used as a uni-directional tool.

The default representation of the data is in one byte (two-digit) hexadecimal numbers in one column and ASCII values in another column. By default, after 16 values are printed a new line is begun.

Values for which the high bit is set (0x80 - 0xff) are highlighted in red. This can sometimes make it easier to see patterns in the data. In addition, one other value can be specified as the "flag" value, and it will be highlighted in green. If one knows or has a guess as to what value might always indicate the beginning of a packet, then flagging this byte can make it easier to notice the size of the packets.

There are a number of interactive commands that can be given via live keyboard input to help parse the data as it streams. In particular, if there is an obvious stride to the data, then adjusting the number of bytes per line (the frequency value) can be used to match the stride and view packets more naturally. In addition, the beginning of the line can be (phase) shifted one byte left or right to attempt to line up the beginning of regularly sized packets with the left-most column.

There are three types of information that can be displayed for each byte: the hexadecimal value, the ASCII value and the binary representation. By default serialspy will display only the hexadecimal values. What is displayed can be adjusted both by command-line-arguments, as well as interactively with the keyboard.

Several of the serialspy options can be adjusted live, while data is streaming. These options can then be used to effectively modify the representation of the stream and make it easier to decipher what is going on. The interactive commands are:

        'q' - quit
        '?' - print help information for the interactive keys
        '+' - increase the frequency
        '-' - decrease the frequency
        '>' - shift the phase to the right
        '<' - shift the phase to the left
        '0' - print remaining bytes in buffer
                (essentially a big phase shift left)
        'a' - toggle ASCII output display
        'b' - toggle binary output display
        'h' - toggle hex output display
        (backspace) - go into passthru mode
                (from which there currently is no return).

The program is terminated by pressing the 'q' or interrupt key (usually ^C). (When in pass-thru mode, the 'q' method will not work.)

OPTIONS

-l <line>

The -l option sets the filename of the serial device over which to communicate with the I/O device. On Linux systems the default is generally "/dev/ttyS0".

-b <baud>

The -b option sets the baud rate to use when communicating with the device. When set to a baud rate that the device is not using, either garbage or no valid values will be returned. Often the baud rate of the device will be on a label on the device, or there will be dip-switches available to set a specific baud rate. In other cases one has to experiment with several baud rates before finding the rate used by the device. The default baud is 115200.

-f <frequency>

The -f option sets the "frequency" of the output, which is to say the number of values that will be displayed on each line. The default value is 16. This value can be interactively changed with the '+' and '-' keys.

-mb <max bytes>

The -mb option sets a maximum number of bytes that serialspy will process before ending operation. This allows one to have the program quit fairly early before pages and pages of data stream by, with perhaps the most interesting data (the initial interrogation) scrolling past the buffer and being lost. By default this feature is disabled, and assigning any negative value will serve to disable this feature.

-1

The -1 option sets the one-time flag that will do only one read from the device or server, process that data and then quit. Thus, however much data is ingested during the first read is all that will be processed.

-pt

The -pt option puts serialspy directly into pass-thru mode. Pass-thru mode signifies that serialspy will NOT b reading the keyboard and thus not allowing interactive changes to the data stream display.

-pseudo

The -pseudo option creates a pseudo serial device that can be used to enable man-in-the-middle spying on the communications between the I/O device and working software. When this option is specified, the name of the newly created pseudo serial port will be output to the terminal, and should then be specified as the device for the software to communicate with the I/O device. NOTE: a shortcoming of this method is that is does not provide an option to use a second physical RS-232 port as the link to the software side of the communications. So, viewing the communications with software on a non-Linux PC is not possible.

-flag <byte>

The -flag option allows one byte value to be set as a value to highlight as the data streams by. This can be useful if one knows (or guesses) what value might be included in all packet headers and thus can see a marker that is associated with the beginning of each packet. By default no byte value will be flagged.

NOTE: the value is specified as a decimal number [0..255], but will be echoed back as a hexadecimal number.

-asc or -noasc

The -asc/-noasc options enable/disable the output of ASCII representation of each byte. The ASCII representation is on by default.

-bin or -nobin

The -bin/-nobin options enable/disable the output of binary representation of each byte. The binary representation is off by default.

-hex or -nohex

The -hex/-nohex options enable/disable the output of hexadecimal representation of each byte. The hexadecimal representation is on by default.

EXAMPLES

Communicate with a Magellan SpaceMouse device on serial port /dev/ttyUSB0 at baud rate 38400:

% serialspy -b 38400 -l /dev/ttyUSB0

BUGS

serialspy should do a clean exit when an interrupt signal (or others) is received.

There should be an option to specify the software side of the communications as a physical RS-232 port to enable the ability to view communications with software running on non-Linux operating systems.

We need to figure out how to disable shell processing of keyboard keys, so hitting ^M sends a 0x0d rather than a 0x0a.  

TODO

*

Consider adding the "From Server:" and "From Client:" markers (or "From Device:").

SEE ALSO

socketspy(1fv), freevr(7fv)  

LOCATION

The source code for serialspy is in the "serialspy.c" file, which includes the vr_serial.c source.  

COPYRIGHT

Copyright 2024, Bill Sherman, All rights reserved.

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLES

BUGS

TODO

SEE ALSO

LOCATION

COPYRIGHT