# EXRAIL Language documentation — EXRAIL Language documentation

# 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

BLINK(vpin, onDuty, offDuty)

  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(tuirntable_id, home, description...)

  defines a Turntable device

  Parameters:

    - turntable_id – ??? TODO ???

    - home – ??? TODO ???

    - description... – Quotyed 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...)

  ??????????????????????

  Parameters:

    - id

    - vpin

    - home

    - 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(sensor_id, value)

  ????????????????????????????????????????

  Parameters:

    - sensor_id

    - 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(id, steps, activity)

  ???????????????????

  Parameters:

    - id

    - steps

    - activity

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(sensor_id)

  ??? something strange in RotaryEncoder HAL…

  Parameters:

    - vpin

ONSENSOR(sensor_id)

  Start task here when sensor changes state (debounced)

  Parameters:

    - sensor_id

ONBUTTON(sensor_id)

  Start task here when sensor changes HIGH to LOW.

  Parameters:

    - sensor_id

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:

    - id

    - pin

    - 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(id)

  Loads stashed value into current task loco.

  Parameters:

    - 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)

  ????

  Parameters:

    - turntable_id

    - position

    - activity

ROTATE_DCC(turntable_id, position)

  ????

  Parameters:

    - turntable_id

    - position

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 poisition (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 poisition (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 poisition (values are hardware dependent)

    - amberpos – servo poisition (values are hardware dependent)

    - greenpos – servo poisition (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 poisition (values are hardware dependent)

    - inactiveAngle – servo poisition (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 – ???names???

SET_POWER(track, onoff)

  Set track power mode.

  Parameters:

    - track – A..H

    - onoff – ??? values ???

SETLOCO(loco)

  Sets the loco being handled by the current task.

  Parameters:

    - loco

SETFREQ(freq)

  Sets the DC track PWM frequency.

  Parameters:

    - freq – ??????????? values ??????

SIGNAL(redpin, amberpin, greenpin)

  Define a Signal with LOW=on leds (is that common annode???)

  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, value, angle, description...)

  Defines a turntable track position.

  Parameters:

    - turntable_id

    - position – ??????????

    - value

    - angle

    - description...

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.

  Parameters:

    - signal_id

VIRTUAL_TURNOUT(id, description...)

  Defines a virtual (no hardware) turnout.

  Parameters:

    - turnout_id

    - description...

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)