Contributing
Contributing to the Code
Engine Driver is open source software written in Java for Android. 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 code.
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 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 run or debug.
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/mstevetodd/EngineDriver_Home
All this documentation is done using reStructuredText and with Sphinx, for which you can find information on the official website: reStructuredText and 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 highlighting extension.
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 -r requirements.txt
On GitHub
Clone the
https://enginedriver.mstevetodd.comrepository. (See Cloning a repository in GitHub)Open your repository ‘Settings’ (the gear icon), go to the ‘Pages’ section and change the ‘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 runmake githubagainPreview 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!
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 DCC and 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 second person (you and your; not I, me, or my) language
A string or list 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 1149.)
Todo
Consist Functions - Follow Rule Style
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1238.)
Todo
Selective Lead Unit Sound?
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1257.)
Todo
Always treat F1 as Sound?
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1266.)
Todo
Always treat F2 as Sound?
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1273.)
Todo
If All matches Fail Action
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1280.)
Todo
Headlight specific String 1
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1289.)
Todo
Headlight specific Action 1
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1298.)
Todo
String 2, 3, 4, 5
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1307.)
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 1314.)
Todo
Only One Gamepad?
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 1407.)
Todo
Manual host specific import/export
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/configuration/preferences.rst, line 2224.)
Todo
Advanced Operation
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/advanced.rst, line 19.)
Todo
Direction Buttons
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/advanced.rst, line 35.)
Todo
Renaming Direction Buttons
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/advanced.rst, line 41.)
Todo
Swapping Direction Buttons
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/advanced.rst, line 46.)
Todo
Conserving Power
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/advanced.rst, line 56.)
Todo
‘Special Partial Matching’ Option
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 254.)
Todo
See the XXX page for more information.
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 303.)
Todo
‘If All matches Fail Action’ Preference
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 386.)
Todo
‘Headlight specific String 1’ Preference
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 395.)
Todo
‘Headlight specific Action 1’ Preference
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 403.)
Todo
String 2, 3, 4, 5 Preferences
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 425.)
Todo
Action for String 2, 3, 4, 5 Preferences
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 433.)
Todo
‘Special’ Consist Function Matching Options
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 444.)
Todo
‘Special - Exact Matching’ Option
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 456.)
Todo
‘Special Partial Matching’ Option
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 461.)
Todo
‘Special Partial - Contains Only’ Option
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/consist-follow-functions.rst, line 466.)
Todo
Selecting locomotives to control
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 123.)
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 131.)
Todo
DCC ‘Advanced Consists’ (CV19)
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 139.)
Todo
JMRI Consists
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 145.)
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 299.)
Todo
Immersive mode (Full Screen)
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 304.)
Todo
Swiping up or Down
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 309.)
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 316.)
Todo
Loco selection screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 327.)
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 334.)
Todo
Changing the turnouts screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/faq.rst, line 353.)
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 93.)
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 99.)
Todo
Not Recommended Gamepads
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/gamepads.rst, line 157.)
Todo
Pause and Limit Speed buttons
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 391.)
Todo
In Phone Loco Sounds buttons
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 411.)
Todo
Load Slider Area
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 427.)
Todo
Brake Slider Area
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 438.)
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 449.)
Todo
Immersive Mode (Full Screen)
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 565.)
Todo
Swipe Up / Down
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 603.)
Todo
Accelerometer (Shake)
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 626.)
Todo
Turnouts/Points Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 647.)
Todo
Turnouts/Points Screen - Entry
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 662.)
Todo
Routes Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 753.)
Todo
Routes Screen - Enter
You can enter the route ID…
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 761.)
Todo
Routes Screen - List
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 767.)
Todo
Routes Screen - Filter
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 781.)
Todo
Web View Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 871.)
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 968.)
Todo
Select from Sever Roster
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1030.)
Todo
Select from Recent Locos List
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1049.)
Todo
Select from Recent Consists List
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1066.)
Todo
Consist Edit Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1122.)
Todo
Lead Loco
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1133.)
Todo
Trailing Loco
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1138.)
Todo
Consist Top
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1143.)
Todo
Consist Lights Edit Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1157.)
Todo
In Phone Loco Sounds Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1217.)
Todo
Function Defaults Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1237.)
Todo
DCC-EX Function Settings Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1252.)
Todo
DCC-EX Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1261.)
Todo
Gamepad Test Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1272.)
Todo
View Log Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1290.)
Todo
About Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1312.)
Todo
Reconnecting Screen
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1328.)
Todo
Layout Switch Button
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1501.)
Todo
DCC-EX Button
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1510.)
Todo
In Phone Loco Sound Button
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1518.)
Todo
Fast Clock
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1551.)
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 1569.)
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 1581.)
Todo
WiThrottle Server Name
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/interface.rst, line 1590.)
Todo
DCC Address
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/operation.rst, line 658.)
Todo
JMRI Defined Turnout/Point list
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/operation.rst, line 668.)
Todo
Recent Turnout/Point list
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/operation.rst, line 679.)
Todo
Routes
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/operation.rst, line 702.)
Todo
Wrong Network
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/wifi_issues.rst, line 23.)
Todo
Firewalls
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/wifi_issues.rst, line 36.)
Todo
Disconnections
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/operation/wifi_issues.rst, line 61.)
Todo
Connecting
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/videos/index.rst, line 21.)
Todo
Turnouts/Points and Routes
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/videos/index.rst, line 61.)
Todo
Server Specific Preferences
(The original entry is located in /home/runner/work/EngineDriver_Home/EngineDriver_Home/docs/videos/index.rst, line 74.)
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 79.)