Disclaimer:

The following text is just a memory-dump. It has not been reviewed, checked or
tested. It may appear to be designed to instill maximum confusion but I can
assure you that the second neuron was offline when I wrote this and so
sufficient organisation to deliberately create chaos was unavailable.

Warranty:

None. This software has been used on my layout, but nowhere else yet.
It is not finished, tested or whatever. It does however operate, and for me it
does not crash. For you it will crash even quicker than windows - for that is
the nature of alpha testing software. If it crashes the error output should be
in stderr.txt - I would welcome such crash dumps and will try to fix the
problems.

Support:

No guarantees. I wrote this software for my own use and currently have no plans
for any kind of commercial exploitation, but am happy for others to benefit
from my labours. I will try to fix any problems you may
find or add new facilities that strike me as interesting.

Compatibility:

Currently the set of CTI modules are supported, though I've only tested
TrainBrain and SmartCab modules.
Merg modules are supported if connected through a simplified RPI that uses no
message types or checksum. I can send you code if you want to make one.
Merg modules will be supported using Gordons RPIs when I can get around to
adding the extra message header and checksum.
The following merg modules are understood: FTC, DPR, SRO4, SRI4.
QPRs are the same as DPRs as far as the stack is concerned - so select DPR.
SRO4s are split into four 8-bit bytes (just as the board is). Each byte can be
either 8 individual outputs, an 8-bit throttle (with direction connected
elsewhere) or a 7-bit throttle and bit7 selecting reverse.
If I have sufficient motivation, or should anyone else want to have a go then
other message protocols can easily be added - its just a matter of creating a
new subclass of serial interface and a set of tree nodes for the GUI.
Tcc does not yet implement software intertia on throttles - thats coming soon.

Files:

tcc.jar is a java archive of tcc, my Train Control Centre application software.

To run it you'll need JRE1.3 (5.3Mbyte)
(http://java.sun.com/j2se/1.3/download-windows.html)
and Java communication API (270K)
(http://java.sun.com/products/javacomm.index.html)

And then run the application:
java -jar tcc.jar ha1.tcl

The file ha1.tcl is the script I am using on my layout (for a diagram see
merg1.sdt [star-office] or MERG1.ppt [powerpoint, but much larger file]).
This presentation also explains the basic philosophy adopted by ha1.tcl, and
the states used by tracks sections, and how they inter-relate. Note that this
is merely how I chose to use the scripting language - you can make much simpler
and completely different setups according to your needs and skills.

tcc should open a desktop window with several other windows opening
automatically. This window configuration is saved in ha1.tcp when tcc exits.

The menu bar:
File/Open. Currently only extracts saved CTC data. This does NOT open .tcl
scripts yet.
File/Save. Saves an extra copy of the CTC windows to the named file. CTC
contents are saved automatically to file.tcp when tcc exits.
File/Exit: Same as closing the desktop window: Save configuration to tcc.tcp,
file.tcp and exit.
Edit: Not used
View/Variables,Sensors,Control,Throttles,CTC,Tracks,Log: opens windows listed
below.
Configure/Hardware: Opens the serial port and stack hardware configuration
window.
Configure/Log: Define what script tracing to use.
Reset: Clear all variables. Script will start again as if tcc was exited and
re-entered. Leaves serial ports running (but of course all control outputs will
be zero). Clears dynamic CTC contents.
Run: Start running the script. This is a button, not a menu.
Stop: (alternates with run) Stops the running script.
Step: Execute a single pass through the script.

The windows:

Variables:
A table of the variables used in the .tcl script. They are grouped into rows
according to instructions in GROUP: statements in the .tcl script.
See below for a discussion of variable names, and how they are arranged in
groups.
Variable names and column headings are not editable, other values are.
Plain integer values are displayed as numbers. Colours, addresses, constants,
times etc are shown symbolically.
Values can only be set to numeric values, by entering a new value in the
appropriate cell.

Sensors:
A table of all sensor inputs received from the hardware. When the serial ports
are not running you can click on the boxes to set sensor data manually.

Controls:
A table of all control outputs available to be sent to the hardware. You can
click on the boxes to set values. This works whether or not the script is
running, and whether or not the serial ports are running (though naturally the
values are not actually sent if the ports are offline).

Thottles:
One row for each throttle, containing name, speed, direction, brake and
momentum. Speed and momentum are currently plain integer fields.

CTC panels:
A grid of cells that can show layout plans or other information.

Tracks:
The pallette for editing CTC panels (when the script is stopped).
Symbols for straight and curved track, left and right turnouts, and crossings
are available. Click on the cell in the pallette and then on a cell in a CTC
panel. The orientation of the symbol placed in the CTC panel depends upon where
you click in that cell. The top-left corner of the pallette symbol is oriented
in whichever corner or side you click in. Experiment and all will become clear.
The "abc" pallette entry allows fixed text to be placed on the CTC panel.
The "B" entry allows track segments to be formed into groups for the $COLOR
BLOCK statement. The blank pallette allows tracks to be deleted.

Log:
Error messages and debug output. This window is copied to tcc.txt.

Log Config:
Determines whether to trace the running of the .tcl script, and what level of
detail to produce.

Qkeys:
An auto-arranging collection of buttons that can be monitored by the script.

Hardware:
A tree (similar to windows explorer) showing the serial port configuration.
Top level: the tree root - ignore this.
Level 2: Interfaces - one entry per serial port being driven
	The NewInterface cell is a pop-up menu to define new interfaces
Level 3: Interface state, port parameters, module stacks on that interface
Stack module level: Each CTI or merg module connected to the port.
Signal level: The name of the signal connected to each pin of the module.
Many nodes are pop-ups to change their values.
Some nodes can be deleted with the del key.
Some nodes can be dragged to reseqence them.
Apart from the delete key, no keyboard interaction is possible with this
window.
CTC panels used by ha1.tcl
CTC1:
The main track layout. Track sections become coloured to show occupancy and
state. The first segment of a section is coloured for train arriving, all
segments for occupied, or stopped. The last segment for train separting.

CTC2:
The train state display. Each train gets a line on the panel. The straight line
is coloured to show which colour this train uses on CTC1. (this uses the
standard resistor colour coding scheme). Immediately to the right of the line
is shown the train type - but are startup these are all blank. Click in one of
the four cells to the right of the line to set train types.
Next is shown the throttle settings for slow (min speed) and full speed. Left
click reduces and right click increases these values.

CTC3:
Shows momentum settings to be used for acceleration and braking.
The next line shows error messages from the script (such as sensor missed when
a train enters a section).
The last line shows messages from the train speed auto-recalibration code.
Certain sections measure the speed of the train and determine whether the train
is going too fast or too slow for its particular type (express trains are
expected to go faster than goods trains etc).

Variable naming

The group function allows related variables (or sensors or controls) to be
shown on a single line of the variables window. Such variables must be named
according to the following rules:

	Name = <prefix> <suffix>
	Prefix = function of the variable
	Suffix = code module or track section the variable applies to

For example I use prefix="s" for status variables, "t" for train numbers.
Suffix "L9" refers to track section L9. So sL9 is the status of track section
L9. All the *L9 variables are on one line, *L10 on another line and so on.
The prefixes are listed along the top of the variables window, the suffixes
down the side.

Running a script without having any hardware connected:

You can run a script without hardware (or simply by having the serial ports
disabled) to debug your script. Simply control the sensor data in the sensor
window by clicking on the boxes.

Sample session with ha1.tcl:
Reading the presentation (merg1.sdp or MERG1.ppt) will help understand this.
Select CurL9 and OptOL9. Click run.
You will see rcL9 activate (feeding power to that track section), also rcL8
(the next section prepares to receive the train). Throttle 6 will begin
increasing speed, in reverse direction (the train has stopped at the end of the
section, covering the exit sensor OptOL9 and is reversing until the sensor is
clear). Clear OptOL9 to signify that the train has started moving. The throttle
will stop, brake, and change to forward.
Also note the brown colouring on CTC1 illustrating the location of train 1.
The throttle setting when OptOL9 went clear is shown on CTC2 as the min speed
for train 1. Full speed is set 5 higher.
Do the following:
OptOL9 on: The train reaches the end of L9. sL9 changes to departing.
OptL8 on: The train enters L8. sL8 changes from Booked to Arriving.
CurL9 off, OptOL9 off, CurL8 on: The train is moving into L8
OptL8 off: The train is fully in L8, sL8 becomes Occupied.
Repeat the sensor changes as the train traverses L8, L7, and enters L6.
Note that TI4 has become booked for the train and is shown set straight on the
CTC.
When the train enters L5 note that TO3 has selected which route the train will
take next, and either L3 or L4 will be booked. Take care to click the correct
entry sensor, or else you will get an error message in CTC3.
If you managed to get a single train around the loop then try it with two or
three trains. It gets fun (read confusing) to do that manually.
The script is currently configured to support upto 6 trains - because thats
really the operation limit for the layout as it currently stands. If you want
many more then the biggest problem is having enough easily recognised colours
for the CTC panel.

The .tdl file

ha1.tdl is the file I actually create manually. It defines the connectivity
between track sections, which stacks sensors and controls are connected to, how
long the tracks are, which throttles are wired to them and where on the CTC
panels the tracks are displayed. I have a collection of scripts which run on a
unix box that helps me make the .tcl file for the style of operation I use.
They will not run on Windoze. They are also very large and relatively
incomprehensible. If you want to use the same style of full computer control
then you are welcome to send me a .tdl file and I'll send you back a .tcl file
that implements your specified layout.
Naturally I'll have to create a formal .tdl definition first.

Modular scripting

In concept, my scripts tie together modules of code for each type of track
section and build a .tcl script automatically. In reality the scripts and the
modules are all intertwined and inseparable. They are only useable for the full
automation, dual optical detection mechanism philosophy I have adopted.
If anyone is interested in making a generic script builder that can be used for any operating style then I can certainly recommend an approach that would
permit different sets of modules to be used for different operating styles, but
use the same script builder and same application code. Note that you cannot see
separated 'modules' within ha1.tcl because I have grouped similar function
together to improve readability.

Of course there's nothing wrong with writing .tcl script manually, as
documented by CTI for TrainBrain.

Differences between tcc .tcl and TrainBrain .tcl:

tcc does not yet support:
1. icons on CTC panels
2. sounds
3. probably some odd functions I have never used.

I have not tested signal outputs. For CTI hardware signals go to special
hardware and I do not have any. For merg modules there is no fundamental
difference between controls and signals - but I will add support for multi-bit
signals sometime (like when I get around to adding signals to my layout!).

Additional in tcc .tcl scripts:

1. Group statements for arranging data in variables windows.
2. Constants - to avoid using unnamed literals everywhere.

Planned additions:

1. Arrays. You will see a lot of constructs like: s=&tc1, s=-, s=tL9+, *s=1
    I want to change this into: tc[tL9]=1
2. Sounds from WAV files and CD tracks (that can play through relays routing
the signal to loadspeakers hidden under tracks or in tunnels).
3. Inertia for merg throttles (computer controlled throttles connected to SRO4
modules - see TB G16/51)
4. Loading and editing .tcl scripts within tcc. Currently if you want to edit
the script you have to quit, edit the file and start up again.