Stage 2 - Adding a Roster

What to expect to learn from stage 2 

At the end of this stage, we expect you will have learnt the following:

How add a Loco Roster, including function labels, to your EX‑CommandStation
How to add images for your locos (Engine Driver only)

Add a Loco Roster to your EX-CommandStation 

EX‑RAIL, the in-built automation capability in the EX‑CommandStation software also has the ability to store roster entries that can be served up to the various throttles.

To add a roster you need to:

create an ‘myAutomation.h’ file with roster entries in it
re-upload the software to the EX‑CommandStation

Create myAutomation.h

In a text editor (e.g. notepad) create a new text file named ‘myAutomation.h’. (Note the capital ‘A’ in the name. The case of all the characters is important.)

If you are already using EX‑RAIL and have a myAutomation.h, then just the add ROSTER(...) lines near the top of the file.

Add a line that looks like:

ROSTER(999,"Loco Name","F0/F1/*F2/F3/F4/F5/F6/F7/F8")

Where:

999 - is the DCC address of your loco
My Loco Name - is anything you want to see as the name of this loco in the throttle apps
F0 F1 F3 … F27. - are the names that you want to see for the functions specific to this loco
*F2 - note that if the function is ‘momentary’ rather than ‘latching’ (On/Off) then start the function label with a asterisk (*). The most common example of this is the Horn/Whistle which is commonly on F2.

Some more realistic examples might look like:

ROSTER (  3,"Eng 3", "F0/F1/*F2/*F3/F4/F5/F6/F7/Mute/F9//") // Address 3, Eng 3, Function keys F0-F10
ROSTER(1224,"PE 1224","") // Motor Only Decoder, But use Engine Driver 'Preferences >In Phone Loco 'Sound'
ROSTER(1225,"PE 1225","Lights/Bell/*Whistle/*Short Whistle/Steam/On-Time/FX6 Bell Whistle/Dim Light/Mute")
ROSTER(4468,"LNER 4468","//Snd On/*Whistle/*Whistle2/Brake/F5 Drain/Coal Shvl/Guard-Squeal/Loaded/Coastng/Injector/Shunt-Door ~Opn-Cls/Couplng/BrakeVlv/Sfty Vlv/Shunting/BrkSql Off/No Momentm/Aux3/Fade Out/F22 Res/F23/Res//Aux 5/Aux6/Aux7/Aux 8")

Note: Add additional ‘ROSTER(…)’ lines for all your locos

Unavailable Functions

If a function is not available leave the spot empty. (Don’t even have the space character.)

For example:

ROSTER(2825,"CN ES44AC","Headlight/Bell/*Horn/Coupler/Dynamic Brake///Flange Squeal/Startup & Shutdown")

Note the two missing text labels for positions F5 and F6. Engine Driver will skip those buttons and not display them at all in the interface since they do nothing for that loco.

Example of loco without sound:

ROSTER(2405,"AT&SF 2-8-0 2405","Headlight")

Note that it only has FO (the Headlight) and not following slashes.

Re-upload the EX-CommandStation software

Using EX-Installer

The EX‑Installer can make use of the config files from a ‘saved’ location.

If you have previously saved the config files…

At the end of the install process it will ask you if you want to save the config files. If you have said Yes (and put them in a folder well away from the EX-Installer folder) you can place your ‘myAutomation.h’ in that folder and rerun the EX‑Installer. the EX‑Installer will ask if you want to use existing config files. Just point it to where you saved and edited the file.

The Roster will be automatically loaded with the EX‑CommandStation software.

If you have not saved the config files…

Re-run the EX‑Installer. Select the same options that you originally chose and also select the create myAutomation.h and the Advanced config options. This will show a myAutomation.h window on the following page. Copy and paste your roster lines into this window then Compile and load the software.

After the load finishes you will be asked to ‘backup/save’ the config files. Say Yes and put them in a folder well away from the EX-Installer folder. You can can then make direct edits to the file there, and when you next run EX‑Installer, it asks if you want to use existing config files. Just point it to where you saved and edited the file.

The Roster will be automatically loaded with the EX‑CommandStation software.

More information on the config files can be found on the Managing config files with the Installer page.

Warning

Never edit any files in the EX-Installer folder. Editing any files in the EX-Installer folder will always cause EX‑Installer to fail.

Using the Arduino IDE

Place your ‘myAutomation.h’ file in the CommandStation-EX subfolder of wherever you extracted the EX‑CommandStation files from GitHub.
Run the Arduino IDE
Open the CommandStation-EX folder
Select the Board, COM port etc. as before
click Upload

The Roster will be automatically loaded with the EX‑CommandStation software.

Add images for your locos (Engine Driver only)

EX‑CommandStation does not natively support roster images, however several of the throttle (controller) apps allow you to do so. Only one will be explored here… Engine Driver.

Engine Driver

There are three ways to load & store your Locomotive Icon Image in Engine Driver 2.32.142 and above.

Automatically from your existing JMRI Roster & Media

If you have a JMRI Server that does support loco images:

Start JMRI and capture and load your images into JMRI Roster & Media panel as normal

Start the wiThrottle Server.

Start the Web Server.

Connect Engine Driver to JMRI wiThrottle Server Discovered Server ‘My JMRI Railroad’ or type in the IP address : Port#

Click Select and load your Locos then Release and repeat until you’ve loaded all the locomotives you require with Icons into a throttle.

These Loco Icons will automatically be saved/cached on the Android device/phone in a new ‘/Android/data/jmri.enginedriver/files/recent_engine_list/recent_engine_list’ folder for you.

Requirements for this to work:

Have identical names (from JMRI Roster ID to DCC-EX EX‑RAIL Roster ID) example ID; “PE 1225”

Have image icons displayed for the locomotives

Manually entered directly into your Android Engine Driver folder

Capture then rename the image exactly like the Roster ID name in JMRI & EXRAIL and save as a .PNG file

Then place the engine Image into your Android device/phone in the
‘/Android/data/jmri.enginedriver/files/recent_engine_list’ folder
example image name; PE 1225.png

Note: certain characters are not allowed in file names so need to be substituted with “_” (underscore) if you have used them in your roster name. They are:

/ (forward slash)

” (double quote)

\ (backslash)

* (asterisk)

? (question mark)

< (less than)

> (greater than)

Select an image on the phone/device (which can be taken on the phone’s camera)

In the Roster List on the Select Loco screen

Long press on the loco

press the New Image button, which will launch the Android system’s default app for choosing images

find and select an image

click Save

You can replace an image with the New Image button or remove it with the Remove button

General Notes on the Local Loco Icons:

If the loco already has an image in the JMRI Roster (of the currently connected wiThrottle Server), you won’t be able to choose a local image.
If you later add an image in the JMRI Roster for the loco (or later connect to a wiThrottle Server that has an image), it will automatically overwrite the local image with the one on the server.
In the Recent Locos list you can not add images to locos entered by a DCC address. (i.e. not from the roster)

Also refer to the Engine Driver Loco Icon Documentation for more information.