How to Add Locomotives to Your DCC-EX Roster – A Beginner's Guide

Once you have your DCC-EX command station connected and your first locomotive running, one of the most useful next steps is to create a locomotive roster, particularly if you have sound-equipped locomotives.

A roster allows you to identify locomotives by name rather than remembering their DCC addresses. More importantly, it lets you assign meaningful labels to your throttle's function buttons, such as Whistle, Horn, Engine Start, Brake or Coupling, making it much easier to access your locomotive's sound features without having to remember which function number does what.

Whether you have a sound-equipped locomotive or a standard DCC decoder, setting up a roster can make operating your model railway much more enjoyable.

In this beginner-friendly guide, we'll explain how locomotive rosters work with DCC-EX, the difference between a throttle application's locomotive list and a roster stored on the command station, and how to set up both.

These instructions apply to DCC-EX command stations, including the ACI CSB1 Express Command Station.

What is a DCC locomotive roster?

Every DCC locomotive has an address programmed into its decoder. This address allows the command station to send instructions to the correct locomotive.

For example, you might have three locomotives:

Without a roster, you would normally enter the DCC address each time you want to select a locomotive. With a roster, a compatible throttle can display a recognisable name, making selection much simpler.

Important: Adding a locomotive to a roster does not change its decoder address. The address stored in the roster must match the address already programmed into the locomotive.

Two ways to manage locomotives in DCC-EX

There are two main approaches, depending on how you want to operate your layout.

There is an important difference: selecting a locomotive by its DCC address in a throttle app lets you drive it, but does not necessarily create a named roster. If you want a shared list of locomotive names and function labels available to compatible throttles, you can create that roster on the DCC-EX command station.

Method 1: Using your throttle application

Some throttle applications allow you to maintain their own locomotive lists, recent locomotive selections or other locally stored information.

This is convenient for a single operator who primarily uses one phone or tablet. The available options depend on the application.

Applications commonly used with DCC-EX include:

• Engine Driver: An Android throttle with support for command station rosters, function labels and locomotive photographs.
• WiThrottle: An Apple iPhone and iPad throttle that can use compatible server rosters.
• ThrottleCard: An Apple throttle application offering locomotive control and roster-related features, depending on its version and configuration.

Not every application allows you to create and edit a complete named roster directly within the app. Some primarily display information supplied by the command station or a JMRI server.

Method 2: Creating a roster on the DCC-EX command station

DCC-EX also supports a shared locomotive roster using its built-in EXRAIL functionality.

With this approach, locomotive names and function descriptions are stored in the command station firmware and made available to compatible throttle applications.

This can be particularly useful for a club layout, a family layout or anyone who uses more than one phone or tablet.

Our recommendation: If you are just starting with DCC-EX, first become comfortable selecting and driving locomotives using your throttle. You can add a shared command station roster later when you are ready.

Method 1: Selecting and organising locomotives using a throttle app

Step 1: Connect your throttle to DCC-EX

Start by connecting your phone or tablet to your DCC-EX command station. If your throttle is already connected and working, you can skip this step.

If you have an ACI CSB1 using its standard Wi-Fi access point configuration, the network details are typically:

• Wi-Fi network: DCCEX_xxxxxx
• Password: PASS_xxxxxx

The exact network name and password depend on your configuration. Use the connection details supplied with your command station.

Open your throttle application and connect to the DCC-EX command station. Once connected, you should be able to access its locomotive controls.

If you need help with the initial connection, see our ACI Quick Start Guides.

Step 2: Select a locomotive by its DCC address

Most compatible throttle applications allow you to select a locomotive by entering its DCC address.

1. Open the locomotive selection screen in your throttle application.
2. Choose the option to select or enter a locomotive address.
3. Enter the address programmed into your locomotive's decoder.
4. Confirm the selection.
5. Check that the correct locomotive responds to your controls.

For example, if Flying Scotsman has decoder address 4472, enter 4472 to select it.

The locomotive should now be available to drive. Many throttle applications also remember recently selected locomotives, making it easier to select them again.

Remember: A recently used locomotive list is not necessarily the same as a permanent named roster.

Step 3: Use the roster features available in your app

How you name and organise locomotives depends on which throttle you use.

Engine Driver (Android)

Engine Driver can display locomotive names and function labels supplied by a DCC-EX command station roster or a compatible JMRI server.

To use an existing command station roster:

1. Connect Engine Driver directly to your DCC-EX command station.
2. Open the locomotive selection screen.
3. Choose the server roster option, if a roster is available.
4. Select the locomotive by its name or running number.

If no server roster is configured, you can still select a locomotive manually by its DCC address.

WiThrottle (iPhone and iPad)

WiThrottle can use locomotive roster information provided by a compatible WiThrottle server, including a DCC-EX command station with an EXRAIL roster.

After connecting to the command station, check the locomotive selection options for an available server roster.

If no roster is available, you can continue selecting locomotives using their DCC addresses. The options for saving names and other information depend on the WiThrottle version.

ThrottleCard (iPhone and iPad)

ThrottleCard is another option for Apple users. Its locomotive selection and organisation features depend on the application version and how it is connected.

Check the app's locomotive or roster management options for available naming, storage and synchronisation features.

For app-specific instructions, consult the application's own documentation or support resources.

Method 2: Creating a shared DCC-EX locomotive roster

If you want your locomotive names and function descriptions to be available from the command station itself, you can create a roster using EXRAIL.

EXRAIL is part of the DCC-EX command station software. Although it is widely used for layout automation, it also provides a straightforward way to define locomotive roster entries.

Before continuing: This method requires editing configuration files and uploading the command station firmware again. It is not necessary simply to drive a locomotive. If your CSB1 is already working correctly, save your existing configuration before making changes.

Step 1: Make a note of your locomotive details

Start by preparing a simple list of the locomotives you want to add.

Make sure the addresses are correct. If you are unsure of a locomotive's decoder address, check its existing programming information before proceeding.

Where do I find the sound functions? Sound-equipped locomotives and sound decoders normally come with a function list or function mapping sheet. This identifies which button (F0, F1, F2 and so on) operates each sound or lighting effect. Check the paperwork supplied with your locomotive or decoder, or the manufacturer's instructions online. The assignments vary between decoders and sound projects, so use your locomotive's actual function list rather than copying the examples below.

Step 2: Understand the ROSTER command

DCC-EX uses the following EXRAIL command to define a locomotive:

ROSTER(4472,"Flying Scotsman","Lights/Sound/*Whistle")

This example contains three parts:

• 4472: The locomotive's DCC address.
• Flying Scotsman: The name displayed by compatible throttle applications.
• Lights/Sound/*Whistle: The labels assigned to the locomotive's function buttons.

The function labels are separated by forward slashes. The first entry represents F0, the second F1, the third F2, and so on.

The asterisk before Whistle means that the function is momentary, rather than an ordinary on/off function. A compatible throttle uses this information to determine how the function button behaves.

Important: These are example function assignments only. Your decoder may use different function numbers. Always check the decoder's instructions and use the correct function mapping for your locomotive.

Step 3: Add your locomotives to myAutomation.h

DCC-EX stores EXRAIL definitions in a file called myAutomation.h.

The filename is case-sensitive, so the capital A must be retained.

For example, a small roster might contain:

ROSTER(4472,"Flying Scotsman","Lights/Sound/*Whistle")
ROSTER(4468,"Mallard","Lights/Sound/*Whistle")
ROSTER(37025,"Class 37","Lights/Sound/*Horn")

Each ROSTER line represents one locomotive. You can add more entries as your collection grows.

If you already use EXRAIL for points, routes or other layout functions, add the roster definitions to your existing myAutomation.h file rather than replacing its contents.

Step 4: Upload the roster using EX-Installer

The recommended method for most users is the official DCC-EX EX-Installer.

New to updating your command station? If you have never updated or reinstalled the DCC-EX firmware before, we recommend reading our ACI Getting Started and Quick Start Guides before continuing.

Before you begin: Download the default configuration files for your ACI CSB1 command station from our ACI CSB1 Configuration Guide and keep a backup. These contain the settings required for your hardware and provide a starting point when adding your locomotive roster.

Once you are familiar with the update process and have your configuration files ready, follow these steps:

1. Connect your command station to your computer using its USB connection.
2. Open EX-Installer.
3. Select the appropriate command station software version and configuration.
4. Choose the option to use your existing configuration files, selecting the ACI CSB1 files you downloaded or your previously saved working configuration.
5. Open the advanced configuration editor and add your ROSTER entries to the existing myAutomation.h file.
6. Check the configuration carefully before compiling and uploading the firmware.
7. Once the upload is complete, reconnect your throttle and check that your locomotives appear in the roster.

Important: Do not replace your ACI CSB1 configuration with generic DCC-EX settings. Always retain the correct hardware configuration, particularly the motor driver and Wi-Fi settings.

For additional information, refer to the official DCC-EX guide to managing configuration files with EX-Installer.

Troubleshooting: Firmware Compilation Errors

Before compiling and uploading your updated DCC-EX firmware, take a moment to check your configuration carefully. Even a small typing mistake can cause the compilation to fail.

If EX-Installer reports a compilation error after adding your locomotive roster, check the following common mistakes:

1. Check capitalisation: EXRAIL commands are case-sensitive. The command ROSTER must be written entirely in uppercase. For example, roster, Roster or ROST will not work.
2. Check double quotation marks: Locomotive names and function descriptions must be enclosed in straight double quotation marks ("). Make sure every opening quotation mark has a matching closing quotation mark.
3. Check commas: Each part of the ROSTER command must be separated by a comma. Missing commas will prevent the command from compiling correctly.
4. Check brackets: Every ROSTER command must begin with an opening bracket ( and end with a closing bracket ).

For example, a correctly formatted roster entry looks like this:

ROSTER(4472,"Flying Scotsman","Lights/Sound/*Whistle")

Tip: If you have added several locomotives and the firmware fails to compile, check each ROSTER entry individually. Comparing your entries with the example above can often reveal a missing character or typing mistake.

If the problem persists, review any error messages displayed by EX-Installer. These may help identify where the problem occurs.

Remember: Do not upload firmware until it has compiled successfully.

If you are unable to resolve a compilation error, please email wecare@acimodelrailways.co.uk for assistance. Where possible, attach your myAutomation.h file and a copy or screenshot of the compilation error shown by EX-Installer. This will help us identify the problem and provide the appropriate guidance.

Step 5: Check the roster in your throttle application

Once the updated firmware has been uploaded successfully:

1. Reconnect your phone or tablet to the command station.
2. Open a compatible throttle application.
3. Refresh or reopen its locomotive selection screen if necessary.
4. Look for the server roster or locomotive roster option.
5. Select one of the locomotives you added.

Instead of selecting only a number, you should now be able to choose the locomotive by its roster name, provided your throttle supports displaying the command station roster.

Depending on the application, its function buttons may also display the descriptions you configured.

Can I add photographs of my locomotives?

Yes, some throttle applications support locomotive photographs, but there is an important distinction.

The DCC-EX command station roster stores locomotive names and function information, not photographs. Images are handled separately by the throttle application or by software such as JMRI.

Adding photographs in Engine Driver

Engine Driver supports locally selected locomotive images for roster entries.

1. Connect Engine Driver to a server that provides a locomotive roster.
2. Open the roster list on the locomotive selection screen.
3. Press and hold the locomotive entry.
4. Select New Image.
5. Choose a suitable photograph from your Android device.
6. Save the image.

These instructions apply to supported Engine Driver versions. Images associated with a JMRI roster may take precedence over locally selected images.

For more information, see the official DCC-EX roster and locomotive image guide.

For WiThrottle and ThrottleCard, check the image features available in your particular application version. Photographs are not automatically transferred from the DCC-EX command station.

Understanding locomotive function labels

Many DCC locomotives have additional functions for lights, sound, horns, whistles and other effects.

These functions are identified by numbers such as F0, F1, F2 and F3.

With a roster, you can give these buttons more meaningful labels.

These are illustrative labels, not a universal decoder configuration. Different manufacturers and sound projects may assign completely different functions.

For example:

ROSTER(4472,"Flying Scotsman","Lights/Sound/*Whistle/Brake/Coupling")

Here the whistle is marked as momentary using an asterisk.

What if a locomotive has unused function keys?

Not every locomotive uses every available function key. Some sound decoders have unused functions, while others may have functions you simply don't need to display.

For example, consider a Class 37 locomotive with the following function assignments:

To create this roster entry, simply leave the unused function label empty:

ROSTER(37025,"Class 37","Lights/Engine Sound/*Horn//Cab Light")

Notice the two forward slashes (//) between Horn and Cab Light. These indicate that F3 has no label, allowing Cab Light to remain correctly assigned to F4.

Important: Do not remove the separator for an unused function in the middle of the list. Otherwise, all subsequent function labels will move down by one function number.

This is particularly useful for sound-equipped locomotives, where function assignments vary considerably between decoder manufacturers and sound projects.

For a locomotive without sound, you might use:

ROSTER(123,"Class 08","Lights")

Only F0 is labelled in this example.

Remember that roster function labels do not reprogram the decoder. They describe the functions already available at the corresponding DCC function numbers.

Frequently asked questions

Do I need a roster to run my locomotives?

No. You can operate a locomotive simply by selecting its DCC address in a compatible throttle. A roster is an optional convenience that makes locomotive selection and function identification easier.

Will adding a locomotive to the roster change its DCC address?

No. Creating a roster entry does not change the decoder's programmed address. The roster entry must use the locomotive's existing DCC address.

Can I use the same roster on multiple phones or tablets?

Yes. A roster stored in the DCC-EX command station can be made available to multiple compatible throttles. This is one of the main advantages of using the shared EXRAIL roster.

Why can't I see my locomotive's name?

Check that your throttle is connected to the correct command station or server, that a server roster has been configured and that the throttle supports displaying it.

If you have just updated the roster, try disconnecting and reconnecting the throttle to refresh its information.

Can I add locomotives using only an iPad?

You can select and control locomotives from a compatible iPad throttle without using a computer.

However, creating or changing an EXRAIL roster stored in the command station normally requires editing the configuration and uploading the firmware using EX-Installer on a suitable computer.

For someone who simply wants to operate locomotives, there is no need to change a working command station configuration.

Can I add more locomotives later?

Yes. You can add additional ROSTER entries to myAutomation.h and upload the updated firmware again. Remember to retain your existing configuration and keep a backup.

Making DCC-EX easier to use

A locomotive roster is a simple way to make your model railway more enjoyable, particularly as your collection grows.

Instead of remembering decoder addresses, you can select familiar locomotive names and, with a suitable throttle, use clearly labelled function buttons and photographs.

If you are new to DCC-EX, we recommend starting with the basic locomotive selection features in your chosen throttle. Once you are comfortable operating your railway, you can decide whether a shared command station roster would be useful.

Further help and useful resources

• ACI Model Railways Quick Start Guides
• ACI CSB1 Configuration Guide
• Official DCC-EX: Adding a Locomotive Roster
• Managing DCC-EX Configuration Files
• DCC-EX Community Support

Need help with your DCC-EX setup?

At ACI Model Railways, we specialise in ready-to-run DCC-EX command stations and accessories, with UK-based support to help you get the most from your model railway.

Whether you are running your first DCC locomotive or expanding an existing layout, we're happy to help with questions about our products.

Explore ACI DCC-EX Command Stations →

Contact ACI Model Railways for assistance →