Elekdra Scripting

The functionallity of Elekdra and some clients can be extended by some user implemented scripts. This goes beyond what is already possible with the XML configuration.

Index

Elekdra signal commanding - how to go beyond what is natively possible over LocoNet with Elekdra
Elekdra Script Client - the low level access to elekdra from user scripts
What can be called from the scripts
Technical background

Elekdra signal commanding

Without scripts, there are two ways to send commands to signals:

OPC_SE over LocoNet - this is only understood by the "Watti" decoder, but has the ability to send a detailed signal aspect information.
A single OPC_SW_REQ over Loconet, which is normally transferred by a DCC command station to a normal switch command that is understood by a normal DCC accessory decoder. Both lots of commercial as well as do-it-yourself decoders are available. Problem: Elekdra can only distinguish between STOP and GO this way.

With a script the user has a lot more flexibility. The following new possibilities are available now:

More than one command

The script can send an arbitrary sequence of LocoNet commands. For example a two armed signal can get two commands, one for each arm. Please see this JavaScript implementation as an example.

Address arithmetics

Some DCC light signal decoders need only a single command but distinguish aspects by different addresses. The configuraton of the signal can define a base address, the script sends a command to this base address plus an offset that selects the actual aspect.

Aspect merging

Sometimes the dependency between the aspect of the mandatory signal and a distant signal on the same mast are beyond simply commanding the distant signal to DARK if the mandatory signal shows STOP. For example if the mandatory signal would show GO and the distant signal would show STOP, the signal may have to actually show GO50. If the user configures a script for the mandatory signal and neither LocoNet nor script for the distant signal, any state change of the distant signal also triggers an execution of the mandatory signal script. This enables the script to combine the state information of both elements to a single aspect, using the LocoNet output that is understood by the decoder.

How to embed the scripts into the configuration

You define the scripts in one or more configuration blocks <elekdra.scripting>. Inside the <elekdra.signal> that shall execute a script on state change, you use <script> in order to name the script that you want to call. Several similar signals could call the same script.

Elekdra Script Client

This program is currently being implemented. The design goals are:

Any status message from Elekdra can trigger a script execution
The scripts can invoke any command in Elekdra
LocoNet interaction should be possible

What can be accessed from the script?

The script has access to several functionallities of the Java program that it was started by.

Logging

Elekdra and all known clients use a software library called Log4J in order to write logging messages into a text file. A logger object that gives the script access to this system is available by the name log. Example:

log.info("hello world!");

You can call logging methods.
Note: standard output is redirected to log.info() and error output is redirected to log.error().

Loconet

Methods that send to Digitrax LocoNet can be accessed via the symbol elekdra. Detailed description folows...

Technical background

All examples are using JavaScript as language, because the Oracle Java Runtime Environment already comes with an integration of this script language. I recommend that you choose the same language unless you really know what you are doing. But in theory every language that has a JSR-226 compliant Java integration can be used, if it is found in the 'classpath'.