Skip to main content

JMRI is...

Common Tools

JMRI provides powerful tools for working with your layout.

System-specific Tools

Layout Automation

JMRI can be used to automate parts of your layout, from simply controlling a crossing gate to running trains in the background.

JMRI: Logix Documentation

Logix™ 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. The user interface is designed to be user friendly to all users with basic familiarity with JMRI. A Logix provides a means for setting up user-specified logic in an intuitive manner, without the user having to be familiar with mathematical logic.

Contents

The documentation below describes Logix, and discusses how to set them up. The documentation is divided into sections; click below for easy access to a listed section. If you prefer to try before reading much, read Introduction to Logix and Conditionals, then click Getting Started and follow those instructions. Return here to read about what you did.

Detail State Variable and Action Lists:

Notice: The examples described in this document use the traditional Conditional List editor.

Conditional Editor details:

Introduction to Logix and Conditionals

A Logix is a small group of Conditionals focused on a single task on the layout. Each Conditional may be viewed as a statement of the form:

if (logical expression) then (action)

The "logical expression" part of a Conditional tests the state of a group of user-specified conditions on the layout, for example, whether certain turnouts are closed or thrown, or whether a block is occupied. The "action" part of the Conditional specifies what action is to be taken if the state of the logical expression changes.

For example, one Logix with several Conditionals could control the appearance of one signal head. The first Conditional could check conditions for a GREEN appearance. A second Conditional could check on another allowed appearance. Other Conditionals could check for other appearances. A Logix is flexible enough so that the signal rules of any railroad might be set up, provided, of course, information needed to test the required conditions is available. So with only one Logix, a user should be able to set up the required logic for setting the appearance of one signal head.

Think of a Logix as a small group of one or more Conditionals that address a single need. Being able to group all the Conditionals that address that single need in one Logix simplifies things. Only one System Name is needed for all the logic addressing the task, and grouping all the logic for the task in one place, makes it much easier to see how related logical expressions might work together and how they might affect each other.

What are Logix?

Except when it is being created or edited, a Logix is "active", which means that the entities (turnouts, sensors, lights, etc.) in logical expressions of the Logix's Conditionals are being monitored. Whenever the state of any of the monitored entities of a Conditional changes, that Conditional "calculates" its logical expression. If the result of the calculation changes the value of the logical expression, then the specified actions of the Conditional are taken.

The monitored entities specified in the logical expression of a Conditional are called "State Variables" and the result of the calculation is the state of the Conditional. It is the change of state of the Conditional that causes it to issue commands for its actions to occur. The logical expression is also referred to as the "antecedent" of the Conditional and the group of actions to take is also called the "consequent" of the Conditional.

A Logix does not have a state as many JMRI entities do. A Logix does have the capability of being "enabled" or "disabled", however. When a Logix is disabled (not enabled), the logical expressions of its Conditionals are still evaluated, but the actions specified in the Conditionals are not taken. Whether each Logix is enabled or disabled is saved when the Logix is saved to disk, so a Logix that was disabled when last stored will start up disabled when next loaded from the configuration file. When a Logix that has been disabled is enabled, the states of all its Conditionals are set to UNKNOWN, and all Conditionals are calculated.

The Logix Table

A Logix is defined via the Logix Table that can be accessed by selecting Logix Table in the Tools menu. The Logix Table lists all currently defined Logix by their System Name and User Name. The table also shows whether a Logix is "Enabled". The last column of the table provides an easy way to edit a Logix and its Conditionals. Clicking the Select choice box for a Logix, will drop down a menu with four choices; Edit, Browse, Copy and Delete. Each choice will bring up a pane for the corresponding operation.

Logix Table controls

Creating a new Logix

To create a new Logix, click the Add... button at the bottom of the Logix Table pane. This will bring up a Create Logix window. Entering a System Name and a User Name, then clicking Create Logix, will create the Logix, and bring up the Edit Logix window. This window allows Conditionals to be created and edited. Once a Logix is created, its System Name cannot be changed. Its User Name, however, may be changed in either the Logix Table or the Edit Logix window. A new User Name may be any useful text, provided the new User Name was not previously assigned to another Logix.

A Logix is named using the JMRI convention. The System Name for the Logix always must begin with the two letters IX and is usually followed by a number selected by the user. For example, valid Logix System Names include: IX1, IX34, and IX100. The user name is whatever the user wants to use to identify the particular Logix, for example, "Signal 5 Control". All letters in a System Name must be in upper case. If the user enters lower case letters, JMRI will automatically convert them to upper case. Also, as a convenience to the user, if the entered System Name does not begin with IX, the program will add IX in front of what is entered. For example, to enter a System Name of IX32, simply enter 32 in the System Name field, and the program will do the rest.

The Edit Logix window displays the System Name and User Name of the Logix at the top. The User Name may be changed by entering/modifying the text in the User Name field. Next is a table of Conditionals belonging to the Logix. To add a new Conditional, click the New Conditional button under the Conditional Table. This will create a new Conditional and open the Edit Conditional window allowing the logical expression and actions of the new Conditional to be defined. An existing Conditional may be edited by clicking the Edit button of that Conditional in the table. The User Name of the Conditional may be changed in the table. The User Name of a Conditional may be any useful text, provided it is not the same as the User Name of another Conditional in the same Logix. The User Name may be the same as the User Name of a Conditional in another Logix. When editing the User Name (or any item in any JMRI table) please remember to move to another cell in the table so that the program is notified that you have finished your entry, otherwise the entry may not take effect.

Clicking Calculate under the Conditional Table causes all Conditionals of the Logix to be calculated. Resulting states are displayed in the State column of the table. However, since the Logix is being edited it is inactive and therefore no Conditional actions are taken. When the editing of the Logix is done, the Logix is activated and may be enabled to allow Conditionals to execute their actions.

The order of Conditionals in the Conditional Table may be changed by clicking Reorder (below the Conditional Table). Clicking Reorder changes all edit buttons in the last Column of the table to First. Select the Conditional that is to be first, and it is immediately moved to the top of the table. All remaining buttons change to Next. Select remaining Conditionals in desired order, until all buttons change back to Edit.

The only time when the Conditionals are evaluated in the order listed is when all of their states are UNKNOWN, such as when the Logix is being enabled. Conditionals are evaluated when one of their state variables changes its state. If an entity is used as a state variable in more than one conditional, it is indeterminate which conditional is evaluated first.

When Done is clicked at the bottom of the Edit Logix window, any change in the Logix User Name is checked and made. A check is made for inconsistencies in specifying that an entity (sensor, turnout, etc.) referenced in multiple state variables is not monitored as a trigger for calculation of the Logix, and a warning message appears if any inconsistencies are found. Then the Logix is activated, the Edit Logix window is dismissed, and the user is returned to the Logix Table. Immediately before the Logix is activated, the state of all its Conditionals is set to UNKNOWN. Immediately after activation, all Conditionals are calculated.

The Edit Logix window also provides a way to delete a Logix if it is no longer needed. Click Delete Logix to delete the Logix being edited and all its Conditionals. This operation can also be done by selecting the Delete item from the drop down Select menu on the Logix Table.

Selecting the Browse item from the drop down menu on the Logix Table will open a window with a list showing the details for each conditional. It is an effective way to review the entire contents of a Logix. Click on the close button to close the window.since 4.7.3

Conditional Browser Window

Selecting the Copy item from the drop down select menu on the Logix Table will show a series of dialog windows that provide a way to copy the Logix and any or all of its Conditional to a new or existing Logix.

Conditionals

A Conditional's System Name has the form IXnnnnCmm, and is set automatically when the Conditional is created by the user clicking New Conditional in the Edit Logix window. The System Name of the first Conditional for Logix IXnnn will always be IXnnnC1, the second Conditional will have System Name IXnnnC2, and so on. The User Name of a Conditional is whatever the user wants to assign to identify the use of the Conditional. An entered User Name must not be used by more than one Conditional within a given Logix, however. The System Name and User Name are displayed at the top of the Edit Conditional window. The User Name may be entered/edited there or in the Conditional Table of the Edit Logix window. The User Name of a Conditional may be any useful text, provided it is not the same as the User Name of another Conditional in the same Logix. The user name may be the same as the User Name of a Conditional in another Logix.

As mentioned above, Conditionals are statements of the form:

if (antecedent) then (consequent).

Therefore a Conditional has two distinct parts: its "logical expression" and its "actions". These are discussed separately below.

Logical expressions connect the states (true or false) of "state variables". State variables test conditions on the layout or in the program, for example, if a sensor is active or inactive, if a turnout is closed, if a signal head is red, if the fast clock time is between 10:00 and 11:00, etc. State variables are linked together in a logical expression by logic operators. For a list of currently available state variables, see State Variables

Logic operators currently available are NOT, AND, AND NOT, OR and OR NOT. The AND operator is set up automatically by the program. For each state variable, the user selects whether the NOT operator is to precede the state variable. If the NOT operator precedes the state variable, the true/false value of the state variable is reversed. For example, if "Sensor Active CS5" is true, "NOT Sensor Active CS5" will be false, and vice versa. Note that "Sensor Active CS5" is sometimes not the same as "NOT Sensor Inactive CS5", because Sensor CS5 may be in the UNKNOWN state.

Logical expressions read like written statements. It is easy to set up a logical expression to evaluate many situations on the layout. For example, "if block 10 and block 11 are occupied and turnout 20 is thrown" would be set up as:

where LS1020 is a sensor that is true when block 10 is occupied (perhaps from a BDL168), sensor LS1021 is true when block 11 is occupied, and Turnout Thrown LT20 is true when turnout LT20 is thrown. This logical expression would calculate to true if all three of the state variables are true, i.e., if block 10 is occupied AND block 11 is occupied AND turnout 20 is thrown; otherwise it would calculate false.

Actions may be specified for each Conditional. A number of action types are available. For example, Set Turnout, Set Signal Appearance, Trigger Route, etc. For a list of currently available action types, see Actions. Each action has a user selectable option of being performed if: 1) the logical expression changes to true, 2) the logical expression changes to false, or 3) the logical expression changes. This means a conditional may actually be three statements.

The Edit Conditional Window

The Edit Conditional window is where logical expressions are set up and where actions are specified. The Edit Conditional window is displayed when a Conditional is created, or when the Edit button of a Conditional is pressed in the Edit Logix window. The Edit Conditional window displays the System Name and User Name of the Conditional at the top. The User Name may be edited by entering/modifying the text in the User Name field. Any text may be used, provided it doesn't duplicate the user name of another Conditional in the same Logix. Next are two sections--one for the setup of a logical expression and one for set up of the actions.

The Logical Expression

The logical expression section contains a table of state variables, with two buttons and a drop down menu box below. The drop down menu allows the choice of what logical operators to use in the antecedent. The choices are: all AND's, all OR's or Mixed. Mixed allows the user to specify any combination of AND's, OR's and NOT's. When this choice is made the logical expression requires parentheses in order to be unambiguous. So, when this choice is made, a text field is displayed so that parentheses can be inserted and the expression modified. The state variables are represented in the expression by their row number.

The first column in the state variable table is the row number of the variable. The next column displays the logic operation preceding the variable in the expression. In the case of "Mixed" a choice box allows the user to choose an operation. However these choices can be changed in the antecedent text field and it is the text field expression that the Conditional uses to determine its state. The third column contains a choice box that allows the user to select the NOT operator as needed.

The fourth column is a description of state variable and the condition to be monitored to be for its state to be true. The next column shows the state that was last tested for the variable (true or false). The state displayed includes the effect of the NOT operator, if NOT is selected.

The "Trigger" column sets whether the state variable should cause the Conditional to perform its actions when this variable changes. Note that the current states of all the variables are always used in the calculation of the Conditional's state. The "Trigger" setting allows a state variable to be "passive" and not cause the conditional to evaluate its state. That is, such a variable state is a necessary condition, but not a sufficient one to cause any actions to take place.

Note: Disabling state variable triggers should be done with caution. Actions are performed only when the state of the logical expression changes. Disabling a trigger can prevent actions from be executed even when this state has changed.

Next is a column of Edit button to modify an existing state variable. The last column of the table (Delete buttons) is used to delete a state variable if you decide it is no longer needed.

Press the Add State Variable to add a state variable (a row in the state variable table). This brings up a window with a choice box for the user to select a state variable type. Available state variables are documented at State Variables. When a type is chosen the Edit Variable window displays a text field for the name of the entity to be used for the state variable. When a name (either System Name or user name) is entered, it must correspond to an existing entity (sensor, turnout, light, etc.). Depending on your selection method, a tabbed Pick List, a single Pick List or a dropdown combo box will be displayed to aid in name selection.

At any time during the entry of state variable data, the Check State Variables button may be clicked to check the entered data and evaluate the state variables. When this button is pressed, the checking and evaluation proceeds until the check completes successfully, or an error is detected. If an error is detected, the checking stops for the user to correct the error and click Check State Variables again. Please remember after editing the System Name and data items to click a different cell in the table before clicking Check State Variables (or Update Conditional at the bottom of the window) so that the program is notified that you have finished your entry. Otherwise your entry may not take effect, and an error may be reported unnecessarily.

Triggering the Actions

There are two policies that can be taken after a conditional's state is evaluated:

Which policy to use is chosen by the radio buttons in the middle of the Edit Conditional window. The Execute actions on change of state only button prevents unwanted behavior from occurring when multiple instances of the "on true" or "on false" actions are executed. That is, if successive triggers cause the logical expression to be evaluated to the same state, only the first trigger will execute the actions. Normally, it is best for a conditional to execute its actions only when the state of the conditional changes. However, if it is important to maintain the actions associated with a particular state of the Conditional the Execute actions whenever triggered button should be used. If external events undo some of the actions of the conditional but do not change the state of the conditional, then this policy will execute the action on any trigger.

The Actions

The Actions section of the Edit Conditional window contains a table of actions, with two buttons below for adding a new action and reordering the list of actions. The section provides for specifying the actions to be taken when a Conditional is calculated and changes its state. The action table consists of a column for the description of the action to be taken and two columns of buttons, Edit and Delete, for editing or deleting an existing action. To add a new action, press the "Add Action" button. A new "Edit Action" window will appear. Select an action type in the type box, and data items needed to completely specify the action will appear to the right of the type box. When a name must be entered, the name must correspond to the System Name or the User Name of an existing entity (sensor, turnout, signal head, etc.) of the proper type. Depending on your selection method, a tabbed Pick List, a single Pick List or a dropdown combo box will be displayed to aid in name selection. Available action types are described in detail at Actions. If you use User Names to specify your actions, the same caution noted above applies. Be very careful when editing User Names that are used to specify actions.

For each action, three options are available for when to perform the action: 1) On Change to True, 2) On Change to False, and 3) On Change. These refer to the calculated state of the Conditional, which is equal to the value of the logical expression as specified in the state variable table. One of these options must be selected. When done, click either "Update" to install your changes, "Cancel" to close the window without any changes or "Delete" to remove the action entirely.

To change the order order of the Conditionals in a Logix, or the order of the actions in a conditional click the "Reorder" button. The right-most buttons in the table will then let you select the first one, next one, etc. Note however, this is merely the order in which the commands are issued but do not guarantee that their final effect will occur in the same order. If it is necessary to have actions take place in a specified order, use separate Conditionals for each action and chain the Conditionals such that a preceding action's completed state is the state variable for the succeeding action.

Saving the Conditional

When the logical expression and actions have been specified, click Update Conditional at the bottom of the window. This initiates a check of the logical expression (the same as done by Check State Variables) and a check of entered data for actions. If the Conditional's User Name has been edited, it is also checked. If an error is found, a message box opens announcing the error, and the update is stopped to allow the user to correct the error and click Update Conditional again. If no error is found, the Conditional is updated with the entered data, the Edit Conditional window is closed, and the user is returned to the Edit Logix window.

Two other buttons are available at the bottom of the Edit Conditional window. Clicking Cancel will close the Edit Conditional window without updating the Conditional. Clicking Cancel results in loss of any data that has been entered. The other button, Delete Conditional, provides an easy way to delete an unneeded Conditional. Click Delete Conditional to delete the Conditional being edited and return to the Edit Logix window.

Getting Started

The following steps let you create your first Logix and become familiar with how the Logix user interface works.

  1. Select Table -> Logix in the Tools menu.
  2. Click the Add... button below the Logix Table.
  3. In the Create Logix window that appears, enter 6 for System Name, and "test" for User Name, then click Create Logix.
  4. In the Edit Logix window that appears, click New Conditional.
  5. In the Edit Conditional window that appears, click Add State Variable to begin defining a logical expression for the Conditional.
  6. In the new window that appears, click the "Variable Type" choice box to reveal a scrolling selection box. Select "Sensor".
  7. Note that a text field appears asking for entry of a sensor name. Enter the name (either System Name or User Name) of any of your existing sensors. (If you don't have an existing sensor, select Sensor Table in the Tools menu and create one.) Select Inactive from the Variable State drop down.
  8. Click the Update button and note the row entries that appear in the state variable table.
  9. Click New State Variable to create another row in the table. Note that AND appears in the first column of the new row. Again select "Sensor" as the variable type, and enter the name and desired state of a different sensor (create it if needed).
  10. Click the third column entry of the second row to reveal the selection box for NOT. Select NOT, then click Check State Variables again. Note that the State of the second state variable has reversed.
  11. For an Action click Add Action.
  12. In the new window that appears, click the "Action Type" choice box to reveal a scrolling selection box. Select "Turnout", and enter the name (System Name or User Name) of one of your turnouts. (If you don't have any turnouts, create one using the Add button in the Turnout Table.) Select Set Turnout for the Action Type, leave the "Turnout Position" option at "Closed" and "Change Option" at "On Change to True".
  13. Click the Update button and note the row entries that appear in the action table.
  14. For another Action - again click Add Action and select "Turnout". Enter the name of the same turnout entered before. Select "On Change to False" as the Trigger Option, and "Thrown" as the Turnout Position.
  15. Click Update to close the Edit Conditional window and return to the Edit Logix window.
  16. Click Done to close the Edit Logix window and activate your new Logix. Click OK in the reminder-to-save dialog that appears.

You'll have created a Logix to control the setting of a turnout according to the states of two sensors. It's as simple as that. It took you more time to read this tutorial than to create the Logix.

Additional Notes

This section contains questions and answers that normally are not needed by Logix users, but in some cases were important or of interest for previous versions of Logix.