EX-RAIL

EX-RAIL Command Reference

Suitable For Level: Propeller Beanie Engineer Hat

EX‑CommandStation provides full automation and accessory control through the Extended Railroad Automation Instruction Language (EX‑RAIL).

This page includes a reference for all available EX‑RAIL commands.

See Also:

Introductory Information

Conventions used on this page

  • CAPITALISED words - These are EX-RAIL commands and are case sensitive

  • lowercase words within brackets/braces () - These are EX-RAIL parameters that must be provided, with multiple parameters separated by a comma ,, for example SEQUENCE(id) or DELAYRANDOM(min_delay, max_delay)

  • Quoted "text" - Text within quote marks "" are used as descriptions, and must include the quote characters, for example ROUTE(id, "description") becomes ROUTE(1, "This is the route description")

  • Square brackets [] - Parameters within square brackets [] are optional and may be ommitted. If specifying these parameters, do not include the square brackets themselves, for example ALIAS(name[, value]) becomes ALIAS(MY_ALIAS) or ALIAS(MY_ALIAS, 3)

  • | - Use of the | character means you need to provide one of the provided options only, for example <D POWER ON|OFF> becomes either <D POWER ON> or <D POWER OFF>

Handy information

  • COMMANDS are case sensitive. i.e. they must be in uppercase. Text parameters you provide (aliases, descriptions) are not

  • AUTOMATION, ROUTE, and SEQUENCE use the same ID number space, so a FOLLOW(n) command can be used for any of them

  • Sensors and outputs used by AT/AFTER/SET/RESET/LATCH/UNLATCH/SERVO/IF/IFNOT refer directly to Arduino pins, and those handled by I2C expansion (as virtual pins or vpins).

  • Signals also refer directly to pins, and the signal ID (for RED/AMBER/GREEN) is always the same as the RED signal pin

  • It’s OK to use sensor IDs that have no physical item in the layout. These can only be LATCHed, tested (IF/IFNOT), or UNLATCHed in the sequences. If a sensor is latched by the sequence, it can only be unlatched by the sequence so AT(35) LATCH(35) for example, effectively latches sensor 35 on when detected once

  • All IDs used in commands and functions will be numbers, or an ALIAS name if configured

  • Most IDs simply need to be unique, however RESERVE/FREE and LATCH/UNLATCH must be in the range 0 - 255

Note

There are four uses of ID numbers in EX-RAIL:

  • AUTOMATION, ROUTE, and SEQUENCE IDs

  • Turnout/Point IDs

  • Vpins - Includes physical pins on the CommandStation, virtual pins (Vpins) on I/O expander modules, and virtual pins that have no physical presence

  • Virtual block IDs as used in RESERVE/FREE

Therefore, you can have an AUTOMATION, a turnout/point, a Vpin, and a virtual block all defined with the same ID without issue as these will not relate to each other. This is probably a great reason to consider aliases to avoid confusion.

Correct use of DONE, ENDIF, and FOLLOW() statements

Every EX‑RAIL automation/route/sequence, event handler, and conditional statement must be terminated by one of these three directives.

On this page, you will see various references to the use of DONE, ENDIF, and FOLLOW() which can be confusing, so refer to this quick list to help understand the context in which each of these should be used:

  • Every conditional statement (all directives starting with the word IF) must be terminated by ENDIF

  • Every group of commands within a ROUTE, AUTOMATION, or SEQUENCE must be terminated by either DONE or FOLLOW(id)

  • Every event handler (all directives starting with the word ON) must be terminated by DONE

For example: (click to show)
// Valid use of a ROUTE with a nested IF statement
ROUTE(1)
  IF(46)
    // Things to be done when sensor ID 46 is active
  ELSE
    // Things to be done when sensor ID 46 is inactive
  ENDIF
  DONE

// Validate use of a sequence that needs to run continuously
// DONE is not required in this instance
SEQUENCE(2)
  IF(46)
    // Things to be done when sensor ID 46 is active
  ELSE
    // Things to be done when sensor ID 46 is inactive
  ENDIF
  FOLLOW(2)

// Validate use of a turnout event handler for turnout ID 200
ONCLOSE(200)
  // Things to be done when turnout 200 is closed
  DONE

AT(vpin) or AFTER(vpin [,debounceTime]) versus IF(vpin)

When defining conditions, the behaviour of AT() and AFTER() is quite different to using conditional IF() statements.

This applies to all directives starting with AT, AFTER, and IF.

When using AT() or AFTER(), this is a blocking activity, meaning the sequence of activities will not progress beyond this particular directive unless the condition is met.

When using IF conditional statements, these will not block if the condition is not met, allowing the sequence of activities to continue.

For example: (click to show)
// Use of AT() to prevent doing anything until a sensor is activated
// This sequence will continue to run until the sensor is activated, in which case those activities will be performed, and it will end
SEQUENCE(1)
  AT(46)
    // Things to do when sensor 46 is activated
  DONE

// Use of IF() to continuously monitor a number of sensors
// This sequence will continually loop to monitor the sensors, meaning the activities related to each sensor are not blocked by the state of other sensors
SEQUENCE(2)
  IF(46)
    // Things to do if sensor 46 is activated
  ENDIF
  IF(47)
    // Things to do if sensor 47 is activated
  ENDIF
  IF(48)
    // Things to do if sensor 48 is activated
  ENDIF
  FOLLOW(2)

Interactive diagnostics and control

Various diagnostic and control commands have been added to control and interact with EX‑RAIL, including the various sequences and objects once they have been defined in myAutomation.h and uploaded to the EX‑CommandStation.

These commands can be run interactively via the serial console or over Ethernet/WiFi if using a throttle or client that provides a suitable interface for sending native DCC-EX commands.

<D EXRAIL state> - Enable or disable EX-RAIL sequence logging

When the CommandStation is connected to a serial monitor, EX-RAIL sequence logging can be turned on or off (Enabled or Disabled).

For example: (click to show)

Example output from Point to Point Shuttle running SEQUENCE(13) with loco ID 18:

<D EXRAIL ON>
<p1 MAIN>
PPA1
<1 18 0 178 0>
<* EXRAIL Sensor 42 hit *>
<* EXRAIL Sensor 42 hit *>
<* EXRAIL drive 18 0 1 *>
<1 18 0 128 0>
<* EXRAIL drive 18 20 0 *>
<1 18 0 20 0>
<* EXRAIL Sensor 41 hit *>
<* EXRAIL Sensor 41 hit *>
<* EXRAIL drive 18 0 0 *>
<1 18 0 0 0>
<* EXRAIL begin(13) *>
<* EXRAIL begin(13) *>
<* EXRAIL drive 18 50 1 *>
<1 18 0 178 0>

</PAUSE> - Pause ALL EX-RAIL automation activities

Pauses ALL EX-RAIL automation activities, including sending an E-STOP to all locos.

</RESUME> - Resume ALL EX-RAIL automation activities

Resume ALL EX-RAIL automation activities, and resumes all locos at the same speed at which they were paused.

</> - Display EX-RAIL running task information

For example: (click to show)

Example outputs also using Point to Point Shuttle:

  • Leaving right side of the shuttle sequence with speed 50F (forward):

</>
<1 18 0 178 0>
<* EXRAIL STATUS
ID=0,PC=12,LOCO=0 ,SPEED=0F
ID=1,PC=12,LOCO=18 ,SPEED=50F *>

</ START [loco_addr] route_id> - Start route, optionally using specified loco

Starts a new task to send a loco onto a Route, or activate a non-loco Animation or Sequence.

</ KILL task_id> - Kills a currently running sequence

Kills a currently running sequence task by ID

</ RESERVE block_id> - Manually reserves a virtual track Block

Manually reserves a virtual track Block, valid IDs are in the range 0 - 255

</ FREE block_id> - Manually frees a virtual track Block

Manually frees a virtual track Block, valid IDs are in the range 0 - 255.

</ LATCH vpin> - Lock sensor ON, preventing external influence

Lock sensor ON, preventing external influence, valid IDs are in the range 0 - 255.

</ UNLATCH vpin> - Unlock sensor, returning to current external state

Unlock sensor, returning to current external state, valid IDs are in the range 0 - 255.

Refer to the LATCH/UNLATCH commands in the Sensors/Inputs - Reading and Responding section below for further details.

Aliases

ALIAS( name[, value] ) - Assigns name to a value

Aliases assigns names to values. They can go anywhere in the sequence. If a value is not assigned, a unique ID will be assigned based on the alias “name” text.

This is a simple substitution that lets you have readable names for things in your sequence. For example, instead of having to remember the VPin a turnout/point is connected to, give the pin number an alias and refer to it by that name. You can use this to name routes, values, pin numbers, or anything you need.

If you simply need a unique identifier for an object used internally to the sequence, such as a turnout/point, route, automation, or sequence, you don’t even need to provide an ID, EX-RAIL will generate one automatically when you omit the value parameter. We recommend using this for all your routes, sequences, and other internal objects so you don’t have to try to remember or keep a list of numbers you’ve used. This also prevents you from assigning the same number to more than one object.

REMEMBER: IDs for RESERVE/FREE, LATCH/UNLATCH, and pins must be explicitly defined.

To put this another way, if you connect an LED to pin 23 and want to turn it on and off, you have to explicitly set its pin number, so ALIAS(TOWER_LED, 23) lets you equate “23” to TOWER_LED. But if you created a route to run your train around an oval, you don’t really need to set the number or even know it. Just use ALIAS(OVAL) and let EX assign a number internally. If you ever wanted to know what number it assigns, you can enter <? OVAL> from the serial monitor with the Command Station running and it will tell you next to “Opcode=”. Since this “hash”, as it is called, is generated by the alias name word, it is always unique and always the same for that word even if you have not created the alias yet. Fun fact, “OVAL” will always equal 27500.

Alias naming rules:

  • Must not be an existing EX-RAIL command name or other reserved word.

  • Should be reasonably short but descriptive.

  • Must start with letters A-Z, a-z, or underscore _ (case sensitive!).

  • May then also contain numbers.

  • Must not contain spaces or special characters.

Parameters:
 > name - name for the Alias. See rules above
 > value - value to insert in place of the Alias

For example: (click to show)

Defining a pin turnout/point without an alias:

PIN_TURNOUT(1, 25, "Coal Yard")

Defining a pin turnout/point with aliases:

ALIAS(COAL_YARD)
ALIAS(COAL_YARD_PIN, 25)
PIN_TURNOUT(COAL_YARD, COAL_YARD_PIN, "Coal Yard")

Note that you could have used the command ALIAS(COAL_YARD, 1) in the example above to explicitly set the number, but unless you have a reason to use specific numbers, let the Command Station do it for you.

In this simple example, aliases seem like overkill, however consider the case where you need to have the “Coal Yard” turnout/point closed or thrown in various different automation sequences, and you will soon see why it’s easier to understand you’re throwing the COAL_YARD turnout/point rather than turnout/point ID 12345.

Alphabetic Command List

Full Alphabetic list of commands: (click to show)

Flow Control

Scripts/Sequences - Types and Control

AUTOSTART - Automatically start sequence at this point during Command Station startup

A sequence is automatically started at this point during startup.

If you have previously relied on the implied AUTOSTART to run things immediately, as of Version 5.0 you must now add this explicitly to the beginning of myAutomation.h

Parameters:
 > none

There are three options to define EX‑RAIL scripts or sequences:

  • AUTOMATION

  • ROUTE

  • SEQUENCE

AUTOMATION( id, "description" ) - Define an automation, advertised to throttles/clients

Define an automation sequence that is advertised to throttles/clients to send a train along.

See Stopping at a Station (simple loop) for a simple example.

Parameters:
 > id - id for the sequence/route/automation
 > description - description for the sequence/route/automation

ROUTE( id, "description" ) - Define a route, advertised to throttles/clients

Define a route that is advertised to throttles/clients. This can be used to initiate automation sequences such as setting turnouts/points and signals to allow a train to be driven through a specific route on the layout. See Creating Routes for various examples.

Parameters:
 > id - id for the sequence/route/automation
 > description - description for the sequence/route/automation

SEQUENCE( id ) - A general purpose sequence, not advertised to throttles/clients

A general purpose automation sequence that is not advertised to throttles/clients. This may be triggered automatically on startup, or be called by other sequences or activities. See Automating various non-track items, Point to Point Shuttle, and Multiple inter-connected trains for further examples.

Parameters:
 > id - id for the sequence/route/automation
 > description - description for the sequence/route/automation

All of these sequence types must be terminated by either a DONE, FOLLOW(id), or RETURN statement. If you use FOLLOW(id) or RETURN, you do not also need a DONE statement as any of these terms will tell EX‑RAIL that the sequence of events has ended.

DONE - Completes a Sequence/Route/Animation/Event, or any other automation

Completes a Sequence/Route/Animation/Event handler, and any other automation definition as shown in the various examples on this page and elsewhere in the EX‑RAIL documentation.

Parameters:
 > none

ENDTASK - Completes a Sequence/Route/Animation/Event, or any other automation

Identical to DONE.

Completes a Sequence/Route/Animation/Event handler, and any other automation definition as shown in the various examples on this page and elsewhere in the EX‑RAIL documentation.

Parameters:
 > none

CALL( id ) - Branch to a separate sequence

Branch to a separate sequence, which will need to RETURN when complete.

Parameters:
 > id - id for the sequence/route/automation to branch to

RETURN - Return to the calling sequence when completed

Return to the calling sequence when completed (no DONE required).

Parameters:
 > none

For example: (click to show)

For example, you have an AUTOMATION which you initiate that sends a train through your layout with multiple station stops, and you want to do the same things at each station.

You could write a very long AUTOMATION sequence to do this, or you could write the sound SEQUENCE once, then call it at each station:

AUTOMATION(21, "Station loop")    // Our station loop sequence
  FWD(30)
  AT(101)                         // At station 1 entrance sensor, call our sequence
  CALL(22)
  AT(102)                         // At station 2 entrance sensor, call our sequence
  CALL(22)
  AT(103)                         // At station 3 entrance sensor, call our sequence
  CALL(22)
  AT(104)                         // At station 4 entrance sensor, call our sequence
  CALL(22)
  FOLLOW(21)                      // Keep looping through the stations (see FOLLOW command reference below)

SEQUENCE(22, "Station sequence")  // Our station sequence
  FON(2)                         // Blow the horn
  FON(3)                         // Break squeal
  STOP                            // Stop at the station
  FON(4)                         // Let out a hiss from the air breaks for a second
  DELAY(1000)
  FOFF(4)
  DELAYRANDOM(2000, 10000)        // Wait between 2 and 10 seconds for passengers
  FON(2)                         // Blow the horn again
  FWD(30)                         // On our way to the next station
  RETURN                          // Return to the calling sequence

FOLLOW( sequence_id ) - Branch or Follow a specified sequence

Branch or Follow a specified sequence. This lets us do clever things like performing a different sequence depending on whether a turnout/point is CLOSED or THROWN, as well as simple things such as the example above where we keep looping through the same sequence.

Parameters:
 > sequence_id - id for the sequence/route/automation to branch to

For example: (click to show)
AUTOMATION(23, "Choose your own adventure") // This let's someone control the sequence by throwing a turnout/point (or not)
  FWD(30)
  AFTER(105)
  IFTHROWN(106)
    FOLLOW(24)
  ELSE
    FOLLOW(25)
  ENDIF
  DONE

SEQUENCE(24, "Adventure 1")                 // Quite a boring adventure to stop in a siding after sensor 106 has activated/deactivated
  AFTER(106)
  FON(2)
  FON(3)
  STOP
  DONE

SEQUENCE(25, "Adventure 2")                 // If we don't throw the turnout/point, let's do our station loop from the example above
  FOLLOW(21)

PAUSE - E-STOP all locos and PAUSE all other EX-RAIL tasks

E-STOP all locos and PAUSE all other EX-RAIL tasks until RESUMEd.

Parameters:
 > none

RESUME - Resume all paused tasks, including loco movement

Resume all paused tasks, including loco movement.

Parameters:
 > none

START( id ) - Execute a route or sequence

Start a new task to execute a route or sequence.

Parameters:
 > id - id for the sequence/route/automation to branch to

DELAY( delay ) - Delay the sequence a number of milliseconds

Delay the current sequence a number of milliseconds.

Parameters:
 > delay - period to delay in milliseconds

DELAYMS( delay ) - Delay the sequence a number of milliseconds

Same as DELAY()

Delay the current sequence a number of milliseconds.

Parameters:
 > delay - period to delay in milliseconds

DELAYMINS( delay ) - Delay the sequence a number of minutes

Delay the current sequence a number of minutes.

Parameters:
 > delay - period to delay in minutes

DELAYRANDOM( min_delay, max_delay ) - Delay a random period of time

Delay the current sequence a random time between min and max milliseconds.

See Multiple inter-connected trains for good examples.

Parameters:
 > min_delay - minimum period to delay in milliseconds
 > max_delay - maximum period to delay in milliseconds

Delay examples: (click to show)
ONCLOSE(102)      // When turnout 102 closed, wait 2 seconds, then set signal 101 green.
  DELAY(2000)
  GREEN(101)
  DONE

AT(123)           // When sensor 123 is activated, set signal 102 red, wait 1 minute, then set signal 102 green.
  RED(102)
  DELAYMINS(1)
  GREEN(102)
  DONE

RANDWAIT( ??? ) - TBA

Parameters:
 > ??? - ???
 > ??? - ???

IFRANDOM( percent ) - Run commands a random percentage of the time

Runs commands in IF block a random percentage of the time. This is handy for more realism by enabling automations that don’t have to run on a schedule.

Parameters:
 > percent - percentage to test against (0-100)

For example: (click to show)
AT(165)           // When sensor 165 is activated, set a lineside merry-go-round in action for 1 minute 50% of the time.
  IFRANDOM(50)
    SET(166)
    DELAYMINS(1)
    RESET(166)
  ENDIF
  DONE

ROUTE_CAPTION( route_id, "caption" ) - Change the label of the Route button

New In Version 5.4

Dynamically change the label of the Route button.

Parameters:
 > route_id - id of the route to change
 > caption - text to replace on the route ‘button’ label

For example: (click to show)
// setup 4 'routes'to switch between tracks/districts between PROG, MAIN and DC
ROUTE(500,"1.Trk: A main, B prog")
    SET_TRACK(A,MAIN)
    SET_TRACK(B,PROG)
    ROUTE_CAPTION(500,"Active")
    ROUTE_CAPTION(501,"Inactive")
    ROUTE_CAPTION(502,"Inactive")
    ROUTE_CAPTION(503,"Inactive")
    ROUTE_ACTIVE(500)
    ROUTE_INACTIVE(501)
    ROUTE_INACTIVE(502)
    ROUTE_INACTIVE(503)
DONE
ROUTE(501,"2.Trk: A dc10, B dc11")
    SETLOCO(10) SET_TRACK(A,DC)
    SETLOCO(11) SET_TRACK(B,DC)
    ROUTE_CAPTION(500,"Inactive")
    ROUTE_CAPTION(501,"Active")
    ROUTE_CAPTION(502,"Inactive")
    ROUTE_CAPTION(503,"Inactive")
    ROUTE_INACTIVE(500)
    ROUTE_ACTIVE(501)
    ROUTE_INACTIVE(502)
    ROUTE_INACTIVE(503)
DONE
ROUTE(502,"3.Trk: A dc10, B DCC main")
    SETLOCO(10) SET_TRACK(A,DC)
    SETLOCO(11) SET_TRACK(B,MAIN)
    ROUTE_CAPTION(500,"Inactive")
    ROUTE_CAPTION(501,"Inactive")
    ROUTE_CAPTION(502,"Active")
    ROUTE_CAPTION(503,"Inactive")
    ROUTE_INACTIVE(500)
    ROUTE_INACTIVE(501)
    ROUTE_ACTIVE(502)
    ROUTE_INACTIVE(503)
DONE
ROUTE(503,"4.Trk: A DCC main, B dc10")
    SETLOCO(10) SET_TRACK(A,DC)
    SETLOCO(11) SET_TRACK(B,MAIN)
    ROUTE_CAPTION(500,"Inactive")
    ROUTE_CAPTION(501,"Inactive")
    ROUTE_CAPTION(502,"Inactive")
    ROUTE_CAPTION(503,"Active")
    ROUTE_INACTIVE(500)
    ROUTE_INACTIVE(501)
    ROUTE_INACTIVE(502)
    ROUTE_ACTIVE(503)
DONE

ROUTE_ACTIVE( route_id ) - Activate a Route

New In Version 5.4

Dynamically flag a Route as active.

See example in ROUTE_CAPTION.

Parameters:
 > route_id - id of the route to activate

ROUTE_INACTIVE( route_id, caption ) - Deactivate a Route

New In Version 5.4

Dynamically flag a Route as inactive.

See example in ROUTE_CAPTION.

Parameters:
 > route_id - id of the route to deactivate

ROUTE_HIDDEN( route_id ) - Hide a Route from display

New In Version 5.4

Dynamically hide a Route.

Parameters:
 > route_id - id of the route to hide

ROUTE_DISABLED( route_id ) - disable a Route

New In Version 5.4

Dynamically disable a Route.

Parameters:
 > route_id - id of the route to disable

STASH( stash_id ) - Stashes the current loco/invert

New In Version 5.4

Parameters:
 > stash_id - id of the stash location to store the value (0-???)

Stashes/Stores the current loco/invert in the specified stash location.

Note

EXRAIL has the ability to switch the DCC direction meaning of FWD and REV so that it can, for example, use the same sequence to drive a normal train or one where the loco is pulling in reverse. If invert=1 in the stash then the loco needs to be moved in reverse in order for the train to move forward.

CLEAR_STASH( stash_id ) - Zeroes the specified stash

New In Version 5.4

Zeroes/Empties the specified stash location.

Parameters:
 > stash_id - id of the stash location to store the value (0-???)

CLEAR_ALL_STASH - Zeroes all stashes

New In Version 5.4

Zeroes/Empties all stash locations.

Parameters:
 > none

PICKUP_STASH( stash_id ) - Retrieves and sets the loco/invert from the specified stash

New In Version 5.4

Retrieves and sets the loco/invert from the specified stash location.

Parameters:
 > stash_id - id of the stash location to store the value (0-???)

Conditional Statements

There are numerous conditional statements available to influence activities based on the states of sensors, signals, turnouts/points, and other items.

Any directive on this page starting with IF must have an associated ENDIF statement, and optionally an ELSE statement if an alternative activity is to be performed.

If a conditional statement is part of an automation sequence, the sequence still needs to be terminated with a DONE, FOLLOW(), or RETURN statement.

This include IFNOT(), IFRED(), IFAMBER(), IFGREEN(),

Refer also to Correct use of DONE, ENDIF, and FOLLOW() statements.

IF ( vpin ) … ELSE … ENDIF - Execute commands if the conditions are met

Perform the following block of commands if the specified sensor is active.

Optionally be followed by an ELSE somewhere in the following commands. Must be followed by an ENDIF somewhere in the following commands.

Parameters:
 > vpin - vpin (or alias) of the sensor to check

Also see IFNOT(), IFRED(), IFAMBER(), IFGREEN(), IFCLOSED(), IFTHROWN(), IFRANDOM(), IFTTPOSITION(), IFRE(), IFTIMEOUT(), IFGTE(), IFLT(), IFLOCO(), IFRESERVE()

IFNOT ( vpin ) … ELSE … ENDIF - Execute commands if the conditions are NOT met

Perform the following block of commands if the specified sensor is not active.

Optionally be followed by an ELSE somewhere in the following commands. Must be followed by an ENDIF somewhere in the following commands.

Parameters:
 > vpin - vpin (or alias) of the sensor to check

ENDIF - Required to end an IF/IFNOT/etc.

Required to end an IF/IFNOT/etc. (Used in all IF.. functions).

Optionally be proceeded by an ELSE somewhere in the preceding commands. Must be proceeded by an IF() somewhere in the preceding commands.

Parameters:
 > none

AT( vpin ) - Halt command execution until the sensor is set

Halt the execution of the current block of commands until the sensor is set.

Parameters:
 > vpin - vpin (or alias) of the sensor to check

AFTER( vpin [,debounce_time] ) - Halt command execution until the sensor is cleared

Halt the execution of the current block of commands until the sensor is cleared.

Parameters:
 > vpin - vpin (or alias) of the sensor to check
 > debounce_time - optional debounce time (default 500mS)

Objects - Definition and Control

Create and manage HAL device objects

HAL( device, parameters ) - Create a HAL device in myAutomation.h

Create a HAL device in myAutomation.h rather than needing to use myHal.cpp

Parameters:
 > device - device
 > parameters - as needed

For example: (click to show)
// Define a third PCA9685 device following the first two default devices at Vpin 132 and I2C address 0x42
HAL(PCA9685, 132, 16, 0x42)

// Define a third MCP23017 device following the first two default devices at Vpin 196 and I2C address 0x22
HAL(MCP23017, 196, 16, 0x22)

// Define a Mega2560 based EX-IOExpander device starting at Vpin 800 at the default I2C address of 0x65
HAL(EXIOExpander, 800, 62, 0x65)

// Define an EX-Turntable device at the default Vpin 600 and I2C address of 0x60
HAL(EXTurntable, 600, 1, 0x60)

HAL_IGNORE_DEFAULTS - Disable default MCP23017 and PCA9685 HAL devices

New In Version 5.4

Disable default MCP23017 and PCA9685 HAL devices

Parameters:
 > none

Signal Objects - Definition and Control

SIGNAL( red_pin, amber_pin, green_pin ) - Define a pin based signal

Define a pin based signal, which requires three active low pins to be defined to correspond with red, amber, and green lights. Active low means they are activated when the associated pins are set to 0V or ground.

Parameters:
 > red_pin - vpin of the red LED. Also defines the signal_id.
 > amber_pin - vpin of the amber LED
 > green_pin - vpin of the green LED

SIGNALH( red_pin, amber_pin, green_pin ) - Define a pin based signal with active high pins

As above to define a pin based signal, but with active high pins instead. Active high means they are activated when the associated pins are set to 5V (or 3.3V if using a 3.3V device).

For both the SIGNAL/SIGNALH commands, signal colour is set using the pin defined for the red pin. If the signal only has two colours (e.g. RED/GREEN), set the unused colour’s pin to 0.

Parameters:
 > red_pin - vpin of the red LED. Also defines the signal_id.
 > amber_pin - vpin of the amber LED
 > green_pin - vpin of the green LED

SERVO_SIGNAL( vpin, red_pos, amber_pos, green_pos ) - Define a servo based signal

Define a servo based signal, such as semaphore signals. Each position is an angle to turn the servo to, similar to the SERVO/SERVO2 commands, and SERVO_TURNOUT

Parameters:
 > vpin - vpin of the servo
 > red_pos - position to move the servo to for a red signal
 > amber_pos - position to move the servo to for a amber signal
 > green_pos - position to move the servo to for a green signal

DCC_SIGNAL( id, addr, sub_addr ) - Define a DCC accessory signal

Define a DCC accessory signal. Control the colour or aspect of these via the defined id

DCCX_SIGNAL( Address, redAspect, amberAspect, greenAspect ) - Defines a signal (with id as dcc address)

New In Version 5.4

This defines a signal (with id same as dcc address) that can be operated by the RED/AMBER/GREEN commands. In each case the command uses the signal address to refer to the signal and the aspect chosen depends on the use of the RED AMBER or GREEN command sent. Other aspects may be sent but will require the direct use of the ASPECT command.

The IFRED/IFAMBER/IFGREEN and ONRED/ONAMBER/ONGREEN commands continue to operate as for any other signal type. It is important to be aware that use of the ASPECT (see below) or <A> commands will correctly set the IF flags and call the ON handlers if ASPECT is used to set one of the three aspects defined in the DCCX_SIGNAL command.

Direct use of other aspects does not affect the signal flags. ASPECT and <A> can be used without defining any signal if the flag management or ON event handlers are not required.

VIRTUAL_SIGNAL( id ) - Define a virtual signal

Define a virtual signal, which is backed by another automation sequence

Parameters:
 > id - id (or alias) of the virtual signal

IFRED( signal_id ) - Test if signal is red

Test if signal is red.

Parameters:
 > signal_id - id (or alias) of the virtual signal to test

IFAMBER( signal_id ) - Test if signal is amber

Test if signal is amber

Parameters:
 > signal_id - id (or alias) of the virtual signal to test

IFGREEN( signal_id ) - Test if signal is green

Test if signal is green

Parameters:
 > signal_id - id (or alias) of the virtual signal to test

GREEN( signal_id ) - Set a defined signal to GREEN

Set a defined signal to GREEN (see SIGNAL).

Parameters:
 > signal_id - id (or alias) of the virtual signal to set

AMBER( signal_id ) - Set a defined signal to Amber

Set a defined signal to Amber (See SIGNAL).

Parameters:
 > signal_id - id (or alias) of the virtual signal to set

RED( signal_id ) - Set defined signal to Red

Set defined signal to Red (See SIGNAL).

Parameters:
 > signal_id - id of the virtual signal to set|BR|

ASPECT( address, aspect ) - Command for DCC Extended Accessories

New In Version 5.4

This command sends an extended accessory packet to the track, normally used to set a signal aspect. Aspect numbers are undefined as standards except for 0 which is always considered a stop. The exact aspect codes to be used must be determined from the documentation for the accessory decoder in use.

ONGREEN( signal_id) - Define event handler for when a signal is set to the green

Define an event handler for when a signal is set to the green aspect.

Parameters:
 > signal_id - id (or alias) of the virtual signal to set

ONAMBER( signal_id) - Define event handler for when a signal is set to the amber

Define an event handler for when a signal is set to the amber aspect.

Parameters:
 > signal_id - id (or alias) of the virtual signal to set

ONRED( signal_id) - Define event handler for when a signal is set to the red aspect

Define an event handler for when a signal is set to the red aspect.

Parameters:
 > signal_id - id (or alias) of the virtual signal to set

Signal example: (click to show)
SIGNAL(25, 26, 27)                // Active low red/amber/green signal using pins 25/26/27 directly on the CommandStation.
SIGNALH(164 ,0, 165)              // Active high red/green signal using the first two pins of an MCP23017 I/O expander module.
SERVO_SIGNAL(101, 100, 250, 400)  // Servo based signal using the first PCA9685 servo module.

GREEN(25)                         // Sets our active low signal to green.
GREEN(164)                         // Sets our active high signal to green.
GREEN(101)                        // Sets our servo based signal to green.

Turnout/Point Objects - Definition and Control

All the below turnout/point definitions will define turnouts/points that are advertised to wiThrottle Protocol apps, Engine Driver, and JMRI, unless the HIDDEN keyword is used.

“description” is an optional parameter, and must be enclosed in quotes “”. If you don’t wish this turnout/point to be advertised to throttles, then substitute the word HIDDEN (with no “”) instead of the description.

TURNOUT( id, addr, sub_addr [, "description"] ) - Define a DCC accessory turnout/point

Define a DCC accessory turnout/point. Note that DCC linear addresses are not supported, and must be converted to address/subaddress in order to be defined. Refer to the Stationary Decoder Address Table (xlsx Spreadsheet) for help on these conversions. (or see TURNOUTL below).

Parameters:
 > id - identifier of the Turnout/Point
 > addr - ranges from 0 to 511
 > subaddr - ranges from 0 to 3
 > description - The description that will be assigned to the turnout/point

TURNOUTL( id, addr [, "description"] ) - Define a DCC accessory turnout/point

Define a DCC accessory turnout/point. This command will convert a linear address to the address/subaddress format using the TURNOUT command above.

Note when providing the name of the profile that the profile names are case sensitive, and must be written exactly as they appear (e.g. Bounce, not bounce or BOUNCE).

PIN_TURNOUT( id, pin [, "description"] ) - Define a pin operated turnout

Define a pin operated turnout. When sending a CLOSE command, the pin will be HIGH, and a THROW command will set the pin LOW.

Parameters:
 > id - unique Id for the servo
 > pin - vpin to which the servo is attached
 > description - The description that will be assigned to the turnout/point

SERVO_TURNOUT( id, pin, active_angle, inactive_angle, profile [, "description"] ) - Define a servo turnout/point

Define a servo turnout/point. “active_angle” is for THROW, “inactive_angle” is for CLOSE, and profile is one of Instant, Fast, Medium, Slow or Bounce (although clearly we don’t recommend Bounce for turnouts/points!).

Parameters:
 > id - unique Id for the servo
 > pin - vpin to which the servo is attached
 > active_angle - the PWM value corresponding to the servo position for THROWN state, normally in the range 102 to 490
 > inactive_angle - the PWM value corresponding to the servo position for CLOSED state, normally in the range 102 to 490
 > profile - one of
    - 0=Instant,
    - 1=Fast (0.5 sec),
    - 2=Medium (1 sec),
    - 3=Slow (2 sec) and
    - 4=Bounce (subject to revision)
 > description - The description that will be assigned to the turnout/point

Refer to Connecting a Servo Module for more information.

VIRTUAL_TURNOUT( id [, "description"] ) - Define a virtual turnout, which is backed by another automation sequence

Define a virtual turnout, which is backed by another automation sequence.

For a good example of this refer to Realistic turnout sequences.

Parameters:
 > turnout_id - The id of the turnout/point
 > description - The description that will be assigned to the turnout/point

IFCLOSED( turnout_id ) - Test if a turnout/point is closed

Parameters:
 > turnout_id - The id of the turnout/point to test

IFTHROWN( turnout_id ) - Test if a turnout/point is thrown

Test if a turnout is thrown

Parameters:
 > turnout_id - The id of the turnout/point to test

ONCLOSE( turnout_id ) - Event handler for when a turnout/point is closed

Event handler for when a turnout/point is sent a close command. Note that there can be only one defined ONCLOSE event for a specific turnout/point.

Parameters:
 > turnout_id - The id of the turnout/point

ONTHROW( turnout_id ) - Event handler for when a turnout/point is thrown

Event handler for when a turnout/point is sent a throw command. Note that there can be only one defined ONTHROW event for a specific turnout/point.

Parameters:
 > turnout_id - The id of the turnout/point

CLOSE( turnout_id ) - Close a turnout/point

Closes a defined turnout/point.

Parameters:
 > turnout_id - The id of the turnout/point to close

THROW( turnout_id ) - Throw a turnout/point

Throws a defined turnout/point.

Parameters:
 > turnout_id - The id of the turnout/point to throw

For example: (click to show)
TURNOUT(100, 26, 0, "Coal Yard")                  // DCC accessory turnout at linear address 101.
PIN_TURNOUT(101, 164, "Switching Yard")           // Pin turnout on an MCP23017 I/O expander module.
SERVO_TURNOUT(102, 102, 400, 100, Slow, HIDDEN)   // A servo turnout on a PCA9685 servo module that is hidden from throttles.
VIRTUAL_TURNOUT(103, "Lumber Yard")               // A virtual turnout which will trigger an automation sequence when CLOSE or THROW is sent.

TOGGLE_TURNOUT( turnout_id ) - Toggle a defined turnout/point between CLOSE/THROW

New In Version 5.4

Toggles the state of the specified turnout/point between closed and thrown.

Parameters:
 > turnout_id - The id of the turnout/point to throw

Turntable/Traverser Objects - Definition and Control

Also refer to EX-RAIL automation.

MOVETT( id, steps, activity ) - Move a EX‑Turntable to a step position and perform an activity

Move the specified EX‑Turntable to the provided step position and perform the specified activity.

Parameters:
 > id - The id of the turntable
 > steps - The step position to move to
 > activity - The activity to perform

Note

From version 5.4.0, we highly recommend using our new turntable/traverser commands which allow turntables/traversers to be advertised to throttles similarly to how turnout/point objects are advertised and operated. Refer to Turntable features.

IFRE ( vpin, value ) - Test if a rotary encoder has been set to a value

Test if a rotary encoder has been set to the specified value

Parameters:
 > vpin - The VPin the encoder is connected to
 > value - value to test

ONCHANGE( vpin ) - Detects a rotary encoder has changed position

Detects a rotary encoder has changed position

Parameters:
 > vpin - The VPin the encoder is connected to

For example: (click to show)
ONCHANGE(700)     // If rotary encoder ID 700 change state do this sequence
  IFRE(700, 1)    // If rotary encoder ID 700 is at position 1, start ROUTE ID 123
    START(123)
  ENDIF
  IFRE(700, 2)    // If rotary encoder ID 700 is at position 2, start ROUTE ID 124
    START(124)
  ENDIF
  DONE

Turntable features

New In Version 5.4

All the below turntable/traverser definitions will define turntables/traversers that are advertised to throttles that understand them, unless the HIDDEN keyword is used.

To fully define a turntable/traverser object, you need to define the object first, and then one or more positions.

“description” is an optional parameter, and must be enclosed in quotes “”. If you don’t wish this turntable/traverser to be advertised to throttles, then substitute the word HIDDEN (with no “”) instead of the description.

DCC_TURNTABLE( id, home_angle, [, "description"] ) - Define a DCC accessory turntable/traverser

Define a DCC accessory turntable/traverser at the specified id and the home_angle angle.

Parameters:
 > id - id of the turntable/traverser, valid IDs are 1 - 32767
 > home_angle - the angle of the home position, valid angles are 0 - 3600

EXTT_TURNTABLE( id, vpin, home_angle, [, "description"] ) - Define an EX-Turntable turntable/traverser

Define an EX-Turntable turntable/traverser at the specified id and vpin with a home_angle angle.

This statement will create the EX‑Turntable turntable/traverser object only, so you will need a separate HAL() statement for an EX‑Turntable device to create the HAL device. It is not recommended to create it via “myHal.cpp”.

The HAL creation will require the vpin and i2c_address parameters.

Parameters:
 > id - id of the turntable/traverser, valid IDs are 1 - 32767
 > vpin - id of the vpin where the EX‑Turntable device is located
 > i2c_address - the I2C address of the EX‑Turntable device
 > home_angle - the angle of the home position, valid angles are 0 - 3600

Example creation and definition:

HAL(EXTurntable,600,1,0x60)            // Create your EX-Turntable device driver
EXTT_TURNTABLE(1,600,45,"My EX-Turntable")  // Create your EX-Turntable object to enable control

TT_ADDPOSITION( id, position_id, value, angle [, "description"] ) - Add a turntable position

Add a position to a turntable/traverser object turntable_id with position index position_id, step or DCC address value, angle degrees from home.

Parameters:
 > id - id of the turntable/traverser, which must be created prior to adding positions
 > position_id - index of the position to add, valid positions are (1 - 48)
 > value - either steps from home for EX-Turntable, or the linear DCC address for a DCC accessory turntable, valid values are (1 - 32767)
 > angle - angle of the position from the home position, valid angles are (0 - 3600)

IFTTPOSITION( id, position ) - Test if turntable/traverser is at a position

Tests if the turntable/traverser at the specified id is at the specified position.

Parameters:
 > id - id of the turntable/traverser to test. (1 - 32767)
 > position - position to rotate to. (1 - 48)

ONROTATE( id ) - Event handler for when a turntable/traverser is rotated

Triggers the event handling mechanism for turntable/traverser id if configured. Note that there can be only one defined ONROTATE event for a specific turntable/traverser.

Parameters:
 > id - id of the turntable/traverser to test (1 - 32767)

ROTATE( id, position, activity ) - Rotate an EX-Turntable turntable/traverser

Rotate an EX-Turntable turntable/traverser at the specified id to the specified position, and perform activity.

Parameters:
 > id - id of the turntable/traverser, valid IDs are (1 - 32767)
 > position - position to rotate to, valid positions are (1 - 48)
 > activity - refer to Ex-Turntable commands, using the “EX-RAIL activity” column

ROTATE_DCC( id, position ) - Rotate a DCC accessory turntable/traverser

Rotate a DCC accessory turntable/traverser at the specified id to the specified position.

Parameters:
 > id - id of the turntable/traverser, valid IDs are (1 - 32767)
 > position - position to rotate to, valid positions are (1 - 48)

WAITFORTT( id ) - Wait for EX-Turntable turntable/traverser to complete a rotation

Wait for the EX-Turntable turntable/traverser at id to complete a rotation. As no feedback can be received from DCC accessory turntables, this is only valid for EX-Turntable.

Parameters:
 > id - id of the turntable to test

Sensors/Inputs - Reading and Responding

JMRI_SENSOR(vpin [,count]) - Creates <S> type sensors visible to JMRI

New In Version 5.4

This command causes the creation of JMRI <S> type sensors in a way that is simpler than repeating lines of <S> commands in mySetup.h.

  • JMRI_SENSOR(100) is equivalent to <S 100 100 1>

  • JMRI_SENSOR(100,16) will create <S> type sensors for vpins 100-115.

Parameters:
 > vpin - vpin to create
 > count - optional. Number of sensors to create. Inclusive on vpin. Default is one (1)

AT( vpin ) - Causes a sequence to wait until a sensor is active/triggered

A sequence will not progress until a sensor has been triggered.

Parameters:
 > vpin - vpin (or alias) of the sensor to test

AFTER( vpin ) - Causes a sequence to wait until after a sensor has been triggered

A sequence will not progress until after a sensor has been triggered and then is off for 0.5 seconds.

Parameters:
 > vpin - vpin (or alias) of the sensor to test

ATTIMEOUT( vpin, timeout_ms ) - Causes a sequence to wait until either a sensor is active/triggered, or if the timer runs out

A sequence will not progress until either a sensor is active/triggered, or if the timer runs out. It then continues and sets a testable “timed out” flag (see IFTIMEOUT).

Parameters:
 > vpin - vpin (or alias) of the sensor to test
 > timeout_ms - time/duration to wait for in milliseconds

IF( vpin ) - If sensor activated or latched, continue

If sensor activated or latched, continue. Otherwise skip to ELSE or matching ENDIF.

Parameters:
 > vpin - vpin (or alias) of the sensor to test

See the Condititional Statments section for more information on IF … ELSE … ENDIF commands.

IFNOT( vpin ) - If sensor NOT activated and NOT latched, continue

If sensor NOT activated and NOT latched, continue. Otherwise skip to ELSE or matching ENDIF.

Parameters:
 > vpin - vpin (or alias) of the sensor to test

See the Condititional Statments section for more information on IF … ELSE … ENDIF commands.

IFTIMEOUT - Tests if “timed out” flag has been set by an ATTIMEOUT() sensor reading attempt

Tests if “timed out” flag has been set by an ATTIMEOUT() sensor reading attempt.

Parameters:
 > none

Note that with the sensor commands IF(), IFNOT(), IFTIMEOUT(), AT(), ATTIMEOUT(), and AFTER(), you can use negative values to enable the use of active HIGH sensors.

For example: (click to show)
AT(40)        // Wait for pin 40 to go low.
AT(-40)       // Wait for pin 40 to go high.

ATGTE( vpin, value ) - Waits for an analog pin to reach a value

Waits for an analog pin to reach the specified value.

Parameters:
 > vpin - analogue pin. vpin (or alias) of the sensor to test
 > value - value to test against

ATLT ( vpin, value ) - Waits for an analog pin to go below a value

Waits for an analog pin to go below the specified value.

Parameters:
 > vpin - analogue pin. vpin (or alias) of the sensor to test
 > value - value to test against

IFGTE( vpin, value ) - Test if analog pin reading is greater than or equal to value

Test if analog pin reading is greater than or equal to value (>=).

Parameters:
 > vpin - analogue pin. vpin (or alias) of the sensor to test
 > value - value to test against

IFLT( vpin, value ) - Test if analog pin reading is less than value

Test if analog pin reading is less than value (<).

Parameters:
 > vpin - Analogue pin. vpin (or alias) of the sensor to test
 > value - value to test against

All the IFGTE(), IFLT(), ATGTE()`and `ATLT() commands read the analog value from an analog input pin (A0 - A5 on an Arduino Mega) or an analog input from an I/O expander module. Valid values are defined by the capability of the analog to digital converter in use.

Sensor examples: (click to show)
IF(25)          // If sensor on the Command Station pin 25 is activated, set a signal red, wait 10 seconds, then close a turnout/point.
  RED(101)
  DELAY(10)
  CLOSE(200)
ENDIF

IFNOT(26)       // If sensor on the Command Station pin 26 is not activated, keep our pedestrian crossing light at 102 green, else set it red.
  GREEN(102)
ELSE
  RED(102)
ENDIF

IFGTE(A2, 512)  // If reading the analog input from a photoelectric light sensor exceeds 512, it's bright enough to turn the street lights off.
  RESET(164)
ENDIF

IFLT(A3, 10)   // If current sensing from an analog occupancy detector had dropped below the threshold, turn off our mimic panel light, otherwise turn it on.
  RESET(165)
ELSE
  SET(165)
ENDIF

LATCH/UNLATCH can be used to maintain the state of a sensor, or can also be used to trigger a virtual sensor to act as a state flag for EX-RAIL. As this effects the state of a sensor, it can be tested via IF/IFNOT and will also work with AT/AFTER.

ATTIMOUT1 ( vpin, value ) - TBA

Waits for ???.

Parameters:
 > vpin - analogue pin. vpin (or alias) of the sensor to test
 > value - value to test against

ATTIMOUT2 ( vpin, value ) - TBA

Waits for ???.

Parameters:
 > vpin - analogue pin. vpin (or alias) of the sensor to test
 > value - value to test against

DRIVE ( vpin ) - TBA

???

Parameters:
 > vpin - analogue pin. vpin (or alias) of the sensor to ???

LATCH( vpin ) - Latches a sensor on

Latches a sensor on (Sensors 0-255 only).

Parameters:
 > vpin - vpin (or alias) of the sensor to unlatch

See UNLATCH() for examples.

UNLATCH( vpin ) - Remove LATCH on sensor

Remove LATCH on sensor.

Parameters:
 > vpin - vpin (or alias) of the sensor to unlatch

For example: (click to show)

In this example, LATCH/UNLATCH is used to toggle between two different activities each time the ROUTE is selected in a WiThrottle:

TURNOUT(17, 30, 1, "Bay to Shed") // DCC turnout/point with linear address 117

ALIAS(BayExitStarter, 107)        // Starter Signal with Route board
ALIAS(ROUTE_TOGGLE, 11)           // State flag to toggle

ROUTE(11, "Bay to Shed")
  IF(ROUTE_TOGGLE)             // If ROUTE_TOGGLE is active, reset the route
    DEACTIVATEL(BayExitStarter)
    DELAY(20)
    CLOSE(17)
    UNLATCH(ROUTE_TOGGLE)           // UNLATCH (Clear) ROUTE_TOGGLE
  ELSE                            // LATCH is not active, so set route and LATCH
    THROW(17)
    DELAY(20)
    ACTIVATEL(BayExitStarter)
    LATCH(ROUTE_TOGGLE)         // LATCH ROUTE_TOGGLE to indicate route set
  ENDIF
DONE
For example: (click to show)

In this example, LATCH/UNLATCH is used to start/stop a separate running sequence.

ROUTE(1,"Shuttle")
  SETLOCO(3)
  IF(99)
    UNLATCH(99)
    DONE
  ENDIF
  LATCH(99)
FOLLOW(2)   // this line is not actully needed

SEQUENCE(2)
  .... move loco etc
  IF(99)
    FOLLOW(2)
  ENDIF
DONE // will also stop loco

ONBUTTON( vpin ) - Event handler for debounced button presses

New In Version 5.4

This new event handler is handy for mimic panel and other buttons that need to perform an action when a button is pressed, rather than having to create a sequence with a combination of AFTER and IF statements to debounce a button which quickly becomes very complicated.

Note that this works for active low buttons only.

Parameters:
 > vpin - vpin to test

ONSENSOR( vpin ) - Event handler for sensors

New In Version 5.4

A new event handler to perform actions when a sensor is activated. Like the other sensor triggers such as IF, AT, and AFTER, a negative value can be used for an active high sensor.

Parameters:
 > vpin - vpin (or alias) of the sensor to test

Output and LED control

SET( pin [,count] ) - Set an output pin HIGH

Set output pin (set to HIGH)

Parameters:
 > pin - The first pin number connected that you which to change
 > count - optional number of pins to change, starting from and including pin. Default is one

RESET( pin [,count] ) - Reset output pin

Reset output pin (set to LOW)

Parameters:
 > pin - The first pin number connected that you which to change
 > count - optional number of pins to change, starting from and including pin. Default is one

FADE( pin, value, ms ) - Fade an LED

Fade an LED on a servo driver to specified value taking specified time.

Parameters:
 > pin - pin/vpin of the LED
 > value - value to fade the pin to
 > ms - duration taken to get to the value in milliseconds

LCN( "msg" ) - Send message to LCN Accessory Network

Send message to LCN Accessory Network.

Parameters:
 > msg - message to write

CONFIGURE_SERVO(vpin, pos1, pos2, profile) - Define LED’s connected to PCA9685 boards

New In Version 5.4

This command offers a more convenient way of defining an LED connected to a PCA9685 pin, instead of performing the HAL call in halSetup.h

Parameters:
 > vpin - The VPin the LED is connected to, e.g. 101 for the second pin on the first PCA9685 servo module
 > pos1 - The desired intensity (brightness) of the LED when turned on, with 0 being off, and 4095 being 100%)
 > pos2 - The desired intensity (brightness) of the LED when turned off
 > profile - the required profile

Examples:
 previously in mySetup.h you would have used:
 IODevice::configureServo(112,2437,0,PCA9685::NoPowerOff);
 Now in myAutomation.h use:

 CONFIGURE_SERVO(111, 2437, 0, PCA9685::NoPowerOff)

NEOPIXEL( vpin, red, green, blue [,count] ) - Controls the colour of attached Neopixel LEDs

New In Version 5.4

Controls the colour of one or more attached Neopixel LEDs

Parameters:
 > vpin - The VPin the first Neopixel connected that you which to change|BR| > red - The desired red colour value (0-255)
 > green - The desired red colour value (0-255)
 > blue - The desired red colour value (0-255)
 > count - number of Neopixels to change, starting from and including vpin. Default is one

Examples:
 NEOPIXEL(100,255,255,255,10) // set 10 Neopixels LEDs to white starting at vpin 100

NEOPIXEL_SIGNAL( signalid, red, green, blue ) - Controls the colour of attached Neopixel LED

New In Version 5.4

Controls the colour of one attached Neopixel LED

Parameters:
 > signalid - The VPin the first Neopixel connected that you which to change|BR| > red - The desired red colour value (0-255)
 > green - The desired red colour value (0-255)
 > blue - The desired red colour value (0-255)

Examples:
 NEOPIXEL_SIGNAL(100,255,255,255) // set one Neopixel LED to white

ANOUT( vpin, value, param1, param2) - Analog output ??

New In Version 5.4

Parameters:
 > vpin - first VPIN allocated
 > value - ???
 > param1 - ???
 > param2 - ???

Examples:
 ANOUT(10000,23,0,0) // will play the 23rd mp3 file.
 ANOUT(10000,23,30,0) // will do the same thing, as well as setting the volume to 30 (maximum value).

For example: (click to show)
//=======================================================================
// Play mp3 files from a Micro-SD card, using a DFPlayer MP3 Module.
//=======================================================================
// Parameters:
//   10000 = first VPIN allocated.
//   10 = number of VPINs allocated.
//   Serial1 = name of serial port (usually Serial1 or Serial2).
// With these parameters, up to 10 files may be played on pins 10000-10009.
// Play is started from EX-RAIL with SET(10000) for first mp3 file, SET(10001)
// for second file, etc.  Play may also be initiated by writing an analogue
// value to the first pin, e.g. ANOUT(10000,23,0,0) will play the 23rd mp3 file.
// ANOUT(10000,23,30,0) will do the same thing, as well as setting the volume to
// 30 (maximum value).
// Play is stopped by RESET(10000) (or any other allocated VPIN).
// Volume may also be set by writing an analogue value to the second pin for the player,
// e.g. ANOUT(10001,30,0,0) sets volume to maximum (30).
// The EX-RAIL sequence may check for completion of play by calling WAITFOR(pin), which will only proceed to the
// following line when the player is no longer busy.
// E.g.
//    SEQUENCE(1)
//      AT(164)           // Wait for sensor attached to pin 164 to activate
//      SET(10003)        // Play fourth MP3 file
//      LCD(4, "Playing") // Display message on LCD/OLED
//      WAITFOR(10003)    // Wait for playing to finish
//      LCD(4, "")       // Clear LCD/OLED line
//      FOLLOW(1)         // Go back to start

// DFPlayer::create(10000, 10, Serial1);

PLAY_SOUND( vpin, fileNumber, volume, ??? ) - Play mp3 files from a Micro-SD card

New In Version 5.4

Play mp3 files from a Micro-SD card, using a DFPlayer MP3 Module.

Alias of ANOUT.

Parameters:
 > vpin - first VPIN allocated
 > fileNumber - number of VPINs allocated
 > volume - volume (0-30)
 > ??? - ??? TBA

Servo Control

SERVO( id, position, profile ) - Move an animation servo

Move an animation servo. Do NOT use for Turnouts/points.

Parameters:
 > id - id of the servo to move
 > position - position to move to
 > profile - one of
    - Instant,
    - Fast (0.5 sec),
    - Medium (1 sec),
    - Slow (2 sec) and
    - Bounce (subject to revision)

SERVO2( id, position, duration ) - Move an animation servo taking duration

Move an animation servo taking duration in milliseconds. Do NOT use for Turnouts/points

Parameters:
 > id - id of the servo to move
 > position - position to move to
 > duration - duration of the move in milliseconds|BR|

WAITFOR( pin ) - Wait for a servo motion to complete prior to continuing

The WAITFOR() command instructs EX-RAIL to wait for a servo motion to complete prior to continuing.

Parameters:
 > pin - vpin to test

A couple of examples: (click to show)
// First example defines a servo turnout/point for the coal yard and a signal for the main line.
TURNOUT(100, 26, 0, "Coal Yard")
SIGNAL(25, 26, 27)

// When our turnout/point is closed, the main line is open, so the signal is green.
ONCLOSE(100)
  GREEN(25)
DONE

// When our turnout is closed, the main line is interrupted, so the signal is red.
ONTHROW(100)
  RED(25)
DONE

// This example triggers an automation sequence when a DCC accessory decoder is activated, including waiting for SERVO motions to complete.
ONACTIVATEL(100)            // Activating DCC accessory decoder with linear address 100 commences the sequence.
  SERVO(101, 400, Slow)     // Move the first servo and wait.
  WAITFOR(101)
  SERVO(102, 300, Medium)   // Move the second servo and wait.
  WAITFOR(102)
  SET(165)                  // Activate a Vpin to turn an LED on.
  SET(166)                  // Activate a second Vpin to turn a second LED on.
DONE

DCC Accessory Decoder Control

ONACTIVATE( addr, sub_addr ) - Event handler for 2 part DCC accessory packet value 1

Event handler for 2 part DCC accessory packet value 1

All these “ON” commands are event handlers that trigger a sequence of commands to run when the event occurs. These can vary from the most basic tasks such as setting signals when turnouts are closed or thrown, to triggering complete automation sequences via a DCC accessory decoder.

Parameters:
 > addr - DCC address ???
 > Sub_addr - sub-address ???

ONACTIVATEL( linear ) - Event handler for linear DCC accessory packet value 1

Event handler for linear DCC accessory packet value 1

All these “ON” commands are event handlers that trigger a sequence of commands to run when the event occurs. These can vary from the most basic tasks such as setting signals when turnouts are closed or thrown, to triggering complete automation sequences via a DCC accessory decoder.

Parameters:
 > linear - ???

ONDEACTIVATE( addr, sub_addr ) - Event handler for 2 part DCC accessory packet value 0

Event handler for 2 part DCC accessory packet value 0

All these “ON” commands are event handlers that trigger a sequence of commands to run when the event occurs. These can vary from the most basic tasks such as setting signals when turnouts are closed or thrown, to triggering complete automation sequences via a DCC accessory decoder.

Parameters:
 > addr - DCC address ???
 > Sub_addr - sub-address ???

ONDEACTIVATEL( linear ) - Event handler for linear DCC accessory packet value 0

Event handler for linear DCC accessory packet value 0.

Parameters:
 > linear - ???

ACTIVATE( addr, sub_addr ) - Sends a DCC accessory packet with value 1

Sends a DCC accessory packet with value 1.

Parameters:
 > addr - DCC address ???
 > Sub_addr - sub-address ???

ACTIVATEL( linear ) - Sends a DCC accessory packet with value 1 to a linear address

Sends a DCC accessory packet with value 1 to a linear address.

Parameters:
 > linear - ???

DEACTIVATE( addr, sub_addr ) - Sends a DCC accessory packet with value 0

Sends a DCC accessory packet with value 0.

Parameters:
 > addr - DCC address ???
 > Sub_addr - sub-address ???

DEACTIVATEL( addr ) - Sends a DCC accessory packet with value 0 to a linear address

Sends a DCC accessory packet with value 0 to a linear address

Parameters:
 > addr - DCC address ???

DCCACTIVATE( addr, sub_addr ) - TBA

Parameters:
 > addr - DCC address ???
 > Sub_addr - sub-address ???

XFON( cab, func )` - Send DCC function ON to specific cab

Send DCC function ON to specific cab (e.g. coach lights) Not for Loco use - use FON instead!

All these “ON” commands are event handlers that trigger a sequence of commands to run when the event occurs. These can vary from the most basic tasks such as setting signals when turnouts are closed or thrown, to triggering complete automation sequences via a DCC accessory decoder.

Parameters:
 > cab - DCC address of your loco
 > func - Function number (0-31)

XFOFF( cab, func ) - Send DCC function OFF to specific cab

Send DCC function OFF to specific cab (e.g. coach lights) Not for Loco use - use FON instead!

All these “ON” commands are event handlers that trigger a sequence of commands to run when the event occurs. These can vary from the most basic tasks such as setting signals when turnouts are closed or thrown, to triggering complete automation sequences via a DCC accessory decoder.

Parameters:
 > cab - DCC address of your loco
 > func - Function number (0-31)

XFTOGGLE( loco, func ) - Toggle DCC function on specific loco

New In Version 5.4

Toggle DCC function on loco with the specified DCC address.

Parameters:
 > loco - DCC address of your loco
 > func - Function number (0-31)

EX-FastClock Event Handlers

Also refer to Controlling EX-RAIL by Time.

ONTIME( value ) - Event handler for when the specified time is reached

Event handler for when the specified time is reached

Parameters:
 > value - value to test against

ONCLOCKTIME( hours, mins ) - Event handler for when the specified clock time is reached

Event handler for when the specified clock time is reached

Parameters:
 > hour - hour to test against
 > minute - minute to test against

ONCLOCKMINS( mins ) - Event handler to be repeated the same time every hour

Event handler to be repeated the same time every hour

Parameters:
 > minute - minute to test against

Locos and Tracks

Locos - Definition and Control

ESTOP - Emergency stops all locomotives

Emergency stops all locomotives.

Parameters:
 > none

SETLOCO( loco ) - Set the loco address for this task

Set the loco address for this sequence.

Parameters:
 > loco - DCC address of your loco

SENDLOCO( loco, route ) - Start route/sequence with a specified loco

Start a new task send a specified loco along a specified route/sequence

Parameters:
 > loco - DCC address of your loco
 > route - route to execute using the specified loco

READ_LOCO - Read loco ID from prog track

Read the loco ID from prog track.

Parameters:
 > none

FWD( speed ) - Drive loco forward at DCC speed

Drive loco forward at DCC speed 0-127 (1=ESTOP)

Parameters:
 > speed - DCC speed (0-127)
    - 2-127 = speed 1-126, 0 = stop
    - 1 = Estop

REV( speed ) - Drive loco in reverse at DCC speed

Drive current loco in reverse at DCC speed 0-127 (1=ESTOP)

Parameters:
 > speed - DCC speed (0-127)
    - 2-127 = speed 1-126, 0 = stop
    - 1 = Estop

SPEED( speed ) - Drive loco in current direction at DCC speed

Drive loco in current direction at DCC speed

Parameters:
 > speed - DCC speed (0-127)
    - 2-127 = speed 1-126, 0 = stop
    - 1 = Estop

STOP - Set loco speed to 0

Set the current loco speed to 0 (same as SPEED(0))

Parameters:
 > none

FON( func ) - Turn on loco function

Turn on the specified function for the current loco.

Parameters:
 > func - Function number (0-31)

FOFF( func ) - Turn off loco function

Turn off the specified function for the current loco.

Parameters:
 > func - Function number (0-31)

FTOGGLE( func ) - Toggle the state of a loco’s function

New In Version 5.4

Toggle off the specified function for the current loco. i.e. Turn off if on, or on if off.

Parameters:
 > func - Function number (0-31)

INVERT_DIRECTION - Switches FWD/REV meaning for loco

Switches FWD/REV meaning for the current loco.

Parameters:
 > none

ROSTER( loco, "name", "func_map" ) - Provide roster info for a specified loco

Parameters:
 > loco - DCC address of your loco > name - the name of this loco that will appear in the throttle apps. Enclosed in quotes (”)
 > funct_map - the names that you want to see for the functions specific to this loco separated by forward slashes (“/”). All enclosed in quotes (”)
    Note that if the function is ‘momentary’ rather than ‘latching’ (On/Off) then start the function label with a asterisk (*). The most common example of this is the Horn/Whistle which is commonly on F2.

Examples:
 ROSTER ( 3,”Eng 3”, “F0/F1/*F2/*F3/F4/F5/F6/F7/Mute/F9//”) // Address 3, Eng 3, Function keys F0-F10
 ROSTER(1224,”PE 1224”,””) // Motor Only Decoder
 ROSTER(1225,”PE 1225”,”Lights/Bell/*Whistle/*Short Whistle/Steam/On-Time/FX6 Bell Whistle/Dim Light/Mute”)
 ROSTER(4468,”LNER 4468”,”//Snd On/*Whistle/*Whistle2/Brake/F5 Drain/Coal Shvl/Guard-Squeal/Loaded/Coastng/Injector/Shunt-Door ~Opn-Cls/Couplng/BrakeVlv/Sfty Vlv/Shunting/BrkSql Off/No Momentm/Aux3/Fade Out/F22 Res/F23/Res//Aux 5/Aux6/Aux7/Aux 8”)

POM( cv, value ) - Program CV value on main

Program CV value on main, must be proceeded by setting the loco ID with SETLOCO( loco )

IFLOCO( loco ) - perform commands if the specified loco ID is defined for this sequence

If the specified loco ID is defined for this sequence, perform the defined activities

Parameters:
 > loco - DCC Address of the loco to test against

For example: (click to show)
// A defined automation sequence that will do activities only if loco ID 123 is in use
AUTOSTART AUTOMATION(1, "Do stuff for loco 123")
  IFLOCO(123)
    // Define activities here e.g. blow horn or whistle
  ENDIF
  DONE

FORGET - Forget the loco in the running automation/sequence

Forget the loco in the running automation/sequence

Parameters:
 > none

TrackManager Control

SET_TRACK( track, mode ) - Configures the mode of a track

Configures the mode of the selected track, refer also to TrackManager (DCC & DC)

Parameters:
 > track - - The track to configure, valid options are A to H
 > mode - - The mode to set the track to,
    valid options for DCC are:
    - MAIN or
    - PROG,
    and valid options for DC are:
    - DC
    - , DCX.
    If a track is unused, it can be set to:
    - NONE

When setting at track mode to either DC or DCX, you must use the SETLOCO( loco ) command first to specify the loco ID that will be used for the DC track then SET_TRACK()

For example: (click to show)
// Set both tracks A and B to be main DCC tracks
AUTOSTART
SET_TRACK(A, MAIN)
SET_TRACK(B, MAIN)
DONE

// Set track A to be a DC track with loco ID 1, and track B to be a DCC programming track
AUTOSTART
SETLOCO(1) SET_TRACK(A, DC)
SET_TRACK(B, PROG)
DONE

SET_POWER( track, ON/OFF ) - Enable/Disable power on a track

Configures the power setting of the selected track, refer also to TrackManager (DCC & DC)

Parameters:

 > track - - The track to configure, valid options are A to H
 > ON/OFF - - Turn the power ON or OFF for this track

For example: (click to show)
// Set track A to be a DC track with loco ID 1 and power on, and track B to be a DCC programming track
AUTOSTART
SETLOCO(1) SET_TRACK(A, DC)
SET_TRACK(B, PROG)
SET_POWER(A, ON)
DONE

SETFREQ( track, frequency ) - Enable a specific frequency

DC/DCX track settings only.

Configures the frequency setting of the selected track.

The settings achievable vary slightly depending upon the processor running the CS but broadly follow the following:

Parameters:
 > track - - The track to configure, valid options are A to H
 > frequency - - The frequency to set for this track
   >valid options are:
    > 0 - Default - low frequency 131Hz
    > 1 - Mid frequency - 490Hz
    > 2 - High frequency - 3400Hz
    > 3 - Supersonic - 62500Hz|BR|

Trial and error will be needed for specific locos that do not respond well to the defaults (low) frequency setting.

Controlling Overload/Shorts

ONOVERLOAD( track ) - Event handler for when an Overload occurs

Creates an event handler for the selected track, to be executed when the MotorDriver routines detect and overload. Refer also to TrackManager (DCC & DC)

Parameters:
 > track - - The track to configure, valid options are A to H

AFTEROVERLOAD( track ) - Event handler for when an Overload clears

Creates a complementary event handler for the selected track, to be executed when the MotorDriver routines indicate the overload is cleared. Refer also to TrackManager (DCC & DC)

Note: AFTEROVERLOAD is only relevant when used within and ONOVERLOAD…. DONE structure.

Parameters:
 > track - - The track to configure, valid options are A to H

The power calculation routines within DCC-EX will check for shorts and overloads and will change the state of the power produced by the MotorDriver board to protect both it and locos from damage. This is usually eveident by the LED’s on the MotorDriver board flashing. However some users may wish to see some physical notifcation of these events. This can now be achieved with EXRAIL and the ONOVERLOAD event.

For example: (click to show)

This first example shows a warning message to an attached screen with an LED being illuminated to warn the user of the overload. Once the overload is cleared the AFTEROVERLOAD code is run automatically.

ONOVERLOAD(A)       // the EXRAIL statement to control the event.
  SCREEN(2,0, "OVERLOAD ON TRACK A")     // A message to the second screen
  PRINT("Overload Detected on Track A")   // Message to system moniter
  SET(27)                                 // Turn on an LED perhaps
  AFTEROVERLOAD(A)
      SCREEN(2,0, "RESTORE A POWER ON")
      PRINT("Overload Cleared on A - Power Restored")
      RESET(27)                           // Turn off the LED
      DELAY(2000)
      SCREEN(2,0, "                  ")   // Clear the screen message
DONE

If the user wishes to turn off power whilst he/she investigates the problem, then this can be achieved using the second example below. POWEROFF can be used, but this will turn off powere to all tracks. Power to the track with the problem can be turned off with a TrackManager command. However in order to execute the AFTEROVERLOAD routine it is necessary to have a reset routine.

// This is the event triggered by an overload.  AFTEROVERLOAD cannot be triggered whilst power is OFF.
ONOVERLOAD(A)
  SCREEN(2,0, "OVERLOAD A POWEROFF")
  PRINT("Overload Detected on A - Turn Off Power")
  SET_TRACK(A, NONE)   // Unsets the TrackManager assignment and turns off power.
  SET(27)              // Light the LED
  AFTEROVERLOAD(A)
      SCREEN(2,0, "RESTORE A POWER ON")
      PRINT("Overload Cleared on A - Power Restored")
      RESET(27)
      DELAY(2000)
      SCREEN(2,0, "                  ")
DONE

// The following turns the poweron and allows the AFTEROVERLOAD to run
// This could also be achieved with a physical button and AFTER(pin) in place of ROUTE()
ROUTE(12,"Reset A")
  SCREEN(2,0,"                  ")
  SET_TRACK(A, MAIN)
  POWERON
DONE

Virtual Block Control

RESERVE( block_id ) - Reserve a block

Reserve a block (0-255). If already reserved, current loco will STOP and sequence waits for block to become free

Parameters:
 > block_id - Block to reserve (0-255)

FREE( block_id ) - Free block

Free previously reserved block.

Parameters:
 > block_id - Block to free (0-255)

IFRESERVE( block ) - Execut commnads if block is NOT reserved

If block is NOT reserved, reserves it and run commands in IF block. Otherwise, skip to matching ENDIF

Parameters:
 > block_id - Block to test (0-255)

System

Communication and Display Functions

LCD( row, "msg" ) - Write message on LCD/OLED

Write message on LCD/OLED, if fitted.

Parameters:
 > row - row of the LED/OLD to write the message
 > msg - message to write

SCREEN( display, row, "msg" ) - Writes a message to a display

Writes a message to the specified display on the specified row.

Parameters:
 > display - which display to write to ???
 > row - row of the LED/OLD to write the message
 > msg - message to write

BROADCAST( "msg" ) - Broadcast to all throttles/JMRI on serial and WiFi

Broadcast to all throttles/JMRI on serial and WiFi

Parameters:
 > msg - message to broadcast

SERIAL( "msg" ) - Writes direct to Serial

Writes direct to Serial (Serial0/USB)

Parameters:
 > msg - message to write

SERIAL1( "msg" ) - Writes direct to Serial1

Writes direct to Serial1.

Parameters:
 > msg - message to write

SERIAL2( "msg" ) - Writes direct to Serial2

Writes direct to Serial2.

Parameters:
 > msg - message to write

SERIAL3( "msg" ) - Writes direct to Serial3

Writes direct to Serial3.

Parameters:
 > msg - message to write

SERIAL4( "msg" ) - Writes direct to Serial4

Writes direct to Serial4.

Parameters:
 > msg - message to write

SERIAL5( "msg" ) - Writes direct to Serial5

Writes direct to Serial5.

Parameters:
 > msg - message to write

SERIAL6( "msg" ) - Writes direct to Serial6

Writes direct to Serial6.

Parameters:
 > msg - message to write

WITHROTTLE( "msg" ) - Writes a message to WiThrottle clients

Writes a message to WiThrottle clients (alias of PRINT)

A a WiThrottle throttle will receive Hmtext.

Parameters:
 > msg - message to write

MESSAGE( "msg" ) - Writes a message to all clients

New In Version 5.4

Writes a message to all serial throttles and all WiThrottle Clients.

A DCC-EX throttle will receive a broadcast <m "text">, and a WiThrottle throttle will receive Hmtext.

Parameters:
 > msg - message to write

CommandStation Functions

POWERON - Power on track and UNJOIN

Turn the track power on and UNJOIN if currently joined.

Parameters:
 > none

POWEROFF - Power off track

Turn the track power off.

Parameters:
 > none

JOIN - Join PROG and MAIN track outputs

Join PROG and MAIN track outputs to send the same MAIN DCC signal.

Parameters:
 > none

UNJOIN - Disconnect prog track from main

Disconnect PROG output from MAIN output.

Parameters:
 > none

ENDEXRAIL - TBA

Parameters:
 > none

KILLALL - Kills all running EX‑RAIL activities

Kills all running EX‑RAIL activities

Parameters:
 > none

PARSE( "msg" ) - Allows parsing of a DCC-EX API command via myAutomation.h

Allows parsing of a DCC-EX API command via myAutomation.h. This allows you to include Native DCC-EX Cammands in myAutomation.h where there is no equivalent EXRAIL command.

Parameters:
 > msg - message to parse

DISABLE_PROG - Disable programming to save RAM/Flash

Disable programming to save RAM/Flash.

Parameters:
 > none

IO_NO_HAL - Reduce FLASH footprint when HAL features not required

To reduce FLASH footprint when HAL features not required.

Note: The HAL is disabled by default on Nano and Uno platforms, because of limited flash space.

Parameters:
 > none

Layout Command Control (LCC)

The following commands have been introduced to support Layout Command Control (LCC) / CBUS.

ONLCC(sender, eventid) - TBA

Todo

LOW - EXRAIL doco - ONLCC

Parameters:
 > sender - TBA
 > eventid - TBA

LCC(eventid) - TBA

Todo

LOW - EXRAIL doco - LCC

Parameters:
 > eventid - TBA

LCCX(senderid,eventid) - TBA

Todo

LOW - EXRAIL doco - LCCX

Parameters:
 > senderid - TBA
 > eventid - TBA

ACON(eventid) - TBA

Todo

LOW - EXRAIL doco - ACON

Parameters:
 > eventid - TBA

ACOF(eventid) - TBA

Todo

LOW - EXRAIL doco - ACOF

Parameters:
 > eventid - TBA

ONACON(eventid) - TBA

Todo

LOW - EXRAIL doco - OACON

Parameters:
 > eventid - TBA

ONACOF(eventid) - TBA

Todo

LOW - EXRAIL doco - ONACOF

Parameters:
 > eventid - TBA

Advanced (Engineers only)

Caution required!

Any commands in this section are intended for Engineer Hat level users that have advanced knowledge of how EX‑RAIL works, and likely some understanding of C++ coding as well.

If you are unsure on the impacts using anything in this section may have, please reach out to the DCC-EX team via the methods listed on our Contact Us page.

STEALTH( code ) - include some C++ code in a ROUTE/SEQUENCE

New In Version 5.4

SERIOUS ENGINEERS and ADVANCED C++ USERS ONLY Engineer Hat

Permits a certain level of C++ code to be embedded as a single step in an EXRAIL sequence.

Please use this option with great care. If in doubt ask for assistance.

Syntax:

STEALTH( .. C++ code ..)

For example: (click to show)
// run a routine to free any LATCHES that are left on.
SEQUENCE(999)
      STEALTH(  //RESET ANY LATCHES WE TURNED ON
      for (int i = 1; i <= 255; i++) {
        if (getFlag(i,LATCH_FLAG)) {    //IF LATCH ON
        setFlag(i,0,LATCH_FLAG);      //RESET LATCH
          }
        }
      )
RETURN

then
CALL(999) inside your onthrow/onclose sections.

STEALTH_GLOBAL( code )

New In Version 5.4

SERIOUS ENGINEERS and ADVANCED C++ USERS ONLY Engineer Hat

Inserts code such as static variables and functions that may be utilised by multiple STEALTH operations.

Please use this option with great care, and you will need to be an advanced C++ user to make use of this command. If in doubt ask for assistance.