JMRI: LogixNG Documentation

This page is the user manual for LogixNG. For the technical aspects and how to extend LogixNG with new features, see the Technical documentation of LogixNG.

LogixNG provide a powerful capability for JMRI to monitor one or more conditions on a layout, and take action when these conditions change in a user-specified way. Logix can be used to control signals, crossing gates, and other types of automation on the layout.

LogixNG documentation

The most common building blocks in LogixNG is Expressions and Actions. Expressions ask a question while Actions do somethings. It can be described as:

if (expression) then (action).

An expression ask a question which can be true or False. "Is turnout LT20 thrown?" If it is, the answer is True, else it's False. Some expressions depends on other expressions. Like the "And" expression, which is True if all of its expressions are True. There is also a timer expression which becomes true when a certain time has passed.

Actions do something. They can set a turnout or a signal. Some actions activates other actions, which in turn do something.

There are also AnalogExpressions, AnalogActions, StringExpressions and StringActions. AnalogExpressions returns an decimal number, for example the voltage to the track. StringExpressions returns a String. An AnalogAction sets a decimal value, for example the desired voltage to the track. A StringAction sets a string, for example a message to be sent to throttles that support text messages.

Expressions

And - True if all of its expressions are true.

Hold - This expression has expressions, the hold expression and the trigger expression. The expression. becomes true when both the hold and the trigger expression is true and it then stays true as long as the hold expression remains true. This expression can be used then a condition is true under a short period of time, for example a button that the user presses, and there the expression needs to stay true.

Reset On True - This Expression has two expressions, the primary expression and the secondary expression. When the primary expression becomes True after have been False, the secondary expression is reset.
The result of the evaluation of this expression is True if both the expressions evaluates to True.
This expression is used for example if one expression should trigger a timer. If the primary expression is a sensor having a certain state and the secondary expression is a timer, this expression will evaluate to True if the sensor has had that state during the specified time.

Timer - This expression has a timer. The expression is true if the time has passed.

Trigger Once - An expression that has another expression. It is true the first time the child expression is true and then becomes false. It stays false until the child expression becomes false and then true again.

Turnout - True if a turnout has a certain state.

Actions

Do If - This action ask an expression if its condition is true. If it is, it activates an other action.

Many - This action activates many other actions.

DoAnalogAction - This action has an AnalogExpression and an AnalogAction. It asks the AnalogExpression about the value and then sets that value to the AnalogAction.

DoStringAction - This action has an StringExpression and an StringAction. It asks the StringExpression about the value and then sets that value to the StringAction.

Turnout - Set the state of a turnout.

AnalogExpressions

GetAnalogIO - Gets the value of an AnalogIO.

AnalogActions

SetAnalogIO - Sets the value of an AnalogIO.

StringExpressions

GetStringIO - Gets the value of a StringIO.

StringActions

SetStringIO - Sets the value of a StringIO.

How to setup LogixNGs

Time Diagram

Plugins for LogixNG

LogixNG has gone thru big changes and the code for plugins is not up to date.

LogixNG supports expression and action plugins. This can be done in two different ways, native plugin or external plugin.

A native plugin is a class that implements the Expression interface or the Action interface. The downside is that the jar file with these classes needs to be placed in the JMRI classpath to be accessible for JMRI. But as long as they are located at the JMRI classpath, they will be included automaticly.

A external plugin is a class that implements the ExpressionPluginInterface interface or the ActionPluginInterface interface. These classes can be placed anywhere, but they needs to be configured by the user. That is, the user has to point JMRI to the jar file and select which classes in the jar file to use with JMRI.

LogixNG system names

LogixNG enforces a strict naming convention of system names.

  • All user created LogixNG system names starts with IQ followed by a number. Example: IQ54
  • All auto-generated created LogixNG system names starts with IQA followed by a number. Example: IQA54

All system names for expressions and actions starts with the system name for the LogixNG that it belongs to, followed by a colon, followed by the type of expression or action, followed by a number.

  • DA Digital Action
  • DE Digital Expression
  • AA Analog Action
  • AE Analog Expression
  • SA String Action
  • SE String Expression

For auto-generated system names, the letter A is appended after the type letters above. For example, DAA for auto-generated digital action and SEA for auto-generated string expression.

Examples for actions and expressions

  • IQ21:DA52 Digital Action
  • IQ21:DE52 Digital Expression
  • IQ21:AA52 Analog Action
  • IQ21:AE52 Analog Expression
  • IQ21:SA52 String Action
  • IQ21:SE52 String Expression
  • IQ21:DAA52 Auto-generated Digital Action
  • IQ21:DEA52 Auto-generated Digital Expression
  • IQ21:AAA52 Auto-generated Analog Action
  • IQ21:AEA52 Auto-generated Analog Expression
  • IQ21:SAA52 Auto-generated String Action
  • IQ21:SEA52 Auto-generated String Expression

Error handling

This is yet to be implemented.

Sometimes an error occurs. It may be due to an error on the layout, an arithmetic error or something else. Each action and expression can handle that and there are a couple of options.

  • Show a dialog box
  • Log the error
  • Log the error once
  • Let the action or exception above handle it

These options can be configured at three different layers:

  • For each action or expression
  • For the LogixNG the action or expression belongs to
  • In the LogixNG preferences

The default is to log the error once. And by default, neither each LogixNG nor each action and expression overrides the settings in the preferences.

The recommendation is to set the desired error handling in the LogixNG preferences, which sets it for all actions and expressions. And then override that setting at the LogixNG level or an individual action or expression when needed.

For example, a LogixNG that has an AnalogAction that sets an analog value may want to abort that particular LogixNG if something goes wrong, for example due to an arithmetic error. In that case, that LogixNG can be configured to "Let the action or exception above handle it", which means that the LogixNG will be aborted since no action or exception in that LogixNG will handle the error.

Note that for actions or expressions that has multiple children, for example the "Many" action, an that is not handled in one of the children will abort that action or expression even if there are more children to execute. Lets say, for example, the action "Many" have three child actions A, B and C, and the Many action itself handles the error but not the child A. If an error occurs in A, the Many action will be aborted so that actions B and C will not be executed, but the parent of the Many action will not be affected by the error.

Execution groups

Execution groups are yet to be implemented.

This section is on an advanced topic that most JMRI users probably don't need to use. It's recommended to learn to use LogixNG before starting to use execution groups.

The LogixNGs are executed when one of the actions or expressions notify the LogixNG manager that it wants to execute the LogixNGs. This may be due to a change on the layout, for example an activated sensor, or a timer that is finished.

As default, this executes all the LogixNGs. But there may cases there this is not desired. It can be due to large layouts or due to some Actions or Expressions that takes a long time to finish.

To solve this, LogixNG groups all the LogixNGs into execution groups. When notified, the LogixNG manager executes the LogixNGs that are part of a particular execution group.

In case one LogixNG wants to trigger execution of another execution group whan the one it belongs to, one can use the ActionTriggerExecutionGroup that notifies the LogixNG manager to execute a predefined exectution group.

If the LogixNG manager gets several notifications before it can execute an execution group, it always starts with the execution group with the lowest system name. For example, the main execution group, IQEG0, always has the highest priority.

The execution groups are Named Beans and has a system name and a user name. The system name is IQEG<number>, where the main execution group has the system name IQEG0. (I=Internal, Q=LogixNG, EG=ExecutionGroup).