Throttle: Open/Configure a Throttle Window
Author: Paul Fraker (paul@frakers.com)
Description: Throttle documentation for JMRI project
Keywords: JMRI decoderpro dcc nmra throttlepro

# Current Throttle documentation

Please note that the Throttles Help was updated. Current version:

- The Throttle menu in JMRI
- The Throttle Window itself
- The Throttle Window menus
- The Throttle Window toolbar
- The Throttle Window controls
- The Throttles List Window
- The Throttles preferences pane

# Throttles in JMRI v2.x

## Open a New Throttle Window

This chapter will walk you through the process of opening up a new throttle window and then configuring it to run a locomotive on your layout. For the purposes of this user guide, we will be using a locomotive that has been equipped with a sound decoder. The decoder's address in our examples here is 8251. If you are following along with a locomotive of your own while you read this, simply replace your loco's decoder address anywhere that "8251" is shown.

So let's get started.

Figure 2-1: New Throttle Menu Option |  | The first thing that we want to do is to open up a throttle window. As outlined in the previous chapter, this is accomplished by selecting the following menu options from the primary main window: Tools Throttles New Throttle

### Structure of a Throttle Window

There are three panels (or sub-windows) associated with each Throttle window. These are identified as:

- Control Panel contains a throttle slider to control the speed of the loco, a forward and reverse selector, an Emergency Stop action button, and an Idle action button (mostly used for sound equipped decoders).
- Function Panel is used to associate the function buttons with the active output functions of the decoder.
- Address Panel is used to identify the decoder's address, and to dispatch or release the identified address.

Important! These three panels are actually windows defined within an overall window. Please note that each of these panels contain their own "minimize" and "close" buttons - as well as can also be resized. You can actually minimize one or more of these panels within the Throttle window. This is being pointed out in event that you accidentally click on one of the buttons and the panel disappears on you.

Figure 2-2: New Throttle Window

## Configure The New Throttle

Now that we have successfully opened up the throttle window, the next thing we need to do is to configure the throttle for operation. We'll do this in two steps. The first will be to assign a locomotive's decoder address. Please note in Figure 2-2 above that all of the panels are pretty much disabled. This is because there is no address assigned yet. After establishing an address, the other options on the panels will become enabled.

### Assign a Decoder Address to a Throttle

The first thing that needs to happen before any options or buttons in the window become active, is to assign a decoder's address in the "Address Panel". There are two ways that this can be accomplished. Manually enter the decoder's address in the large text box, then click on the "Set" button. Important! When manually entering an address, be sure to click on the Set button. Without this step, all throttle actions remain disabled. Or, use the drop down list to select from the roster list (as shown in the figure on the right). Please note that when you select a loco from this list, it simply reads the decoders address from the roster file - it currently does not cross reference this to any saved throttle layout files. |  | Figure 2-3: Address Selection
After an address is selected, all other controls and options in the throttle window will become enabled. Two other option buttons also become active in the "Address Panel". These are described as... Dispatch releases the decoder address back to the command station in a "dispatch" mode. Usually, only one address can be in dispatch state at the command station - all others are either "in use" or "idle" (released). The controls and options in the throttle window will become disabled until another address is "Set". Release releases the decoder address back to the command station as "no longer needed". The controls and options in the throttle window will become disabled until another address is "Set". |  |

| Figure 2-4: Address Panel (with an active address)

## Control Panel - Let's Run a Train

Now that you have established an address for the throttle, you should be able to run the train on your layout (if your layout is active and the address you entered is valid to a locomotive on the track). You do this using the "Control Panel" (see Figure 2-5). But here is where things get a little sticky. There are multiple combinations of DCC systems and computer platforms that make up for slight differences in the functionality of the throttles. The programmers are working hard at trying to get these throttles to function identically. But because of these differences, you may discover that not everything noted in the following text will function as defined for your system. Important! The "Control Panel" must have the "focus" for it to become active (and usable). In other words, it's window bar must be active. If you are following along with this text with your own locomotive and just entered an address in the Address Panel, you will discover that the Address Panel is the window with the current focus. None of the keyboard or mouse actions described below will move the train until the Control Panel has the focus. To make the Control Panel the active window, use your mouse pointer to click somewhere within the Control Panel. |  | Figure 2-5: Control Panel

Beware of where you click with your mouse pointer in the Control Panel. If you click anywhere near the slider, your loco may take off on you unexpectedly (more on this below). If you click anywhere on the words "Forward" or "Reverse", you will activate that action - which isn't too bad - except if the loco is running in the opposite direction from what action you clicked on. Depending on your screen resolution size, if you attempt to click on the window bar itself, you may accidentally close down the Control Panel window or minimize it. This could of course immediately confuse any new user. So when first clicking in the Control Panel to make it the "active" window with the focus, and you know that your loco is stopped, it is suggested to click on the "Idle" button (if you know for fact that your loco is stopped), or the forward or reverse area (depending of course on the current direction of the loco). In other words, you want to click somewhere within the border of the Control Panel window, yet not cause your loco to do something that you don't want it to do. After a little experimentation, you will discover what is comfortable for your usage. The only point we are trying to make here is that many new users immediately get frustrated with the throttles because they can't get their loco to move, not realizing that the Control Panel does not have the focus. Or they have clicked on a function button (more on these below), which then changes the "active" window to the Function Panel.

### Keyboard Throttle Control

There is a group of keyboard action keys that have been defined as "standard" across all DCC systems and computer platforms. They are identified in the following table:

KEY* | ACTION
+ | Increase speed by 1 step of each press of the key
- | Decrease speed by 1 step of each press of the key
* | Idle (set speed to 0, any speed momentum is enabled)
/ | Emergency Stop! (instantly halts the locomotive)
Up arrow | Forward direction
Down arrow | Reverse direction
Left arrow | Increases speed by 1 step for each press of the key
Right arrow | Decreases speed by 1 step for each press of the key
Page Up | Increases speed by approximately 10% for each press of the key
Page Down | Decreases speed by approximately 10% for each press of the key

Note: The implied keys noted above (with the exception of the arrow keys) are those found on the numeric keypad of the keyboard. For laptops and other keyboards that don't have a separate numeric keypad, experimentation on your part may be needed to find the correct key combination. The arrow keys are usually found grouped in their own separate area.

Using the standard key actions are pretty easy. After making the Control Panel have the active focus, each click of the + on the numeric keypad should increase the speed on your locomotive. Each click of the - key on the numeric keypad should decrease the speed of your locomotive. To bring the locomotive to a stop, a single click of the / key on the numeric keypad will set the speed of the locomotive to zero.

Of course, in addition to the standard keyboard actions, what is the point of having a mouse if you can't use the mouse to control your trains. So now let's discuss how to move your locomotive using the mouse on your computer.

### Mouse Control

You can perform all of the keyboard actions noted above by using your mouse pointer within the Control Panel window. We'll start by defining the Forward, Reverse, Stop and Idle controls. They are pretty simple to use.

BUTTON | ACTION
Forward | Changes the direction of the locomotive to forward.
Reverse | Changes the direction of the locomotive to reverse.
STOP! | Clicking on this button will perform an immediate physical stop of the locomotive. If any braking momentum feature is enabled for the decoder, it will be ignored halting the locomotive immediately. When using a sound decoder (such as a Soundtraxx DSD-150), and the decoder has a "sound shutdown action" (like in the diesel decoders), the associated engine shutdown sound will occur.
Idle | Clicking on this button will set the speed of the locomotive to 0. If any braking momentum feature is enabled for the decoder, it will still be active and slow the locomotive down to a stop. When using a sound decoder (such as a Soundtraxx DSD-150), the engine sound will remain in its "idle" state.

#### THE SLIDER BAR

The slider bar can function differently for each user depending on several factors. This user guide is not going to try to identify all of the different possibilities. Instead, it is going to identify several of the primary ways that the slider bar can work. At least one of these methods should work for you. You may discover that your setup can utilize more than one of these. A little experimentation on your part may be required.

1. Slider Method 1
   - Clicking anywhere above the current slider pointer position will INCREASE the loco speed by 1 speed step. For example, if the locomotive's current speed setting was 23, then a single click will advance the speed to 24. Another click will increase the speed to 25. Another click...to speed step 26. Another...to speed step 27. And so on...until it reaches the maximum speed steps for your system. This action has the same effect as using the + key on the numeric keypad.
   - Clicking anywhere below the current slider pointer position will DECREASE the loco speed by 1 speed step. For example, if the locomotive's current speed setting is 21, then a single click will decrease the speed to 20. Another click will decrease the speed to 20. Another click...to speed step 19. And so on...until it reaches speed step 0. This action has the same effect as using the - key on the numeric keypad.

   Note: Clicking too far below the slider (especially when close to the bottom of the slider bar) may not have any effect because you are actually clicking on the "Forward" option. Therefore, it is suggested that when decreasing speed with this method, that you click on the word "Stop" (not the emergency stop button (STOP!) but the word "Stop" located at the lower end of the speed slider).

   Note: If the decoder has acceleration or braking rates enabled, the loco will speed up or slow down accordingly. If no momentum values are enabled, the loco will speed up or slow down abruptly.

2. Slider Method 2
   - Click and hold the left mouse button over the slider pointer and then drag it to a speed that you wish, and release the mouse button. This will send a "set speed to" command to the decoder.

   Note: If the decoder has acceleration or braking rates enabled, the loco will speed up or slow down accordingly. If no momentum values are enabled, the loco will speed up or slow down abruptly to the speed set when the mouse button was released.

3. Slider Method 3
   - Clicking anywhere above the current slider pointer position will increase the slider pointer to the place where the mouse pointer was clicked. For example, if the locomotive's current speed setting was around 25% of the slider bar, and the mouse pointer was positioned near approximately the 75% point the slider bar when clicked, then the speed of the locomotive would be changed to approximately 75%.
   - Clicking anywhere below the current slider pointer position will decrease the slider pointer to the place where the mouse pointer was clicked. For example, if the locomotive's current speed setting was around 50% of the slider bar, and the mouse pointer was positioned approximately around the 25% point on the slider bar when clicked, then the speed of the locomotive would be changed to approximately 25%.

   Note: If the decoder has acceleration or braking rates enabled, the loco will speed up or slow down accordingly. If no momentum values are enabled, the loco will speed up or slow down abruptly.

   Note: Clicking too far below the slider (especially when close to the bottom of the slider bar) may not have any effect because you are actually clicking on the "Forward" option. Therefore, it is suggested that when decreasing speed with this method, that you click on the word "Stop" (not the emergency stop button (STOP!) but the word "Stop" located at the lower end of the speed slider.

IMPORTANT! The easiest way to stop a locomotive for any of the methods outlined above is to simply click on the "Idle" button located at the bottom of the Control Panel window. Or more abruptly, you can also click on the emergency stop button: STOP!

If you have discovered that your system works in some way different from any of those shown above, then you have simply found yet another method.

### Acquiring a Dispatched Locomotive

When the decoder address is first "Set", the software queries the current status of the decoder. This includes the current direction of the locomotive, its current speed, and what function buttons are on or off. The software will set the current direction indicator and identify any functions that are "active" (in the "on" state). But, if the loco is moving, the loco's speed is not established on the Speed Control slider bar.

Note: At this time, the slider bar does not automatically correspond to the actual speed. This is important to understand because of what action you are going to see when you first click on the speed slider bar. When you first "Set" a decoder address, the slider bar is set to the zero (0) position. So if you acquired a locomotive that is actually moving and you click on the slider bar, it is going to set the speed to zero (or wherever you click and set the slider bar pointer).
A future enhancement of the throttle feature will be to synchronize the slider bar pointer accordingly. Until then, just beware of this little reaction.

### The Function Panel

The Function Panel has 28 function buttons available for each throttle window. Most decoders currently don't handle 28 functions. The function panel displays the buttons in two groups, press the "*" button in the lower left corner to see the second set of function buttons. Clicking on the function buttons correlate to pressing the same function button on a hand-held throttle. The F0 function is normally used for the lights. This is the basic functionality of the Function Panel. All buttons function like an on/off toggle: click once to turn "on"; click again to turn "off". The next chapter provides more advanced features for customizing the Function Panel buttons. |  | Figure 2-6: The Function Panel

If you are reading this page from top to bottom as a training manual, at its conclusion you should be able to...

- open a new throttle window
- establish an active decoder address
- run a locomotive through its paces
- and activate the lights (and any other enabled functions for your decoder)

The next chapter will identify throttle features that can be customized in order to make your digital model railroading experience even more enjoyable.

|  | TOC |  |