This draft documents the actual implementation. Please refer to the source code for implementation details as the implementation is currently unstable.

The distant signal API is available as advtrains.distant and implemented by advtrains_interlocking/distant.lua. The API is not documented at the moment as it is not considered stable.

Internally, the method of assignment (i.e. whether the signal is assigned manually or by the routesetting system) is irrelevant to the API. However, this information is kept.

Distant signals are automatically updated when (un)assigned.

The signal formapecs have been slightly reworked to allow manually assigning distant signals.

Automatic signal assignment is partially implemented. Distant signals are assigned when the route is set. However, automatically unassigning signals is not yet implemented.

• The signal aspect accessors (advtrains.interlocking.signal_set_aspect and advtrains.interlocking.signal_get_aspect) have been modified to cache signal aspects. The advtrains.interlocking.signal_get_real_aspect function is added to access the signal aspect directly.
• advtrains.interlocking.signal_set_aspect has been modified to
  • Update the distant signals
  • Adjust the signal aspect based on the signal type and the distant signal assignment.
• The advtrains.interlocking.signal_readjust_aspect function is added to readjust the aspect of the signal.

Route signals share a similar aspect table as traditional speed signals, with two additional fields:

• type2group: the type of route signal
• type2name: the name of the signal aspect

Conversion between speed signal aspect tables and route signal aspect tables is possible, although currently with a few minor issues.

The corresponding API is implemented in advtrains_interlocking/signal_aspects.lua and available as advtrains.interlocking.aspects.

There is currently some work on implementing distant signaling. Differences between the proposal and the implementation will be addressed in a later draft, along with other issues not mentioned here.

This draft is mainly written to address the issues that appeared in the first draft. In particular, it addresses a request to implement route signaling.

Distant signals may be assigned to any signal. These distant signals are automatically set with the signals they are assigned to.

With automatic distant signal assignment, the user needs to assign distant signals to TCBs. A TCB may have multiple distant signals assigned to it. For combined main/distant signals, however, the main and distant aspects may not be assigned separately.

These distant signals are then assigned to main signals when needed and unassigned when the aspect of the distant signal become irrelevant to rail operation. Specifically:

• When a route is set, the distant signals along the route are assigned to the upcoming signal (i.e. the signal first signal a train should encounter after passing the TCB). These distant signals are then set correspondingly.
• When a train leaves a TCB, the distant signal, if assigned to another signal, is unassigned. This should, at least theoretically, be safe as no other train is, at the moment, allowed to pass the TCB that the distant signal is assigned to.

• When a signal aspect is set, the distant signals are set correspondingly.
• When a distant signal is unassigned, its distant aspect is set to nil.

The functions are given as indices of the advtrains.interlocking table.

• The name field includes the name of the main aspect, if the alternative signal aspect table is used.
• The dst field includes the distant aspect. This is mentioned in the current source code, but not used at the moment and may need further discussion.
• The dst_name field includes the name of the distant aspect, if the alternative signal aspect table is used,
• The dst_repeater field is set if the signal is a distant signal repeater.
• The dst_shortened_distance field may, in the future, be used to indicate that the distance to the oncoming signal is shortened.

• assign_distant(pos, dst) - Assign dst to the signal at pos
• unassign_distant(dst) - Unassign the distant signal dst
• distant_of(pos) - Get the distant signals assigned to pos
• get_assignment(pos) - Get the signal that pos is a distant signal of

• set_distant(pos, dst) - Set the distant aspect of pos to dst
• set_main(pos, main) - Set the main aspect of pos to dst

The alternative signal aspect table is mainly intended for route signaling.

The table of supported aspects should include the following fields:

• name: A name identifying the signal aspect table. Note that this is not shown to the user
• label: The name of the signal aspect to show to the user (e.g. in a UI). The use of attrans is recommended here.
• main: A list of supported main aspects. An error is signaled if this list has less than two entries.
• dst: A translation table where each key is the name field of the aspect and the value is a name that is passed to the set_aspect field of the distant signal.
• alt_translation: A translation table where the key is the name of the table of supported aspects and the value is a table with key-value pairs of the original aspect name and the translated aspect name (as in the main field of the aspect)

When registering, the signal should provide the following fields:

• aspects: The name of the table of supported aspects (see above).
• is_dst: A boolean indicating whether the current signal is a distant signal.

Each main aspect entry should contain the following fields:

• name: The internal name of the particular aspect.
• main: The maximum allows speed. This is -1 in a lot of cases.

The last entry in the list of supported aspects should have the main field set to 0 (i.e. stop). The nth entry in the list (which is not the first or last entry) indicates that the next signal has the same aspect defined by the n+1th entry in the list. The first entry in the list indicates that the next signal has the same aspect of the first or the second entry in the list.

• When a distant signal defined with the alternative signal aspect definition table is assigned to a signal that is not defined with the same signal aspect table, the distant signal is always given the n-1th entry (with n being the number of defined main aspects of the distant signal) unless the main aspect of the upcoming signal is -1, in which case the distant signal is given the first entry of the defined main aspects of the distant signal, or an entry in the translation table can be used to determine the distant signal aspect.
• When a distant signal defined with the current signal aspect definition table is assigned to a signal defined with the alternative current signal aspect definition table, the main field of the signal aspect is passed to the distant signal.

This draft has been superseded.

In this proposal, error situations do not need to be detected unless it is explicitly stated that the error is signaled.

• Each TCB side can have one distant signal and multiple distant signal repeaters assigned to it.
• The main signal can also be assigned as a distant signal, but it is an error if the main signal is a distant signal repeater.
• Distant signals should be able to operate as a regular distant signal or as a repeater. It is an error if this condition is not satisfied.
• It is an error if there is no regular distant signal between a distant signal repeater and a main signal.

Edit: I think I should allow having only one distant signal assigned to a TCB side at a time. This is likely easier to implement; alternatively, it should be possible to assign a distant signal to reflect the signal aspect of a main signal or a distant signal (e.g. for a distant signal repeater). — ywang 2022-01-01 03:00

The distant signals of a main signal is only set when the route to the main signal is set and goes through the distant signals. The interlocking system can do so by traversing through the route to the main signal and setting the distant signals on its way. The first distant signal is treated as a regular distant signal, and the rest are treated as distant signal repeaters. A list of distant signals assigned to the main signal should be kept to make sure that the distant signals are updated as the aspect of the main signal changes.

It should be selectable whether a signal on the route should be treated as distant signal and which not. At least the user shoud be able to set which is the first intermediate signal on the route that should serve as distant signal. The reason for this is that there may be a very long block (the route start signal should not pre-display any distant aspect here) and there is a dedicated distant-only signal before the next main signal. — orwell 2021-12-31 17:22

What I thought about was that you need to explicitly set a signal as a distant signal by assigning it to a TCB (separately from the main signal - if you have e.g. a Ks signal you need to assign it twice) or by assigning it to an existing signal. — ywang 2022-01-01 03:00

I thought about this again: the main and distant aspects, when both assigned, should be assigned to the same TCB. It does not make much sense otherwise. — ywang 2022-02-10 17:49

— orwell 2021-12-31 17:22 The above approach requires that each distant signal (even if it is a pure distant signal without main signal function) is assigned to a TCB (correct?).

I propose a separate mode where the distant signal is not assigned to a TCB, but instead shows the distant aspect of one (user-selected) main signal at all times, irregardless of route settings. Of course this only makes sense for pure-distant signals.

We can use this for simple distant signals before mainline main signals when we don't want to add another TCB (and thus make the block section 2 track sections instead of just one).

Makes sense. I have appended it to the previous section. — ywang 2022-01-01 03:00

The procedure of setting the aspect of distant signals must be done in a way that the distant signal(s) showing the aspect of the main signal can be found. Distant signals are unset (i.e. set to nil) when the main signal and/or the distant signal becomes irrelevant for any train, such as when the distant signal is a combined signal showing the Hp 0 aspect.

In the following case:

^
|
+---- Main signal H1
|
|  ^
|  |
|  +- Main signal H2
|  |
|\/|
|/\|
|  |
|  +- Combined signal H4 (main)/V2 (distant)
|  |
|  V
|
+---- Combined signal H3 (main)/V1 (distant)
|
V

If both routes H4→H2 and H3→H1 are set, then

• V1 is set to reflect the main aspect of H1. It is unset when the train passes H1.
• V2 is set to reflect the main aspect of H2. It is unset when the train passes H2.

If the route H3→H2 is set, then

• V1 is set to reflect the main aspect of H2. It is unset when the train passes H2.
• V2 remains unset as it is not relevant for the train using the route.

— orwell 2021-12-31 17:22 IMO the easiest way to provide clean distant signal support is via extending the “Signal Aspect” table. Proposal:

asp = {
  ... other fields as usual ...
  dst_pos = <position vector>,
  dst = nil, -- 'dst' field is not provided directly

Then, within advtrains.interlocking.signal_set_aspect(pos, asp), the dst_pos field is looked up and the dst field is set accordingly before the set_aspect() of the node definition is called.

2 things need to be taken care of:

1. the signal API somehow needs to keep track of the aspects the signals are supposed show - not only for the TCB-assigned signals but for all signals
2. the signal API needs to remember a reverse lookup of signals that have dst_pos set on a signal, to trigger aspect updates accordingly.

With this implementation, the distant signals feature can also easily be used from LuaATC-controlled signals. The route mechanism can just plug into that and set the position of the route end signal as dst_pos.

Whether signal is a distant signal repeater would then be another field in the aspect definition (dst_repeater = <boolean>)

Also, there is this “Verkürzter Bremswegabstand” light in Ks signals - dst_short = <boolean>?

In an earlier implementation I simply put the distant signal information (position of the main signal or the distant signal) in the signal table itself instead of the aspect table. That made it possible to keep track of what is assigned to what. I would prefer having the signal aspect table as a fallback when the source of the train is unknown. The “verkürzter Bemswegabstand” feature might be a bit complicated when you have a distant signal that can be assigned to multiple main signals (e.g. at a turnout), and I would prefer a method that computationally figures out whether the braking distance is reduced, which is beyond my abilities at the moment. — ywang 2022-01-01 03:00