/*
	Copyright (c) 1999,2000,2001,2002 Grahame M. Kelly (grahame@wildpossum.com)
	formerly (gmkelly@zip.com.au).

	You may distribute and/or use for any purpose modified or unmodified
	copies of this software if you preserve the copyright notice above.

	THIS SOFTWARE IS PROVIDED AS IS AND COME WITH NO WARRANTY OF ANY
	KIND, EITHER EXPRESSED OR IMPLIED.  IN NO EVENT WILL THE
	COPYRIGHT HOLDER BE LIABLE FOR ANY DAMAGES RESULTING FROM THE
	USE OF THIS SOFTWARE.

	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

*/


You should have the following files when you untar the distribution:

BCircuit.txt	Text file with all the wiring details disclosed for the
		RS232 buffer circuits.
Makefile	Just type "make" to create the LinuxSPA executable.
README		This file your reading now.
Sniffer.png	PNG copy of the wiring & concept diagrams (use GIMP to see).
TODO		Future requirements I should undertake to improve system.
LinuxSPA.c	Source Code.
LinuxSPA.h	Source Header File.
std232.c	Source Code of standard RS232 filter.
std232		Executable rs232 filter.
LinuxSPA         Executable serial LinuxSPA.
ascii.flt	User Modifiable Filter data (plain txt file), used by std232.
raw.file	Sample raw output from my Nikon E950 Camera.
cooked.file	Sample cooked output from my Nikon E950 Camera.
connector-1.kil Connection for simple 3 wire circuit (without RS232 buffer).
connector-1.ps	PostScript file for printing connector-1.kil diagram. 
connector-2.kil	Connection for Modem Line Connector in (KDE) Kontour format.
connector-2.ps	PostScript file for printing connector-2.kil diagram.
ChangeLog	A Log containing the changes made over time.
COPYING		GPL Copyright notice.
READING_Mat..	More RS232 programming reading materials.
INSTALL		How to build and run serial-LinuxSPA.


Serial Sniffer - NOTES -

You may ask do I need to use an RS232 buffer circuit (in shown in the
wiring doc and BCircuit concept diagram) or can I simply use a three
wire directo connector (as connect-1.ps & connector-1.kil depict) ?
Answer - It depends on the fanout capability of the RS232 driver of the
device under test (DUT). Most computers use chips that have no problems
accomadating a direct connection. It is a matter of suck'n'see really.
If the data you snif coming from the DUT doesn't make much sense but the
stream from the computer side is OK, then you'll probably require the
RS232 buffer circuits.

This release (0.7) contains command line switches to allow a more 
configureable serial LinuxSPA program. There is no need to play with
LinuxSPA.h or to remake every time you want to modify parameters. It
is all handled by the command line now.

LinuxSPA [OPTIONS]

-A --deviceA  : Application Computer serial port. Default = /dev/ttyS0
-B --deviceB  : Device Under Test serial port. Default = /dev/ttyS1
-b --baudrate : Serial line baudrate (110,300,600,1200,1800,2400,4800,9600,
              : 19200, 38400, 57600, 115200, 230400), Default = 115200
-d --databits : Data Bits (5,6,7 or 8), Default = 8
-h --help     : Help screen
-m --mode     : Sniffer Mode type (1 or 2), Default = 1
-s --stopbits : Number of Stop Bits (1 or 2), Default = 1
-p --parity   : Parity setting (Odd, Even, None), Default = N
-v --verbose  : Verbose flag On
-x --Debug    : Debugger On, Default Off

Additonally, Serial Sniffer has now been set up at sourceforge.net.
Best to got to this site for newer releases, bug fixes and accurate
documentation after May 2002. See the following for more details:
http://sourceforge.net/projects/serialLinuxSPA/



Serial Sniffer - Graphical GNOME Implementation

http://www.geocities.com/cronos1_mx/Gserial-LinuxSPA/
for a work-in-progress development of a nice graphical fontend 
to the serial LinuxSPA.



Serial Sniffer - README -

I wrote this serial LinuxSPA to help me reverse engineer (which is
legal in Australia) my Nikon E950 CoolPix Digital Camera. I wanted to see why
it would not correctly work with the Gphoto s/w. I particularly like the
Gphoto developments and wanted to contribute to the Open Source Community.

Serial Sniffer is a program that can operate in two modes.

Type 1 Mode - 	The RS232 connections are buffered with the aid of
		a two IC circuit ( 1 x 1488, 1 x 1489 IC) that take
		the "load" off the camera which had a poor +/- 5v d.c.
		RS232 swing. While this is OK in most cases I found
		that when doubling up on RS232 inputs the swing 
		deminished greatly. The circuit is simple and is
		given in detail in the Sniffer.png file which you can
		view using the GIMP. 

				Snop Port A
				Rd
				|
	Win98 Tx ---------------+-----------------------> Rd  Digital
	      Rd <-----------------+--------------------- Tx  Camera	
				   |
				   Rd
				Snop Port B


Type 2 Mode -	The RS232 connection is served with a listen and forward
		approach. i.e. The Snop ports read their input and
		there after writes the read value back onto the RS232
		line as the following diagram depicts.


				Snop Port A
				Rd	Tx
				|	|
	Win98 Tx ---------------+	+---------------> Rd  Digital
	      Rd <--------------+	+---------------- Tx  Camera
				|	|
				Tx	Rd
				Snop Port B


Note: I have tested both approaches to Serial Sniffing. Each has its
good and bad features. Type 1 - mode is the preferred mode as it does not
force any i/o retransmission timing restraints on the equipment under test.
Type 2 - mode is good if the timing restraints are not limiting and you
want to make sure of the send and recieve transmission timing is resonabily
track correctly. Which every mode you choose, its sometimes better to do
both to double check your captured data, before committing "excess brain
power" in decrypting the "unknown" protocol. Type 2 mode can also be use
to "vary" the protocol messages if you wish to experiment further.

Before you embark on your debugging efforts, I strongly suggest that you
use a terminal emulation program like Linux - minicom, at the foreign Win98
end, and simply loop back the "camera" end. Key a few characters and see
the sequence of bytes returned by the format section of LinuxSPA. This is
especially important if you are going to intercede the protocol with your
own adjustments as mentioned above. Once you see what you expect, then you
can procede with confidence.

You can try different Unix piping to get the best result you like. e.g.:

"LinuxSPA | tee > ./raw.file | std232 | tee > ./cooked.file"
which will snif the RS232 port, put the raw data from LinuxSPA in file: raw.file
then puts this output thru the std232 filter to produce cooked data that is
then saved to file cooked.file as well as being displayed on your console.

"LinuxSPA | std232 > ./cooked.file" is probably all you need to run for really
simple serial data capture.

If you wish to modify the std232 filter, or better still make your own then
copy ascii.flt and modify it to suit your needs, copy std232.c to another file
say "my232.c" modify the source line #define ASCII  "./ascii.flt" to read
#define ASCII  "./ascii2.flt" where ./ascii2.flt is the name of the ascii.flt
file you copied and modified above. Simple do a "make" and then you can do
your own filtering as follows:

"LinuxSPA | my232 >./mycooked.file" to see your results.


Finally, remember to set TYPE2 to TRUE as TYPE1 is set as the default,
in the LinuxSPA.h file, before doing a "make" which generates the LinuxSPA
executable.

Happy reverse engineering (where it is legal) and enjoy.
Cheers, Grahame.  (grahame@wildpossum.com)
July 19th, 2003.


Note corrections to BCircuits.txt file. 7th Nov, 2003.
Rename made from 19th April, 2002 file.
