DCC System Compatibility
WiThrottle does not control a DCC system, it controls JMRI or an interface module. It extends the functions of the interface out to the iPhone, iPad, or iPod touch in your hand.
WiThrottle does not know what kind of system it is connected to. As a result, it works with almost all DCC systems. Digitrax, Lenz, NCE, MRC, CVP, MERG, and even TMCC (which is not true DCC). TMCC does have some limitations, but the basic throttle controls and functions have been reported to work. Bachmann has restricted their protocol, which prevents control via JMRI. If a JMRI on-screen throttle can work, then so will WiThrottle, with one known exception: The Lenz XPressNet Phone Adapter (XPA) system does not operate fast enough to handle the data speeds from the app.
Selecting a Locomotive
The top portion of this screen has a "New Entry" field (1) which will bring up a keypad for address entry. The lower section contains a list which allows access to the last six addresses used by this device and also addresses stored in the roster (2) of the server. The "Set" button (3) requests the address in (1) from the server. The "Release" (4) button tells the server that you are done controlling the selected address.
Controlling Locomotive Speed
The top bar (1) controls and indicates current direction of the selected address. The "slider" (2) has an indicator that shows the current speed step as well as relative position. You do not need to tap directly on the "handle" to change speed, anywhere on the line will respond to changes. Tapping on the top half of this area will increse the speed by one step and the bottom half will decrease by one step. The "STOP" button (4) will set the selected address to an emergency stop, ignoring any momentum programmed into the decoder.
Controlling Locomotive Functions
The app pulls any function labels automatically from the interface's roster. This allows different decoders to have the appropriate labeling. You can then enter them by going to the Function Labels tab in JMRI, or to Roster on an MRCWi-Fi module's website. Any blank labels will show the default function number in WiThrottle.
The app also has an option on its Settings screen to hide unlabeled function buttons. If this is selected, if any function buttons have a custom label, only those with a label will appear in the app. If no buttons have custom labels in JMRI roster for that decoder, all function buttons will appear.
You can also set the momentary or lock option of each function. For example, the Digitrax sound decoders (SDH164D) have a crossing horn on F7, but it only sounds when the function is turned on. From a throttle, the first press of F7 turns the function on, sounds two longs, one short, and one long. The second press turns F7 off, which does nothing. The third press turns F7 on again, starting the cycle over. If you set the F7 function in JMRI or an MRCWi-Fi module to momentary (turn off "Lock" in JMRI), each press of F7 in WiThrottle will sound the crossing horn.
Using the Dual Throttle View
The address box above each throttle (1)(2) opens the address screen for that throttle. Tapping on the direction indicator (3) will send an Idle command for that throttle. When sliding the speed control, it will stop before crossing the direction change point (4). Lifting your finger before resuming control will allow the direction to change. The function buttons (5) slide horizontal to show the second throttle's functions, and vertical to show up to F28.
Idling for Alerts
On the Settings screen of the app, there is a switch called Immediate Idle for Alerts. With it set on, a train stops when control is interrupted (i.e. phone call or leaving throttle screen). When set off, the train will run for about 10 seconds after control is interrupted. This delay can be changed in JMRI Preferences WiThrottle Seconds Until E-Stop, or in Module Settings on an MRCWi-Fi module's website.
Controlling Turnouts and Routes
The app can control any turnouts (and routes) that the interface can control. Turnouts and routes can be added to the JMRI turnout table or the MRCWi-Fi module's accessory list (note: the MRCWi-Fi module cannot control routes). Turnouts and routes can be found in WiThrottle by sliding the function buttons pane to the right. If there are no turnouts (or routes) in the list, the control screen is hidden in the app. When using JMRI, if they cannot be controlled from within JMRI, WiThrottle will not be able to control them either.
Using JMRI, you can limit which turnouts appear. In JMRI, with the WiThrottle window active, go to WiThrottle Filter Controls. You can then pick which turnouts to display or hide.
Creating Universal Consists
The Address screen has a form of Universal Consisting local to the app that can join addresses together without making any programming changes to the decoders. When you Set an address (lets say 355(L)) another button appears labeled Add. You can enter another address (or select from the roster list) and then Add it to the first address. It will ask Normal or Reverse orientation relative to the first locomotive. The two locomotives are then linked together on the throttle. The address will appear as 355(L)+1. If you tap that address while on the Address screen it will open a window that gives options for changing direction or releasing the addresses individually. You are able to Add as many addresses to this consist as your command station will allow.
Using the JMRI WebServer
WiThrottle is able to display any windows that are open in JMRI, including any control panels. This is served by the WebServer which can be started at the bottom of the Tools menu (Debug menu prior to JMRI 2.14). Once the web server is started, WiThrottle finds it automatically when it connects. The WiThrottle app will create a new tab at the bottom of the screen for the WebServer. Opening the tab and tapping Add (the book button at the top) will allow you to add a path to your panel window. Enter:
and hit return. Capitalization matters and any spaces need to be replaced by %20. Then just navigate back to the screen that displays the panel. It will remember what you enter and multiple windows/frames/panels can be added to this list. This part of JMRI has been undergoing many changes and depending on the exact version of JMRI you have, the path format you have to enter may be different. This help page from JMRI has the format information. JMRI 3.2 or higher is recommended, as it contains many improvements to the WebServer.
The WebServer also feeds roster icon images to the roster list of the WiThrottle address screen. And in addition to viewing completed windows, you can even watch a panel on your iOS device as you build it on a computer by entering the name of the editor window.