Software/LOCOMGRVersion 1.4 |
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 locomgr.zip 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:
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:
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:
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. throttle>
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:
"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:
Free: 5417 1442 - 4000hp
In Use: 5780 - 1800hp
Dropping a locomotive from a consist also changes its status to IDLE.
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 |
| Consist: | |
| Free: (PgUp, PgDn)
5780 - 1800hp 1442 - 2000hp
|
In-Use: (Ctrl-PgUp, Ctrl-PgDn)
5417 - 2000hp
|
The screen is divided as follows:
The menu commands have the following behavior:
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:
Consist breaking is even easier:
[ ] - 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.
| 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) |
| 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. |
| status fromhandle# tohandle# | prints status of all handles in range. |
| force handle# status | forces handle status to common, in_use, idle, or free. |
| 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. |
| 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 |
First public release, named HOSTLER; command-line interface, four joystick throttles (throttle1), consist manager, 20-loco roster manager.
Changed name to LOCOMGR; increased roster capacity to 100.
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...
Bugfixes:
Enhancements:
Bugfixes, interface cleanup:
Added functionality:
Bugfixes:
Added Functionality:
Bugfixes:
Added functionality:
This list is my own, but I'm more than welcome to suggestions.
If you have any problems or suggestions with LOCOMGR, feel free to contact me at glenn_butcher@pcisys.net