
$Id: README,v 1.5 1997/05/26 17:08:05 bri Exp $

Brian Ward <bri@blah.math.tu-graz.ac.at>

Introduction
------------
These are the installation instructions for mtd and tktrain.
Additional documentation is available in PROTOCOL and through one of these
two URLs:

http://www.math.psu.edu/ward/rail/mtd/
http://blah.math.tu-graz.ac.at/~bri/rail/mtd/

You need POSIX termios, ANSI C, and Tk4.2, as far as I know. You do not
actually need a digital system to try it out. You will probably need to
know a little about Unix if you plan to use mtd, but not much.

This is still a fairly early release, and there is much to be done, and
that's why these installation instructions are a little stupid.

Get the package and unpack it. If you're reading this, you might have done
that already.


mtd
---
If you do have a DCC system (and at the moment, it'd better be the Lenz
system, or it won't work), first read the appropriate README (README.lenz,
..), and then compile mtd:

Edit mtd.c and change /dev/cua0 to your digital system's serial port. Look
over the Makefile and change anything that you need to. The most important
thing here is to see if you have a joystick or not (see below).

Then make. If it compiled okay, do a ./mtd and type "vr" and press return.
It should say something vaguely comprehensible. Then try a "li 5", and the
information for the loco at address 5 should come back. Then go on to
tktrain.

Edit config.tcl. Change wish's pathname (first line) if necessary. If you are
using mtd and actually want to control your locos, first do this:

% cp defaults.tcl config.tcl

Then edit config.tcl and look it over, and change what you have to.

If you don't have mtd, don't do any of this!


tktrain
-------
Then you're ready to test it out. Make sure you're in the mtd directory
and type:

./tktrain

(if you're in a lurch, "wish -f tktrain" might work)

The New Cab, Layout, and Quit buttons should appear. Try them out. Some mtd
commands will appear on stdout if you aren't running mtd. Ignore them
(mostly).

If you actually use this package, please, PLEASE let me know. I wrote it
well knowing that there may not be any other users besides myself.


Joystick support
----------------
This version of tktrain includes joystick support for Linux. It's
experimental, so be careful. You need a fairly recent version of the
joystick driver - 0.8 should be okay. The only joysticks it supports well
are those that you can turn the "springback" off on. I use the CH Products
Mach series. They're cheap and quite robust.

And then you need to do a few things in config.tcl, specifically:

set joystick_support 1
set joystick_port <joystick port, either 0 or 1>

Then the thresholds (floating point, please):
set JS_min 27.0
set JS_max 2080.0
set JS_x_forw 1600.0
set JS_x_back 400.0

You get these numbers in the following manner. Type

./jthrot

and do some things with your joystick. jthrot will send you line after line,
four numbers each. First, pull the all the way back and see what the
second number is. That's about what you want to use for JS_max. Then all
the forward, and that's what JS_min should be. Simple, huh? And for
JS_x_forw and JS_x_back, you want to set these to the values of left and
right for which you want the train to change its direction.

"Why is all this necessary?" you ask. Well, it so happens that PCs use
analog joysticks and these numbers differ for all joysticks. In fact, my
joystick is on a very long extension cable which even changes things
around.

Now that you're ready to use the joystick, you'll find that when you fire
up tktrain, there's a new slider on top of the main window. That's the
address of the loco that the joystick is bound to. Before you set it to a
real loco (this is the part where XXX comes in), make sure to set a cab to
that address too.

The current way to choose an address for the cabs and joystick is very weak
and I expect that it will be next thing that I'll improve.


Making layouts
--------------

As things are a little rough at the moment, making layouts isn't exactly
the simplest thing in the universe, but it's doable. To roll your own, edit
layout1.tcl, and party away:

To make a straight piece of track:

mk_str <widget> <name> <x> <y> <ang> <length>

<widget> is the canvas widget which the layout's on, and will be $w.c in
mk_layout.

<name> is a name you give it. If this is an accessory track, you want this
to be unique (most of the time).

<x> <y> are the coordinates of where the track starts. 0 0 is the bottom
left. You can measure this any way you want-- just change the "scale",
"lay_x", and "lay_y" parameters (at the top of tklayout) accordingly.

<ang> is the angle in which the track points. It is measured in degrees.

<length> is the length of the track.

Curved track is similar:

mk_curv <widget> <name> <x> <y> <ang> <radius> <extent>

<widget>, <name>, <x>, and <y> are the same as in the straight track. <ang>
is the angle tangent to the curve at where it starts (it's basically the
same as straight track, too). <radius> is the radius of the curve. That is,
you had a circle made up of pieces of track like this, what would the
radius of that circle be? It should be in the same units as the <length> of
the straight track. The circle's center is at the point <radius> units
above <x> <y> on the line perpendicular to <ang>. <extent> is how much of
that aforementioned circle this curve takes up, in degrees. Trick 1: this
can be negative. Trick 2: so can <radius>.

Making a turnout is then easy, if you say that a turnout is just a curved
piece of track on top of a straight piece of track:

mk_turnout <widget> <name> <x> <y> <ang> <length> <radius> <extent> <l_r>

<widget>, <name>, <x>, <y>, <ang>, <length>, <radius>, and <extent> have
the same meanings as above, however, <l_r> is "left" or "right". For this
reason, don't ever use Trick 1 or Trick 2 on a turnout unless you're just
plain nuts to start with.

To make the turnouts do something:

config_turnout <widget> <name> <addr>

<widget> should be the same as above. <name> is the hopefully unique name
that you gave your turnout (you can play tricks here, too, to get different
representations, but I won't talk about that right now). <addr> is the
address of the turnout. Now, this needs to be said, of course: right now,
the "+" state of the turnout means it branches, "-" means it's straight. I
don't support the reversal of that yet, but I will. And remember that the
addresses start from 0, whereas on the LH100, they start from 1 (so "9" on
your LH100 is "8" here).

If you did this right, when you click on the turnout, it will swap its
colors and position. Looks neat.

An uncoupler (should be named momentary):

config_uncoupler <widget> <name> <addr> <output>

The first three are the same as above. <output> is new, because there are
two outputs per address, and an uncoupler only needs one, so you specify
which that is; it's either 0 ("-") or 1 ("+").

I would highly suggest not running mtd when testing out new layouts. I have
plans for making a drag-and-drop interface to replace all of this hassle,
but that's not current; I have other things to do at the moment.

In case you're wondering, the default track layout is part of mine. It's
made of Roco Line track (with the neat rubber ballast), and is measured in
millimeters, taken right from the Roco catalog. I stripped down some of the
curves, though; on the display, they are much sharper than thay actually
are here. Abstractions are a rather nice thing to have when doing this,
anyway.

