Glenn Butcher

About Us
Journal Archive
Picture Albums
Slashdot Quotes
Resume (.pdf, 17K)



Dissertation (.pdf, 446K)

CNN: Technology
CNN: Top Stories
COS Gazette: Headlines
COS Gazette: Metro
Honolulu Advertiser
Internet News
NPR News
NY Times
PCMag: Reviews
The Hawaii Channel
Toms Hardware: Articles
Toms Hardware: News
Washington Post
Yahoo: Boeing
Yahoo: Missile Defense
Yahoo: Tech Tuesday
Yahoo: Top Stories

Home DNS
InOut Board
UBW IR Receiver
Gantt Chart
Google Map Test

LaBelle Long Caboose
NG TerraServers
Cumbres and Toltec Maps

Other Stuff
Gumbo Recipe
Salsa Recipe
Weather Station
Website Tags


Version 1.4
6 May, 2000

LOCOMGR is a MS-DOS program designed to put a simple-to-use interface on locomotive handling in Digitrax DCC systems. LOCOMGR implements four joystick throttles in the manner of Mike Brand's DCC-MB system. LOCOMGR provides both a relatively intuitive command line interface and a full-screen, single-character-command interface. LOCOMGR requires John Kabat's LOCONT1 driver software, version 1.4 or better.

 LOCOMGR is copyrighted 2000 by Glenn Butcher, but the source code is licensed under the GPL. It's written in Turbo Pascal (that may be enough to deter most hacking...), and modifications and bug-fixes are encouraged as long as you meet the terms of the GPL.

 This document describes how to get and use LOCOMGR.


The file is available here. (45K).


Simply unzip the zip file in a directory of your choosing; it should be a directory devoted to LOCOMGR. The source code is contained in a subdirectory called SOURCE; you should use the WinZip option that preserves subdirectories.

Joystick throttles are very easy to make; mine consist of a 100K potentiometer and a SPST switch mounted in a small box and wired to an RJ-11 connector. I built a four-gang RJ-11 cluster connected to the joystick port of a '286 PC, mounted in the control panel of my small N scale railroad. If you only want to use consisting, you do not need joystick throttles.  To build your throttles, I recommend the data at Mike Brandt's  DCC-MB Throttles page; that way, your throttles have a consistent interface with others' efforts.  Note that Mike calls for a pushbutton switch for directional control and an emergency brake; LOCOMGR is currently set up to use a toggle switch where on=reverse.  Lars Lundgren also has data on building various types of joystick throttles at his  TMWDCC page.

If you want to quickly build a single throttle that connects to LOCOMGR's throttle 1, here's a diagram that describes the connections:

Execution and Setup

Before you run LOCOMGR, you need to first connect your PC to the Loconet using Digitrax's MS-100.  Then, you need to run the the LOCONT1 driver. Do so by running it from the command line:

c:\ locont1 -c 1

The -c is used to set the serial port used for the Loconet interface; if omitted, the default port is COM1.  Make sure your Digitrax command station is powered up before you run the LOCONT1 driver so that it can initialize properly.  LOCONT1 uses interrupt 60 by default, and LOCOMGR is hard-coded to use this interrupt only (I'll change that in a future version). Once LOCONT1 is loaded, you can run LOCOMGR:

c:\ locomgr

Before you use the LOCOMGR throttles, you'll need to align the software with the throttle potentiometer.  To do this, connect the throttle to the joystick inputs you plan to use, then execute the align command:

> throttle align throttle#

You'll be prompted to turn the throttle pot to the minimum value then press a key, then turn the pot to maximum and press a key.  This will set up LOCOMGR to recognize this particular throttle's behavior for translation into valid Loconet commands.  Once you've done this, do not use a different throttle with the designated throttle number until you have reaccomplished the alignment operation.


When executed, LOCOMGR loads and runs commands from a file called config.cmd. This file usually contains the pot settings for min and max values, set using the throttle align command. The included example config.cmd also contains commands to read a roster file called roster.txt and to apply these locomotives to Digitrax handles.  The roster file contains all of your decoder-equipped locomotives, and has the following three fields, each separated by a space:

  1. Locomotive number - This is the address used by the command station to control the locomotive, either two or four digits.
  2. Locomotive alias - This is the address used by the user to identify the locomotive.  This is the number used in locomgr commands.  If you're not using separate aliases, this number is the same as the locomotive number.  This does not control DCS100 aliases!
  3. Locomotive type - This is the locomotive model number, typically "GP-9", 

    "RS-1", etc.  It currently has no application in LOCOMGR.

  4. Horsepower - The locomotives rated "horsepower."  The roster displays show the cumulative "horsepower" of each single locomotive or consist - useful if you use horsepower ratings to build consists to handle given train tonnages.  This field has no effect on locomotive speed or configuration variables.

Both files allow the use of the "#" character in the first position of a line to designate the line as a comment; locomgr ignores these lines.

 LOCOMGR uses a two-tier command structure. Most commands are assigned to one of the following categories:

  • roster
  • throttle
  • consist
  • handle

At the command prompt, >, you can enter full commands, e.g.:

> throttle assign 5417 1

or you can set a category to enter sub-commands:

> throttle
throttle> assign 5417 1
5417 assigned to throttle 1.
throttle> assign 1442 2
1442 assigned to throttle 2.

The last five commands entered can be scrolled and reused for execution by using the up-arrow and down-arrow keys.

Help is available at the command prompt, both at the top level and in each of the categories; see the help for specific commands. All locomotives handled by LOCOMGR must be specified in the loaded roster. At present, there are three fields for each roster entry:

  • Locomotive number
  • Locomotive type
  • Horsepower

"Horsepower" is used in the consist category to provide total horsepower of the assembled consist. Roster entries can be added in the roster category, or the file can be edited by hand.

A shortcut method is available at any prompt level to assign locomotives to throttles. Simply type the locomotive's number at the prompt and press return - the locomotive previously assigned to throttle 1 is released, and the new locomotive is assigned to throttle 1. Typing a throttle number after the locomotive number performs the same operation for the designated throttle:

> 5417
5417 assigned to throttle 1.
> 1442
5417 released from throttle 1 first.
1442 assigned to throttle 1.

LOCOMGR 1.4 is untested in widespread use, so errors in handling locomotives may result. If a locomotive is left in an inconsistent status, its status can be forced by executing:

> handle force handle# status

Handle numbers for locomotives can be obtained by executing:

> roster list long

Making consists simply involves adding the sub locomotive to the top locomotive as follows:

> consist add 1442 to 5417

Once you've done this, do a

> consist list

The list shows all locomotives, either free or as part of a consist. The first locomotive in a consist is the top locomotive. Note the total horsepower of the consist tacked on the end of the entry:

   5417 1442 - 4000hp

In Use:
   5780 - 1800hp

Dropping a locomotive from a consist also changes its status to IDLE.

Menu Mode

Executing the following command:

> menu

puts LOCOMGR in full-screen menu mode.  From here, most LOCOMGR functions can be executed with single-character commands.  The screen looks like this:

Menu: (a)ssign (r)elease (t)op (c)onsist (l)ink (u)nlink track-p(o)wer e)xit-menu
      dispatch-(g)et dispatch-(p)ut (loco#: asgn to throt 1)
Throttles:   1: 5417   2: ----  Track: on
Free:     (PgUp, PgDn)
  5780 - 1800hp
  1442 - 2000hp


In-Use:    (Ctrl-PgUp, Ctrl-PgDn)
   5417 - 2000hp



The screen is divided as follows:

  • Top black bar: displays the menu, which is comprised of descriptive words with the single character command appended with a paren ")".
  • Blue bar: Displays the assignments of the four throttles.  Only throttles that have been aligned are displayed and available for assignment.
  • Red bar: Displays a consist being built using the t)op and l)ink commands.
  • Gray boxes: The entire roster is displayed in the gray boxes as either Free or In-Use; this display updates with the execution of every menu command.
  • Green bar: used to prompt for input such as loco addresses or throttle numbers.
  • Bottom black bar: used by the program to display success and error messages.

The menu commands have the following behavior:

  • (a)ssign: Prompts for a locomotive number in the green bar, then a throttle number.  If the locomotive isn't already in use or in the middle of a consist, the throttle is assigned to that locomotive.  If another locomotive was previously assigned to that throttle, it is released.
  • (r)elease: Prompts for a throttle number.  Releases the locomotive assigned to that throttle.  .
  • (t)op: The locomotive assigned to throttle 1 is made the top (left-most) locomotive in the red consist line.  If a consist previously occupied the consist line, it is replaced.
  • (c)onsist:  Prompts for a locomotive number.  This locomotive is then displayed in the consist list.  If the locomotive is the top of a consist, the whole consist is displayed in the consist list.  This command allows you to put a consist in the consist line for breaking-apart without having to put the consist in throttle 1 first.
  • (l)ink: The locomotive assigned to throttle 1 is added to the consist in the red consist line.  The throttle is then automatically assigned to the consist top.
  • (u)nlink: Prompts for a locomotive number.  If the locomotive is part of a consist, it is separated from the consist and assigned to throttle 1.  The consist does not have to be displayed in the consist line, but doing so makes breaking up easier to follow.
  • track-(p)ower: Each press of "r" toggles the track power between on and off.
  • e)xit-menu: Exits menu mode and returns to command mode.
  • dispatch-(g)et: Retrieves the dispatched locomotive and assigns it to throttle 1.
  • dispatch-(p)ut: Releases the locomotive assigned to throttle 1 and dispatches it to the system.

As in command mode, locomotives can be assigned to throttle 1 by simply typing their number.  As the above commands change the free and in-use status of locomotives, the locomotive numbers will move from the Free to the In Use columns, and vice versa.  When prompted for an input at the green line, typing the <ESC> key will abort the input and return you to the menu.

As an example of using the menu, consider the following steps for building a consist:

  1. The locomotive to be used as the top is assigned to throttle 1 by typing it's number.
  2. The (t)op command is used to put the locomotive on the consist line.
  3. The locomotive is then moved into position, leaving it set to move in a particular direction.
  4. The first locomotive to be added is assigned to throttle 1 by typing it's number.

  5. The locomotive is moved into position coupled to the top locomotive, leaving it set to move in the same direction as the top locomotive.
  6. The (l)ink command is used to add the locomotive to the consist.
  7. Steps 4-6 are repeated for each locomotive to be added to the consist.
  8. After the last locomotive is added, the top locomotive is already assigned to throttle 1, so the entire consist can then be moved to the ready track.

Consist breaking is even easier:

  1. The (c)onsist command is used to put a consist in the consist line.  This step is not required.
  2. The (u)nlink command is used to prompt for a locomotive number.  If assigned to a consist, the locomotive is separated and assigned to throttle 1.
  3. The locomotive is then moved to wherever it needs to go.
  4. Steps 2-3 are repeated until the locomotives to be separated from the consist have been separated.  Keep in mind that if you separate a locomotive that is in the physical middle of a consist, you won't be able to move it until you've separated locomotives to either side of it (except by 0-5-0...;-)

Command Summary

[ ] - surround an optional item.

| - choose from either the left-hand or the right-hand word.
# - suffixed to a descriptor, designates that a number is required.

Top-Level Commands:

ver reports LOCOMGR version
run filename runs commands contained in filename
power on|off turns on|off track power. Prior to 1.3.1, the command was "track on|off"; this command still works.
set throt# min|max val sets min/max pot values
set hp on|off sets horsepower display in roster list on or off.
writeconfig writes config to config.cmd
back returns to command level
menu invokes full-screen menu
done exits program (also available in all parts)

Roster Commands:

read file reads roster from file.
write file writes roster to file.
list [long] lists loaded roster.
add adds a roster entry
delete deletes a roster entry
apply assigns locomotives in internal roster to Digitrax handles.

Handle Commands

status fromhandle# tohandle# prints status of all handles in range.
force handle# status forces handle status to common, in_use, idle, or free.

Throttle Commands:

status [throttle#] prints status of all throttles, or throttle#.
assign loco# throttle# assigns loco# to throttle#.
release throttle# releases loco assigned to throttle#.
align throttle# prompts alignment of throttle pot.
put loco# dispatch locomotive.
get throttle# assigns dispatched loco to throttle.

Consist Commands:

link loco#1 to loco#2 add loco#1 to consist with loco#2 as top.  Prior to 1.3.1, this command was "add loco#1 to loco#2"; this command still works.
unlink loco# drops loco# from consist.  Prior to 1.3.1, this command was "drop loco#"; this command still works.
list lists in-use and free locos and consists

Version History

1.1, 7 February 2000

First public release, named HOSTLER; command-line interface, four joystick throttles (throttle1), consist manager, 20-loco roster manager.

1.2, 10 February 2000

Changed name to LOCOMGR; increased roster capacity to 100.

1.2.1, 23 February 2000

Bug fix in JOYSTK.PAS to bound the counter for joystick position - only 1X had the bound; reading the second stick would lock up the computer in an infinite loop if the joystick card was not present.  Thanks to Marty Quaas for the DR...

1.3, 8 March 2000


  1. Initialize throttle speed to 0.
  2. Check for consist=mid or sub when assigning locos to throttles.
  3. Implement 60-second timer to send purge reset speed messages for assigned throttles.


  1. Full-screen menu mode with single character commands.

1.3.1, 3/19/2000

Bugfixes, interface cleanup:

  1. Menu mode: tr)ack interferes with r)elease; now (p)ower.
  2. Menu mode: surrounded commands with parentheses.
  3. Menu mode: only display aligned throttles.
  4. Menu mode: fully backspace a prompt, <ESC> exits prompt with no data.
  5. Command mode: changed consist add and drop to link and unlink -  menu consistency (add and drop still work!).
  6. Command mode: changed track to power - menu consistency (track still works!).
  7. Loconet: dispatchget parameter locorec changed to var.

Added functionality:

  1. Menu mode: dispatch-(g)et, dispatch-(p)ut.
  2. Command mode: set hp on|off to toggle horsepower display.

1.3.2, 3/20/2000


  1. Assign loco behavior: check inuse and consist accomplished in proper order.
  2. reset connbr :=0 when creating new consist in menu.

Added Functionality:

  1. Menu mode: Display track power status on throttle line.

1.4, 5/6/2000


  1. Disabled unconsist check to allow orphaned consists to be recovered (until the real problem can be found)
  2. Command mode: handle blank line by returning to prompt

Added functionality:

  1. Roster reorganized to include aliases and DCC addresses.  OLD ROSTERS MUST BE MODIFIED!!
  2. "#" in first column of roster line ignores line
  3. "#" in first column of .cmd file line ignores line
  4. Throttle assignment prompts for roster entry if the loco is not already there
  5. Command mode: up-arrow and down-arrow scroll through last five commands
  6. Command mode: roster add and roster delete commands

Things To Do

This list is my own, but I'm more than welcome to suggestions.

  1. Implement linked list for roster.

  2. Command-line settable interrupt.
  3. Better scaling for pot position-to-DCC speed setting.
  4. Execute a command file specified in the DOS command line - locomgr commands.cmd
  5. set commands for functions 1-8, directional lighting bit.

  6. Throttle 0 for keyboard operation.
  7. Other throttle configurations - two throttles with a function each, one throttle with three functions, two walkaround throttles, etc.
  8. Aliasing two-digit addresses to locomotive numbers (3/19/2000).  (1.4)
  9. Periodic refresh of menu roster to capture roster changes from other throttles (3/19/2000).
  10. Simple CV programming (5/6/2000).

If you have any problems or suggestions with LOCOMGR, feel free to contact me at