Conditional List Editor
When Edit is selected for a Logix, the Edit Logix window is displayed.
The Edit Logix window allows Conditionals to be created and edited. The system name and user name of the Logix are displayed 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 (a new row in the Conditional Table), and open the Edit Conditional pane 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. Conditional user names may be any useful text, provided the new user name is not used by another Conditional belonging to this Logix. It may be the same as the user name of another Logix's Conditional. 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. Since the Logix is "inactive" while being edited, no Conditional actions are taken when the Calculate button is pressed.
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. Note that the order that Conditionals are listed in the Logix does not determine the order in which they're evaluated, nor does it force evaluation of one Conditional when an earlier or later one is evaluated. For more on this, see the discussion on the Logix main page.
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 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 at the top displays the system name and user name of the Conditional. The system name is automatically set by the program and cannot be changed. The user name may be edited by entering/modifying the text in the User Name field. The user name may not be the same as the user name of another Conditional in this Logix, but may be the same as the user name of a Conditional in a different Logix.
Next are two sections--one for the setup of a logical expression and one for set up of actions. Conditionals are statements of the form:
if (logical expression) then
A Conditional has two distinct parts: its "logical expression" and its "action". The window has separate sections for the set up of each.
The logical expression section contains a table of state variables, with two buttons below. The first column in the state variable table displays the row number of the state variable. This is only of importance when the Logic Operator choice is set to 'Mixed'. The second column contains an automatic AND when the Logic Operator choice is set to 'AND' or an automatic OR when the choice is 'OR'. When the choice is 'Mixed' the user may select AND or OR as needed. 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 the state variable type and the condition for which it is to be tested. Next is a column displaying the current state for the test description. The state displayed includes the effect of the NOT operator, if NOT is selected.
The Triggers Calculation column contains checkboxes that normally are checked, so that a change in the state variable will trigger a calculation of the Logix. For those cases where a change in a specific entity (sensor, turnout, etc.) should not trigger a calculation result, you should uncheck the checkbox by clicking on it. Unchecking the checkbox tells the program to monitor that entity for state changes and calculate the state of the Conditional, but take no action on the result of the calculation.
The last two columns of the table (Edit and Delete buttons) are used to edit or delete that row in the state variable table. Delete a state variable if you decide it is no longer needed. The State column of the table shows the state (true or false) of each state variable when it is evaluated.
At any time during the entry of state variable data, Check State Variables may be clicked to check entered data and evaluate state variables. When this button is pressed, checking and evaluation proceeds until the check completes successfully, or an error is detected. If an error is detected, checking stops for you to correct the error and click Check State Variables again. Please remember after editing 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.
The Reorder button is used to changed the order of the conditional variables. This button is disabled if the Logic Operator is set to Mixed.since 4.9.2
The default Logic Operator is "AND". In this case the Conditional will test if all variable tests are true, after taking the "NOT" negations into account. Using the Logic Operator box below the list of variables, you can change that to "OR" or "Mixed". "OR" means the conditional will be true if any one of the variable tests are true, after accounting for the negations. Selecting "Mixed" will let you enter a logical expression in a new text box using AND's, 'OR's and NOT's and the row numbers. In this expression, each variable is referred to by number, e.g. R1, R2, R3 for the 1st three variables, you can use the operators "and", "or" and "not" in addition to parentheses. Some examples:
R1 and R2
R1 or (R2 and R3)
(R2 and R3) or (R3 and R1)
Add/Edit State Variables
Press the Add State Variable to add a new state variable (a row in the state variable table) or click on an Edit button to edit an existing State Variable. .
If a new Variable is being created, only the Variable Type will be displayed. Once a choice has been made, other fields will be displayed based on the selected type. Available state variable types 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.). The actual method for entering names will depend on the conditional name selection method setting. See Conditional Name Selection Method.
For Conditional References, the text input field is replaced by two drop down combo boxes. The first box is used to select the Logix, the second box is used to select a Conditional that belongs to the selected Logix. since 4.7.4
After the name is entered, select the required state from the Variable State drop down box. Depending on the selected variable type and state, additional fields may be displayed.
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 pane) 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.
The action section contains a table of actions, with two buttons below. The action list shows a description of each action. The Edit button is used to change an action. The Delete button is used to delete an action.
Actions are evaluated in the order listed. To change that order, click the "Reorder" button on the "Edit Conditional" window. The right-most buttons by the actions will then let you select the first one, next one, etc.
Press the Add Action button to add a new action or click on an Edit button to edit an existing Action. .
If a new Action is being created, only the Action Group will be displayed. Once a choice has been made, other fields will be displayed based on the selected type. Available Acton types are documented at Actions.
When a type is chosen, the Edit Action 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.). The actual method for entering names will depend on the conditional name selection method setting. See Conditional Name Selection Method.
As an advanced feature, the name of an entity can be entered as an "indirect reference" to a memory location. By that we mean, rather than naming the action directly, the value of a memory location is used for the name of the action. To do this you enter the name of the memory entity preceded with the "@" symbol.
For example, suppose an Input Memory icon or a ComboBox Memory icon sets the value of memory MyMemory10 to a turnout name. Also let an action entity of type turnout be named @MyMemory10. Also let its action type be "Set Turnout Position Thrown" when the change option is "On Change to True". When the logical expression changes to true, the turnout named in the current value of memory MyMemory10 will be thrown.
The Name Selection method must be a picklist in order to use this feature.
The data items needed to completely specify the action will appear to the right of the type box. If you don't know what needs to be entered in a data field, hover your cursor over it, and a hint message will appear.
For each action, three options are available for when to trigger the action:
- On Change to True
- On Change to False
- On Change
If the Execute Actions option has been changed to Execute Action whenever triggered, then the options are:
- When Triggered True
- When Triggered False
- Whenever Triggered
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.
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 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 you to correct the error and click Update Conditional again. If no error is found, the action 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.
For more information, consult the main Logix documentation.
Logix Documentation Pages Logically Listed
Logix documentation is divided into eight different help pages. While these are referenced via links in various places, not all are easy to find (perhaps three links down). They are additionally listed here for convenience.
- Main Logix description and explanation
- Description of Logix Table contents and usage
- Logix Table add and edit action description
- Enumeration of Logix conditionals state variables and actions
- Logix conditionals list editor instructions
- Logix conditionals tree editor instructions
- Logix conditionals copy instructions