User Interface


The user interface for Engine Driver is described and explained in these pages as ‘screens’. There are several ‘Main Screens’ which you will routinely interact with and and larger number of ‘Secondary / Support Screens’ that will interact with infrequently.

There are also some settings that impact all of the Engine Driver screens, which are described towards the end of this page:

Main Screens

There are five main screens:

Connection Screen

../_images/connect.png

This screen is the first screen you normally see when starting Engine Driver. (Other than the first time you start Engine Driver.)

It allows you choose which WiThrottle Server or DCC-EX Server to connect to, which you must do to control your trains.

There are three ways you can select a WiThrottle Server or DCC-EX Server to connect to:

Once you select a server the Throttle Screen will be automatically displayed.

If you only ever connect to one WiThrottle Server or DCC-EX Server you can effectively bypass this screen by enabling the Auto-Connect to WiThrottle Server? preference.

Note

See WiFi Issues for more assistance with connection difficulties.

Connection Method Options

IP Address and Port

Enter the IP address or URI of the server in the first field, and the port in the second field, then click Connect. Engine Driver will attempt to connect to it, and the Throttle Screen will be displayed.

Discovered Servers

This is the most common way to connect.

Your WiThrottle Server or DCC-EX Server will attempt to broadcast its details so that apps like Engine Driver can automatically find it. If Engine Driver does find it, it will be listed here.

To connect to any WiThrottle Server or DCC-EX Server in this list, simply click on the row. Engine Driver will attempt to connect to it, and the Throttle Screen will be displayed.

Recent Servers

To connect to any WiThrottle Server or DCC-EX Server in this list, simply click on the row. Engine Driver will attempt to connect to it. If successful the Throttle Screen will be displayed.

Note that, just because it is in this list, it does not mean that you can connect to it now. It only means that you have successfully connected to it in the past.


Action Bar (Connection Screen)

The Action Bar appears at the top of all screens. It will show different information and different buttons depending on a) the particular screen and b) preferences you have set.

In the Connection Screen the Action Bar only displays:

  • The app name (Engine Driver)

Note

See the Action Bar section of this page for more information.


Overflow Menu (Connection Screen)

The Overflow Menu (or simply ‘Menu’) appears in the Action Bar at the top of most of the Main Screens is normally three dots (⁞) or three bars (≡). It will show different options depending on a) the particular screen, b) preferences you have set and c) the state of certain elements in the app.

Specific to the Connection Screen, the Overflow Menu can display:

Note

See the Overflow Menu section for more information.

Throttle Screen

../_images/throttle_vertical_outline.png

The Throttle Screen has two distinct areas:

  • The Action Bar

  • One or more Throttle Areas

There are also some settings that impact the whole Throttle Screen which described towards the end of this section:

  • Background

  • Immersive Mode (Full Screen)

  • Swipe Up / Down

  • Accelerometer (Shake)

The Throttle Screen allows you to control:

  • Access common functions from the Action Bar and Menu

  • Control one or more locos

The Throttle Screen contains between 1 and 6 Throttle areas depending on the Throttle layout chosen and the number of throttles for that layout (only some allow this to be changed).


Throttle Area

../_images/throttle_area1.png

Each Throttle on the Throttle Screen will display different information and buttons depending on the Throttle Screen Layout in the Throttle Screen Layout preference.

Each Throttle Area allows you to:

  • Select and release locos

  • Control the speed and direction of your trains

  • Activate DCC decoder functions like the light, bell, horn

  • Activate Virtual (IPLS) Sounds (bell, horn, short horn) (if enabled)

../_images/throttle_area2.png


Loco Select Button

The loco Select button in the Throttle Area allows to select or release locos for that particular Throttle. Click on the button and you will be taken to the Select Loco screen.

Once you have selected a loco, the label on the button will change to the DCC Address(s) or the Server Roster name(s) of the Loco depending on how you selected the loco in the Loco Select Screen, and if you have the enabled the Loco Address instead of Name? preference.

When the button is displaying DCC Address(s) or the Server Roster name(s), click on the button again and you will be taken to the Loco Select Screen where you can de-select the loco(s), select additional locos to make a Consist / Multiple Unit train, edit the locos in the consist, or edit the lights of the locos in the Consist / Multiple Unit.

Note

See the Operation page for more information.


Speed indicator

The Speed Indicator or Speed area of each throttle of the Throttle Screen indicates the throttle amount/setting (rather than the actual speed of the locos controlled by the the throttle).

Depending on the Speed Units Preference the upper limit shown will be different:

Speed Unit Setting

Low value

High Value

Percent 0 - 100%

0

100

Auto Speed steps

?

?

8 steps

0

8

10 steps

0

10

14 steps

0

14

28 steps

0

28

128 steps

0

128

Also, if one of the Shunting/Switching layouts is selected, the high number will be negative (‘-’) when reversed (e.g. -100 - 0 - 100)

The Speed Indicator area also can show:

  • Volume indicator

  • Gamepad Indicator

  • Direction indicator (Shunting/Switching Layouts only)

Volume Indicator

A ‘V’ will be shown in the Speed Indicator area to indicate which throttle is being controlled by the hardware volume buttons. Touch another Speed Indicator to change which Throttle the Hardware Volume buttons control.

Gamepad Indicator

A number (‘1’,’2’, etc.) will be shown in the Speed Indicator area to indicate which throttle is being controlled by the each connected gamepad. Set one of the gamepads to allow you to switch throttle it controls.

Direction Indicator

If one of the Shunting/Switching layouts is selected, a triangle symbol will be shown to indicate direction (pointing Up for forward, and down for reverse).

Note

See the Throttle Control Preferences section of the Speed Units preference for a information on changing the Speed Units options.


Speed Slider Area
../_images/slider_horizontal.png

The Throttle areas can be configured to have a Speed Slider. (All Throttle Screen Layouts except the ‘Big Button’ layouts include sliders by default.)

Dragging you finger along the slider will increase or decrease the speed of the loco(s) selected for the that Throttle.

Pressing and holding your finger at one spot on the slider will cause Engine Driver to slowly increase or decrease the speed of the loco(s) selected for that Throttle till it gets to that point.

Depending on the Throttle Screen Layout chosen in the Throttle Screen Layout preference, all sliders on the Throttle Screen will be either:

  • one-directional (0% - 100%) [1]
    or

  • bi-directional (-100% - 0 - +100%)

Bi-directional sliders are useful for when you are switching/shunting. i.e. moving your locos backwards and forwards a lot.

Several preferences can change the appearance or actions of the Speed Slider:

  • Increase Slider/Speed Height?
    When set, this preference will show a taller Slider, or Speed buttons, for throttles

  • Throttle Speed Slider Margin
    When set, this changes the space between either the edge of the screen and the ends of the Slider, or if the Speed Buttons are enabled, the edge of the Speed Buttons and the ends of the Slider. Specific in pixels haw far to offset

  • Hide Speed Slider?
    When this preferences is set, Engine Driver will not show speed slider, use speed buttons instead

  • Tick Marks on Speed Sliders?
    When this preferences is set, Engine Driver will show tick marks on the background of the Speed Sliders

  • Switching throttle Dead Zone
    When this preferences is set, Engine Driver will set the size of the dead zone, or detent, on the slider of the Switching/Shunting Throttle Screen

  • Stop Button Vertical Margins
    When this preferences is set, Engine Driver will add the entered number of pixels to offset margins of the stop button from the speed buttons and bottom of screen


Stop Button
../_images/stop_button_horizontal.png

Clicking the Stop button of a throttle will the Loco or Consist / Multiple Unit controlled by that throttle. If the locos have momentum configured in the decoder it/they will come slowly to a stop. i.e. it obeys the momentum CV settings.

Note

See the Emergeny Stop Action Bar button for information on stopping locos immediately, overriding the momentum setting.


Speed Buttons
../_images/speed_buttons_horizontal.png

The Throttles may optionally be configured have simple buttons that allow you to increase or decrease the loco’s speed in pre-defined steps.

For horizontal speed sliders, the buttons are displayed at the left and right ends of the sliders. For vertical speed sliders, the buttons are displayed at the top and bottom of the sliders.

When enabled:

For the Horizontal Sliders only, The position of these buttons in relation to the speed sliders (the space between), can be altered with the Speed Slider Margin preference.

Note

See the Display Speed Buttons? preference for more information on enabling these buttons.

See the Speed Button Change Amount preference for information on the about these buttons.


Direction Buttons Area
../_images/direction_buttons.png

Each Throttle on the Throttle Screen will display Forward and Reverse direction buttons, depending on the Throttle Screen Layout in the Throttle Screen Layout preference. ‘Shunting/Switching’ layouts do not show the direction buttons.

Change direction while moving preference.

Note

See the Direction change while moving? and Stop on Direction change? preferences for information on preferences which alter when the buttons are available and the way the they work.


Function Buttons Scroll Area

The Function Buttons Scroll Area will show form 0 (zero) to 26 function buttons depending on a number of factors. Each button will show either:

  • Labels provided from the Server Roster, which can be individually specified for each loco in the Server Roster

  • The default labels for Engine Driver (which can be changed)

The Function Button area can also show:

  • IPLS buttons (In Phone Loco Sounds)

  • Pause

  • Limit Speed

The Function Buttons Scroll Area is shown by default on all Throttle Screen layouts except Simple. It can be enable for the Simple layout

Note

See the Function Button Area Size preference for information on how to show the Function Button Scroll Area on the simple layout.


DCC Function buttons

DCC Function Buttons are displayed here. If there are too many to display in the screen area allocated, then the area becomes scrollable (without scroll bars) so that they can all be viewed and pressed as needed.

All throttle layouts other than the ‘Simple’ layout show a Function Buttons Scroll Area by default. For the ‘Simple’ layout it must be enable in the preferences if required.

Will show from 0 (zero) to 26 DCC function buttons, depending on a number of factors. Each button will show either:

  • Labels provided from the Server Roster, which can be individually specified for each loco in the Server Roster

  • The default labels for Engine Driver (which can be changed)

If the loco (or first loco of a Consist / Multiple Unit) was selected from the WiThrottle Server or DCC-EX Server Server Roster, then (by default) the number of functions and labels on the buttons will be whatever is configured for that loco in the WiThrottle Server or DCC-EX Server. This is also turn if the loco is selected from the Recent Locos list or the Recent Consists / Multiple Units list.

If the loco (or first loco of a Consist / Multiple Unit) was added by entering its DCC Address, then the number of functions and labels on the buttons will be whatever is configured in Engine Driver in the Function Defaults Screen.

The behaviour of the Function Buttons for locos selected from the WiThrottle Server or DCC-EX Server Server Roster can be overridden with the Use default function labels? preference. If this is enabled, the locos selected from the WiThrottle Server or DCC-EX Server Server Roster will also show the Default Functions labels.

Clicking on any function button will instruct the loco to activate that DCC Function in the loco. By default this is only sent to the Lead loco, however this can be overridden in a number of different ways.

Note

See the Function Defaults Screen section for more information on configuring the labels and number of default function buttons.

See the Function Buttons page for more information on the DCC Function buttons.

For labels from Server Roster Entries you need to edit the Function buttons in the WiThrottle Server or DCC-EX Server, or configure Engine Driver to use the default labels.


Pause and Limit Speed buttons
../_images/limit_speed_and_pause_buttons.png

The Function Button area can also show: * Pause button * Limit Speed button

These are optional buttons that, if enabled, appear in the same areas as the Function Buttons and the In Phone Loco Sounds buttons (if enabled).

Pause Button

When clicked while the Loco or Consist / Multiple Unit is moving, the Pause button will gradually slow the train down zero and a predefined rate. The rate can be altered in the preferences.

When subsequently clicked while the Loco or Consist / Multiple Unit is stationary, the Pause button will gradually increase the speed of the train till it is at the speed that it was at when the button was first pressed. i.e. its original speed.

Alternate Pause Button

An ‘alternate Pause button’ can be enabled in the preferences. This behaves exactly the same as the normal Pause button, but appears below the throttle slider and speed buttons.

Limit Speed Button

When enabled by clicking on the Limit Speed button, Engine Driver will restrict the maximum speed on the throttle to the predefined amount. By default the speed will be 50%, but this can be changed in preferences.

Note

See the ‘Limit Speed’ & ‘Pause’ button Preferences section on the Preferences page for more information on these buttons.


In Phone Loco Sounds buttons (IPLS)

The Function Button area can also be configured in the preferences to show the IPLS buttons (In Phone Loco Sounds)

These are optional buttons that allow you to ‘play’ specific loco related sounds through your device/phone.

The buttons include:

  • Mute

  • Bell

  • Horn

  • Short Horn

‘Horn’ and ‘Short Horn’ are momentary. ‘Mute’ and ‘Bell’ are latching.

‘Mute’ can be hidden by changing a preferences.

Note

See the Virtual Sounds - In Phone Loco Sounds (IPLS) section of the operation page for more information using the IPLS.

See the In Phone Loco Sounds (IPLS) page for more information on the configuring IPLS buttons.


Load Slider Area

This is unique to the Semi-Realistic Throttle (SRT).

The ‘Load’ slider is intended to simulate if the train you are controlling has none, a few, many, or a huge number of carriages behind it. Load can also be increased or decreased to simulate going up or down a slope.

The Load can be set to show either a percentage slider or a slider with a distinct number of steps/notches.

The maximum load can be set in the preferences. (the Default is 1000%) The Load slider is exponential in scale, so from notch 0 to 1 to 2 only small increases of load are applied, but by the final notches, huge changes are applied.

Refer to the Semi-Realistic Throttle (SRT) page for more information.


Brake Slider Area

This is unique to the Semi-Realistic Throttle (SRT).

The ‘Air Brake’ feature is designed to simulate a very rough approximation of the Westinghouse Air Brake system used by early US railroads.

The Brake slider can be used with or without the simulation of the Air Reservoir and Air Line.

Refer to the Semi-Realistic Throttle (SRT) page for more information.


Web View Area (Throttle Web View)

Todo

LOW: Web View Area (Throttle Web View)

Optional, shows a web browser in the lower half of the Throttle Screen.

Your JMRI Layout panels can be displayed here if you have configured them in JMRI.

Anything that can be shown in the Web View Screen can equally be shown here, just in a smaller space.

Note

see preference

see initial page preference

different to the main Web View Screen including a different preference to set the initial page.

see increase size


Action Bar (Throttle Screen)

../_images/action_bar.png

The Action Bar appears at the top of all screens. It will show different information and different buttons depending on a) the particular screen and b) preferences you have set.

In the Throttle Screen the Action Bar can display:

  • The app name (Engine Driver)

  • Optionally configured information:

  • Optionally configured buttons:

    • Emergency Stop (EStop)

    • Track Power

    • Flashlight

    • Throttle Web View

    • Throttle Layout Switching

    • In Phone Loco Sound

    • Children’s Timer

Note

The optional action bar buttons are enabled via the Menu ‣ Preferences ‣ Throttle Screen Status Row Preferences.

See the Action Bar section of this page for more information.


Overflow Menu (Throttle Screen)

../_images/menu_throttle.png

The Overflow Menu (or simply ‘Menu’) appears in the Action Bar at the top of most of the Main Screens is normally three dots (⁞) or three bars (≡). It will show different options depending on a) the particular screen, b) preferences you have set and c) the state of certain elements in the app.

Specific to the Throttle Screen, the Overflow Menu can display:

Note

See the Overflow Menu section for more information.

../_images/background_fill.png


Background

Engine Driver can show a background image of your choosing on the Throttle Screen. Any image/photo on your device/phone can be used.

Note

See the Background Images section of the preferences for more information on how to select a background image.


Immersive Mode (Full Screen)

Immersive mode hides the system navigation buttons at the bottom of the screen on the Throttle screen only, to give you more screen real estate for the throttle UI.

It can optionally also hide the Android System Status Bar at the top of the page.

Swiping up from off screen will normally temporarily show the Android navigation buttons again.

You can also configure specific Swipe up or Swipe down or Shake preferences to enter or exit immersive mode.

Note

See the Swipe Up-Down Preferences for more information on how to configure immersive mode.


Swipe Left / Right (From Throttle)

Swiping Left from the Throttle Screen will take you to the Routes Screen, unless it has been disabled in the preferences

Swiping Right from the Throttle Screen will take you to the Turnouts/Points Screen, unless it has been disabled in the preferences

By default, you can Left/Right Swipe from any part of the screen, but this can be changed to just the Action Bar in the preferences. This can be useful if Left/Right swipes in the Web View Screen and Throttle Web view causes problems.

Note

See the Left/right swipe preferences for information on how to enable and disable which screens are in the Left / Right swipe sequence.

See the Disable Full Screen Swipe prefernce to enable or disable the Swipe Action Bar only option.


Swipe Up / Down

Swiping Up and/or Down on the Throttle page can optional be configured to:

  • Do Nothing

  • Hide the Web View (if enabled)

  • Lock and Dim the screen

  • Dim the screen

  • Enable/Disable Immersive mode

  • Switch Throttle Layouts

  • Increase/Decrease Loco speed

  • Go to the next throttle

Note

See the Swipe Up/Down preferences for information on how to configure what the up and down swipes do.


Accelerometer (Shake)

Shaking your device/phone while on the Throttle page can optional be configured to:

  • Do Nothing

  • Hide the Web View (if enabled)

  • Lock and Dim the screen

  • Dim the screen

  • Switch Throttle Layouts

  • Go to the next throttle

Note

See the Accelerometer (Shake) preferences for information on how to configure what the Accelerometer (Shake) do.

Turnouts/Points Screen

Accessed from any of the Main Screens by the Menu ‣ Turnouts` or Menu ‣ Points or by swiping right from the Throttle Screen if enabled in the Left with the Swipe through Turnouts? or Swipe through Points? preference: Menu ‣ Preferences ‣ Left/Right Swipe Preferences ‣ Swipe through Turnouts/Points

This screen allows you to display all Turnouts/Points that have been defined in JMRI.

Turnouts/Points can be operated three ways:

  • By entering the DCC Address

  • From the Defined Turnout/Point list provided by the WiThrottle Server or DCC-EX Server (JMRI)

  • From the Recent Turnout/Point list

Turnouts/Points can be changed from ‘Closed’ to ‘Thrown’ and vice versa be pressing on either the Closed or Thrown buttons

../_images/turnouts_jmri.png

Via the list from Server

By selecting the ‘JMRI Defined’ radio button, Engine Driver will show the Turnouts/Points defined in the Command Station/Server.

Click on the button(s) on the beside the entry to Throw` or Close the Turnout/Point.

Note:

  • If the Turnout/Point button says ‘Thrown’, then clicking on the button will ‘Close’ the Turnout/Point and the button will then say ‘Closed’.

  • If the Turnout/Point button says ‘Closed’, then clicking on the button will ‘Throw’ the Turnout/Point and the button will then say ‘Thrown’.

Note

Note that this list can optionally be set to always show Close and Throw rather than Closed or Thrown by setting the Always Show Throw/Close? preference.

../_images/turnouts_entry.png

By Entering an Address

By selecting the ‘Address/Recent’ radio button, Engine Driver will allow you to throw/close any arbitrary Turnout/Point.

Enter the address of the Turnout/Point and press any of the buttons:

  • Throw

  • Close

  • Toggle

Recent

By selecting the ‘Address/Recent’ radio button, Engine Driver will allow you to throw/close any recently used Turnout/Point.

Click on the buttons on the beside the entry to ‘Throw’ or ‘Close’ the Turnout/Point.

Filter by location

The ‘Turnout/Points List’ can be filtered. The filtering relies on the idea that the first part of every Turnout/Point name is a ‘Location’, followed by a common separator, then the actual name for the Turnout/Point name. The ‘filter’ then allows you to select one of those locations and Engine Driver can just show the Turnout/Points at the ‘Location’.

The Location Delimiter preference allows you to set the character that marks the end of the Location portion of Turnout/Point and Route names. By default it is a colon (“:”) but any character can be used.

Note

A number of preferences can alter the way Turnouts/Points are displayed. See Turnouts/Points and Routes Preferences for more information.


Action Bar (Turnouts/Points Screen)

../_images/action_bar.png

The Action Bar appears at the top of all screens. It will show different information and different buttons depending on a) the particular screen and b) preferences you have set.

In the Turnouts/Points Screen the Action Bar can display:

  • The app name (Engine Driver)

  • Optionally configured information:

  • Optionally configured buttons:

    • Emergency Stop (EStop)

    • Track Power

    • Flashlight

Note

The optional buttons are enabled via the Menu ‣ Preferences ‣ Throttle Screen Status Row Preferences.

See the Action Bar section of this page for more information.


Overflow Menu (Turnouts/Points Screen)

The Overflow Menu (or simply ‘Menu’) appears in the Action Bar at the top of most of the Main Screens is normally three dots (⁞) or three bars (≡). It will show different options depending on a) the particular screen, b) preferences you have set and c) the state of certain elements in the app.

Specific to the Turnouts/Points Screen, the Overflow Menu can display:

Note

See the Overflow Menu section for more information.


Swipe Left / Right (From Turnouts/Points)

Swiping Left from the Turnouts/Points Screen will take you to the Throttle Screen, unless it has been disabled in the preferences

Swiping Right from the Throttle Screen will take you to the Web View Screen, unless it has been disabled in the preferences

By default, you can Left/Right Swipe from any part of the screen, but this can be changed to just the Action Bar in the preferences. This can be useful if Left/Right swipes in the Web View Screen and Throttle Web view causes problems.

Note

See the Left right swipe preferences for information on how to enable and disable which screens are in the Left / Right swipe sequence.

See the Disable Full Screen Swipe prefernce to enable or disable the Swipe Action Bar only option.

Routes Screen

../_images/routes.png

Accessed from any of the Main Screens by the menu Menu ‣ Routes or by swiping left from the Throttle Screen if enabled in the Left with the Swipe through Routes? preference: Menu ‣ Preferences ‣ Left/Right Swipe Preferences ‣ Swipe through Routes

This screen displays all Routes that have been defined in your Command Station/Server and allows you to activate them.

By System name

You can enter the route ID and click Set button to activate a route.

Via the List from the Server

You can select the route from the list provider by your Command Station/Server

Click on the Set buttonon the beside the entry to activate the Route.

Note, When using the Native DCC-EX Protocol the DCC-EX EX-CommandStation (only) can:

  • dynamically change the label on the the button

  • dynamically show or hide Routes

  • dynamically enable or disable Routes

Filter by location

The ‘Routes List’ can be filtered. The filtering relies on the idea that the first part of every Route name is a ‘Location’, followed by a common separator, then the actual name for the Route name. The ‘filter’ then allows you to select one of those locations and Engine Driver can just show the Routes at the ‘Location’.

The Location Delimiter preference allows you to set the character that marks the end of the Location portion of Turnout/Point and Route names. By default it is a colon (“:”) but any character can be used.

Note

A number of preferences can alter the way Routes are displayed. See Turnouts/Points and Routes Preferences for more information.


Action Bar (Routes Screen)

../_images/action_bar.png

The Action Bar appears at the top of all screens. It will show different information and different buttons depending on a) the particular screen and b) preferences you have set.

In the Routes Screen the Action Bar can display:

  • The app name (Engine Driver)

  • Optionally configured information:

  • Optionally configured buttons:

    • Emergency Stop (EStop)

    • Track Power

Note

The optional buttons are enabled via the Menu ‣ Preferences ‣ Throttle Screen Status Row Preferences.

See Action Bar section of this page for more information.


Overflow Menu (Routes Screen)

The Overflow Menu (or simply ‘Menu’) appears in the Action Bar at the top of most of the main screens is normally three dots (⁞) or three bars (≡). It will show different options depending on a) the particular screen, b) preferences you have set and c) the state of certain elements in the app.

Specific to the Routes Screen, the Overflow Menu can display:

Note

See the Overflow Menu section for more information.


Swipe Left / Right (From Routes)

Swiping Left from the Routes Screen will take you to the Web View Screen, unless it has been disabled in the preferences

Swiping Right from the Routes Screen will take you to the Throttle Screen, unless it has been disabled in the preferences

By default, you can Left/Right Swipe from any part of the screen, but this can be changed to just the Action Bar in the preferences. This can be useful if Left/Right swipes in the Web View Screen and Throttle Web view causes problems.

Note

See the Left right swipe preferences for information on how to enable and disable which screens are in the Left / Right swipe sequence.

See the Disable Full Screen Swipe prefernce to enable or disable the Swipe Action Bar only option.

Web View Screen

../_images/web_view_screen.png ../_images/web_view_screen2.png

Accessed from any of the main screens by the menu Menu ‣ Web or by swiping left or right twice from the Throttle Screen if enabled in the Left with the Swipe through Web? preference: Menu ‣ Preferences ‣ Left/Right Swipe Preferences ‣ Swipe through Web It can also be accessed, if the Screen orientation preference is set to Auto Web, by rotating the Android Device/Phone.

This screen displays a web browser interface that lets you view any web page. Normally this will be a web page on your JMRI server.

From the JMRI web server you can view and interact with additional features of JMRI. The menu at the top right of the web panel screen allows you to further display:

  • Rosters

  • Operations

  • Trains

  • Tables

  • Turnouts/Points

  • Sensors

  • Routes

  • Reporters

  • Memories

  • Blocks

  • Layout Blocks

  • Lights

  • Signal Masts

  • Signal Heads

  • Locations

  • Cars

  • Engines

  • ID Tags

This can be used for:

  • A webThrottle screen

  • Your JMRI layout panel(s)

  • Any URL in a full screen. This is in addition to being able to display your JMRI layout panel in a small section of the main Throttle Screen.

Tap on any of the Open Windows to expand its view. You can then resize the panel by pinching and zooming. It is sometimes useful to rotate your device to landscape mode, so as to better view your layout.


Action Bar (Web View Screen)

../_images/action_bar.png

The Action Bar appears at the top of all screens. It will show different information and different buttons depending on a) the particular screen and b) preferences you have set.

In the Web View Screen the Action Bar can display:

  • The app name (Engine Driver)

  • Optionally configured information:

  • Optionally configured buttons:

    • Emergency Stop (EStop)

    • Track Power

Note

The optional buttons are enabled via the Menu ‣ Preferences ‣ Throttle Screen Status Row Preferences.

See Action Bar section of this page for more information.


Overflow Menu (Web View Screen)

The Overflow Menu (or simply ‘Menu’) appears in the Action Bar at the top of most of the main screens is normally three dots (⁞) or three bars (≡). It will show different options depending on a) the particular screen, b) preferences you have set and c) the state of certain elements in the app.

Specific to the Web View Screen, the Overflow Menu can display:

Note

See the Overflow Menu section for more information.


Swipe Left / Right (Web View Screen)

By default, swiping left or right or the Main Screens (of which the Web view is one) will take to one of the other Main Screens. This can be problematic on the Web View Screen as the swipes may mean something else on the web page.

If the Disable full screen Swipe? preference is enabled, only the Action Bar can be swiped to change screens. This is useful if you find it difficult to swipe left and right on either of the two Web Views without accidently changing screens.

Secondary / Support Screens

The following additional screens will be shown at different times and for various reasons:

Intro/Setup Wizard Screen

The Setup Wizard will start automatically the first time you run Engine Driver after you install it. It sets some basic preferences and asks for the necessary permissions. These preferences can be subsequently be changed use the : Menu ‣ Preferences, or by re-running the wizard, which can only be done from the menu on the Connection Screen.

Note

See the Setup wizard page for more information.

Loco Select Screen

../_images/select_roster_existing_consist.png

The Loco Select Screen allows you add locos to a (one of) throttle on the Throttle Screen. It also provides access to the additional screens for ‘Editing the Consist’, ‘Editing Lights’ and editing the ‘In Phone Locos Sounds’.

The Loco Select Screen is only shown when you click a Select button on the Throttle Screen.

Not that the Select button will should the Address(es) or the Name(s) of a|loco_consist| Train only the first loco is selected. Click on the button will (while it is in this state) will again take to this screen to allow to you add additional Locos to the Consist / Multiple Unit Train, or make other changes to the Consist / Multiple Unit Train.

Selection Method

There are four ways you can choose a loco for the Throttle. Select one of the radio buttons depending on how you want to the choose the loco:

  • DCC Address

  • Server Roster

  • Recent Locos

  • Recent Consists

Select by DCC Address

Todo

MEDIUM: Select by DCC Address

Shown if you select DCC Address in the Selection Method.

You can enter the loco’s DCC address (verify short or long), and press Acquire to select the loco. You will then be taken back to the Throttle Screen with that loco selected.

Select from Sever Roster

Shown if you select Server Roster in the Selection Method.

If the loco you want to control is in the list, simply click on it and you will be taken back to the Throttle Screen with that loco selected.

For this to be possible, the Loco you want to control needs to be in the Server Roster of the WiThrottle Server or DCC-EX Server. Not all WiThrottle Server or DCC-EX Server support a Server Roster. Refer to the JMRI documentation or your WiThrottle Server or DCC-EX Server device’s documentation for creating a Server Roster.

Filter the Roster

The ‘Roster’ can be filtered by entering text in the Contains... field.

As you type each character the filter will be applied and the list will be reduce to only those entries that contain the text you have entered.

The filter is case insensitive.

Download to the Roster

By clicking the Download button, all locos in the Server roster will be drawn in the ‘Recent List’ in Engine Driver.

For this the filter is ignored. i.e. the Whole Server Roster is downloaded, not just what you can see on screen.

Note that if there are more locos in the Roster than, the Maximum Recent Locos preference value, the Maximum Recent Locos will be automatically increased the number in the roster + 1.

Icons / Loco Images

From the Server

Engine Driver is designed to retrieve the Loco Images from JMRI if provided. To do this, JMRI’s Web Server must be enabled DecoderPro ‣ Actions ‣ Start Web Server

The images will be loaded gradually, after Engine Driver connects to the server and you use the Loco Select Screen for the first time.

Each time you Acquire a loco, any icon is cached in Engine Driver, so will load faster that others the next time you use Engine Driver.

Adding a local image

For locos in a Roster from a non-JMRI Command Station/Server, that does not support loco icons, you can add a local image as an icon for the entry.

Long Press on a Roster Entry you will see

  • A New Image button

  • The existing image if there is one

  • A Remove button, if there is an existing image

  • A Save button

AS long as you have granted the Optional Permissions you will be able to use the New Image button to find and select an image stored on your device/phone to use as a Loco Icon.

Warning

The size of the image must be relatively small.

If you select an image but nothing happens, try reducing the size the image, then try again.

Select from Recent Locos List

Shown if you select Recent Locos in the Selection Method.

Engine Driver remembers the last 10 locos that you have selected. (That number can be increased or decreased with Maximum Recent Locos preference.)

If the loco you want to control to is in the list, simply click on it and you will be taken back to the Throttle Screen with that loco selected.

Remove Recent Loco entries

To remove a single entry from the recent Locos list, swipe right on that entry.

To remove all entries, click the CLear List button.

Naming a Recent Loco

For locos that have bee acquired by DCC Address, and are now in the Recent Locos list, these locos can be renamed.

Long Press on the entry in the Recent Locos list, and enter a new name.

Select from Recent Consists (MU) list

Shown if you select Recent Consists (MU) in the Selection Method.

Selecting a Consist / Multiple Unit in the Recent Consists (MU) list will automatically add all the remembered locos, including their facing.

Naming a Recent Consist (MU)

For all Recent Consists (MUs) these Consists (MUs) can be renamed.

Long Press on the entry in the Recent Consist (MU) list, and enter a new name.

Remove Recent Consists (MU) Entries

To remove a single entry from the recent Consists (MU) list, swipe right on that entry.

To remove all entries, click the CLear List button.

Select Loco - Core On Screen Buttons

Acquire

Shown if you select DCC Address in the Selection Method.

After you enter a loco’s DCC address you press Acquire to select the loco. You will then be taken back to the Throttle Screen with that loco selected.

Release

Shown if you have one or locos already selected (acquired) for that throttle.

Clicking this button will release all the locos currently controlled by the throttle.

Edit Order & Facing

Shown if you have one or locos already selected (acquired) for that throttle.

Clicking this button will show the Consist(MU)EditScreen.

Edit Lights

Shown if you have one or locos already selected (acquired) for that throttle.

Clicking this button will show the ConsistLightsEditScreen.

Loco Sounds

Shown if you have one or locos already selected (acquired) for that throttle.

Clicking this button will show InPhoneLocoSoundsScreen.

Consist (MU) Edit Screen

../_images/consist_edit2.png

The Consist (MU) Edit Screen is automatically shown if you add a second, or subsequent, loco to a throttle via the Select button, or if you click on the Edit Order & Facing button on the Loco Select Screen (which will only be available if you have already acquired more than one loco on the throttle.)

On this screen, for your on-the-fly you can:

Lead Loco

The Lead Loco drop down will show the current lead loco in the consist / multiple unit.

With the Lead Loco drop down, you can change the lead loco to any other loco in the consist / multiple unit.

Trailing Loco

The Trailing Loco drop down will show the current trailing (last) loco in the consist / multiple unit.

With the Trailing Loco drop down, you can change the trailing (last) loco to any other loco in the consist / multiple unit.

Change Facing

The All Locos in Consist (MU) section of the Consist (MU) Edit Screen shows a list of all locos in the consist / multiple unit along with the facing of each loco.

Clicking on the row of the loco changes the facing of that loco in the consist / multiple unit.

This allows you to easily run a second (or more) loco facing rearwards/backwards in the consist / multiple unit train.

Note that this DOES NOT alter the decoder CV for the default direction. Engine Driver simply sends reverse speeds commands to the individual loco while it is sending forward speed commands to the other locos in the consist / multiple unit.

Remove a Loco

The All Locos in Consist (MU) section of the Consist (MU) Edit Screen shows a list of all locos in the consist / multiple unit along with the facing of each loco.

Swiping Right on the row of the loco will remove that loco from the consist / multiple unit.

Note that you can’t remove the Lead Loco.

Consist (MU) Lights Edit Screen

../_images/consist_lights_edit_screen.png

The Consist (MU) Lights Edit Screen is shown if you click on the Edit Lights button on the Loco Select Screen (which will only be available if you have already acquired more than one loco on the throttle.)

It will also be shown if you long press on the Loco Select button, a) if you have already acquired a consist / multiple unit, and b) if the Control consist Lights on long click preference is enabled.

The Consist (MU) Lights Edit Screen shows a list of all locos in the consist / multiple unit along with the light rule for each loco in the consist / multiple unit.

Clicking on the row of any entry will alter the light rule for that loco.

The options are:

  • Unknown

  • Follow Fn Btn

  • On

  • Off

Unknown means that rule has not been set so Engine Driver does not know the current state of the lights in that loco.

Follow Fn Btn (Follow Function Button) means the that lights in the locos will obey whatever the Light Function (F0) is set to.

On means that lights in that loco will be permanently turned on, and the Light Function (F0) will have no effect.

Off means that lights in that loco will be permanently turned off, and the Light Function (F0) will have no effect.

Note that the Lead Loco will always be Follow Fn Btn and cannot be changed.

Power Screen

../_images/power.png

Accessed from any of the main screen via : Menu ‣ Preferences ‣ Left/Right Swipe Preferences ‣ Power or from the Action Bar if enabled with the Layout Power button? preference : Menu ‣ Preferences ‣ Throttle Screen Action Bar Preferences ‣ Layout Power button?.

This screen allows you to toggle the state of track power to your layout.

  • When the button is Green, it indicates that track power is ‘On’.

  • When the button is Red, it indicates that track power is ‘Off’.

  • When the button is Amber, it indicates that track power state is unknown.

  • Pressing a Green button will cause the button to be changed to Red and the track power will be turned ‘Off’.

  • Pressing a Red button or Amber button will cause the button to be changed to Green and the track power will be turned ‘On’.

Preferences Screen

../_images/preferences-1.png

Accessed from any of the main screens via Menu ‣ Preferences.

This screen allows you to personalise Engine Driver for how you want it to use it.

Note

See the Preferences page for details on the preferences that can be set.

In Phone Loco Sounds Screen

../_images/ipls_screen.png

This screen allows you to set Engine Driver to play synchronised loco sounds through the speaker of your Android device / phone, or through BlueTooth speakers connected to it.

See Virtual Sounds - In Phone Loco Sounds (IPLS) for more information.

Accessed from Throttle Screen by the Menu ‣ Loco Sounds or from the Status Bar if enabled with the In phone sounds button preference.

Function Defaults Screen

../_images/function_defaults1.png

This screen allows you to override the appearance of the Function buttons on the throttle screen, primarily for locos that have not been acquired from the Server Roster.

Some of these have equivalent items in the preferences.

Accessed from the menu on the Throttle Screen as Menu ‣ Function Defaults.

Number of Default Functions

This preference is used to limit the number of Function Labels shown for selected locos that are not from the Server Roster, or where you have set the Use default function labels? preference.

Number of Default Functions for Roster

This preference is used to limit the number of Function Labels shown for Server Roster Entries that don’t have any function Labels configured.

Use Default Function Labels

If this preference is enabled locos acquired from the Server Roster will also use the default function labels as defined on this screen.

Override WiThrottle Default Latching

If this preference is enabled an additional Function Latching Settings Screen will be available from the menu.

The DCC-EX Function Settings Screen then allows you override to default latching/momentary behaviour of all/any function for locos acquired from the DCC-EX EX-CommandStation by entering is DCC address . i.e. not locos acquired from the roster.

Use Defaults for Roster Entries With no functions

If this preference is enabled, locos in the Server Roster that have no function buttons defined will show no Function buttons on the Throttle Screen.

If this preference is NOT enabled, locos in the Server Roster that have no function buttons defined will show the default functions and and labels as defined on the screen.

This preference is enabled by default.

Function List

The function list shows up to 32 functions with both a number and a label.

The Function Number defines which DCC function number should be activated when you click the corresponding button on the Throttle Screen.

Not all numbers (0-31) need be included.

The order of the number can be changed.

The Function Label defines what label/text should show on the corresponding button on the Throttle Screen.

Function Latching Settings Screen

../_images/function_latching_settings.png

The function list shows 32 functions with both a label and a drop-list to say if the function should be latching or not (momentary).

This screen is only available in the menu if the Override WiThrottle Default Latching option is enabled on the Function Defaults Screen and you are are connected to a WiThrottle Server. (Not an DCC-EX EX-CommandStation using the Native DCC-EX Protocol.)

Accessed from the menu on the Throttle Screen as Menu ‣ Function Latching Settings.

Each Function is listed (from the Function Defaults Screen with the option set the function to either:

  • Latching

  • Not Latching (Momentary)

DCC-EX Function Settings Screen

../_images/dcc-ex-functions-screen.png

This screen allows you to override to default latching/momentary behaviour of all/any function for locos acquired from the DCC-EX EX-CommandStation by entering is DCC address . i.e. not locos acquired from the Server Roster.

This screen is effectively the same as the Function Latching Settings Screen but is only available when connected to an DCC-EX EX-CommandStation using the DCC-EX Native protocol. (Not WiThrottle protocol)

Accessed from the menu on the Throttle Screen as Menu ‣ DCC-EX Function Settings.

DCC-EX Screen

../_images/dcc-ex-cv-prog-screen.png

This screen allows you to perform a number of DCC-EX EX-CommandStation specific actions including reading and writing CVs.

See Features when using the Native Protocol when connected to a DCC-EX EX-CommandStation for more information.

This menu item and screen is only available if connected to a DCC-EX EX-CommandStation using the Native DCC-EX Protocol.

Accessed from the menu on the Throttle Screen as Menu ‣ DCC-EX.

WiThrottle - Programming on the Main Screen

../_images/pom_screen.png

This screen allows you to program CVs in decoders on the main (Operation mode programming) on some systems / DCC Command Stations.

Accessed from the menu on the Throttle Screen as Menu ‣ DCC-EX CV Prog on MAIN.

The menu option is only shown if the Show WiThrottle PoM Page preference is enabled.

note: You cannot READ CVs. You can only write them.

Todo

LOW: Programming on the Main Screen

Warning

This feature only works on a very small number of DCC Command Stations. It works by sending a hex packet to the DCC Command Station.

Gamepad Test Screen

../_images/gamepad_test_screen.png

This screen serves two purposes.

  • If accessed from the preferences it allows to experiment with the difference gamepad types and different setting with the button configuration.

  • When automatically open when you first connect a gamepad from the Throttle Screen it is used to confirm that the Gamepad is configured sufficiently to control the throttle.

The screen contains:

  • Gamepad ‘Type’ drop down

  • Indicators for all the possible supported gamepad buttons (Some may not be available for any given gamepad type.)

  • ‘All Codes:’ - this shows the up and down key codes as a button is pressed

  • ‘Key Code:’ - this shows the key code of the last pressed button

  • ‘Function:’ - this shows the function assigned to the last pressed button

  • ‘Test Status:’ - this Shows the status of the test. Only relevant for a Gamepad Test.

Accessed from the Throttle Screen via the Menu ‣ Gamepads -> Gamepad Test X. (where ‘X’ is the number of the gamepad.) or from the Test Gamepad settings now! preference.

Note

See the Gamepad Preferences for more information on configuring a gamepad.

See the Gamepads page for more information on selecting and using gamepads.

View Log Screen

../_images/log_view.png

This screen allows you to view the internal Engine Driver log of events. This is sometimes useful for analysing problems.

The option to Start recording to file creates a user-accessible file that can be sent to the Engine Driver app developers or the Groups.io help group to assist you in resolving a problem. The file will be located on your mobile phone at: Internal storage /Android/data/jmri.enginedriver/files. It will be named something like: logcat9999999999999.txt.

Note: This location cannot be accessed easily on later versions of Android (>13). So to see it or send to the developers for support you must connect your device/phone to a PC.

Enable the Show Timestamps on Log? preference to include the timestamp on each line of the log.

Accessed from any of the main screens via Menu ‣ View Log.

Saving a log file

To record a log file in EngineDriver….

  1. Start Engine Driver.

  2. From the menu, select View Log

  3. Click Start recording to a file

  4. Click Close

  5. Attempt whatever is causing the problem a few times

  6. Exit ED

  7. Connect a USB cable to your phone and PC

  8. Allow access if the phone asks.

  9. In some versions of Android you may also need to change the connection type on the phone from ‘charging’ to ‘file transfer’

  10. Open a file manager and find the connected phone

  11. Browse down to the folder ..\Internal shared storage\Android\data\jmri.enginedriver\files

  12. Find the most resent file that looks like logcatxxxxxxxxxxxxx.txt e.g. logcat1699833098998.txt

13a. Attach that file to a message in qroups.io using the paperclip button on the toolbar above the message content 13b. Attach that file to a message in discord using the + button on the row of the message content 13c. Attach that file to an email message and send to the developers

About Screen

../_images/about.png

This screen displays

  • Information about Engine Driver

  • Information about the WiThrottle Server or DCC-EX Server it is currently connected to (if any)

  • A page of basic information about Engine Driver

Displayed information includes:

  • OS: (Android version)

  • SDK:

  • DeviceID:

  • IP: (of the device/phone)

  • SSID:

  • Net:

  • EngineDriver: (version)

  • Protocol: (WiThrottle or DCC-EX)

  • Heartbeat:

  • Host: (IP Address) Port:

  • Server: (details)

Reconnecting Screen

../_images/reconnecting_screen.png

This screen displays if Engine Driver has not been able to communicate with the WiThrottle Server or DCC-EX Server within a specified time.

Engine Driver will attempt to reconnect to the Command Station/Server.

Note

See the WiFi Issues page for more information on how to minimise disconnections.

Common Elements and Features

This section describes some of the elements and features that appear throughout or affect the entire Engine Driver app.

Theme / Styles

Themes provide different colours and textures to the buttons, backgrounds, sliders etc. for all the screens in Engine Driver. i.e. It changes the appearance of the entire app.

There are a number of themes to choose from:

Example

Theme

../_images/throttle_horizontal_original_theme.png

Original theme

../_images/throttle_horizontal_high_contrast_theme.png

High contrast theme

../_images/throttle_horizontal_outline_theme.png

High contrast

../_images/throttle_horizontal_dark_theme.png

Dark theme

../_images/throttle_horizontal_colorful_theme.png

Colourful theme

../_images/throttle_semi_realistic_neon_blue_theme.png

Neon Blue theme

Note

See the Theme / Style preference on the preferences page for more information.

Localisation

Changing the Localisation primarily changes the language used in the menus, buttons and messages throughout Engine Driver.

Supported localisations are:

  • Use Phone’s global setting

  • English (US) - Engine Driver’s default

  • English (UK)

  • English (AUS)

  • English (NZ)

  • Italian

  • Portuguese

  • German

  • Spanish

  • Catalan

  • French (FR)

  • French (CA)

  • Czech

  • Japanese

Note

See the Localisation preference on the Preferences page for more information.

Action Bar

../_images/action_bar.png

The Action Bar appears at the top of all screens. It will show different information and different buttons depending on a) the particular screen and b) preferences you have set.

The Action Bar can display:

  • The app name (Engine Driver)

  • Optionally configured information:

  • Optionally configured buttons:

    • Emergency Stop (EStop)

    • Track Power

    • Flashlight

    • Throttle Web View

    • Throttle Layout Switching

    • In Phone Loco Sound

    • DCC-EX

    • Children’s Timer

The optional buttons are enabled and configured via the corresponding preferences in the Throttle Screen Action Bar preference group. (Other than the Children’s Timer which is configured in the Children’s Timer preference group.)

Emergency Stop Button

../_images/estop.png

Clicking this button will attempt to quickly stop all locos controlled by the device / phone. Locos controlled by other people/devices are not stopped.

The Emergency Stop Action Bar button is enabled with the Emergency Stop button? preference.

Track Power Button

../_images/power_green.png

Track Power, when pressed will turn on/off the power to the track. The colour of the button will change colour:

  • ‘Amber’ = unknown state

  • ‘Red’ = Power is Off

  • ‘Green’ = Power is On

The Track Power Action Bar button is enabled with the Layout Power button? preference.

Flashlight Button

../_images/flashlight_on.png

Flashlight, when pressed will turn on/off the Device’s camera light.

The device / phone must have a camera to be able to use this feature.

The Flashlight Action Bar button is enabled with the Flashlight button? preference.

Throttle Web View Button

../_images/web_view.png

Throttle Web View, when pressed will show or hide the Throttle Web View panel on the Throttle Screen.

The Throttle Web View Action Bar button is enabled with the Throttle Web View button? preference.

Note: the Throttle Web View? preference must be enabled for this to have an effect.

Layout Switch Button

../_images/throttle_switch_button.png

The Layout Switch button, when pressed will swap the Throttle Screen Layout between two predefined layouts.

The Layout Switch Action Bar button is enabled with the Show Layout Switch button preference.

DCC-EX Button

../_images/dcc_ex_button.png

The DCC-EX button, when clicked will open the DCC-EX Screen.

The DCC-EX Action Bar button is enabled with the DCC-EX button? preference and is only available when connected to a DCC-EX EX-CommandStation using the Native DCC-EX Protocol.

In Phone Loco Sound Button

../_images/in_device_sounds_outline.png

In Phone Loco Sounds, when clicked will open the In Phone Loco Sounds Screen.

The In Phone Loco Sounds Action Bar button is enabled with the In Phone Loco Sounds Button preferences.

Children’s Timer Button

../_images/timer.png

The Children’s Timer Button, when pressed will activate the Timer for the preset time period.

The Children’s Timer Button Action Bar button is enabled with the Show Timer button? preference.

Note

See the Children’s Timer section of the Advance Operation page for more information.

Fast Clock

../_images/fast_clock.png

The Fast Clock is a non-real time clock used for compressing running times for scheduled running.

JMRI and some DCC Command Stations can broadcast a Fast Clock time continuously. Enabling this preference will cause Engine Driver to display the Fast Clock time on the Action Bar.

The Fast Clock Action Bar button is enabled with the Fast Clock Display preference.

Note

See JMRI’s Fast Clock page for information on how to set up a Fast Clock.

Children’s Timer Status and Countdown

../_images/childrens_timer_countdown.png

Todo

LOW: Children’s Timer Status and Countdown

Note

See the Children’s Timer part of the Advance Operation page for more information.

Full Screen or Action Bar Only left/right swipe

By default swiping left or right (almost) anywhere on a Main Screen will cause ED to take you one of the other Main Screens.

While this is dependant on which screens you have enabled for swiping through, it can also be changed so that the swipe only works on the Action Bar. This is mostly advantageous when you use the Web View Screen where left/right swipes may ahve a different meaning or purpose.

This option is also enabled/disabled in the Left/Right Swipe Preferences.

WiThrottle Server Name

../_images/action_bar_server_name.png

Engine Driver can be configured to show the server name on the Action Bar. This option is also enabled/disabled in the Show Server Description preference.

Overflow Menu

../_images/menu_throttle.png

The Overflow Menu (or simply ‘Menu’) appears in the Action Bar at the top of most of the main screens is normally three dots (⁞) or three bars (≡). It will show different options depending on a) the particular screen, b) preferences you have set and c) the state of certain elements in the app.

The Overflow Menu can display: