LogixNG Reference - Chapter 6

Expression Descriptions

The expression descriptions are grouped by the socket type and category.

since 5.1.3The Call Module expression has been moved from the Other category to the Flow Control category.

Expression dialogs

When the category and type has been selected, the detail expression dialog will be displayed. The content of the dialog will vary depending on the category and type. The typical digital expression item dialog is described below.

The dialog for adding and editing expressions consists of an upper part that contains the item and the states for that item. The lower part is common to all expressions.

Chapter 6 typical expression

The Edit screen is the same except for the title, the Create button and the current content will be in the fields.

The left section is normally used to select the item, such as a turnout or a sensor. The right section is the state to be checked. The center section will normally have a is / is not combo box. The default mode will be to use the Direct tabs.

See Reference, Local Variable and Formula for details about the other tabs.

The lower section contains a standard set of items

Error Handling
If Use default is selected, the value in Preference will be used. For other options see error handling.
Catch "Abort execution"
If the error handling (see previous) for any child node is set to Abort execution, a parent node should have this option checked. This lets the parent node handle the error.
Listen
Normally, any change to an expression item should trigger the true/false evaluation. Sometimes an expression item should participate in the evaluation but not trigger it. The Listen checkbox is used to control the trigger state.
Edit comment
Each expression can have a comment. The comment dialog has a multiline text area. Click OK to save the comment.
Formula functions
These are explained in the Formula chapter.
Cancel
Close the dialog without applying any changes.
Create/OK
Save the new expression or the changes to an existing expression.

Digital expression :: Item

Audiosince 5.5.4

Returns true if the selected audio object has the indicated state. The drop-down list contains the defined audio listeners and audio sources.

Chapter 6 expression audio item

The Check only on change option is used to change the logic of the expression evaluation. When the option is not enabled, the normal evaluation occurs: Does the current state match the indicated state. When the option is enabled, the evaluation becomes: Has the current state changed to the indicated state since the last check.

Block
Clock
Conditional

If the conditional named is used in more than one Logix, the results are unpredictable.

Dispatcher

A Dispatcher train only exists from the time it is created until it is terminated. LogixNG uses the Dispatcher TrainInfo file to refer to a potential Dispatcher train. See the Saving and Retrieving Active Train Information section at Activate New Train. The train is started using the LogixNG Dispatcher Load train from train info file Action. If the related train does not exist when the expression is evaluated, the result will be false. That means a false result is either actually false or the train does not exist.

Train Mode:

Train Status:

Entry/Exit

Evaluate if an Entry/Exit pair has a specified state.

Chapter 6 entryexit expression
Inactive
Evaluate to true if the state of the specified entry/exit pair is inactive.
Active
Evaluate to true if the state of the specified entry/exit pair is active.
Other
Evaluate to true if the state of the specified entry/exit pair is unknown or inconsistent.
Reversed
Evaluate to true if the specified entry/exit pair is active and reversed. A reversed route occurs when the sensors for a bidirectional entry/exit pair are selected in the reverse order. The evaluation is triggered by a change to the active/inactive state of the entry/exit pair.
Bidirectional
Evaluate to true if the specified entry/exit pair has the Both Way option enabled in the entry/exit pair table. The evaluation is triggered by a change to the active/inactive state of the entry/exit pair. Changes to the Both Way option do not trigger evaluation.
Light
Local variable

Compares the value of the specified local variable to either a string, a memory variable, another local variable or a table cell. See Simplified Table Cell Reference for details on defining the table cell. Evaluates to true if the comparison is true.

The Type indicates the how the comparison process works.

For information about regular expressions, see: https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html

Memory

Compares the value of the specified memory variable to either a string, another memory, variable, a local variable or a table cell. See Simplified Table Cell Reference for details on defining the table cell. Evaluates to true if the comparison is true.

The Type indicates the how the comparison process works.

For information about regular expressions, see: https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html

OBlock
Power

The Ignore unknown state option is used to bypass the the unknown state. This can occur when transitioning between the on and off states.

Reference

If there is a possibility that a reference will refer to an item that does not exist or it is the wrong item type, the Reference expression can test that case and return true or false.

An example would be a table that has optional cells. A table for a staging yard ladder will have a variable number of turnouts based on the selected track.

Enter the reference to be checked and specify the type.

Chapter 6 reference dialog
Reporter

Compare the content of one of the three Reporter data fields to a string, a memory variable or a local variable. See the Memory description for a list of the comparisons.

Note: The meaning of the reports and the state number are defined by originating hardware.

Script

A script expression calls a Jython or ECMAScript script. The script context contains a result boolean object. When the script is done, it does a result.setValue(x) where x is, or evaluates to, True or False.

Chapter 6 digital expression script

The Register listener and Unregister listener options are used if the script is to run based on some other JMRI event. For example, the following register command will cause the script to be run every fast minute.

memories.getMemory('IMCURRENTTIME').addPropertyChangeListener('value', self)

Select the type of script. The supported script types are Jython Files and ECMAScript Files.

For details on accessing LogixNG objects from a script see Chapter 13 - Jython Scripting Support.

Sectionsince 5.3.5
Sensor
Sensor Edgesince 5.1.7

Returns True if the state of the sensor goes from one predefined state to another, for example from "Active" to "Inactive".

Chapter 6 expression sensor edge

If the option Only true on the first occurrence is selected, the expression will only return True once and there after return False. This is useful if you want the expression to return True only the first time it is evaluated.

Signal head
Signal mast
Transitsince 5.3.5
Turnout
Warrant

Digital expression :: Common

And

And evaluates the child expressions and if all of them returns true, the And expression returns true as well.

Antecedent

The Antecedent expression is mainly included to make import from Logix to LogixNG simple. It works exactly as Antecedent in Logix. It has a number of child expressions and an antecedent that defines how the evaluation of the expressions should be done. Each child expression is referenced in the antecedent by R1, R2, R3, ..., there R1 is the first child expression, R2 is the second child expression, and so on. Note that this differs from other expressions in LogixNG. Other LogixNG expressions use the socket name, but since the Antecedent expression is included to work as Antecedent works in Logix, the antecedent has been kept from Logix Antecedent as well. Note: Antecedent is included for compatibility with Logix but it's recommended to use Formula instead. Formula is much more powerful, uses the socket names and also works with numbers and strings.

Digital Formula

Formula is the next generation of Antecedent. It supports many operators, like ==, !=, <=, >=, <, >, +, -, *, / and %. It supports local variables, memories and functions. It supports all the types of expressions, digital, analog and string expressions. See Generic expression for details on the result of merging the other expressions.

Not

The Not expression has one child expression and answers true if the child expression answers false, and false if the child expression answers true.

Or

Or evaluates the child expressions and if at least one of them returns true, the Or expression returns true as well.

Timer

The Timer expression returns False until some time has passed. It then returns True once and the timer starts again. This expression is intended to be used together with the Sequence action. This makes it possible to have sequence steps based on time durations.

Chapter 6 timer expression

Digital expression :: Flow Control since 5.1.3

Call module

Call a module and and return its true/false response. See Chapter 10 - Modules

Digital expression :: LocoNet

Slot Usage

Evaluate the LocoNet slot usage.

Chapter 6 loconet slot usage

Digital expression :: Linux

Linux Line Powersince 5.3.4

The Linux upower command line tool is used to determine if external power is active. For example, if the external power is removed, then this tool can be used to do a graceful shutdown before the battery dies.

The expression runs the upower command line tool every five seconds. If it detects a change, it triggers the execution of the ConditionalNG.

When the expression is added, the upower command is checked to make sure it is present and working. A warning message will be displayed if there is an issue.

Chapter 6 linux line power

Digital expression :: Other

Always false

The False expression always answers false.

Always true

The True expression always answers true. This expression is commonly used as a child to the Trigger Once expression.

Connection namesince 5.1.3

The Connection name expression returns true if the selected manufacturer and connection type match a connection in Preferences ⇒ Connections.

This can be used to determine whether JMRI is using a real layout connection or a simulated connection. For example, a startup LogixNG can set an internal sensor that indicates the simulation state. Other LogixNG definitions can then check the state to determine what actions are appropriate. A good example is whether the Simulate turnout feedback action should be used.

The connection name is selected by choosing the manufacturer and then a connection name from the connection list.

Chapter 6 connection expression
File as flagsince 5.5.2

The File as flag expression checks for the existence of a file. If the file exists, the expression returns true, otherwise it returns false . When the file is found, it can be kept or deleted. Normally the file will be created by some process that needs to notify JMRI about an event. For Linux and macOS, touch filename works from the command line or a script. The are several options for Windows, such as copy nul filename, type nul > filename, or echo > filename.

Chapter 6 file as flag expression

The file selector is used to create the path to the file and file name. The default path is the user files location. If the file does not currently exist, select a different file and then replace the file name with the planned file name before creating the expression.

The default file action when the file is found is Keep file. The Delete file action can be selected which would be useful for repetitive external events.

Example

The LogixNG Timer action is used to run the File as flag expresson every 5 seconds. When the file exists, an internal sensor is set Active. The file is deleted and the timer loop resumes running File as flag. The sensor is used to trigger another process which handles the event. For simple actions, Then could be used to do the work.

Configure the Timer action.

Chapter 6 file as flag timer

Create the LogixNG.

Chapter 6 file as flag example
Hold

The Hold expression has two child expressions, one trigger expression and one hold expression. For this expression to become true, both the trigger expression and the hold expression must answer true. But then it stays true as long as the hold expression stays true.

Last result of digital expression

Each digital expression retains its most recent true/false state. This can be checked if the expression has a user name. See Chapter 3. Select the user name from the combo box.

Chapter 6 expression last result
Log data

The Log data expresson works the same as the Log data action. See Log data action for details.

Since this is an expression, it must return true or false. The window for creating the expression version includes a combo box for selecting True or False

Chapter 6 log data return options

True is recommended for And expressions and False for Or expressions.

Trigger once

The TriggerOnce expression answers true one single time and then false until its child expression becomes False and then True again.

Most often, the TriggerOnce expression will have the expression Always true as its child and it will then answers true one single time and then false until JMRI is restarted.

Analog expression :: Item

Analog constant

Return a constant as an analog value.

AnalogIO

AnalogIO reads the value of an AnalogIO and returns its value. There is currently two items that can be used with AnalogIO:

Some connections supports meters, for example current and/or voltage meters. This depends on the hardware connected to JMRI. An example is the Roco Z21 that has a current and voltage meter that JMRI can listen to.

Local variable as analog value

Return value of a local variable as an analog value.

Memory as analog value

Return value of a memory variable as an analog value.

Minutes since midnight

Return the number of minutes since midnight using either the fast clock or the system clock.

Analog expression :: Common

Analog formula

Return the result of a formula as an analog value.

String expression :: Item

Memory as string value

Return the value of a memory variable as a string value.

String constant

Return a constant as a string value.

StringIO as string value

since 5.11.2Return the value of a StringIO as a string value. StringIOs are defined in the StringIO table.

This can be used to provide an argument for an If statement. The following example tests a StringIO value for a match.

Chapter 6 if stringio value

String expression :: Common

String formula

Return the result of a formula as a string value.

Generic expression

The Digital Formula expression can use any of the other expressions. This means the lists from the other sockets and categories are combined.

The combined Item list:

The combined Common list:

The Flow Control, LocoNet and Other lists are the same as Digital expression.

Chapter 7 - References

Return to the Reference TOC