














			D I G I T A L  C O M M A N D  C O N T R O L

			     P R O T O C O L  A N A L Y S E R 
				












				     U S E R  G U I D E













				    (c) Bob Backway 1995

			    Australian Digital Command Control












			CONTENTS



		1.0	Overview				1
			1.1	Licence agreement		1
			1.2	Disclaimer			1

		2.0	Quick Start				2

		3.0	Software Installation			2

		4.0	Hardware Installation			2

		5.0	Data Acquisition			3
			5.1	Loading Data Files		3
			5.2	Sampling Data			3
			5.3	Saving Data Files		3

		6.0	Changing Parameters			4
			6.1	Selecting Protocol		4
			6.2	Selecting Mode			4
			6.3	Buffer Size			4
			6.4	Filtering Data			4
			
		7.0	Display Options				5
			7.1	Decoded Display			5
			7.2	Raw Data Display		5
		
		8.0	Oscilloscope Mode			6
		
		9.0	When things go wrong :-(		6

	       10.0	Contacting ADDC				6
				




		This document pertains to Version 1.0 dated 21/07/95		

(c)ADCC1995										    1

1.	OVERVIEW

With Australian Digital Command Controls Protocol Analyser and your IBM PC compatible machine you will finally be able to see what's in those packets as they appear on the track. You can view the waveform itself, view the raw data as a string of ones and zeros or view the packets in a completely decoded form. The data samples can be saved and later loaded for view and the data itself can be filtered to an individual address for ease of viewing. The fully decoded packet includes preamble, error byte and synchronisation information.

The National Model Railroad Association (NMRA) Standards and Recommended Practices relevant to this product are:
	S-9.0
	S-9.1
	S-9.2
	RP-9.2.1
	RP-9.2.3
It is recommended that you obtain a copy of these documents from the NMRA in order to fully understand the DCC protocol.

ADDC's Protocol Analyser was originally created to help reverse engineer Digital Command Control products in order to gain a greater understanding of their operation. It should be a useful tool for DCC developers, repairers, hackers and clubs who want to settle address arguments. The product has grown up with DCC and expanded as the NMRA's Working group worked through the many complexities of the protocol. Despite the numerous pages of specifications programmed into this analyser it is very simple to use - but it still may be a good idea to browse this manual before you start.

1.1	Licence Agreement
	
Use of this product implies agreement with the conditions below.

This product comes in two parts, software in a compressed form on a disk and a hardware interface "dongle".

The software part may be freely distributed only in its compressed form which includes this manual and the sample files. Under no circumstances can the software be reverse engineered nor modified in any way. Any person obtaining the software part by itself from any other party is hereby granted a partial licence to use only the software part for review, observational or educational use, but not commercial use, providing they agree to the conditions in this agreement. At any time a full licence can be granted by purchasing the hardware part in the complete product.

The hardware part may not be reverse engineered nor reproduced in any way. It is this part which is proof of the purchase of a full licence to use this product to gather new data. Upon purchase of the hardware part in the complete product the user is granted a full licence to use all the features of this product, including data aquisition.

1.2	Disclaimer
	
While every reasonable attempt has been made to ensure that this product performs as advertised and conforms to the relevant NMRA Standards and Recommended Practices no warranty is implied in respect to this products performance. Australian Digital Command Control or their agents accept no liability for the accuracy or otherwise of any interpretation of data that this product performs. The ultimate interpretation should always rest with the NMRA specifications and this product should be used in conjunction with those specifications.

2									          (c)ADCC1995

2.0	QUICK START

	1. Place the disk in drive A:
	2. At the DOS prompt type "A: INSTALL<Enter>"
	3. Type "CD<SPACE>\DCCPA<Enter>"
	4. Install hardware dongle into parallel port 1 (if purchased)	
	5. Type "DCCPA<Enter>"
	


3.0	SOFTWARE INSTALLATION

The original software is provided in compressed form on 3.5" floppy disk with an installation batch file. The batch file installs and decompress the software into the directory C:\DCCPA. 

If you have received your software via the 'net place it in the directory C:\DCCPA, uudecode it, and run DCCPASFX.EXE. Once installed change directory to C:\DCCPA and run DCCPA.

An icon is provided should you wish to run the analyser from Windows (tm). In the Program Manager select File, New, Program Item, Browse, select the directory C:\DCCPA, select DCCPA.EXE, browse the same directory for the icon file DCCPA.ICO. Enter "DCCPA" in the name section and click OK. Double click the icon to run the Analyser.


4.0	HARDWARE INSTALLATION

The dongle is designed to attach to LPT1, the first Parallel Port on the PC, a 25 pin female 'D' socket. It is safer to plug the dongle in with the power off. 

Power is supplied to the dongle via a user supplied 7.5 Volt, 100mA DC, unregulated power pack. The DC power inlet is centrally mounted at the rear of the dongle. The centre conductor is the positive one, the outer is ground:

			ground --(.)
				  ^-- positive 7.5V DC

The two terminals on top of the dongle are for the track connection. Wires or banana plugs with clip leads may be connected here. If the leads are long twist them in a drill to provide better noise imunity.

Run the software to test the presence of the dongle and track signal. A warning will appear if neither are present. A green LED lights on the dongle when power and a DCC type signal are present.

(c)ADCC1995										    3

5.0	DATA AQUISITION

DCC data files may be loaded from and saved to disk. Each file is saved with a header containing a "long" description, the date saved and parameter settings at the time the file was saved. The header information is displayed in the file pick window for those files on the system and in the parameter window for the file currently loaded. When a DCC file is loaded the header information is used to set the parameters so the file can be viewed as it was saved. Refer to Section 6 for information on parameters and how to change them.

It is hoped to build a library of files of various DCC implementations. Sample DCC files are provided for your use in understanding the following sections.

5.1	Loading data files

Data files are loaded by pressing <L>oad while in the main menu. You will be asked to provide the file name eg "sample1<Enter>". Do not add the .DCC extension as the program will do that for you.

A list of available DCC files provided. The <PageDn> key can used to move a page at a time through the list and back to the start.

The file will then be loaded and the buffer size and other parameters updated to that of the loaded files header.

5.2	Sampling Data

Sampling can only be performed if the dongle provided in the full version is attached. Refer to the relevant sections above if you have a "Check hardware attached" message.

Don't forget that he programming track may only have signal during programming/verify operations. Data can only be acquired during these operations and so they may have to be repeated to fill the buffer and allow display. It is suggested that small buffer sizes be used in this case.

There are two methods of sampling data, "once only" sample or "continuous" samples.

To obtain a once only sample first check the buffer size setting and ensure it meets your needs. The smallest buffer provides approximately one screen of data if filtering is not active. Press <G>et sample to initiate data acquisition. Once the data has filled the buffer it will be displayed on the screen fully decoded. Press <SPACE> to move through the buffer thirty packets at a time. <Esc> at any time returns to the main menu.

To view continous samples press <C>ontinuous after first selecting one of the smaller buffer values. Large buffers defeat the purpose of the continuous mode as you will have to keep pressing <SPACE> to page through the buffer before the next sample is taken. Press <SPACE> to halt continuous mode and view/save the current sample. 

5.3	Saving Data Files

To save a data file press <S>ave. Enter a file name and provide a long description. Spaces in the long description are automatically converted to "_". The saved file will contain the current parameter settings so ensure that these are set to what you desire before saving.

4									          (c)ADCC1995

6.0	CHANGING PARAMETERS

Press <M>enu to enter the parameter window and change the following parameters.

6.1	Selecting Protocol

Select using <SPACE> either the NMRA protocol as defined by the NMRA Standards and Recommended Practices or the Lenz Protocol.

If the NMRA protocol is selected speeds are shown in 28 speed mode. With Lenz selected the speeds are shown in 14 speed mode and the U bit in S-9.2 is used for headlight control.

The 128 speed mode uses a completely different packet structure and will be decoded in both cases.

Press <E>nter to confirm selection.

6.2	Selecting Mode

The protocol analyser has two decoding modes, Operations mode (RP-9.2.1) for running locos and Service Mode (RP-9.2.3) for programming them. The data can decode with significant differences between the two modes, but will not be damaged if the wrong mode is selected. 

The mode can be selected with <SPACE> and then <E>nter to confirm selection.

6.3	Buffer Size

When a file is loaded or data is captured it is loaded into a buffer for analysis. The buffer size is automatically changed to match that of any data file when one is loaded. The size of the buffer can also be set in binary increments from 128 bytes to 4096 bytes.

Press <M>enu, press enter until the cursor is on the Buffer Size field, then press <SPACE> to select the desired size and press <Enter> to confirm.


6.4	Filtering Data

The primary address at which decoded display commences can be set by entering a value into the "Start Decode" field.

Data applicable to only one primary address can be displayed  by entering a value in the "Decode Only" field. 

Only a primary address can be entered. For 10 and 14 bit addresses all those matching the primary address will be shown after the primary address has been entered.

Entering or leaving these fields set to "0" allows immediate decode of all addresses.
Filters are not available in raw decode mode.

(c)ADCC1995										    5

7.0	DISPLAY OPTIONS

7.1	Decoded Display

By default the data is displayed in its decoded form. A few typical decoded packets are shown below followed by a description of each column:

   Line  Pre  Address              Instruction                 Error  Sync  Count Time
    1    13~  MultiFunctn7   21    Forward Speed  Stop          /     0001     1  6.636
    2    15~  MultiFunctn7   45    Functn Group 1 Fn  3 1       /     0001     1  6.972

-Line number is for reference, often as a cross reference to the raw data viewing screen.
-Number of ones in the preamble. If this field appears in purple the number is less than what is recommended in the current mode.
-Major address division followed by the address in decimal. The wording used is the "best abbreviation" of the relevant words in the NMRA documents. Different colors have been given to the major divisions to ease recognition.
-In the Lenz mode a headlight symbol appears in the next column when the light is set "on".
-Instruction field, again it is colour coded for ease of recognition. Speeds are shown in 14 Speed Mode for Lenz, 28 Speed Mode for NMRA. Functions set are indicated by the presence of those set, function numbers not present are not set. The light function (FL)shows the headlight symbol when active.
-Error shows a green tick "/" if the transmitted error byte is equal to the locally generated error byte. A non matching error byte is indicated by a red "x".
-Synchronisation and stop bits for the packet are shown next. Bits coloured purple indicate an unexpected or error condition.
-Number of packets detected since the packet shown on the previous line, useful only when filtering data. The number of intervening packets is one less than the figure shown.
-Time interval between the stop bit of the previous packet and the stop bit of this packet in milliseconds. The time is not measured but calculated using the nominal length of a one bit of 116 microseconds and a zero bit of 200 microseconds as per S-9.1. This time is a nominal time only and if zero stretching is currently being employed to operate a DC locomotive the actual times may be significantly longer.

On occasions where a packet decodes to an unassigned area of code the appropriate message will appear. The message will often indicate the general address area that the packet is in.

Faulty packets are still decoded as far as is possible as an aid to fault finding.

7.2	Raw Data Display

Press <R>aw to display the data in its Raw form. 

	11111111111110
	   1 	00010101,01100000,01110101.111111111111110
	   2 	00101101,10000101,10101000.111111111111110

In the raw form the data is still formatted into packets, one per line, the synchronisation bits marked with commas (,) and the stop bit with a full stop (.). Line numbers are provided for cross reference between the two viewing modes. 

The line before line one is the initial synchronising preamble, the following preambles are placed at the end of the preceding line.

NOTE:	THE DATA FILTERS DO NOT APLY TO RAW VIEW MODE.
6									          (c)ADCC1995

8.0	OSCILLOSCOPE MODE

The oscilloscope provided is of a "poor man's" design, crude but sufficient for first in analysis. The timebase is directly related to the speed of the machine, samples are taken as fast as the machine can process them, and so cannot be calibrated "at the factory".

Enter this mode by pressing <O>scilloscope. A timebase number from 1 to 6 representing the division of samples by the power of two is then entered. For example pressing <3> divides the timebase by 2 to the power 3 which equals 8. The preferred timebase number can be gained with experience for a particular machine.

The waveform appears on the screen at a resolution of half a character. This is generally sufficient to view general packet waveforms and, in particular, the operation of DC mode.
<Esc> returns to Protocol Analyser operation.

8.0	WHEN THINGS GO WRONG :-(

8.1	Software Messages

	"Check Hardware...."
Do you have the dongle that comes with the full licence?
Is the dongle plugged in to LPT1 (the first printer port).
Is the green LED on?
Confirm that power is available from the plug pack.
Is there a track signal? The programming track should be switched to the main track for software start up so that the hardware test can be performed.

	"Cannot load file..."
The file is either not present, is corrupted or does not have a correct DCC header.

	"Sampling..... but nothing happens"
	"Triggered.... but nothing happens"
Check that signal is present. On the programming track signal is not present until you start to program/verify.
Have you specified a filter condition that cannot be met?

8.2	Hardware Problems	

Check and confirm the hardware and track signal connection using <T>est hardware. If the green LED is not on check power and/or track signal. Remember that the signal may not be present on the programming track at all times. If the LED is on check the connection to and/or the parallel port of the PC.

9.0	CONTACTING AUSTRALIAN DIGITAL COMMAND CONTROL

Australian Digital Command Control can be contacted at:

PO Box 74
Huntingdale 3166
Victoria, Australia

Phone/FAX/Answermachine 03 9754 6502
International Phone/FAX/Answermachine +61 3 9754 6502

Only purchasers of a full licence are entitled to support although comments received from others will be read.