tsim

tsim is a simple train simulator written by Magnus Carlsson and Alois Goller and used on the Concurrent Programming course at Chalmers University of Technology. This page describes tsim v0.7-HUT (which contains some modifications for compatibility with more operating systems) by Jan Lönnberg used on the Concurrent Programming course at Helsinki University of Technology. tsim simulates trains running on a track that can be edited through a graphical user interface. The trains can be controlled by another program through standard input and output. You can use the utility 2 to connect the standard input and output of tsim to the standard output and input (respectively) of another program, such as the Java interface for tsim.

The simulator (tsim-0.7), Java interface (TSim), 2 (2.c) and the track used for the programming task at HUT (track) can be downloaded here.

tsim uses X11 for its GUI, so you will need the X11 libraries and include files to compile and run tsim. To compile tsim, run make in the tsim-0.7 directory. This will generate an executable called tsim (or tsim.exe on Windows Cygwin) in that directory. tsim should compile without modification on Linux and Cygwin. You must edit the C compiler flags in the Makefile to compile on Solaris, FreeBSD and Irix. tsim can use an external sound player for sound effects; by default mpg123 is used on Unix and Sound Recorder on Windows. The supplied sound effects are public domain samples converted to MPEG Layer 3 WAVs.

Using tsim

tsim can be started in three different ways:

tsim <filename>

This starts tsim with the track contained in the specified file. HUT students should modify the supplied track.

tsim <width> <height>

This starts tsim with an empty track with the specified size.

tsim

This starts tsim with an empty 20×20 track.

When you start tsim, the following windows appear:

[screenshot of tsim]

Main tsim window containing the supplied track

[tsim tools window]

tsim tools window

The main tsim window displays the track and the trains. The track consists of segments placed on a square grid. Unsurprisingly, trains travel along tracks and collide if they occupy the same track segment. Similarly, a train derails if it moves into a square that does not contain a track segment connected to the previous track segment. Switches connect a common part of the track to one of two alternative track parts. This means that a train entering a switch from the common part will continue onto either the left or part part depending on the state of the switch. A train entering from the connected left or right part will proceed onto the common part, while a train entering from the unconnected part will derail. The currently connected track part is marked by a small arrow. Stops may also be placed on the track. The train can crash into these.

The tools window contains tools to edit the track and control the trains. The upper row contains (from left to right) tools to place stations, track segments, sensors (shown as small T-shapes) and trains. Clicking the sensor tool and clicking a track segment places a sensor on that segment or removes the existing sensor. Sensors may not be placed on crossings, switches or stops. In the lower row, you will find:

The delete tool. Selecting this deletes the contents of any square you click on.
The switch tool. Selecting this allows you to toggle switches by clicking them. This is useful for testing.
The speed tool. Selecting this allows you to change the speed of trains.
The co-ordinate display. You will need to use this co-ordinates to identify sensors.
The save button. Click this to save your track (including sensors and trains).
The quit button. Click this to quit tsim. This will also cause the Java interface to terminate, if it is connected to the simulator.

Configuring tsim

tsim is configured using X resources. The following X resources are supported by tsim:

bitmapDir

The directory tsim uses to find bitmaps. Change this if tsim is not run from the current directory.
Default: ./bitmaps

soundDir

The directory tsim uses to find sounds. Change this if tsim is not run from the current directory.
Default: ./sounds

timeoutInterval

Time for each time step in tsim (in seconds).
Default: 0.1

acceleration

Acceleration in pixels/(second²).
Default: 5.0

playCmd

Sound playback command. The name of the sound file to play is specified as %s.
Default (Windows): sndrec32 /play /close /embedding "%s"
Default (Unix): mpg123 "%s"
Set this to an empty string to disable sound (very useful in university computer labs; default in Niksula!).

foreground

Foreground colour.
Default: black

background

Background colour.
Default: white

X resources are typically loaded from ~/.Xresources. They can also be set using

xrdb
-merge

. The format used in both cases is:

tsim*<resource>:<value>

For example, to direct sound output through aRts (which is very useful when using KDE), run xrdb -merge and enter the following:

tsim*playCmd:artsdsp mpg123
"%s"

tsim Java interface

The tsim Java interface allows you to control the simulator using a Java program. The Java interface package includes a description of the interface (in TSim/doc). The Java interface is typically used through the utility 2 (included in the tsim package) as follows:

./2 "cd tsim-0.7; ./tsim
../track-sensors" "java
trains.Train"

2 can be compiled using the following command line (assuming you have gcc installed):

gcc -o 2 2.c

Starting 2 as shown above results in two processes running as follows:

[User <-> tsim <-> tsim Java interface (TSim.*) <-> user train code (trains.*)

[User <-> tsim <-> tsim Java interface (TSim.*) <-> user train code (trains.*)

Structure of tsim runtime configuration

This configuration is used for concurrent programming exercises. In this configuration, 2 starts tsim and a Java virtual machine running the student's train controller code and the tsim Java interface, and connects tsim and the JVM with each other by rerouting their standard input and output to each other using pipes. The student code should not access standard I/O (System.in and System.out), as this will interfere with the connection between tsim and the tsim Java interface. Standard error (System.err) can be used for debugging.

Note that each of the above components may use several threads. For example, the student's code should have one thread for each train.

The functionality of the tsim Java interface is accessed by the student's code through the TSim.TSimInterface class. To get an instance of this class, call TSim.TSimFactory.getTSimInterface(). It is important that you only call this once, as creating multiple running tsim interfaces in the same process will cause communication errors.

Each train is identified by an id number, which is an increasing integer starting from 1. For example, if there are two trains, their ids will be 1 and 2.

The TSimInterface has three primary methods through which the trains are controlled:

```
public void setSpeed(int trainId, int speed)
```
This method sets the speed of the train identified by trainId to speed. The speed is measured in pixels/second. A negative speed value causes the train to travel backwards. You may not set a negative speed when the train is travelling forwards or a positive speed when the train is travelling backwards; the train must be stopped in order to change direction.
```
public void setSwitch(int xPos, int yPos, int switchPos)
```
This method sets the state of the switch at (xPos, yPos) to switchPos. switchPos can be either TSimInterface.SWITCH_LEFT or TSimInterface.SWITCH_RIGHT.
```
public SensorEvent getSensor(int trainId)
```
This method waits until a sensor event is received from train trainId and returns the sensor event. Sensor events are generated when a train enters or exits a square containing a sensor. Sensor events can be examined through the following SensorEvent methods:

```
public int getXpos()
```
This method returns the X position of the sensor.
```
public int getYpos()
```
This method returns the Y position of the sensor.
```
public int getStatus()
```
This method returns the status of the sensor: SensorEvent.ACTIVE if a train has entered the sensor's square and SensorEvent.INACTIVE if a train has left the sensor's square.
```
public int getTrainId()
```
This method returns the id of the train.

For further details, see TSim/doc/index.html in the tsim package.

Page last updated by Jan Lönnberg 2005-08-30.