Table of Contents

• Introduction
• Installation
• Command Syntax
• Screen Layout
• Operation
• Profile
• Internals
• Requirements
• Registration and Shareware Fee
• Summary of Changes
• Miscellaneous Information

Introduction

HanDig provides simple manual control of your Digital model railroad from the computer keyboard. It allows control of all loc and function decoders (of which 8 are visible on the screen) and a range of switches (max 256). HanDig also reads feedback encoders and displays the information on the screen. The use of Handig is straight-forward and it is excellent for testing the basic functions of your digital modelrailroad. The most frequently used controls need only a single keystroke.

HanDig currently supports:

• Märklin Digital & Delta, Lenz Digital Plus, Trix Selectrix, Uhlenbrock Intellibox (P50X protocol) and Digitrax Loconet.
• 2 ports simultaneously with independent choice of protocol per port

Installation

The file HanDig30.ZIP is a ZIP archive to be unpacked with UNZIP or PKUNZIP (recent version).
After unpacking you'll find the following files:

• Read.Me - Basic documentation
• HanDig.HTM - This documentation
• HanDig.EXE - Excutable (requires OS/2 Warp4+).

• DIGIAPI.DLL - DigiAPI primary Application Program Interface.
• SERVICE.DLL - Service routines common for all protocols.
• LENZ.DLL - Support for Lenz Digital Plus protocol.
• LOCONET.DLL - Support for DigiTrax Loconet protocol.
• MARKLIN.DLL - Support for Marklin Interface 6050/6051 protocol
• P50X.DLL - Support for UhlenBrock Intellibox (P50X) protocol.
• REXX.DLL - Support for procedures in REXX (not used by HanDig).
• TRIX.DLL - Support for Trix Selectrix Interface protocol.
• DigiAPI documentation files in HTML format.

It is recommended to keep all files in the same (preferrably a separate) directory. You may place the DLLs in any LIBPATH directory. When you put the DLLs in the directory of Handig itself you should either have a specification of this directory in the LIBPATH statement of CONFIG.SYS, or a ".;"-entry in the LIBPATH statement.

HanDig will create a 'profile' file called HanDig.Pro in the current directory. This is to remember your last setup, which makes it possible to re-start without any commandline parameters. If you restart HanDig all previous settings will be as before, but any commandline parameters may overwrite profile parameters.

Command syntax

The general idea of the parameters for HanDig is to let you use your own modelrailroad system as descibed in its documentation. Therefore HanDig does not force you to learn a different notation, even not the system-independent notation (numbering) used by DigiAPI, which is meant for programmers to build software which can be run with different systems.

The command syntax looks a bit complicated, but most parameters are optional. And once you have set the profile correctly for your modelrailroad (maybe with trial and error?), you can start HanDig without commandline parameters. An alternative is to edit the profile, which uses the same syntax.

  HanDig [port-specs] [switch-range] [contact-range]

      port-specs: port assignment and protocol in format: dev:p
                  dev - Device name (normally COM1, etc)
                  p   - Protocol letter
                        Protocols supported by Handig (ic DigiAPI!)
                          D = Digitrax Loconet
                          I = Märklin 6023 (TRAIN_ING)
                          L = Lenz Digital Plus
                          M = Märklin Digital
                          T = Trix Selectrix
                          U = UhlenBrock Intellibox

    turnout range: Specification of lowest and highest turnout number in the
                  format Txx Tyy
                  Specification of 'xx' (lowest) and 'yy' (highest) number
                  is protocol dependent:
                  Intellibox: switch number (1..256)
                  Lenz:       switch number (1..256)
                  Loconet:    switch number (1..256)
                  Marklin:    switch number (1..256)
                  Trix:       switch decoder address (0..111)

   contact range: Specification of lowest and highest sensors in the
                  format : Cxx Cyy
                  The specification of 'xx' (lowest) and 'yy' (higest) is
                  protocol dependent:
                  Intellibox: number of attached S88 (1..31)
                  Lenz:       sensor encoder address (0..127)
                  Loconet:    sensor encoder group (1..256)
                  Marklin:    number of attached S88 (1..31)
                  Trix:       sensor encoder address (0..111)

Two port specifications are accepted. The first or only specification will be used for commands. If this is the only port, it will also be used for sensor monitoring, but if you specify a second port monitoring will take place over the second port.
The switch and contact specifications come in pairs: the first for the lower bound, the second for the upper bound. For Märklin it is sufficient to specify only the number of S88's you use, since reading is always starts with the first S88. If you specify a range, then only that range will be displayed.

If a file HanDig.Pro is present in the current directory, the settings of the profile will be processed first, and commandline parameters will override profile settings, see also Profile.

If no profile file is present and no commandline parameters are specified, HanDig defaults to the equivalent of the commandline:

  COM1:U  COM1:U  T1  T256  C1  C8

Screen Layout

Below a capture of the Handig screen used to control a modelrailroad with Märklin Interface.

Besides top title line and bottom line with general operational information, there are 3 distinctive display areas:

1. A single line with 8 loc and function decoder fields. The info of each:
   • loc decoder: address, speed (expressed in -99..+99 % of maximum speed, and auxiliary function
   • function decoder or loc-decoder with 4 extra functions: address, function settings (ON = 1,2,3,4)
   The sequence number preceding this info corresponds to the computer Function key with which this decoder can be selected. All displayed decoders receive a 'zero' command at startup, so the displayed status is actual (loc direction is assumed to be 'forward'). The currently selected loc-speed or extra function is highlighted or blinking.
2. A block of (max) 16 lines with 16 switches per line. Of each switch the number and state is displayed. Note: the position may not be the actual position: at startup there are no switch-initialisation commands being sent by Handig! You may perform a reset with 'Ctrl-End' or 'Ctrl-Home', see chapter Operation. The latest selected switch has its number highlighted.
3. A block of sensor information lines with max 64 sensor contact points per line in groups of 8 contacts, preceded by the sensor encoder address. With Märklin and the Intellibox the sensor info is displayed in 2 groups of 8 contacts per S88 (note: contacts 9..16 are displayed as 1..8!). The actual number of displayed contact points is the actual range requested at startup of HanDig, possibly limited by screen size, and rounded to the full encoder range.

Operation

Handig is exclusively keyboard controlled (no support for mouse or other). The normal cursor is switched off, the currently highlighted or blinking field indicates which component is under control, being either a loc or function decoder, or an individual switch.

Notes:

• Loc-speed changes are always one decoder speed step. When the number of speed steps is unknown and cannot be detected, 14 steps are assumed.
• Addresses in the first block are predefined as Loc decoders with addresses 10, 20, .. , 80, but both type and address can be changed. Changes will be saved in the file 'HanDig.Pro' for next time. A decoder address can only be changed when its speed is 0. Loc decoders with 1 auxiliary and 4 extra functions can be controlled by a combination of a Loc and a Function decoder field with the same address, or by alternating the decoder type of the specific decoder field.

Profile

HanDig uses a file HanDig.Pro to read operational parameter at start, and to store these at termination to be used with the next run without the need to specify commandline parameters then. The profile uses commanline syntax and contains the following information (in this sequence):

• 2 fields of port information in the format: dev:p
  dev - Device name (normally COM1, COM2, etc)
  p - Protocol identification (letter, see CommandLine).
  The first port is for commands, the second for sensor monitoring. When using a single COM-port both fields should be identical!
• 8 fields of loc/function decoder information: Lxx or Fxx
  xx - decoder address (1..99)
  L or F - loc or function decoder (or each part of a combination)
• 2 fields for the range of active switches in the format: Txxx.
  xxx - is system dependent, the same specifications apply as for the Commandline.
  HanDig supports only 1 block of contiguous turnouts.
• 2 fields for the range of used sensor contacts in the format: Cxxx.
  xxx - is system dependent, the same specifications apply as for the Commandline.
  HanDig supports only 1 block of contiguous sensors.

Loc and function decoder addresses are 'real' addresses. Other addresses may be selected dynamically during the active time of HanDig. The switch and contact specifications are relative numbers: Switch 1 is the first switch on the decoder with the lowest supported address, and contact 1 is the first contact on the sensor encoder with the lowest supported address or position. With some systems address ranges may be fixed, while with other systems you can choose address ranges.
Let us have a look at an example of a model railroad with, 40 switchpoints and 64 sensor contacts, with the Interface connected to COM2.

Märklin

Loc decoder address range is 1..80, the switch decoders are at configured for addresses 1..40 and 4 S88's sensor encoders are attached. The profile will look like:
COM2:M COM2:M L20 F20 L34 L35 F35 L36 L40 F80 T1 T40 C1 C4
The low bound of sensor encoders is always '1' with Märklin.

Uhlenbrock Intellibox

Almost the same as for Marklin, the profile will look like:
COM2:U COM2:U L20 F20 L34 L35 F35 L36 L40 F80 T1 T40 C1 C4
The low bound of sensor encoders is always '1' with the Intellibox.

Lenz

Loc decoder address range is 1..99, the switch decoders are configured for address range 55..64 (switch numbers 217..256), the sensor encoders for address range 65..72. The profile will look like:
COM2:L COM2:L L20 F20 L34 L35 F35 L36 L40 F80 T55 T64 C65 C72

Loconet

Loc decoder address range 1..80, switches 1..256, sensor counter in groups of 8 contacts. The profile will look like:
COM1:D COM2:D L20 F20 L34 L35 F35 L36 L40 F80 T1 T40 C1 C8

Trix Selectrix

For Loc decoders address range 1..80 is chosen, for switch decoders the range 81..84 and for sensor encoders the range 100..107. The profile will look like:
COM2:T COM2:T L20 F20 L34 L35 F35 L36 L40 F80 T81 T85 C100 C107

Internals

HanDig is designed for system tests and on purpose kept simple. Although the underlying support routines are multi-tasking, HanDig itself is a single task and issues commands in the sequence of the related keyboard action. The commands are queued for immediate execution (no delays). Switches are turned off automatically. Due to the buffering of keyboard input you may observe a delay between hitting a key and the execution of the related command, especially when using the typamatic feature of the keyboard (for example with Enter-key or Space-bar). A 'stop' command (Esc-key) may be executed before previously queued other commands!

Requirements

HanDig is a 32-bits OS/2-only program. It requires OS/2 Warp 4.0 or higher and a VGA-screen (color preferred). The screen will be used in 34-lines mode, which allows up to 256 switches and 576 sensor contacts to be displayed.

Registration and shareware-fee

HanDig itself is free, but since it is based on a package DigiAPI (a programmers interface for Digital Model Railroads), the conditions of use of HanDig are 'inherited' from DigiAPI. When you run HanDig without a registration for DigiAPI you'll notice:

1. During startup of HanDig a message reminds you about the free trial period of 45 days, and how long to go before registration is required to continue using HanDig (DigiAPI).
2. About 20 minutes after startup a HALT is issued, which will be shown in the upper right corner of the screen and HanDig refuses to send any further loc speed commands to the modelrailroad, everything else still works. Even GO works, but with any loc speed command a new Halt will be issued!

Summary of changes

Miscellaneous information

HanDig is a sample program to test and demonstrate the package DigiAPI for Märklin Digital, Lenz Digital Plus and Trix Selectrix, Uhlenbrock Intellibox and Digitrax Loconet. DigiAPI offers a combination of an Application Programming Interface and communication drivers to simplify program development for Digital Modelrailroads. You don't have to know anything about the communications properties and interface protocols of any of the supported systems.
DigiAPI has been tested with C an C++ programs, but it will probably be useful with other languages if the same (C-language) calling convention is used. You'll probably find DigiAPI (most recent is version 3.0 dd March 2001, distributed as file DIGAPI30.ZIP) on the same place where you found HanDig.

Other useful building blocks and utilities when you are experimenting with or developing programs for digital modelrailroads might be:

IBTerm

General purpose terminal emulator program to test/control with special features to test/control a modelrailroad with the Uhlenbrock Intellibox, in particular with its ASCII variant of P50X protocol (P50Xa). It has many features to experiment with communications parameters (port settings) and keyboard input.

DigiScope

Analysis of the datastream between computer and Interface. Turns your PC into a datascope for 'Märklin Digital' or Lenz Digital Plus, Trix Selectrix, Uhlenbrock Intellibox of DigiTrax Loconet.

DigiTrc

Trace formatter for all programs based on DigiAPI, and the above 'independent' utilities.

AsynMon

Universal ASYNchronous port MONitor program with high resolution timing of data and status events and special extensions for modelrailroads.

Questions, remarks, appraisals and suggestions are welcome!

Please contact me by E-mail: Rob Hamerling
homepage: http://www.geocities.com/digithalys/ or its shadow: http://home.planet.nl/~hamer449/

Computer controlled modelrailroading is fun! Rob Hamerling.