scope - Linux Serial Line Analyser
scope is a simple Linux program that allows you to capture data flowing between two devices that communicate over a 7-wire (or fewer) RS232 serial connection. To do this, it requires a special cable. This page tells you how to obtain scope and how to build it, install it, and build the cable.
Table Of Contents
1 Download Instructionsscope is currently at version 0.04. This adds --- lines in continuous mode (-c option) to distinguish between different packets. It has been tested on Red Hat 9, and also builds fine on Ubuntu Linux 5.04.
Prior to this, is was available as part of my linux-ncp package, but has proved very useful, and so I've made it into a package in its own right.
You may download it here: scope-0.04.tar.gz.
Then, do this:
gzip -cd scope-x.xx.tar.gz | tar xvf -(Where x.xx is the version you downloaded).
Then read the file called README. This is displayed below.
2 The README File
Scope: A Serial Line Analyser/Logger for Linux (and possibly other UNIX systems) ============================================== (C) 1999-2005 Matt J Gumbley http://www.gumbley.me.uk/scope.html Introduction ============ Scope is a general-purpose serial line monitor, capable of recording the traffic on an RS232 cable (if provided with a suitable cable and recording computer). Tested On... ------------ It was written for: Red Hat Linux 4.2/Sparc, Red Hat Linux 6.0/Sparc, Red Hat Linux 6.2/Intel Red Hat Linux 9/Intel Ubuntu Linux 5.04/Intel although it should also compile on other UNIXes. You may need to make changes to asy.c. Licensing --------- This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Building and Installing ======================= The program now uses GNU autoconf, thanks to Warren Young. To build, use the usual configure invocations; a 'configure --help' will show you what is supported. Typically, you may wish to place the program in a location other than its default. So, './configure --prefix=/wherever/you/want' is all that's needed. Once configuration is done, type 'make', and then 'make install'. For further information, refer to the file INSTALL, which is ripped verbatim from some other package which uses autoconf ;-) (Note to developers: the configure script supplied was generated with autoconf 2.13-5 on a Red Hat 6.2/Intel system) Specific configure options for this program ------------------------------------------- There are none, yet. How to Use Scope ================ Basically, scope will monitor /dev/ttyS0 and /dev/ttyS1, with output on standard out, at 19200 bps. Use the -d option to suppress the control/status line data (since that's not 100% working), and use other options to control speed, different ports, verbosity etc. scope -h will give a short help file; there is no man page. Capture the output in a file, and use this as input to some of my other programs, such as ncpscope. The Special Serial Cable ------------------------ Scope works best when used in conjunction with a special serial cable. This cable goes inline between the two devices that you want to monitor, and splits signals on the "main" line into two serial ports which are monitored simultaneously to provide a composite view of the current line status. The cable I use connects to a Sun SparcStation 5, which has two serial ports, both D25's - similar to a PC. On a Sparc 10, the two ports (A/B) are housed in a single socket - the cable is wired as follows: SUN PORT A FEMALE MALE SUN PORT B D25 D25 MALE D25 1 - FG ----- 1 2 - TD ----- 2 ------ SRD 16 3 - RD --------- 3 - RD ----- 3 4 - RTS ---- 4 ----- SCTS 13 5 - CTS -------- 5 - CTS ---- 5 6 - DSR -------- 6 - DSR ---- 6 7 - GND -------- 7 - GND ---- 7 8 - DCD -------- 8 - DCD ---- 8 20 - DTR ---- 20 ----- SDCD 12 22 - RI ----- 22 Basically, the first port is used to read most lines, and the second port is used to read TD, RTS and DTR, which are read on the input lines RD, CTS and DCD So wire the second plug: 2 ----------- 3 4 ----------- 5 20 ----------- 8 DISCLAIMER ========== Standard disclaimer applies. If you blow up your systems with this, don't blame me - it works fine (ish) for me. TODO ==== * Make it work properly on Intel Linux (CRTSCTS undeclared for some reason) - this ioctl option is not used on Intel. Add #define CONFIG_M386 in global.h to make this work. * Use select(), don't poll. * Add pass-through mode (for Charlie Stross) - anything coming in on one port is echoed to another.
3 The ChangeLog File
0.04 04/11/2005 Continuous mode now outputs --- lines when there's a delay in data being observed. Helps to distinguish between different packets. 0.03 08/10/2002 Added the following features, from a patch from Warren Young:- It adds the -1 command line argument, which makes it only read from one serial port. I needed this because I was just interested in making it show me what a particular program was sending. - autoconfiscation consequence #1: all the -DUNIX and -DLINUX stuff is gone. - consequence #2: The old CRTSCTS check is also removed, as it doesn't seem necessary. It must have been a bug in the old Linux headers, since that's POSIX standard, I think. (*) The code as it is now works on both RH6.2 and 7.3. If you have a platform where this still breaks, there are better ways of handling this problem with autoconf than platform-specific ifdefs. I can help you code up the necessary autoconf invocations if you don't want to take the time to figure it out yourself. - consequence #3: The "byte" and similar typedefs are now based on the reasonably-portable u_int8_t and similar types usually found in sys/types.h. If you have a platform that doesn't have these typedefs, again, there are ways to extend autoconf to detect that platform's sized int typedef style. - I removed several skeleton files like 'src/header'. I don't think they belong in a source distribution. - Obviously the makefile structure is now different. A lot of the code you had in your makefiles is replaced by autoconf. For example, the "forwarding" targets so that "make clean" in the top level also does a clean in src. Also things like VERSION and the install directory stuff already exist in autoconf/automake. - Several of the Makefile targets weren't ported to automake, like the backup one. If you still want these, just add them to Makefile.am. You might check to see if there's an equivalent already, though. The "tar up the source code" target isn't needed any more, for example, because "make dist" will do what you want now. (Or if it doesn't, it can be fixed so that it does, rather than replacing the target with a hand-rolled version.)Many thanks, Warren! (*) Matt thinks this may have been a Sparc Red Hat Linux 6.0 thing; he's not bothered about that version, since he's on 6.2 now. If this is an issue for you, earlier versions of scope are availabel from the project home page. Added -w "write this string" option, which writes the given string out on the first port, then starts monitoring. You can include returns, e.g.: -w "AT&V\\r" which on some modems will cause a settings dump to be generated. 0.02 20/02/2002 Added fix for compile error on RH7.x, from a patch by Grant Edwards: "The 'timezone' struct has been obsoleted, so I've jettisoned it. Passing a NULL for the second parameter to gettimeofday is backward compatible at least as far back as RH6. FWIW, I verified that the same change will work under Solaris (though asy.c doesn't compiler -- no surprise there). I've also added an "#include" or two to get rid of some warnings about implicit declarations of exit() and strcpy()." Thanks, Grant!