Contributing
Contributing to the Code
Engine Driver is open source software written in Java. The source code is available on github.com/JMRI/EngineDriver.
It is recommended that you contact M Steve Todd if you intend to contribute to the code base, before you start working.
On the Android device you intend to test on
Make sure that the developer options are enabled and
Android debuggingis on, andunknown sourcesis on. You can also use the Virtual Devices in Android Studio to test you cade.
Here are all the steps needed for Microsoft Windows:
On GitHub
Clone the JMRI/EngineDriver repository. (See Cloning a repository in GitHub)
Create a Personal Access Token that will allow you remotely update your repository. See [here] for details. Copy the full code of the token somewhere as you will need it later.
Install Android Studio.
Open Android Studio
(If necessary, close any open project and restart, so you get the Welcome Wizard)Select
Check out project from Version control-> GitIn the Clone Repository window, enter the Git Repository URL:
https://github.com/JMRI/EngineDriver, ->Clone.
Note this is the original repository, not your clone.Open the project.
Only if needed…
Take the Run -> Run… -> Edit Configurations option
In the Run/Debug Configurations window, press the “+”, then Android App
Enter Name “EngineDriver”, and select Module: EngineDriver
Click
Run.You will likely get one or more error messages about missing components. Click on the link in each message and Android Studio will automatically download the missing components.
To test your changes:
Connect your phone via USB
In the Select Deployment Target window, your attached phone should show under Connected Devices.
Select your device and press
runordebug.EngineDriver should compile and be installed on your device.
To publish your changes:
Android Studio, commit and push your changes to your own GitHub repository..
To do this you will need to define a new remotehttps://github.com/<your name>/EngineDriverGo to GitHub and issue a pull request for your branch to be pulled into the original repository. Once it’s merged in by one of the admins, your changes will go live!
Contributing to the Localisation (Languages)
We are always looking for people to help with maintaining and expanding the non-English versions of the text in the code.
It is possible to do so via the methods described in Contributing to the Code but if you are not a developer this can be daunting.
If you are interested in helping with this please please contact the developers and we can provide a simpler way to contribute.
Contributing to the Documentation
This documentation is open source and can be accessed on github.com/flash62au/EngineDriver_Home
All this documentation is done using reStructuredText, for which you can find information on the official website: reStructuredText or the Sphinx document builder tool website. reStructuredText is a markdown type language, for typesetting documents from websites to PDF or LaTeX documents. This Website is built upon this technology, so you should make yourself familiar with this by looking through the links provided.
reStructuredText QuickReference Guide
The steps listed here provide guidance on how to edit and preview changes to the documentation.
You need to install a number of tools on you local machine:
An appropriate text editor.
For Windows we recommend the free Visual Studio Code IDE (VSC).If using VSC, we recommend installing the
reStructuredText Syntax highlightingextension.
A version of Git.
For Windows we recommend the free GitHub Desktop.A current version of ‘Python 3’ (which also installs ‘pip’).
The Microsoft Store contains Python published by the Python Software Foundation for Windows.
Then use ‘pip’ to install the required packages; ‘sphinx’ and the theme ‘sphinx_rtd_theme’.
Open and command prompt and enter:pip install -U sphinxpip install sphinx-rtd-theme
On GitHub
Clone the
https://flash62au.github.io/EngineDriver_Homerepository. (See Cloning a repository in GitHub)Open the your repository settings (the gear icon), go to the ‘Pages’ section and change the ‘source-branch’ to
gh-pages/ (root).Your repository must be
public
On your PC
Using GitHub Desktop, clone your repository to your local machine
Edit the files in the
EngineDriver_Home/docsfolderSave, then check and preview your changes by running
make githubfrom the root of theEngineDriver_Homefolder. 1
This must be done fromcmd.exein Windows, notPowerShell.
If any warnings are reported, fix these and run make GitHub againPreview your changes locally by going to your local directory
EngineDriver_Home/docs/_build/htmland openindex.htmlin your web browser of choice.Use GitHub Desktop to commit and then push your changes
In GitHub
You can check the ‘actions’ to see if it built correctly.
You can preview the pages on GitHub athttps://<yourname>.github.io/EngineDriver_HomeIssue a pull request for your branch to be pulled into the main branch.
Once it’s merged in by one of the admins, your changes will go live!
- 1
There is a batch file
make github.batin theEngineDriver_Homefolder which should be able to be double-clicked on the run this command. It will pause at the end to allow you see if there are any issues.
Style Guidelines
Use British/Australian/Canadian spelling e.g. ‘colour’ not ‘color’.
(Primarily because it is used in more English speaking countries)Use railroad/railway terminology that is understandable by all English-speaking people.
Where there are clear differences from US to non-US terminology use both with a slash between and use the US version first. e.g. turnouts/points, consists/multiple units, switching/shunting. (Primarily because JMRI uses the US terminology)In general use ‘loco’ instead of ‘locomotive’ or ‘engine’
Avoid the term ‘Checked’. Use ‘Enabled’ instead. (“Checked’ is more a US term.)
Use bolded **Engine Driver** or |ed| not ‘Engine Driver app’, ‘EngineDriver’ or ‘Engine Driver Throttle’ (except on the first page) - Engine Driver
No full stop at the end of a numbered or unnumbered list
Numbered lists should be avoided, unless there is a specific need
Use first person (you and your; not I, me, my or am) language
A string of nouns should be sequenced in alphabetic order, unless it makes more sense within the context to display them in some other sequence
Double quotes (”) should only be used for quoting text from people, documents or web sites
No quotes around ‘Also See’ type references
Avoid ‘(above)’ or ‘(below)’ in text. Use hypertext links instead
‘TODO’ or |todo| or .. todo:: in the text means that it is still a work-in-process and needs to be updated. It may be followed by descriptive text in italics describing the issue to be fixed
Use ``literal text blocks`` when describing preference values -
literal text blocksUse :menuselection:`Menu –> Preferences –> ..` for menu descriptions -
Use :guilabel:`GUI labels` for buttons - GUI labels
Avoid using ‘phone’ alone. Preferably use ‘Android device/phone’
For dates, use dd-mmm-yyyy or yyyy-mm-dd to avoid confusion with the way dates are uniquely written in the US.
e.g. 2-Mar-2022 or 2022-3-2, not 2-3-2022Heading levels:
######### with overline, for parts - not really used
************ Page Titles
========= for sections
--------------- for subsections
^^^^^^^^^ for subsubsections
""""""""""""""" for paragraphs
''''''''''''''''''''''''''' for sub paragraphs
TODO
Todo
Conserving Power
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/conserving_power.rst, line 12.)
Todo
Function Buttons
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/functions.rst, line 9.)
Todo
DCC Functions
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/functions.rst, line 14.)
Todo
Linking Functions to IPLS buttons
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/functions.rst, line 32.)
Todo
Functions and Gamepads
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/functions.rst, line 37.)
Todo
Advanced Consist Function Mapping
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/functions.rst, line 43.)
Todo
Bell, Horn/Whistle
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/ipls.rst, line 38.)
Todo
Maximum throttle Change Can’t remember when this is used.
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 861.)
Todo
Consist Functions - Follow Rule Style
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 945.)
Todo
Selective Lead Unit Sound?
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 964.)
Todo
Always treat F1 as Sound?
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 973.)
Todo
Always treat F2 as Sound?
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 980.)
Todo
If All matches Fail Action
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 987.)
Todo
Headlight specific String 1
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 996.)
Todo
Headlight specific Action 1
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1005.)
Todo
String 2, 3, 4, 5
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1014.)
Todo
Action for String 2, 3, 4, 5
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1021.)
Todo
Only One Gamepad?
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1099.)
Todo
Manual host specific import/export
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1850.)
Todo
Advanced Operation
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/advanced.rst, line 18.)
Todo
Consist Follow Functions
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/advanced.rst, line 24.)
Todo
Direction Buttons
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/advanced.rst, line 32.)
Todo
Renaming Direction Buttons
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/advanced.rst, line 38.)
Todo
Swapping Direction Buttons
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/advanced.rst, line 43.)
Todo
Conserving Power
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/advanced.rst, line 53.)
Todo
Selecting locomotives to control
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 122.)
Todo
How do I work with Consists
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 130.)
Todo
DCC ‘Advanced Consists’ (CV19)
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 138.)
Todo
JMRI Consists
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 144.)
Todo
Hiding the title bar and navigation bar
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 298.)
Todo
Immersive mode (Full Screen)
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 303.)
Todo
Swiping up or Down
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 308.)
Todo
Showing the web page at the bottom of the throttle screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 315.)
Todo
Loco selection screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 326.)
Todo
Locos in the roster not showing
A1. check you don’t have a filter
A2. ???
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 333.)
Todo
Changing the turnouts screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 352.)
Todo
As of version 4.???, by default Engine Driver assumes you will only use 1 gamepad. To allow for more than one you must…
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/gamepads.rst, line 92.)
Todo
If you turn the gamepad off…
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/gamepads.rst, line 98.)
Todo
Not Recommended Gamepads
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/gamepads.rst, line 156.)
Todo
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 roster, which can be individually specified for each loco in the 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 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. This is also trun if the loco is selected from the Recent Locos list or the Recent Consist/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 Default Functions.
The behaviour of the Function Buttons for locos selected from the WiThrottle Server roster can be overridden with the Use default function labels? preference. If this is enabled, the locos selected from the WiThrottle Server roster will also show the Default Functions labels.
Clicking on any 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 differnt 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 Roster Entries you need to edit the Function buttons in the WiThrottle Server, or configure Engine Driver to use the default labels.
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 334.)
Todo
Pause and Limit Speed buttons
The Function Button area can also show: * Pause * Limit Speed
These are optional buttons
Note
See the ‘Limit Speed’ & ‘Pause’ button Preferences section on the Preferences page for more information on these buttons.
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 366.)
Todo
In Phone Loco Sounds buttons
The Function Button area can also show the IPLS buttons (In Phone Loco Sounds)
These are optional buttons
Note
See the In Phone Loco Sounds (IPLS) page for more information on the IPLS buttons
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 384.)
Todo
Web View Area (Throttle Web View)
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 399.)
Todo
Immersive Mode (Full Screen)
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 505.)
Todo
Swipe Up / Down
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 526.)
Todo
Accelerometer (Shake)
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 531.)
Todo
Turnouts/Points Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 538.)
Todo
Turnouts/Points Screen - Entry
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 553.)
Todo
Routes Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 637.)
Todo
Routes Screen - Enter
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 645.)
Todo
Routes Screen - List
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 649.)
Todo
Routes Screen - Filter
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 661.)
Todo
Web View Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 744.)
Todo
Swipe Left / Right (Web View Screen)
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 835.)
Todo
Select by DCC Address
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 896.)
Todo
Select from Sever Roster
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 905.)
Todo
Select from Recent Locos List
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 924.)
Todo
Select from Recent Consists List
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 941.)
Todo
Consist Edit Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 997.)
Todo
Lead Loco
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1008.)
Todo
Trailing Loco
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1013.)
Todo
Consist Top
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1018.)
Todo
Consist Lights Edit Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1032.)
Todo
In Phone Loco Sounds Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1092.)
Todo
Function Defaults Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1112.)
Todo
Gamepad Test Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1127.)
Todo
View Log Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1145.)
Todo
About Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1167.)
Todo
Reconnecting Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1183.)
Todo
Layout Switch Button
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1351.)
Todo
In Phone Loco Sound Button
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1361.)
Todo
Fast Clock
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1394.)
Todo
Children’s Timer Status and Countdown
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1412.)
Todo
Full Screen or Action Bar Only left/right swipe
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1424.)
Todo
WiThrottle Server Name
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1433.)
Todo
Turnouts / Points
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/operation.rst, line 637.)
Todo
DCC Address
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/operation.rst, line 670.)
Todo
JMRI Defined Turnout/Point list
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/operation.rst, line 680.)
Todo
Recent Turnout/Point list
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/operation.rst, line 693.)
Todo
Routes
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/operation.rst, line 716.)
Todo
Wrong Network
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/wifi_issues.rst, line 22.)
Todo
Firewalls
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/wifi_issues.rst, line 35.)
Todo
Disconnections
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/wifi_issues.rst, line 63.)
Todo
Connecting
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/videos/index.rst, line 17.)
Todo
Turnouts/Points and Routes
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/videos/index.rst, line 57.)
Todo
Server Specific Preferences
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/videos/index.rst, line 70.)
Todo
Preserving the battery in your device
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/videos/index.rst, line 75.)