|FreeVR: Virtual Reality Integration Library|
SERIALSPYSection: FreeVR Commands (1FV)
Updated: 18 September 2013
Index Return to Main Contents
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).All other typed characters are sent over the serial line directly to the device. Thus, passthrough mode is generally used when there is a need to send characters to the device that would otherwise be captured and consumed by the serialspy interactive mode. NOTE: all interactivity is disabled after entering "passthru" mode.
The program is terminated by pressing the 'q' or interrupt key (usually ^C). (When in pass-thru mode, the 'q' method will not work.)
Communicate with a Magellan SpaceMouse device on serial port /dev/ttyUSB0 at baud rate 38400:
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.
Copyright 2013, Bill Sherman, All rights reserved.
This document was created by man2html, using the manual pages.
Time: 05:02:19 GMT, December 13, 2013