dtcltiny Handbook

# dtcltiny

## Introduction

dtcltiny is a program to control model train locomotives equiped with a digital decoder. For every single locomotive dtcltiny provides a separate controller interface to operate speed, driving direction and functions (e.g. light, sound, ...). Additionally programming of decoders according to NMRA-DCC standard and Uhlenbrock is possible. Further features are provided, which are described in detail in separate chapters of this handbook.

## Software requirements

Besides a running Linux system installation featuring a graphical desktop and Qt libraries (version 4 or 5) you need a SRCP server to connect dtcltiny, acting as a SRCP client, to your model railway layout. The SRCP server must at least support SRCP protocol version 0.8.0, for automation mode support for SRCP 0.8.4 is necessary. SRCP means "Simple Railroad Command Protocol" and defines a command protocol to control digital model railways. For more information please refer to Der Moba. In most cases the well known "srcpd" system daemon (http://srcpd.sourceforge.net/) will be used to take over the task acting as a software based central control unit. Hint: It is not necessary to setup a SRCP server if you only like to run dtcltiny for testing purposes.

## Hardware requirements

Hardware requirements depend on your server setup respectively on its connection to your model railway layout. The SRCP protocol is designed to run over a TCP/IP network so SRCP clients and SRCP server may run on different hosts.

Figure 1: Mainwindow with locomotive controllers and routes windows

## Installation

### rpm

Install the package as root using this command:

> `rpm -i <filename.rpm>`

### source-rpm

Built a new binary rpm package as root running the command

> `rpm --rebuild <filename.src.rpm>`

The freshly built rpm package now ready for installation can be found in directory `/usr/src/redhat/RPMS/i386` (other rpm based Linux distributions should use a similar directory layout, SuSE: `/usr/src/packages/RPMS/i586`, Mandrake: `/usr/src/RPM/RPMS/i586`). Install this package as described above.

### Sourcecode (.tar.gz/.tar.bz2)

Reveal tar archive by command

> `tar xzf dtcltiny-0.4.4.tar.gz`

The sourcecode can be found in subdirectory dtcltiny-0.4.4. Change into this directory and compile code with

> `./configure && make`

After the successfull compile run, install dtcltiny as root with

> `make install`

## Program start

In normal operation mode the SRCP server should be started first. About how to do this please refer to the server documentation. For testing purposes this step can be skipped.

dtcltiny can be startet using your desktop menu (category "Games"), or right away from a terminal window:

> `dtcltiny [<filename.dtcl>]`

Example:

> `dtcltiny locos.dtcl`

filename.dtcl This optional parameter points to an existing configuation file where dtcltiny can find an already configured controller setup. These files typically have the file extension ".dtcl".

On startup dtcltiny also reads a user preferences file where several settings are stored. These settings can be adjusted to your personal needs using the menu "Options/Settings". The data itself is stored to file `~/.dtcltiny` and is used for the next program session start.

After program lauch you will find a more or less empty program window, if no pre-configuration was loaded, or a window exposing several controllers. The user preferences section enables you to automatically load a specified configuration file on program startup.

## Operation

### Adding and changing controllers

To add a new controller choose menu "Controller -> Add". The new controller gui appears and can be configured using the context menu (right klick on controller). Activate context menu item "Settings" to open a dialog window offering several options. These options are organized in three different tabs.

#### General

Figure 2: Controller settings tab »General«

This tab can be used to configure general controller properties.

Input lines for locomotive name or alias are only informative, their purpose is to ease controller identification. The alias can be used to represent a train number like in time tables. One of both titles is shown on a controller label. A small image can also be assigned to visually link this controller to a locomotive model. This locomotive image must be availabel as xpm-file.

The checkbox »Reverse Logic« helps to adjust the drive direction of the model. Checking or unchecking just changes the default direction.

Group box "Logik" at the bottom of this window provides options for decoder parameters. Please first select the required decoder; if your model is not listed select a generic one, depending on your digital protocol (NMRA DCC, Motorola). Now select the protocol, there may be one ore more offered by the selection box. Right of these selection boxes a short text gives some hints about protocol properties. At least enter your decoder address.

#### Functions

Figure 3: Properties dialog tab »Functions«

Depending on the capabilities of the selected decoder this page shows a different number of up to 28 functions, organized in rows. Whether all functions can actually be used also depends on the used decoder; please refer to the decoder manual for details. Option "Visible" controlls if the respective function gets a button on the controller GUI or not. Due to limited space only up to six function buttons can be placed on the controller GUI front. Up to twelve functions can be activated by function keys of a common keyboard.

In the next row the function effect can be selected. The last column provides an option to select whether the button behaves as a switch or as a pushbutton. Especially the later may be prefered for whistle sound or decoupling.

#### Speed

Figure 4: Properties dialog tab "Speed"

Short settings description in tab »Speed«:

Maximum
  Die höchste Fahrstufe, die vom Controller eingestellt werden kann. Sie bewirkt eine Begrenzung der Höchstgeschwindigkeit. Den Wert hier nicht auf maximal zu stellen, ist nur sinnvoll bei Decodern, die keine einstellbare Höchstgeschwindigkeit haben.
Average
  Eine beliebige mittlere Geschwindigkeit, die durch Drücken des gelben Streifens neben dem Geschwindigkeitsregler eingestellt wird.
Minimum
  Wie Durchschnitt, nur geringere Geschwindigkeit, aktivierbar durch den grünen Streifen.
Maximum speed
  Oben kann noch die Vorbild-Höchstgeschwindigkeit eingestellt werden. Dies dient zur Anzeige der momentanen Vorbild-Geschwindigkeit im Controller-Fenster.
Acceleration
  Die Wartezeit in Millisekunden zwischen einzelnen Fahrstufen beim Beschleunigen. Alle Fahrstufen bis zur Endgeschwindigkeit werden durchlaufen. Bei Decodern mit 128 Fahrstufen sollte man auf jeden Fall einen geringeren Wert einstellen, als es der Voreinstellung entspricht. Wenn der Decoder eine einstellbare Beschleunigung bietet, sollte man hier null einstellen.
Breaking
  Same as described for acceleration is applicable for breaking.

Hint: Die Software-Verzögerung beim Beschleunigen Bremsen tritt nur in Kraft, wenn man die Fahrgeschwindigkeit mit einem Klick auf den grünen, gelben oder roten Balken, sowie das Bremssymbol wählt. Der Schieberegler folgt dabei der momentanen Geschwindigkeit. Wird während einer solchen Phase am Schieberegler gezogen, bricht der Beschleuigungs-/Bremsvorgang ab. Wird dieselbe Lok noch von einem anderen Regler (z.B. von einem Clubkollegen) gesteuert, unterbricht dessen Einflußnahme auf die Lokgeschwindkeit ebenfalls den Beschleuigungs-/Bremsvorgang.

Sobald Sie auf "OK" klicken, erscheint der neue Controller im Hauptfenster. Nachträgliche Änderungen der Einstellungen sind möglich, wenn Sie mit der rechten Maustaste auf einen Controller klicken und im Kontextmenü "Eigenschaften" auswählen. Dieses Menü bietet auch einen Eintrag zum Löschen eines Controllers. Mit "Datei -> Speichern unter" kann man die Einstellungen der Controller in eine Datei sichern, um sie später mit "Datei -> Öffnen" wieder zu laden.

### Main program control

Neben den normalen Menüeinträgen befinden sich unterhalb des Menübalkens u.a. drei Schalter, deren Funktionen hier kurz erläutert werden:

1. Power on
2. Power off
3. Emergency stop + Power off

Diese Funktionen sind nur anwählbar, also farbig, wenn eine Verbindung zum SRCP-Server aktiv ist. Ansonsten sind sie ausgegraut.

### Controller operation

Starten Sie das Programm und legen Sie einen Controller an. Wenn Sie nun mit der Maus ein paar Sekunden auf ein Steuerelement zeigen (nicht klicken), bekommen sie eine Erklärung angezeigt (Tooltip). Deshalb und weil alles selbsterklärend sein sollte, verzichte ich hier auf eine nähere Beschreibung. Nur wenige kurz Punkte:

- Wenn sie auf den Schalter mit dem Name/Alias klicken, wird jeweils die jeweils andere Bezeichnung angezeigt.
- Auf die gleiche Weise kann man von Anzeige "Real Speed" auf "Speed Steps" umschalten.

### Delayed acceleration and breaking

Wird auf den grünen, gelben oder roten Streifen neben dem Schieberegler oder auf den Bremsbutton geklickt, wandert der Schieberegler mit der eingestellten Brems- und Beschleunigungsverzögerung in Richtung Zielwert. Dieses wird aber vorzeitig beendet, wenn

- der Schieberegeler betätigt wird (per Maus oder Tastatur),
- ein anderer SRCP-Client die Geschwindigkeit der Lok verändert (siehe Synchronisation mit anderen Controllern),
- eine andere Zielgeschwindigkeit angefordert wird oder
- ein Nothalt ausgelöst wird.

### Keyboard shortcuts

Spacebar | Change direction of travel (current controller)
° (Degree) | Switch function 0 (current controller)
F1...F12 | Switch special functions 1...12 (current controller)
<Ctrl>-x | Emergency stop (current controller)
<Strg>-b | Break (current controller)
Arrow key Up/Down | Increase/Decrease velocity by 1 step (current controller)
Page up/donw | Increase/Decrease velocity by 1/10 of maximum velocity (current controller)
Tab | Change focus to next controller
<Ctrl>-n | Add new locomotive controller
<Ctrl>-o | Controllerfeld aus Datei laden
<Ctrl>-q | Exit program
<Ctrl>-s | Digital power on/off

### Decoder programming

No description available yet. The dialog window may be selfexplanatory in most cases.

## Synchronization with other SRCP-clients

Da ein SRCP-Server in der Regel die Kommunikation mit mehreren SRCP-Clients unterstützt, ist es möglich, dass dieselbe Lok von mehreren Benutzern gleichzeitig bedient wird. Um die Controlleranzeige synchron mit den tatsächlich eingestellten Fahrwerten zu halten, unterstützt dtcltiny die Auswertung des Infoports. Diese Funktion ist automatisch aktiv, muss also nicht explizit eingeschaltet werden. Automatische Beschleunigungs- und Bremsvorgänge werden bei Beeinflussung vom Infoport abgebrochen.

Um die Beeinflussung einer mit dtcltiny gesteuerten Lok von anderen SRCP-Clients zu verhindern, unterstützt dtcltiny den SRCP-Befehl "LOCK". Damit lässt sich der Zugriff durch andere Controller verhindern bzw. explizit erlauben; dtcltiny kann die entsprechende Lokomotive damit wahlweise exklusiv steuern. Ein- und Ausschalten läßt sich diese Funktion über das Kontextmenü des entsprechenden Controllers (Sperren/Entsperren).

## Automation

In cooperation with an other SRCP client, which can provide special information about the railway route to be covered, dtcltiny can automatically controll trains on a railway model layout. This automation feature encloses move off in front of signals, switching from stop to permission to proceed, keep speed limits respectively abide target speeds on track and halt in front of stop signals.

This functionality is based on the SRCP Generic Messages (GM) technology, introduced by protocol version 0.8.4. The GM extension enables SRCP clients to exchange types of information which are not part of the SRCP specification. In case of dtcltiny CRCF (Common Railroad Configuration Files) as a kind of freely extensible macro language is used to encapsulate higher level data.

The program spdrs60 (http://spdrs60.sourceforge.net/) can be used as communication counter part answering requests about layout data. For more details please refer to the spdrs60 handbook, chapter 8. spdrs60 can handle routes configurated with data corresponding their length, speedlimits, train-numbers etc. As spdrs60 can act as CRCF server these data can be requested by CRCF clients like dtcltiny.

In order to activate automation several requirements must be met, first for spdrs60:

- The automated railway track must be completely covered by routes.
- Routes must be equiped with entry and exit signals (at least virtually).
- Routes must be configured to be released by occupation of the correct track. Automatical route release enables spdrs60 to forward train numbers from one route to the following route.
- All routes must be configurated with data about their length and target speed respective speedlimit.
- Routes used by controlled trains must contain the right train number.
- The same train number may not be set at different routes at the same time.
- The layout properties for Generic Messages (menu Edit Settings) must be set to enable broadcasted CRCF messages.

For dtcltiny the following requirements must be met:

- The user option for model scale must be set correctly.
- The alias value for the respective train controller must be set to the same train number used in spdrs60.
- In train controller settings for CRCF, speed control must be set to active.
- The maximum value for real speed (in km/h) must be set correctly. dtcltiny currently does not provide automatical speed calibration, so here you are on your own.

The following steps are carried out during automated drive:

- The locking table (spdrs60) anounces the train occupying a new route via broadcasted CRCF message.
- The train controller (dtcltiny) now knows the route id the train currently uses. If the basic data of this route (length, speedlimit etc.) is not known by the train controller, this data is requested from spdrs60. The controller owned route data is displayed in a list window opened by context menu "Routes". The currently used route is highlighted accordingly. During normal operation changing data is updated accordingly. Does the displayed data not comply to the real situation on the layout the controller can not work properly.
- If the train is currently halted in front of a stop signal and the signal changes to proceed, the train will move off and accelerate until the target speed is reached.
- If the train drives at target speed and the new route has a different target speed, the acual speed is adjusted to the new value.
- When the train controller receives the message about a route change, a break point is calulated to stop the train in front of the new route exit signal.
- The length value of the route is used in terms of this is the distance from the "new route announcement" to the exit signal. On the layout this distance may be different from the distance between entry and exit signal of a route.

## How to add more decoders and protocols

The available decoders and protocols are stored in separate text files named "decoders" and "protocols". They can be found in directory »data« where they can be edited by any text editor. Generally it is possible to add any number of new items as long as the text format and its key-value pair systematics is kept. New values are read by dtcltiny on opening the controller configuration dialog window (context menu "Properties").

## Liability

The authors of this software do not grant any liability regarding correct function or damages caused by this software.

## License

The sourcecode is copyrighted according to GPLv2. For more information please refer to http://www.gnu.org/.

## Thanks

- Stefan Preis, who developed dtcl which was used as a model for this program.
- Torsten Vogt, who setup DDL and therefore built the base for model railroad control development on Linux at all.
- All users who gave constructive feedback.
- All developers of SRCP.

Markus Pfeiffer, 01.12.2001; translation to English and extension: Guido Scholz