EXRAIL Language documentation

Introduction

EXRAIL - Extended Railroad Automation Instruction Language

This page is a reference to all EXRAIL commands available with EX-CommandStation.

Macros

Defines

ACTIVATE(addr, subaddr)

Send DCC Accessory Activate packet (gate on then off)

Parameters:

  • addr – DCC short address of accessory

  • subaddr – DCC sub address

ACTIVATEL(linearaddr)

Send DCC Accessory Activate packet (gate on then off)

Parameters:

  • linearaddr – DCC linear address of accessory

AFTER(vpin, timer...)

Wait for sensor activated, then decativated for given time.

Parameters:

  • vpin – Virtual Pin number of sensor

  • timer... – optional wait in mS, default 500

AFTEROVERLOAD(track_id)

Wait for overload to be resolved.

Parameters:

  • track_id – A..H

ALIAS(name, value...)

defines a named numeric value.

Parameters:

  • name – c++ variable name that can be used throighout the script

  • value... – if omitted, a large negative value is created automatically

AMBER(signal_id)

Sets a signal to amber state.

See also

ONAMBER

Parameters:

  • signal_id

ANOUT(vpin, value, param1, param2)

Writes to the HAL analog output interface of a device driver. Values and meanings of extra parameters depend on driver.

Parameters:

  • vpin – Virtual pin number of device

  • value – basic analog value

  • param1 – device dependent

  • param2 – device dependent

AT(vpin)

wait intil a sensor becomes active

Parameters:

  • vpin – Virtual pin of sensor. Use negative value for sensors that are HIGH when activated

ASPECT(address, value)

Sends a DCC aspect value to an accessory address. May also change status of a signal defined using this aspect.

Parameters:

  • address – Linear DCC address of device

  • value – Aspect value (Device dependent)

ATGTE(vpin, value)

Wait for analog sensor to be greater than given value.

Parameters:

  • vpin – Analog pin number

  • value – integer value to compare against

ATLT(vpin, value)

Wait for analog sensor value to be less than given value.

Parameters:

  • vpin – Analog pin number

  • value – integer value to compare against

ATTIMEOUT(vpin, timeout_ms)

Wait for sensor active, with timeout. Use IFTIMEOUT to determine whether the AT was satisfied.

See also

IFTIMEOUT

Parameters:

  • vpin – Sensor pin number

  • timeout_ms – Millseconds to wait before timeout

AUTOMATION(sequence_id, description)

Defines starting point of a sequence that will be shown as an Automation by the throttles. Automations are started by the throttle handing over a loco id to be driven.

Parameters:

  • sequence_id – Unique sequence id value

  • description – (Quoted text) will be shown on throttle button

AUTOSTART

A new task will be created starting from this point at Command Station startup

Starts a blinking process for a vpin (typically a LED) Stop blink with SET or RESET.

Parameters:

  • vpin – Pin to blink

  • onDuty – Milliseconds with LED ON

  • offDuty – Milliseconds with LED off

BROADCAST(msg)

Send raw message text to all throttles using the DCC-EX protocol.

See also

WITHROTTLE

Parameters:

  • msg – Quoted message

CALL(sequence_id)

transfer control to another sequence with expectation to return

See also

RETURN

Parameters:

  • sequence_id – SEQUENCE to jump processing to, must terminate or RETURN

CLEAR_STASH(stash_id)

Clears loco value stored in stash

Parameters:

  • stash_id – which stash to clear.

CLEAR_ALL_STASH

Clears all stashed loco values.

CLOSE(turnout_id)

Close turnout by id.

See also

THROW

Parameters:

  • turnout_id

CONFIGURE_SERVO(vpin, pos1, pos2, profile)

setup servo movement parameters for non-turnout

Parameters:

  • vpin – must refer to a servo capable pin

  • pos1 – SET position of servo

  • pos2 – RESET position of servo

  • profile – Movement profile (Instant, Fast, Medium, Slow, Bounce)

DCC_SIGNAL(signal_id, addr, subaddr)

Define a DCC accessory signal with short address.

Parameters:

  • signal_id – Id used for all signal manipulation commands

  • addr – DCC address

  • subaddr – DCC subaddress

DCCX_SIGNAL(signal_id, redAspect, amberAspect, greenAspect)

Dfeine advanced DCC accessory signal with aspects.

Parameters:

  • signal_id – DCC Linear address AND Id used for all signal manipulation commands

  • redAspect

  • amberAspect

  • greenAspect

DCC_TURNTABLE(turntable_id, home, description...)

defines a Turntable device

Parameters:

  • turntable_id

  • homeAngle – the angle of the home position, valid angles are 0 - 3600

  • description... – Quoted text description of turntable

DEACTIVATE(addr, subaddr)

Sends DCC Deactivate packet (gate on, gate off)

Parameters:

  • addr – DCC accessory address

  • subaddr – DCC accessory subaddress

DEACTIVATEL(addr)

Sends DCC Deactivate packet (gate on, gate off)

Parameters:

  • addr – DCC Linear accessory address

DELAY(delay_ms)

Waits for given milliseconds delay (This is not blocking)

Parameters:

  • delay_mS – Delay time in milliseconds

DELAYMINS(delay_minutes)

Waits for given minutes delay (This is not blocking)

Parameters:

  • delay_minutes

DELAYRANDOM(mindelay, maxdelay)

Waits for random delay between min and max milliseconds (This is not blocking)

Parameters:

  • mindelay – minumum delay in mS

  • maxdelay – maximum delay in mS

DONE

Stops task loco (if any) and terminates current task.

DRIVE(analogpin)

RESERVED do not use.

Parameters:

  • analogpin

ELSE

introduces alternate processing path after any kind of IF

See also

IF

ENDIF

determines end of IF(any type) block.

See also

IF IF something ENDIF, or IF something ELSE something ENDIF

ENDTASK

same as DONE

See also

DONE

ESTOP

Performs emergency stop on current task loco.

EXTT_TURNTABLE(id, vpin, home, description...)

This statement will create the EX‑Turntable turntable/traverser object only, so you will need a separate HAL() statement for an EX‑Turntable device driver.

Parameters:

  • turntable_id

  • vpin

  • homeAngle – the angle of the home position, valid angles are 0 - 3600

  • description...

FADE(vpin, value, ms)

Modifies analog value slowly taking a given time.

Parameters:

  • vpin – Servo virtual pin number

  • value – new target value

  • ms – time to reach value

FOFF(func)

Turns off current loco function.

See also

FON

Parameters:

  • func

FOLLOW(sequence_id)

Task processing follows given route or sequence (Effectively a GoTo)

Parameters:

  • sequence_id

FON(func)

Turn on current loco function.

See also

FOFF

Parameters:

  • func

FORGET

Removes current loco from task and DCC reminders table.

FREE(token_id)

Frees logical token.

See also

RESERVE

Parameters:

  • token_id – 0..255

FTOGGLE(func)

Toggles function for current loco.

Parameters:

  • func

FWD(speed)

Instructs current loco to set DCC speed.

Parameters:

  • speed – 0..127 (1=ESTOP)

GREEN(signal_id)

Sets signal to green state.

Parameters:

  • signal_id

HAL(haltype, params...)

Defines VPIN mapping for specific hardware drivers.

Parameters:

  • haltype – driver name, normally device type

  • params... – depend on driver.

HAL_IGNORE_DEFAULTS

System will ignore default HAL device mappings.

IF(vpin)

Checks sensor state, If false jumps to matching nested ELSE or ENDIF.

Parameters:

  • vpin – VPIN of sensor. Negative VPIN will invert sensor state.

IFAMBER(signal_id)

Checks if signal is in AMBER state.

See also

IF

Parameters:

  • signal_id

IFCLOSED(turnout_id)

Checks if given turnout is in close state.

See also

IF

Parameters:

  • turnout_id

IFGREEN(signal_id)

Checks if given signal is in GREEN state.

See also

IF

Parameters:

  • signal_id

IFGTE(vpin, value)

Checks if analog vpin sensor >= value.

See also

IF

Parameters:

  • vpin

  • value

IFLOCO(loco_id)

Checks if current task loco = loco_id.

See also

IF

Parameters:

  • loco_id

IFLT(vpin, value)

Checks if analog sensor < value.

See also

IF

Parameters:

  • vpin – Analog vpin of sensor

  • value

IFNOT(vpin)

Inverse of IF.

See also

IF

Parameters:

  • vpin

IFRANDOM(percent)

randomly satisfield IF at given percent probability

See also

IF

Parameters:

  • percent

IFRED(signal_id)

Checks if given signal is in RED state.

See also

IF

Parameters:

  • signal_id

IFTHROWN(turnout_id)

Checks if given turnout is in THROWN state.

See also

IF

Parameters:

  • turnout_id

IFRESERVE(token_id)

Attempts to reserve token and if satisfiled the token remains reserved.

See also

IF RESERVE FREE

Parameters:

  • token_id

IFTIMEOUT

Checks TIMEOUT state after an AT/AFTER request with timeout value.

See also

IF AT AFTER

IFTTPOSITION(turntable_id, position)

Checks if Turntable is in given position.

See also

IF

Parameters:

  • turntable_id

  • position

IFRE(vpin, value)

Checks external rotary encoder value.

Parameters:

  • vpin – of device driver for rotary encoder

  • value

INVERT_DIRECTION

Marks current task so that FWD and REV commands are inverted.

JMRI_SENSOR(vpin, count...)

Defines multiple JMRI

Parameters:

  • vpin – first vpin number

  • count... – Number of consecutine VPINS for which to create JMRI sensor feedbacks. Default 1.

JOIN

Switches PROG track to receive MAIN track DCC packets. (Drive on PROG track)

KILLALL

Tertminates all running EXRAIL tasks.

LATCH(vpin)

Make all AT/AFTER/IF see vpin as HIGH without checking hardware.

Parameters:

  • vpin – Must only be for VPINS 0..255

LCC(eventid)

Issue event to LCC.

Parameters:

  • eventid

LCCX(senderid, eventid)

Issue LCC event while impersonating another sender.

Parameters:

  • senderid

  • eventid

LCD(row, msg)

Write message on row of default configured LCD/OLED.

See also

SCREEN

Parameters:

  • row

  • msg – Quoted text

SCREEN(display, row, msg)

Send message to external display hadlers.

Parameters:

  • display – number, 0=local display, others are handled by external displays which may have different display numbers on different devices.

  • row

  • msg – Quoted text

LCN(msg)

Reserved for LCN communication. Refer to their documentation.

Parameters:

  • msg

MESSAGE(msg)

Send a human readable message to all throttle users.

Parameters:

  • msg – Quoted text

MOVETT(turntable_id, steps, activity)

Move Turntable to specific position.

See also

ROTATE

Parameters:

  • turntable_id

  • steps – position to move to

  • activity – see ROTATE

NEOPIXEL(vpin, r, g, b, count...)

Set a NEOPIXEL vpin to a given red/green/blue colour.

Parameters:

  • vpin – VPIN of a pixel

  • r – red component 0-255

  • g – green component 0-255

  • b – blue component 0-255

  • count... – Number of consecutive pixels to set, Default 1.

NEOPIXEL_SIGNAL(vpin, redcolour, ambercolour, greencolour)

Define a signal that uses a single multi colour pixel.

See also

NEORGB

Parameters:

  • vpin – unique signal_id

  • redcolour – RGB colour use NEORGB(red,green,blue) to create values.

  • ambercolour

  • greencolour

ACON(eventid)

Send MERG CBUS ACON to Adapter.

Parameters:

  • eventid

ACOF(eventid)

Send MERG CBUS ACOF to Adapter.

Parameters:

  • eventid

ONACON(eventid)

Start task here when ACON for event receied from MERG CBUS.

Parameters:

  • eventid

ONACOF(eventid)

Start task here when ACOF for event receied from MERG CBUS.

Parameters:

  • eventid

ONACTIVATE(addr, subaddr)

Start task here when DCC Activate sent for short address.

Parameters:

  • addr

  • subaddr

ONACTIVATEL(linear)

Start task here when DCC Activate sent for linear address.

Parameters:

  • linear

ONAMBER(signal_id)

Start task here when signal set to AMBER state.

Parameters:

  • signal_id

ONTIME(minute_in_day)

Start task here when fastclock matches.

Parameters:

  • minute_in_day – (0..1439)

ONCLOCKTIME(hours, mins)

Start task here when fastclock matches time.

Parameters:

  • hours

  • mins

ONCLOCKMINS(mins)

Start task here hourly when fastclock minutes matches.

Parameters:

  • mins

ONOVERLOAD(track_id)

Start task here when given track goes into overload.

Parameters:

  • track_id – A..H

ONDEACTIVATE(addr, subaddr)

Start task here when DCC deactivate packet sent.

Parameters:

  • addr

  • subaddr

ONDEACTIVATEL(linear)

Start task here when DCC deactivate sent to linear address.

Parameters:

  • linear

ONCLOSE(turnout_id)

Start task here when turnout closed.

Parameters:

  • turnout_id

ONLCC(sender, event)

Start task here when LCC event arrives from sender.

Parameters:

  • sender

  • event

ONGREEN(signal_id)

Start task here when signal set to GREEN state.

Parameters:

  • signal_id

ONRED(signal_id)

Start task here when signal set to RED state.

Parameters:

  • signal_id

ONROTATE(turntable_id)

Start task here when turntable is rotated.

Parameters:

  • turntable_id

ONTHROW(turnout_id)

Start task here when turnout is Thrown.

Parameters:

  • turnout_id

ONCHANGE(vpin)

Toratry encoder change starts task here (This is obscurely different from ONSENSOR which will be merged in a later release.)

Parameters:

  • vpin

ONSENSOR(vpin)

Start task here when sensor changes state (debounced)

Parameters:

  • vpin

ONBUTTON(vpin)

Start task here when sensor changes HIGH to LOW.

Parameters:

  • vpin

PAUSE

Pauses all EXRAIL tasks except the curremnt one. Other tasks ESTOP their locos until RESUME issued.

PIN_TURNOUT(id, vpin, description...)

Defines a turnout which operates on a signle pin.

Parameters:

  • turnout_id

  • vpin

  • description... – Quoted text (shown to throttles) or HIDDEN

PRINT(msg)

prints diagnostic message on USB serial

Parameters:

  • msg – Quoted text

PARSE(msg)

Executes <> command as if entered from serial.

Parameters:

  • msg – Quoted text, preferably including <>

PICKUP_STASH(stash_id)

Loads stashed value into current task loco.

See also

STASH

Parameters:

  • stash_id – position in stash where a loco id was previously saved.

POM(cv, value)

Write value to cv on current tasks loco (Program on Main)

Parameters:

  • cv

  • value

POWEROFF

Powers off all tracks.

POWERON

Powers ON all tracks.

READ_LOCO

Reads loco Id from prog track and sets currenmt task loco id.

RED(signal_id)

sets signal to RED state

Parameters:

  • signal_id

RESERVE(token_id)

Waits for token for block. If not available immediately, current task loco is stopped.

Parameters:

  • token_id

RESET(vpin, count...)

Sets output pin LOW.

See also

SET

Parameters:

  • vpin

  • count... – Number of consecutive pins, default 1

RESUME

Resumes PAUSEd tasks.

See also

PAUSE

RETURN

Returns to CALL.

See also

CALL

REV(speed)

Issues DCC speed packet for current loco in reverse.

See also

FWD

Parameters:

  • speed – (0..127, 1=ESTOP)

ROTATE(turntable_id, position, activity)

Rotates a turntavble top a given position.

Parameters:

  • turntable_id

  • position_id

  • activity –

    • Turn: Rotate turntable, maintain phase

    • Turn_PInvert: Rotate turntable, invert phase

    • Home: Initiate homing

    • Calibrate: Initiate calibration sequence

    • LED_On: Turn LED on

    • LED_Slow: Set LED to a slow blink

    • LED_Fast: Set LED to a fast blink

    • LED_Off: Turn LED off

    • Acc_On: Turn accessory pin on

    • Acc_Off: Turn accessory pin off

ROTATE_DCC(turntable_id, position_id)

Rotates turntable to given position using DCC commands.

Parameters:

  • turntable_id

  • position_id

ROSTER(cab, name, funcmap...)

Describes a loco roster entry visible to throttles.

Parameters:

  • cab – loco DCC address or 0 for default entry

  • name – Quoted text

  • funcmap... – Quoted text, optional list of function names separated by / character with momentary function names prefixed with an *.

ROUTE(sequence_id, description)

DEfines starting point of a sequence that will appear as a route on throttle buttons.

Parameters:

  • sequence_id

  • description – Quoted text, throttle button capotion.

ROUTE_ACTIVE(sequence_id)

Tells throttle to display the route button as active.

Parameters:

  • sequence_id – of ROUTE/AUTOMATION

ROUTE_INACTIVE(sequence_id)

Tells throttle to display the route button as inactive.

Parameters:

  • sequence_id – of ROUTE/AUTOMATION

ROUTE_HIDDEN(sequence_id)

Tells throttle to hide the route button.

Parameters:

  • sequence_id – of ROUTE/AUTOMATION

ROUTE_DISABLED(sequence_id)

Tells throttle to display the route button as disabled.

Parameters:

  • sequence_id – of ROUTE/AUTOMATION

ROUTE_CAPTION(sequence_id, caption)

Tells throttle to change thr route button caption.

Parameters:

  • sequence_id – of ROUTE/AUTOMATION

  • caption

SENDLOCO(cab, sequence_id)

Start a new task to drive the loco.

Parameters:

  • cab – loco to be driven

  • route – sequence_id of route, automation or sequence to drive

SEQUENCE(sequence_id)

Provides a unique label than can be used to call, follow or start.

See also

CALL

See also

FOLLOW

See also

START

Parameters:

  • sequence_id

SERIAL(msg)

Write direct to Serial output.

Parameters:

  • msg – Quoted text

SERIAL1(msg)

Write direct to Serial1 output.

Parameters:

  • msg – Quoted text

SERIAL2(msg)

Write direct to Serial2 output.

Parameters:

  • msg – Quoted text

SERIAL3(msg)

Write direct to Serial3 output.

Parameters:

  • msg – Quoted text

SERIAL4(msg)

Write direct to Serial4 output.

Parameters:

  • msg – Quoted text

SERIAL5(msg)

Write direct to Serial5 output.

Parameters:

  • msg – Quoted text

SERIAL6(msg)

Write direct to Serial6 output.

Parameters:

  • msg – Quoted text

SERVO(vpin, position, profile)

Move servo to given position.

Parameters:

  • vpin – of servo

  • position – servo position (values are hardware dependent)

  • profile – movement profile (Instant, Fast, Medium, Slow, Bounce)

SERVO2(vpin, position, duration)

Move servo to given position taking time.

Parameters:

  • vpin – of servo

  • position – servo position (values are hardware dependent)

  • duration – mS

SERVO_SIGNAL(vpin, redpos, amberpos, greenpos)

Dedfine a servo based signal with 3 servo positions.

Parameters:

  • vpin – of servo, acts as signal_id

  • redpos – servo position (values are hardware dependent)

  • amberpos – servo position (values are hardware dependent)

  • greenpos – servo position (values are hardware dependent)

SERVO_TURNOUT(turnout_id, vpin, activeAngle, inactiveAngle, profile, description...)

Define a servo driven turnout.

Parameters:

  • turnout_id – used by THROW/CLOSE

  • vpin – for servo

  • activeAngle – servo position (values are hardware dependent)

  • inactiveAngle – servo position (values are hardware dependent)

  • profile – movement profile (Instant, Fast, Medium, Slow, Bounce)

  • description... – Quoted text shown to throttles or HIDDEN keyword to hide turnout button

SET(vpin, count...)

Set pin HIGH.

See also

RESET

Parameters:

  • vpin

  • count... – Number of sequential vpins to set. Default 1.

SET_TRACK(track, mode)

Set output track type.

Parameters:

  • track – A..H

  • mode – NONE, MAIN, PROG, DC, EXT, BOOST, BOOST_INV, BOOST_AUTO, MAIN_INV, MAIN_AUTO, DC_INV, DCX

SET_POWER(track, onoff)

Set track power mode.

Parameters:

  • track – A..H

  • onoff – ON or OFF

SETLOCO(loco)

Sets the loco being handled by the current task.

Parameters:

  • loco

SETFREQ(freq)

Sets the DC track PWM frequency.

Parameters:

  • freq – Frequency is default 0, or 1..3

SIGNAL(redpin, amberpin, greenpin)

Define a Signal with LOW=on leds.

See also

SIGNALH

Parameters:

  • redpin – vpin for RED state, also acts as signal_id

  • amberpin

  • greenpin

SIGNALH(redpin, amberpin, greenpin)

define a signal with HIGH=ON leds

Parameters:

  • redpin – vpin for RED state, also acts as signal_id

  • amberpin

  • greenpin

SPEED(speed)

Changes current tasks loco speed without changing direction.

Parameters:

  • speed – 0..127 (1=ESTOP)

START(sequence_id)

Starts a new task at the given route/animation/sequence.

Parameters:

  • sequence_id

STASH(stash_id)

saves cuttent tasks loco id in the stash array

Parameters:

  • stash_id – position in stash array to save loco id

STEALTH(code...)

Allows for embedding raw C++ code in context of current task.

Parameters:

  • code... – c++ code to be executed. This requires intimate understanding of the product acrhitecture.

STEALTH_GLOBAL(code...)

Allows for embedding raw c++ code out of context.

Parameters:

  • code... – c++ code to be defined. This requires intimate understanding of the product acrhitecture.

STOP

Same as SPEED(0)

See also

SPEED

THROW(turnout_id)

Throws given turnout.

See also

CLOSE

Parameters:

  • turnout_id

TOGGLE_TURNOUT(turnout_id)

Toggles given turnout.

Parameters:

  • tuirnout_id

TT_ADDPOSITION(turntable_id, position_id, value, angle, description...)

Defines a turntable track position.

Parameters:

  • turntable_id

  • position_id – each position is given an id

  • address – DCC accessory address

  • angle – Used only for throttles that may draw a visual representation of the turntable

  • description... – quoted text or HIDDEN

TURNOUT(turnout_id, addr, subaddr, description...)

Defines a DCC accessory turnout with legacy address.

Parameters:

  • turnout_id – to be used in THROW/CLOSE etc

  • addr – DCC accessory address

  • subaddr – DCC accessory subaddress

  • description... – Quoted text or HIDDEN, appears on throttle buttons

TURNOUTL(tirnout_id, addr, description...)

Defines a DCC accessory turnout with inear address.

See also

TURNOUT

Parameters:

  • turnout_id – to be used in THROW/CLOSE etc

  • addr – DCC accessory linear address

  • description... – Quoted text or HIDDEN, appears on throttle buttons

UNJOIN

Disconnects PROG track from MAIN.

See also

JOIN

UNLATCH(vpin)

removes latched on flag

See also

LATCH

Parameters:

  • vpin – (limited to 0..255)

VIRTUAL_SIGNAL(signal_id)

Defines a virtual (no hardware) signal, use ONhandlers to simulate hardware.

See also

SIGNAL ONRED ONAMBER ONGREEN

Parameters:

  • signal_id

VIRTUAL_TURNOUT(id, description...)

Defines a virtual (no hardware) turnout, use ONhandlers to simulate hardware.

See also

TURNOUT ONCLOSE ONTHROW

Parameters:

  • turnout_id

  • description... – quoted text or HIDDEN

WAITFOR(pin)

WAits for completion of servo movement.

Parameters:

  • vpin

WAITFORTT(turntable_id)

waits for completion of turntable movement

Parameters:

  • turntable_id

WITHROTTLE(msg)

Broadcasts a string in Withrottle protocol format to all throttles using this protocol.

Parameters:

  • msg – quoted string

XFOFF(cab, func)

Turns function off for given loco.

Parameters:

  • cab

  • func – function number

XFON(cab, func)

Turns function ON for given loco.

Parameters:

  • cab

  • func

XFTOGGLE(cab, func)

Toggles function state for given loco.

Parameters:

  • cab

  • func

XFWD(cab, speed)

Sends DCC speed to loco in forward direction.

Parameters:

  • cab

  • speed – (0..127, 1=ESTOP)

XREV(cab, speed)

Sends DCC speed to loco in reverse direction.

Parameters:

  • cab

  • speed – (0..127, 1=ESTOP)