Author: Daniel Bergqvist
Keywords: jmri LogixNG reference action items

# LogixNG Reference - Chapter 5

## Action Descriptions

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

since 5.1.3For, For each , If Then Else, Sequence, and Table: For each have been moved from the Common category to the Flow Control category. Call Module has been moved from the Other category to the Flow Control category.

- Digital action
  - Item
  - Common
  - Flow Control since 5.1.3
  - Display
  - MQTT since 4.99.7
  - LocoNet
  - Merg Cbus since 5.11.7
  - OperationsPro since 5.13.2
  - Other
- Digital boolean action
  - Common
- Analog action
  - Item
  - Common
- String action
  - Item
  - Common

## Action dialogs

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

The dialog for adding and editing digital action items consists of an upper part that contains the item and the actions for that item. The lower part is common to all actions.

For some actions, for example Signal head, you need to first select the item and then you can select the action to do on that item. For example, for Signal head, you first select the signal head to act on and then you can select the appearance to set for that signal head.

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 action to be performed. 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 Preferences 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.
Edit comment
  Each action 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 action or the changes to an existing action.

## Digital action :: Item

- Audio
- Block
- Clock
- Clock Rate
- Dispatcher
- Enable/Disable Logix
- Enable/Disable LogixNG
- Entry/Exit
- Light
- Light intensity
- Local variable
- Memory
- OBlock
- Power
- Program On Main
- Reporter
- Request update of all sensors
- Request update of sensor
- Request update of turnout
- Route
- Script
- Sensor
- Set reporter
- Signal head
- Signal mast
- Sound
- Table
- Throttle
- Throttle function
- Turnout
- Turnout, lock
- Warrant

#### Audio

Control an Audio source.

Select an audio source from the list and the action to be performed.

#### Block

- Block Sensor Active: Set the sensor that provides occupancy to active.
- Block Sensor Inactive: Set the sensor that provides occupancy to inactive.
- Alternate Color On: Enable alternate color for the related layout block.
- Alternate Color Off: Disable alternate color for the related layout block.
- Empty (null): Set the block value to the null value.
- Value: Set the block value to a string or via a reference such as from a memory variable.

#### Clockupdated 4.99.7

- Set Fast Clock: Sets the time on the fast clock to the entered time. The time can be entered as hh:mm where hh is hours and mm is minutes on a 24-hour clock or as the number of minutes since midnight, such as 720 for noon. This action sets the fast clock to the specified time regardless of whether the fast clock is running or stopped.
- Start Fast Clock: Starts the JMRI fast clock running. If the fast clock is already running, this action has no effect.
- Stop Fast Clock: Pauses the JMRI fast clock. If the fast clock is not running, this action has no effect.

In addition to setting the time using a constant value, the other LogixNG modes can be used. For example, the new time can be in a memory variable which will be used to set the fast clock time.

The Memory listen option can used to automatically update the fast clock time when the memory variable changes. This eliminates the need to have a separate expression to invoke the Set Fast Clock action.

#### Clock Ratesince 4.99.7

- Set Clock Rate: Sets the rate for the fast clock to the entered value. For example, a value of 4 will set the fast clock rate to 4:1, which is 15 real minutes for a fast clock hour.
- Increase Clock Rate: Increase the fast clock speed by the entered value.
- Decrease Clock Rate: Decrease the fast clock speed by the entered value.

The rate values can be whole numbers or decimals, such as .5. The rate values can also be supplied from the other LogixNG modes, such as a memory variable.

#### 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. If the related train does not exist when the LogixNG action occurs, the action will be ignored. There will be no notification.

- Load train from train info file: Create a new Dispatcher train using the selected train info file.
- Terminate train: Terminate a Dispatcher train that was previously started using LogixNG.
- Set train priority: Change the priority of a train. The default is 5. The allowed range is 0 to 100.
- Set Reset when Done: Enable or disable the Reset when Done option.
- Set Terminate when Done Enable or disable the Terminate when Done option.

#### Enable/Disable Logix

- Enable: Enables the specified logix. Specify the logix to enable by selecting its name.
- Disable: Disables the specified logix. Specify the logix to disable by selecting its name.

#### Enable/Disable LogixNGsince 5.7.5

A LogixNG has to be both enabled and activated before it will execute.

Enable/Disable are intended to be persistent changes. Activate/Deactivate are temporary changes.

- Enable: Enable the selected LogixNG. The setting will be retained when a tables and panels store occurs.
- Disable: Disable the selected LogixNG. The setting will be retained when a tables and panels store occurs.
- Activate: Activate the selected LogixNG. The change only persists during the PanelPro session.
- Deactivate: Deactivate the selected LogixNG. The change only persists during the PanelPro session.

#### Entry/Exit

Manage an Entry/Exit pair. The last three items are implemented in JMRI 5.5.7.

Set NX Pair Enabled
  Enable the selected Entry/Exit pair.
Set NX Pair Disabled
  Disable the selected Entry/Exit pair.
Set Set NX Pair Segment Active / Inactive
  Request that the route segment for the selected Entry/Exit Pair be activated if not active or deactivated if active. This toggles the active state.
Set NX Pair Inactive
  Deactivate the Entry/Exit route for the selected Entry/Exit pair if it is currently active. The Cancel/Clear Down dialog will be displayed if a default action has not been defined in the Entry/Exit options.
Set NX Pair Active
  Activate the Entry/Exit route for the selected Entry/Exit pair if the route is not currently active. Depending on the types of conflicts, the activation may silently fail or display a Route Not Clear dialog.
Set NX Pair Reversed
  Activate the Entry/Exit route for the selected Entry/Exit pair in the reverse direction if the route is not currently active. Depending on the types of conflicts, the activation may silently fail or display a Route Not Clear dialog. This option is only enabled for selected Entry/Exit pairs that have the Both Way option enabled.

#### Light

- Off: Set the selected light off.
- On: Set the selected light on.
- Toggle: Toggle the selected light.
- Set Intensity: Sets the intensity of a specified variable intensity light to the entered intensity value. Specify the light to set by selecting its name. Specify the intensity by entering the percent intensity as an integer in the range 0 to 100. If the specified light is not a variable light, or if the intensity value entered is not an integer in the required range, an error message is displayed.
- Set Transition Time: Sets the transition time of a specified variable intensity light to the entered time. Specify the light to set by selecting its name. Specify the transition time by entering the number of fast clock minutes needed to move from 0% intensity to 100% intensity. If the specified light is not a variable light, or if a positive integer is not entered for the number of fast clock minutes, an error message results.
- Unknown: Set the selected light state to unknown.
- Inconsistent: Set the selected light state to inconsistent.

#### Light intensity

The Light intensity action is an alternate method to set the Variable Light Intensity value. The standard method sets the value directly from the action using any of the standard input methods.

This action creates a child analog expression called Intensity. Analog expressions are normally used to create a dynamic values, such as random numbers. Using the `sin()` function along with the Minutes since midnight analog expression, it is possible to change light intensity based on the time of the day using the fast clock or the system clock.

Here is an example using the sin() function.

#### Local variable

Local variables are described in Chapter 8 - Local Variables.

Instead of specific actions, local variables use tabs to select the action.

- Null: Select the Null tab to set the selected local variable to the null value.
- Constant: Select the Constant tab, select the value Type and enter a value for the selected local variable.
  - String
  - Integer
  - Floating number
  - Boolean (True/False)
- Memory: Select the Memory tab and select the memory which will provide the value for the selected local variable.
- Block: Select the Block tab and select the block which will provide the value for the selected local variable.
- Reporter: Select the Reporter tab and select the reporter which will provide the current report for the selected local variable.
- Variable: Select the Variable tab and enter the local variable name which will provide the value for the selected local variable.
- Reference: Select the Reference tab and enter the reference value which will provide the value for the selected local variable.
- Table: See Simplified Table Cell Reference. The rest of chapter 11 has all of the details on tables.
- Formula: Select the Formula tab and set the selected local variable to the result of a formula calculation.

Note: The Memory, Block and Reporter tabs have an option to listen to changes to their value.

#### Memory

Instead of specific actions, memory uses tabs to select the action.

- Null: Select the Null tab to set the selected memory to the null value.
- Constant: Select the Constant tab and enter a string value for the selected memory.
- Memory: Select the Memory tab and select the memory which will provide the value for the selected memory.
- Table: See Simplified Table Cell Reference. The rest of chapter 11 has all of the details on tables.
- Variable: Select the Variable tab and enter the local variable name which will provide the value for the selected memory.
- Formula: Select the Formula tab and set the selected memory to the result of a formula calculation.

#### OBlock

- Deallocate Block: Deallocates an Occupancy block. Specify the OBlock by selecting its name.
- Set Block Value: Set a value for the selected block.
- Set Block Error: Set the selected block status to "block error".
- Clear Block Error: Remove the "block error" status for the selected block
- Set Block OutOfService: Sets the status of an Occupancy block to Out-Of-Service. Specify the OBlock by selecting its name.
- Clear Block OutOfService: Sets the status of an Occupancy Block to the current normal status. Specify the OBlock by selecting its name.
- Get Allocating Warrant: Copy the name of the Warrant that has this OBlock allocated to a memory variable.
- Get Block Value (trainName): Copy the current value of this OBlock to a memory variable.

#### Power

- Off: Turn track power off.
- On: Turn track power on.

#### Program On Mainsince 5.7.3

The Program on Main action provides the ability to change CV settings. This is similar to the Single CV Programmer.

Depending on the command station, selecting a Long address for address less than 128 might be ignored or create an error.

The roster is not used or updated.

A local variable can be assigned which will contain the results of the operation. The local variable is only updated if there are actions in the Execute action. If the value is not zero, there was an error.

    LogixNG: IQ:AUTO:0001
        ConditionalNG: IQC:AUTO:0001
            ! A
                Many
                   ::: Local variable "result", init to None ""
                    ! A1
                        Program CV 29 to 32 for address Autodetect 1234 using programming mode OPSBYTEMODE
                            ! Execute
                                Many
                                    ! A1
                                        Log data: Only text: pom returned
                                    ! A2
                                        Log local variables

#### Reporter

The Reporter action is used to copy the report content to a memory variable or a LogixNG local variable. There are three kinds of information.

- Current Report: The current value unless the hardware says there is nothing to report. In that case the value will be null.
- Last Report: Normally the current report and last report are the same. If the current report is null, this will be most recent valid report. If no report has ever been received, this will be null.
- State: A number that represents the last report.

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

#### Request update of all sensorssince 5.1.6

Request the current status of sensors. The request can be limited to specific connections or all connections. The action depends on whether the connection supports sensor state requests.

As of JMRI 5.7.5, supported connection types include :

- BiDiB
- CBUS
- C/MRI
- IPOCS
- Lenz XpressNet
- LocoNet
- OpenLCB
- Roco Z21 CAN
- XBee

For connections that send individual Sensor status requests, the delay between individual requests uses the connection Output Interval within Additional Connection Settings.

Some hardware types, eg. Acela and NCE, are constantly polled so this action may have little consequence.

#### Request update of sensorsince 5.7.4

Request the current status of a specific sensor. The action depends on whether the connection supports sensor state requests.

As of JMRI 5.7.5, supported connection types include :

- BiDiB
- CBUS
- C/MRI
- IPOCS
- Lenz XpressNet
- OpenLCB
- Roco Z21 CAN
- XBee

#### Request update of turnoutsince 5.13.6

Request the current status of a specific turnout. The action depends on whether the connection supports turnout state requests.

Depending on the accessory decoder a LocoNet request might work if the turnout feedback is set to MONITORING or INDIRECT.

As of JMRI 5.7.5, supported connection types include :

- BiDiB
- CBUS
- C/MRI
- IPOCS
- Lenz XpressNet
- OpenLCB
- Roco Z21 CAN
- XBee

#### Route

- Trigger route: Triggers the specified route. Specify the route by selecting its name.

#### Script

- Run script: Starts the specified script. Specify the script to start by entering its name in the field provided or use the "..." file selector.
- Single line command: Enter the command in the Script field.
- Type of script: Supported script types are Jython Files and ECMAScript Files.

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

#### Sensor

The delayed options are handled by Execute Delayed.

- Inactive: Set the selected sensor to inactive.
- Active: Set the selected sensor to active.
- Toggle: Toggle the state of the selected sensor.
- Unknown: Set the selected sensor state to unknown.
- Inconsistent: Set the selected sensor state to inconsistent.

#### Set reportersince 5.7.5

Set a value for the selected Reporter.

The Set reporter as an IdTag option is used to provide the report as an IdTag if it's not an IdTag already.

#### Signal head

- appearance: Sets the specified signal head to the selected appearance. Specify the signal head to set by selecting its name. Select the appearance Appearance list.
- lit: Sets the specified signal head to lit. Specify the signal head by selecting its name.
- not lit: Sets the specified signal head to not lit. Specify the signal head by selecting its name.
- held: Sets the specified signal head to hold. Specify the signal head to hold by selecting its name.
- not held: Clears the hold on the specified signal head. Specify the signal head by selecting its name.

#### Signal mast

- aspect: Sets the specified signal mast to the selected aspect. Specify the signal mast to set by selecting its name. Select the aspect from the Aspect list.
- lit: Sets the specified signal mast to not lit. Specify the signal mast by selecting its name.
- not lit: Sets the specified signal mast to not lit. Specify the signal mast by selecting its name.
- held: Sets the specified signal mast to held. Specify the signal mast to hold by selecting its name.
- not held: Clears the hold on the specified signal mast. Specify the signal mast by selecting its name.
- permissive sml disabled: Disable permissive SML for the selected signal mast.
- permissive sml not disabled: Enable permissive SML for the selected signal mast.

#### Sound

Plays the specified sound file. Specify the sound file to play by entering its name in the field provided. Click the file selection button to bring up a file selection dialog to aid in finding the file. Navigate to your sound file, then click your sound file's name in the dialog and the name will be copied to the field.

#### Tablesince 5.7.4

Replace the content of the specified table cell.

Note: Since tables are created from CSV files during PanelPro startup, the content changes are temporary.

#### Throttle

The Throttle action controls a throttle.

The LogixNG throttle can use either the default throttle connection or an alternate throttle connection. The default connection is defined in Preferences ⇒ Defaults. If there is more than one connection, other connections might support a throttle.

since 5.9.5When enabled, the Stop loco when switching loco option stops the loco before switching to another loco. This is the default and was the previous behavior. Warning: When the option is disabled and and a loco change occurs, the previous loco will continue running until some other process tells it to stop.

Address — Analog Expression
  Value between 1 and 9999.
Speed — Analog Expression
  Value between 0.0 and 1.0.
Direction — Digital Expression
  True for forward.
Function — Analog Expression
  Value between 0 and 28.
FunctionOnOff — Digital Expression
  True for function on

The analog expressions can be an analog memory expression or an analog constant expression. In the future, AnalogIO will also be available.

The digital expressions are either Always true or Always false .

#### Throttle functionsince 5.5.6

The Throttle function action is similar to the Throttle action, except that it only sets a throttle function On or Off.

The Connection drop down can be used to specify the connection to be used.

#### Turnout

The delayed options are handled by Execute Delayed.

- Closed: Set the selected turnout closed.
- Thrown: Set the selected turnout thrown.
- Toggle: Toggle the state of the selected turnout.
- Unknown: Set the selected turnout state to unknown.
- Inconsistent: Set the selected turnout state to inconsistent.

#### Turnout, lock

Locks or unlocks a turnout. Select the name for the turnout, and choose the operation from the popup menu. Note: To control the type of turnout lock go to the Turnout Table and select the Lock Mode.

- Lock: Lock the selected turnout.
- Unlock: Unlock the selected turnout.
- Toggle: Toggle the lock state for the selected turnout.

#### Warrant

- Allocate Warrant Route: Allocates (reserves) the OBlocks comprising the route of the warrant for use by the warrant. Specify the warrant by selecting its name.
- Deallocate Warrant: Deallocates the OBlocks comprising the route of the warrant so they may be allocated to other warrants. Specify the warrant by selecting its name.
- Set Route Turnouts: Sets all the turnouts comprising the route of the warrant. Specify the warrant by selecting its name.
- Auto Run Train: Starts playback of the recorded script for the train specified in the warrant. Specify the warrant by selecting its name.
- Manually Run Train: Serves a "clearance" to an operator that a humanly run train has running rights for the extent of the warrant's route. Specify the warrant by selecting its name.
- Control Auto Train: Issues the specified command to an auto run train. Specify the warrant of the train by selecting its name. The commands are:
  - Halt
  - Resume
  - Abort
  - Stop
  - EStop
  - MoveToNext
  - SpeedUp
- Set Train ID: Set the train ID from the roster or the DCC address. When a DCC address is used, also specify Long or Short. Example: 1234(L) or 10(S).
- Set Train Name: Set the train Name for the selected Warrant.
- Current Location: Copy the current OBlock name for the selected warrant to a memory variable.

## Digital action :: Common

- Digital Formula
- Execute delayed
- Many
- Read analog and set analog
- Read string and set string
- Timer

#### Digital Formulasince 4.25.8

The Digital Formula action provides the ability to create formulas that are not directly related to other items, such as sensors, which use the Formula tab.

The formula action is in particular useful when working with local variables. You can for example increase a local variable by the formula `index++` or make some calculations, like `turnout = name.substring(2)` which removes the first two characters from the string.

The dialog for creating a Digital Formula consists of a single text field.

See Chapter 9 - Formula for details.

#### Execute delayed

Delay the execution of the following action for a specified amount of time. The action can be a single action similar to the Logix Delayed Set ..., but this can be any item, such as signals. The action can be a series of actions by using the Many action. It can be a complex action by using an If-Then-Else action.

Note: When using If-Then-Else, the Always execute option is required. Any expressions that refer to JMRI table items, such as sensors, turnouts, signals, etc., need to use the No Listen option.

When the timer starts, a copy of the current local variables is attached to the action that will be run when the timer delay is done. This makes it possible to pass data to the future action.

Delay duration

  The time delay units are milliseconds, seconds, minutes and hours.

Reset timer if already started

  The default mode is that once a timer starts, subsequent requests will be ignored. If this option is enabled and a timer is already running, it will be canceled and started again. The local variables will be based on the current values at the time of the reset.

Use individual timers

  This option makes it possible to pass different local variable values to a series of timers. The actions will be the same but the data can be different. Note: This option disables the reset option.

There is no Cancel timer capability. If there might be a need to prevent the action from running, an If-Then-Else as the first step of the action can be used to check some item, such as a sensor, to see if the action should proceed.

See Timeout for a conditional delayed execution.

#### Many

The Many action executes many child actions.

#### Read analog and set analog

Read an analog child expression and execute an analog child action.

#### Read string and set string

Read a string child expression and execute a string child action. This is used to copy string values from a Memory, a StringIO or as a constant. The destination will be a Memory or a StringIO. There are special expressions and actions.

Expressions

- Memory
- Constant
- StringIO

Actions

- Memory
- StringIO

#### Timer

Timer has a number of actions, each executed after a period of time. The time to wait can be 0, which means the related action is executed immediately.

Options:

Start timer immediately on load
  When selected, the timer steps will start when the LogixNG has been loaded. If this option is not selected, a Start expression will be used to start the timer steps when the expression becomes true.
Run timer continuously
  If not selected, the timer will run one time and then stop. When selected, the timer steps will repeat. A Stop expression can be used to stop the timer steps when the expression becomes true. The Stop expression can use the same object, such as a sensor that starts the timer when active and then stops the timer when the sensor is inactive.
Start/Stop by Start expression
  When selected, the timer will start when the Start expression becomes true and will stop when the Start expression becomes false. The Stop expression is ignored.
Combo Box
  Select the time unit.
Delay by local variables
  Instead of using fixed delay times, it is possible to assign delay times to local variables. The timer step number will be appended to the prefix value, such as delay1, delay2, etc.

If all times to wait are zero, the timer will automatically stop after executing all the actions once, even if it is set to run continuously. This is a safety feature to avoid locking up JMRI.

To add a socket for the Timer action, edit the Timer and click the Add timer button and a new socket will be added to the end. To remove a socket for the Timer action, edit the Timer and click the Remove timer button and the last socket will be removed. The socket can only be removed if there is no action connected to it.

This example shows using the Timer to implement a traffic light. Note: This example shows renaming the A1, A2, etc. sockets to meaningful names.

Another example is using a Timer to blink a light. Create a Timer with a single socket and a Light action that toggles the light on/off. If you want different times for on and off, create a Timer with two sockets where the first socket turns the light on and the second socket turns the light off.

The Timer action can be used in LogixNG Modules. Due to the nature of repetitive timer events, there are some restrictions.

- The calling LogixNG and the Module run all of their actions with each Timer step. Avoid including any other logic in the calling LogixNG or the Module.
- The trigger event for the LogixNG can be either a if-then-else with the expression set for Always execute or a Listen on beans item.
- Start/Stop by Start expression is selected.
- The Start expression for the Timer should be the Always true expression.

## Digital action :: Flow Control since 5.1.3

- Break
- Call module
- Continue
- Error
- Exit
- For
- For each
- For each with delay
- If Then Else
- Return
- Run once
- Sequence
- Table: For each

#### Break

Breaks the execution of a For, For each or Table: For each action.

If Break happens in a Module and there is no loop in the Module itself, it breaks the loop in the calling ConditionalNG or Module.

#### Call module

See Chapter 10 - Modules for details.

#### Continue

Continues the execution of a For, For each or Table: For each action.

The current execution is aborted and the next loop is executed.

If Continue happens in a Module and there is no loop in the Module itself, it continues the loop in the calling ConditionalNG or Module.

#### Error

Triggers an error. The user can enter an error message if desired.

This might be useful if a particular condition should never occur in the ConditionalNG or Module. In this case, the Error action can be used to alert the user.

#### Exit

Exits the execution of the ConditionalNG. If the Exit action is in a Module, the Module and the ConditionalNG will be exited.

#### For

For is a for-loop. It has four children.

- Init - this action is executed only one time. It's used to initialize the loop, for example setting a Memory to a particular value.
- While - this expression decides if the loop should run one lap more. The loop will continue to run until this condition will be false.
- AfterEach - this action is executed at the end of the loop. It can for example be used to increment a counter in a Memory.
- Do - this action is executed in each loop. It does the main work.

When For is executed, the Init action is run once. After that, the While expression is evaluated. If the While returns true, the Do action is executed and at last the AfterEach action is executed. Then the process is repeated, except that the Init action is only executed once.

#### For eachsince 5.1.3

For each takes a Collection, a Map or a Manager as parameter and loops thru all the items. For maps, each item is a Map.Entry. Use `getKey()` and `getValue()` to get the key and the value of each item in the map. If the parameter is a manager, the method `getNamedBeanSet()` is called to get all the named beans in the manager.

Each item is placed in a specified local variable. The action is then invoked for each item.

The following example sets all of the sensors to Inactive.

For another example, see Listen on beans - Local variable.

#### For each with delaysince 5.13.6

For each with delay combines For each with Execute delayed. Compared to For each, the difference is that the action to be executed for each item will be delayed. A good example is setting turnouts to a known state without overloading the command station or the DCC connection.

While the timer options work the same as Execute delayed, there are some potential issues if either option is selected.

Reset timer if already started
  Only some items will be processed if the action is run again before the previous task has finished.
Use individual timers
  There is a possibility that a lot of items will be processed at the same time.

For best results do not use the timer options.

#### If Then Else

Reads a digital child expression and if the answer is true it executes the then child action, else it executes the else child action.

There are two settings that control the if-then-else processing.

When is the If-Then-Else executed

Execute on change
  Executes the Then or the Else action only when the If expression has changed from True to False, or from False to True. Note that the expression is assumed to be changed whenever the LogixNG is first enabled (including when the xml data file is loaded with "enabled" checked). In the simple example below, Light IL2 will be set "on" when the LogixNG is first enabled (Sensor IS1 status is "unknown"). When the sensor is changed to "inactive" the lights will not change. When the sensor is then changed to "active," the Light IL1 will also go "on".
Always execute
  Executes the Then or the Else action every time the If Then Else action is executed, regardless of whether the expression has changed value.

The default execution setting can be change using Preferences ⇒ LogixNG.

How is the If expression evaluatedsince 5.1.6

Evaluate all expressions
  All of the expression elements are evaluated to determine the true/false state of the If.
Evaluate needed expressions
  Evaluate each expression element until true/false is determined. An And series ends when an element is false. An Or series ends when an element is true.

##### Else_Ifsince 5.1.3

The Else_If option provides a compact method to collapse a repetitive nested If-Then-Else tree.

To create a new Else_If expression/action pair, right click on the Else row and select Insert new socket before.

A new expression/action pair will be added before the Else.

Here is simple example of using LogixNG to create signal logic.

The example first checks the turnout block. If that is ok, it then checks the route to each possible destination signal based on the turnout state. If nothing works, it sets the signal to display Stop.

#### Return

Returns from the Module or the ConditionalNG.

If Return is in a ConditionalNG, it's the same as Exit. But if it's in a Module, it only exits the Module, not the ConditionalNG.

#### Run oncesince 5.3.1

Run the assigned action only one time during a JMRI session.

The assigned action will be the Many action if there is more than one action to be performed. This provides an alternate method compared to Trigger once for startup initialization.

#### Sequence

The Sequence action executes a series of action/expression pairs. For each pair, the action will be performed and then the expression will wait until it becomes true. When it is true, the next action/expression pair will be started. The Timer expression can be used to do a time based step instead of an event based step.

Options:

- Start sequence immediately on load — Run the sequence when the data file loading is done.
- Run sequence continuously — The sequence will repeat forever or until stopped. If this option is not selected, the sequence will run one time and the sequence can be started again later.

When a sequence action is added, it has connections for Start, Stop and Reset expressions.

- Start: When the Start expression is true, the sequence will start with the first action/expression pair or resume if a stop occurred during the sequence.
- Stop: When the Stop expression is true, the sequence will stop running.
- Reset: When the Reset expression is true, the sequence will be interrupted if running, and return to the first action/expresson pair.

#### Table: For each

See Chapter 11 - Table Actions for details on table actions.

## Digital action :: Display

- Audio icon on web panel
- Icon/Label by class on panel
- Icon/Label on panel
- Turnout on LayoutPanel
- Window management

#### Audio icon on web panelsince 5.5.6

The Audio Icons on JMRI panels can be used to play sounds on devices displaying JMRI panels using a web browser. The Audio icon on web panel action can be used to start and stop the audio source assigned to the audio icon. For example, LogixNG can play notification sounds on a dispatcher panel.

Note: The sound will not be played on the computer running JMRI. If desired, use the Audio action to play the sound locally.

Before creating the action, assign an id to the Audio Icon using Edit Id from the icon context menu.

Select the panel, the id for the Audio Icon and whether to Play or Stop the sound.

If the Audio Icon is to be used only by the action, the icon can be hidden.

#### Icon/Label by class on panelsince 5.5.4

Disable/Enable/Hide/Show all of the icons or labels on a specific panel that been assigned a class name.

Icons and labels don't have names. To identify the icon or label, the Edit Classes... menu item in the right click context menu is used to assign a class name. A class name cannot have a comma. Multiple classes separated by commas can be assigned.

Select the panel and one of the classes. Select the desired action.

#### Icon/Label on panel

Disable/Enable/Hide/Show an icon or label on a specific panel.

Icons and labels don't have names. To identify the icon or label, the Edit Id... menu item in the right click context menu is used to assign a name.

Select the panel and one of the ids. Select the desired action.

#### Turnout on LayoutPanelsince 5.3.1

Disable/Enable a turnout item on a specific Layout Editor panel. A separate action is needed since the turnout image on a Layout Editor panel is not an icon.

The action applies to a single turnout item. To change all of the turnouts, use a For each action.

#### Window managementsince 5.7.6

JMRI uses a lot of windows. Each panel is a window, various tools have windows, tables can be shown in windows, etc. The Window management action provides three tools to help manage the windows.

Show/Hide
  The visibility of the window is changed. The window size and location are not affected.
Maximize/Normalize/Minimize
  Minimize and normalize use the OS process to move the window to and from the task bar or dock. Normalize returns the window to the same location and size. Maximize fits the window to the screen size. Normalize will return the window to the orignal location and size. There is one exception. If the window location or size has changed while maximized, that becomes the new location and size and normalize will not revert to the previous location and size.
To front/back
  Bring to front makes the window the top window. Bring to back makes the window the bottom window.

The Ignore Window not found option is used to prevent errors when optional windows are not currently open.

A simple implementation of this can done using the LogixNG icon with an inline LogixNG. See Inline LogixNG and LogixNG icon.

#### Window to frontsince 5.7.4

The Window to front action has been replaced by the Window management action. Existing actions will be automatically converted.

## Digital action :: MQTT since 4.99.7

- Publish
- Subscribe

#### Publish

This action publishes a message. Both the topic and the message can be entered directly in the action or indirectly using a local variable or a memory.

since 5.9.1Retain is used to tell the MQTT broker if it should also send the message to new subscribers or if it should only send the message to current subscribers.

Default
  Use the connection setting.
Yes
  Tell the broker to send the message to the current subscribers and also send the message to new subscribers when they subscribe.
No
  Tell the broker to only send the message to the current subscribers. New subscribers will not see the message.

#### Subscribe

This action subscribes to a topic. When someone publishes a message, this action triggers the execution of the ConditionalNG. It can also optionally put the topic and the message into local variables. The topic can use wildcard, like loco/# where # is the wildcard.

## Digital action :: LocoNet

- Clear loconet slots
- Set speed to zero for all loco slots
- Update loconet slots

#### Clear loconet slots

This action clears the slot status in the command station if you are using LocoNet.

#### Set speed to zero for all loco slotssince 5.1.6

Sets the speed of the Digitrax command station slots to zero.

#### Update loconet slots

This action forces an update of the LocoNet slot status in JMRI.

## Digital action :: Merg Cbus since 5.11.7

- Send MERG CBUS event

#### Send MERG CBUS event

This action sends a MERG event to a node.

The Event types are Off, On and Request.

The Connection defaults to the first MERG connection. If there is more than one, other connections can be selected.

## Digital action :: OperationsPro since 5.13.2

- Run automation

#### Run automation

This action is used to run an OperationsPro Automation. These are defined using the Automation tool in Trains ⇒ Tools ⇒ Automation.

Select an Automation from the list.

## Digital action :: Other

- Create beans from table
- Decode JSON
- Execute action
- Execute program
- Find table row or column
- Listen on beans
- Listen on beans - Local variable
- Listen on beans - Table
- Log data
- Log local variables
- Logix
- Show dialog
- Shut down task
- Shutdown
- Simulate turnout feedback
- Timeout
- Web browser
- Web request

#### Create beans from tablesince 5.1.6

See Chapter 11 - Table Actions for details.

#### Decode JSONsince 5.7.4

A JSON string in the first variable is decoded as a JsonNode tree and placed in the second variable.

The decoding process translates the JSON string into a nested set of LogixNG Maps and Arrays. Use a LogixNG formula to access a particular node.

Here is a sample JSON structure.

    {"menu": {
      "id": "file",
      "value": "File",
      "popup": {
        "menuitem": [
          {"value": "New", "onclick": "CreateNewDoc()"},
          {"value": "Open", "onclick": "OpenDoc()"},
          {"value": "Close", "onclick": "CloseDoc()"}
        ]
      }
    }}

Here is a LogixNG that gets the second menuitem value and prints it to the JMRI system console. In this example, node value = Open is printed

           1:  LogixNG: test read
           2:      ConditionalNG: IQC:AUTO:0002
           3:          ! A
           4:              Many
           5:                 ::: Local variable "node", init to String ""
           6:                  ! A1
           7:                      Set variable node to the result of formula "str(jsondecoded{"menu"}{"popup"}{"menuitem"}[1]{"value"})"
           8:                  ! A2
           9:                      Log data: String.format: node value = %s

jsondecoded is the global variable that has the result of the Decode JSON action. The items in the JSON tree are delimited by braces. The JSON list rows are referenced by row number in brackets. Note: The first row is zero. In this example, all of the node values are strings, so the formula is enclosed with a str() command. Node values can also be other data types such as integer and float. LogixNG has int() and float() commands to handle those data types.

#### Execute actionsince 5.7.8

Execute action is used to execute a different part of the current ConditionalNG. This can be useful if you need to execute a part of the ConditionalNG at several different places, for example if you have several Listen On Beans - Local variable in the same ConditionalNG. This is similar to calling a sub-routine.

The first step is to assign a user name to the action to be executed. Right click on the action and select Change user name. Enter the user name and click on OK.

When the Execute action is added, a dialog is displayed. Select the user name from the combo box and click on OK.

This example calls a sub action to display the current local variables.

Normally a ConditionalNG will execute all of the actions in the top level Many. In this example, that would result in a second execution of the sub action. The Return action is used to finish the ConditionalNG execution sequence.

Note: This example was used to verify that the local variable list varies depending on when the sub action was called.

#### Execute programsince 5.13.6

Execute program is used to execute a program/script outside of JMRI. The program has no access to the JMRI run-time environment. The File as flag expression can be used to notify JMRI of the program state. Program output is not captured. This includes print and echo statements. Using redirect does not work. To retain output, it must be written to a file.

The dialog has 3 tabs. The Program tab has the name of the program and if necessary, the path to the program. This will vary depending on the operating system. In the image it is a script in the scripts directory within the user files location using the macOS/Linux command line format.

The Parameters tab is used to define the command line parameters. Each parameter is a separate row. If a parameter has arguments, those are also separate. For example, `cut -d : -f 1,7 /etc/passwd`, requires 5 entries.

The Working directory tab sets the working directory before starting the program. This is used for relative path execution and file references. The default working directory is the profile's User Files Location.

#### Find table row or columnsince 5.1.6

See Chapter 11 - Table Actions for details.

#### Listen on beans

See Chapter 7 - Listen on beans for details.

#### Listen on beans - Local variablesince 5.1.3

Add a listener to the bean referenced by a local variable. The local variable can have either the system name, the user name or the bean itself. The Execute socket provides the logic that will be executed when an event occurs.

The bean Type and the listen local variable name are required. The other local variables are optional.

- Bean — The affected object.
- Event — The property name.
- Value — The new value.

This action is especially useful together with the action For each. This sample listens for sensor state changes and prints a message on the system console.

#### Listen on beans - Table

See Chapter 11 - Table Actions for details.

#### Log data

While developing a ConditionalNG, it can be helpful to see field content, make note of the location within the tree, etc. Adding the Log data type in the Other category will display a dialog to configure the Log data options.

Another approach for displaying data is to use the Show dialog action.

Select either or both Log options

- Log to the log: Help ⇒ System Console.
- Log to the Script Output: Scripting ⇒ Script Output.

There are three format types.

- Only text: The text typed into the Format box will be displayed on the log. The data in the table is ignored.
- Comma separated list: The values for the items in the table will be displayed separated by commas. The content in the format field is ignored.
- String.format: Use the format string to format the data in the table. See the java method String.format() for the syntax of the format string. Note: The format is similar `sprintf`.

The table lists the data sources for the comma separated and and string format options.

Click on the Add button to add an entry to the table. Select the source type and add the name or a reference in the Data field.

This example uses the string.format option to combine text with the contents of two memory variables.

#### Log local variables

See Chapter 8 - Debugging local variables for details.

#### Logix

LogixNG has an action called Logix that emulates how JMRI Logix works. The action Logix has one expression and a Logix Action. The digital boolean Many action can be used to support multiple Logix Actions as shown in the example. A Logix Action responds to True, False, or Either Logix evaluation states. The action Logix was added mainly to support import of JMRI Logix to LogixNG.

The Logix action supports On Change and When Triggered.

An example Logix within LogixNG. This is a tweaked import from Logix. The Log data actions were added and the individual True LogixNG actions were combined within a standard Many.

This example uses When Triggered. This means that one or more actions will be executed when either IS101 or IS102 changes. The On Change option only executes the actions when the evaluation of the expression changes between true and false.

#### Show dialogsince 4.25.8

The Show dialog action displays a window that can be used to provide notification of an event that has occurred or needs to be handled. It can also be used to request whether an action should be performed by the LogixNG.

Normally, warnings and such can be handled by displaying a message in the system console. The dialog is useful when an immediate notification is needed.

The Show dialog definition is similar to the Log data definition. See Log data for details on formating and including variables.

Additional Features:

Buttons
  One or more buttons can be included in the dialog. At least one button must be selected.
Modal
  A dialog can be modal or non-modal. Modal means that the dialog window remains above any other window and the user cannot do anything in any other JMRI window until it is closed.
Multiline
  The multiline option enables the ability to have multiple lines displayed by the dialog. To get a new line, use the HTML <br> tag.
Selected button
  If a predefined local variable is supplied, the selected button number is copied to the local variable. The button numbers are shown next to the button text in the button selection section.
Input stringsince 4.99.1
  If a predefined local variable is supplied, a text input field is included. The current value of the variable will be displayed in the text input field. When the dialog is closed using one of the buttons, the value in the input field will be copied to the local variable.

Note: When the dialog is displayed, the rest of the conditional continues to run. In the first example, the A3 action will execute while the dialog is displayed.

After the dialog action has been created, two new rows are added. These are both optional and can be left empty.

Validate
  The Validate expression can be used to check for valid input when using an input local variable. If the expression is false, the dialog will remain open until the expression is true. The close button on the window can be used to bypass validation and execution. If the expression is true or no expression was defined, the Execute action will run.
Execute
  The Execute action is run when the validation expression is true or if one was not defined. A common use is handling a multiple button dialog that has the selected button local variable.

##### Sample dialog with button checking

##### Sample multiline dialog with string.format

##### Sample input dialog with validation using a digital formula

#### Shut down tasksince 5.1.6

Create a task that will run before JMRI shutdown occurs.

If the Expression is empty or returns true, the Action will be executed before JMRI shutdown continues. If the Expression returns false, the JMRI shutdown process is stopped.

#### Shutdown

The Shutdown action can either shutdown or restart the computer, or shutdown or restart JMRI. The default action is Shut down JMRI.

#### Simulate turnout feedbacksince 5.1.3

The Simulate turnout feedback action is used to make turnouts behave as expected when using a simulated layout connection. The feedback delay is 3 seconds.

The following feedback modes are supported. The available modes depend on the layout connection type.

- EXACT
- INDIRECT
- MONITORING
- ONESENSOR
- TWOSENSOR
- LNALTERNATE

The Connection name expression can be used to create a LogixNG that automatically enables turnout feedback when using a simulated layout connection.

#### Timeoutsince 4.25.8

The Timeout action is used to execute a default action if an expression is not true within the specified time internval.

The Timeout action dialog is similar to the Execute Delayed dialog. The Timeout configuration also requires an expression. If the expression is true before the time expires, the action is not executed.

#### Web browser

The Web Browser action opens a web page in the default web browser.

The URL is supplied using a string expression.

#### Web requestsince 5.3.5

The Web Request action sends a GET or POST request to a web server. When the request has completed, the Execute action is performed.

The request information is defined using the Web Request dialog. The dialog settings will depend on the web server application requirements.

Note: The LogixNG_WebRequest_Test.php portion of the URL is a sample application.

##### Top Level Tabs

URL

  The URL contains the address of the web server. For GET requests, parameters can be added to the URL using the ?name=value&name2=value2 format. Parameters in the Parameter section are also added to the GET request URL.

  For POST requests, the parameters are defined in the Parameters section.

Charset

  Specify the character set to used for the application.

Request method

  Specify the request method to used for the application.

User agent

  Specify the user agent to be used for the request. The default is Mozilla/5.0 .

##### Local Variables

Local variable for response code

  The value of the local variable will be the numeric response code from the server. For successful requests, the value will be 200.

Local variable for reply content

  The value of the local variable will be the content returned from the server. Sometimes the content will have error messages detected by the server or the application.

Local variable for cookies

  The value of the local variable will have a copy of the current cookie. If the cookie needs to be shared by different ConditionalNGs, use a global variable.

##### Examples

There are two example files included in the JMRI distribution. They are located at help/en/html/tools/logixng/reference/WebRequestExample

WebRequest.xml

  This is a layout config xml file that has sample table entries.

LogixNG_WebRequest_Test.php

  This is a PHP program that acts as a web based application. This needs to be installed in a web server that has been configured to run PHP programs. The source code can be downloaded from GitHub.

## Digital boolean action :: Common

- Logix Action
- Many

To make import from Logix to LogixNG easier, LogixNG has a special action, Logix, that works similar to a Conditional in Logix. The LogixNG Logix action has a digital expression socket and a digital boolean action socket. The usual setup in LogixNG is a Logix action with a Many child with a number of Logix Action children.

#### Logix Action

When a Logix expression is evaluated, a Logix Action is invoked to perform the LogixNG actions if its state matches the result of the expression evaluation.

See the example at Logix.

#### Many

The Many action is used together with the Logix action to let the Logix action have more than one action child.

## Analog action :: Item

- Light intensity
- Memory

#### Light intensity

Sets the intensity of the selected variable light to an analog value.

#### Memory

Sets a memory to an analog value.

## Analog action :: Common

- Many

#### Many

Sets the value of many analog actions.

## String action :: Item

- Memory
- StringIO

#### Memory

Sets a memory to a string value.

#### StringIO

The StringIO action sets the string value of a StringIO. StringIOs are defined in the StringIO table. LCThrottles is a default StringIO for LocoNet. This is used to send a message to the LocoNet throttles.

## String action :: Common

- Many

#### Many

Sets the value of many string actions.

Chapter 6 - Expression Descriptions

Return to the Reference TOC