Signal Modules

The basic signal model in Rail3D is very good at what it does - it keeps the train apart properly - however, it is not sophisticated enough to cope with some of the more complicated routing examples. For example:

• Single line passing loops you can easily create a single line passing loop and have trains passing properly, but without some extra effort you will soon or later get the layout “locked up” with a train in each side of the loop and one on each of the approaches, and hence nothing able to move.
• Bidirectional working it’s not possible to reliably model bidirectional working with the basic signals without sooner or later getting into a lockup situation.
• Single line intermediate signals similar to bidirectional working, sooner or later it will lock up.
• Selective routing you may want to route trains into a yard, or choose a platform depending on other factors - but this cannot be achieved with the basic signal system.
• Routing by priority you may want to give express trains priority over frieght - but this cannot be achieved easily with the basic signal system.

All of these problems can be resolved (to some extent) with scripts, but generally the solutions are complex, and as they need scripts distributed over many signals, it can be difficult to achieve. The new “Signal module” feature makes things a lot simpler and easier to understand.

Signal Modules Concept

The concept is simple: to group a number of signals together and control them from a single script.

Example

For my example I’m going to build a control module for a single line passing loop:

I’m using Swiss metre guage models (because I’ve been working on myh bvz layout recently) and the signals are type “ch_Ltype3″.

In each direction I have a distant (type ch_Ltype2D), home and starter. Note that signals of this type behave like semaphores, and that the home signal are not section signals.

If you build this layout and run it for long enough (with enough trains) you will find a number of problems with the operation:

• You can get the lock-up situation described above where there are two trains sitting in the loop, and two more sitting on the home signals.
• Using signals with semaphore type operation, you will find that when (eg) an up train approaches from the left, all the up signals will clear (including the starter) if possible. Ideally it would be nice if the signal logic was a bit more intelligent and would not lock the next section to early if there is a down train wanting to come through.
• In Swiss operation, both sides of the loop are bi-directional and you would expect the first train to arrive to enter the loop when passing, and the second to run through the straight line. This can be solved with scripts on each signal, but it is complicated to set up, see Passing Loops On Single Lines

Implementation

Firstly, we need to define the signals under control. There are all sorts of ways one could do this, but I’ve decided to use the signal panel as the way to do it. This has the advantage(s) that we already have the signal panel defined as a means of grouping related signals, and it gives me a degree of abstraction in the script I write so that a generic script can be re-used with minimal customisation: the customisation for each specific application is defined by the parent signal panel, and finally it gives us a nice display where we can see what is going on during test and development.

So, the first step is to create a signal panel covering the cluster of signals, you can see my simple panel in the above screenshot. Later, I’m going to need to identify the signals, so I’ve given them signal ids: “ud”, “uh”, “us” for Up Distant, Up Home, Up starter and similarly “dd”,”dh”,”ds”.

In the latest code (later than build 101.8.1) I’ve added some new script functions and the ability to define a script on the panel: On the panel dialog, select “Edit Script” from the “Settings” menu.

A panel script has some extra features:

• Panel scripts receive input from all the signals on the panel
• Panel scripts can modify the action of the signals on the panel.

This is achieved through some new script entry points:

• OnSignalOnTrain(): This function is called whenever a train passes one of the signals referenced by the panel.
• OnSignalCanClear(): This function is called when a signal on the panel is about to clear - the script may return a flag to cancel the signal clearing (see note below)
• OnSignalCanRouteTo(): This function is called when the signalling system is about to set a route to a signal reference by the panel- the script may return a flag to cancel the route setting.

I’ve also added a new function that returns the distance a train is from a signal: Signal.GetDistance(Train);

Note: the OnSignalCanClear() function doesn’t appear to be called for signals that are wanting to set a route to a signal not on the panel.

Testing this out

Some simple script fragments to test these new functions:

OnSignalOnTrain()
{
	debug.print(Train.GetRoute());
	debug.print(" passing ");
	debug.printL(Signal.GetID());
}

This simple prints out a debug statement whenever a train passes one of the signals on the panel. You can also see how it is possible to access the details of the train and the signal.

OnSignalCanClear()
{
	return FALSE;
}

This code simply stops any of the panel signals from clearing (returning true) would allow them to clear as normal.

OnSignalCanRouteTo()
{
	return FALSE;
}

This code simply stops any routes being set to the panel signals. You can think of this as if a train is being offered from a neighbouring box and refused.

Step One: Stopping the forward routing from happening too soon.

In order to maximise the efficient use of the route, I don’t want trains to lock the route ahead too soon, so I’m going to add a simple section of code

OnSignalCanClear()
{
	sigid=Signal.GetID();
	float x=Signal.GetDistance(Train);

	if(sigid=="UH")
	{		
		if(x>UpAppDist)
			return FALSE;
	}

	if(sigid=="DH")
	{
		if(x>DnAppDist)
			return FALSE;
	}

	return TRUE;
}

Actually I’m controlling the home signal (because later I’m going to want to for the bi-directional loop problem). When something causes the home signal to clear (ie an approaching train), I don’t want the signal to clear too soon, because this will in turn lock the section ahead. Equally, I would like the signal to be clear before the train gets to the distant signal, so that the train is not checked unduly. So, I use the new Signal.GetDistance function to get the distance the train is from the signal (in metres) and compare this with the approach distance I’ve defined in my script’s init function:

	float UpAppDist=650;
	float DnAppDist=1050;

If the train is too far away, the signal is prevented from clearing, otherwise it is allowed to clear as normal.

Obviously, this is a fairly simple (though effective) way to achieve what I want, a more refined solution would involve looking at the class of the train, how far away any other trains are and giving priority as appropriate.

Step Two: Preventing the lock up

This is the more interesting problem, but put simply: if we have three trains in the panel area we are alright, four trains means a lock up.

So to solve this: a) we need to keep track of the number of trains in the panel area, and b) we need to prevent the fourth train from entering the panel area.

To achieve this I define a variable: TrainCount to hold the number of trains in the area. Next I write code to determine whether a train can be allowed to approach the loop:

OnSignalCanRouteTo()
{
	sigid=Signal.GetID();

	if((sigid=="UD") || (sigid=="DD")
	{
		// Maximum number of trains can cope with is three
		if(TrainCount>2)
			return FALSE;
		TrainCount++;
	}

	return TRUE;
}

This function is called when the routing logic tries to set a route to any of our signals, and in this case I’m concerned with routes being set up to the distant signals (ud and dd).

So with no trains in the loop area, TrainCount is zero and when a route is set to the distant signal, the function increments the train count and returns true (which allows the route to be set). The same is true for the second train and third trains to approach, but when a fourth train is offered, TrainCount is 3, so the test if(TrainCount>2) evaluates true and the function returns false which prevents the route being set.

This effectively prevents the lockup situation, but it is not quite complete, because we need to decrement our train counter when the trains leave the area - to do this I’m monitoring trains passing the starting signals:

OnSignalOnTrain()
{
	sigid=Signal.GetID();

	if(TrainCount>0)
	{
		if(sigid=="US")
			TrainCount--;
		if(sigid=="DS")
			TrainCount--;
	}
}

with a check as well to prevent the count going negative.

Making it Generic

A few little changes are needed to make the script generic.

• If sigid=Signal.GetID(); is changed to sigid=Right(Signal.GetID(),2); then the signal ids can be changed to (eg) London_DS and Glasgow_DS and the script will still work.
• The main functions OnSignalOnTrain() etc can be saved in a script file, then each time the script is to be used, the panel just needs the init() function and an include for the main script:

Init()
{
	persistent int TrainCount;
	float UpAppDist=650;
	float DnAppDist=1050;
}

INCLUDE PassingLoop.cpp

Note that this defines the approach distances which are the only bits that need to be customised for the specific location.

	sig=GetSig(“*ds”);            // and for the down signals.
	lnk=sig.GetRearLink();
	if(lnk.GetLocked())
		iTrains++;		
	if(lnk.GetOccupied())
		iTrains++;	

	sig=GetSig(“*dh”);
	lnk=sig.GetRearLink();
	if(lnk.GetLocked())
		iTrains++;
	if(lnk.GetOccupied())
		iTrains++;