Table of Contents

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

Introduction

HANDIG1 provides simple manual control of your Digital model railroad from the computer keyboard. It allows control of all loc and functiondecoders (of which 8 are visualised on the screen) and a range of switches (max 256). HANDIG1 also reads feedback encoders and displays the information on the screen. The use of HANDIG1 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.

HANDIG1 currently supports:

• Märklin Digital, Lenz Digital Plus, Trix Selectrix, Uhlenbrock Intellibox (limited).
• 2 ports simultaneously with independent choice of protocol per port

Installation

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

• HANDIG1.HTM - This file.
• HANDIG1.EXE - DOS excutable.
• Readme - Brief introduction.

It is recommended to keep all files in the same (preferrably a separate) directory.

Note: HANDIG1 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 start HANDIG1 a next time all previous settings will be as before, but any commandline parameters may overwrite profile parameters.

Command syntax

The general idea of the parameters for HANDIG1 is to let you use your own modelrailroad system as descibed in its documentation. Therefore HANDIG1 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 somewhat 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 HANDIG1 without commandline parameters.
An alternative is to edit the profile, which uses the same syntax.

  HANDIG1 [port-spec] [switch-range] [contact-range]

       port-spec: port assignment and protocol in format: xPy
                  x - Port number (1 for COM1, etc)
                  P - indicates this is a port specification
                  y - Number of the protocol being used.
                      The numbers are defined by DigiAPI, currently
                      supported by HANDIG1 (ic DigiAPI)
                         1 = Märklin Digital
                         2 = Lenz Digital Plus
                         4 = Märklin 6023 (TRAIN_ING)
                        11 = Trix Selectrix
                        18 = Uhlenbrock Intellibox

    switch range: Specification of lowest and highest switch number in the
                  format xxS yyS
                  The specification of 'xx' and 'yy' is protocol dependent:
                  Marklin: lowest and highest switch (1..256)
                  Lenz:    lowest and highest switch number (1..256)
                  Trix:    lowest and highest switch decoder address (0..111)
                  IB:      lowest and highest switch decoder address (1..256)
   contact range: Specification of lowest and highest contact in the
                  format : xxC yyC
                  The specification of 'xx' and 'yy' is protocol dependent:
                  Marklin: lowest and highest number of attached S88
                           feedback unit (1..31)
                  Lenz:    lowest and highest feedback encoder address (0..127)
                  Trix:    lowest and highest feedback encoder address (0..111)
                  IB:      lowest and highest feedback encoder address (1..31)

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 feedback 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 always all S88's are read.

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, HANDIG1 defaults to the equivalent of the commandline:

  1P1 1P1 1S 256S 1C 4C

Screen Layout

Besides top title and bottom lines with general 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 HANDIG1! 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 feedback information lines with max 64 feedback contact points per line in groups of 8 contacts, preceded by the feedback encoder address. With Märklin the feedback info is displayed in 2 groups of 8 contacts per S88 (note: contacts 9..16 are numbered 1..8 when 'ON'!). The actual number of displayed contact points is the actual range requested at startup of HANDIG1, possibly limited by screen size, and rounded to the full encoder range.

Operation

HANDIG1 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 functiondecoder, or an individual switch.

Note: Loc-speed changes show steps of about 7% of maximum speed. This corresponds to single step in most cases (14 speed steps decoder), but when a decoder is programmed for 28 steps, it will automatically take 2 steps.

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 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 altering the decoder type of the specific decoder field.

Coupling or locking

When you select the same address for decoders of the same type (loc or function), the display fields are 'coupled'. Changes of one decoder will be propagated to corresponding display fields. Uncoupling can only take place when speed is zero or all functions are OFF.

Profile

HANDIG1 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 contains the following information (in this sequence):

• 2 fields of port information in the format: xPy
  x - COM-port number
  y - Protocol used (see DigiAPI.h of DigiAPI package for numbers). The first port is for commands, the second for feedback monitoring. When using a single COM-port both fields should be identical!
• 8 fields of loc/function decoder information: xxL or xxF
  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: xxxS
  xxx - is system dependent, the same specifications apply as for the Commandline.
  HANDIG1 supports only 1 block of contiguous switches.
• 2 fields for the range of used feedback contacts in the format: xxxC
  xxx - is system dependent, the same specifications apply as for the Commandline.
  For Märklin only 1 feedback field is required. Feedback monitoring always starts from contact 1 on feedback encoder 1, so only the number of feedback encoders is needed.
  HANDIG1 supports only 1 block of contiguous feedback contacts.

Märklin

Loc decoder address range is 1..80, the switch decoders are at configured for addresses 1..40 and 4 S88's feedback encoders are attached. The profile will look like:
2P1 2P1 20L 20F 34L 35L 35F 36L 40L 1F 1S 40S 1C 4C
The low bound of feedback encoders is always '1' with Märklin.
When you use Märklin protocol with the Intellibox, please configure your Intellibox for 6050 protocol and 2400 bps before starting HANDIG1.

Lenz

Loc decoder address range is 1..99, the switch decoders are configured for address range 55..64 (switch numbers 217..256), the feedback encoders for address range 65..72. The profile will look like:
2P2 2P2 20L 20F 34L 35L 35F 36L 40L 80F 55S 64S 65C 72C

Trix Selectrix

For Loc decoders address range 1..80 is chosen, for switch decoders the range 81..84 and for feedback encoders the range 100..107. The profile will look like:
2P11 2P11 20L 20F 34L 35L 35F 36L 40L 80F 81S 85S 100C 107C

Uhlenbrock Intellibox

Loc decoder address range is 1..80, the switch decoders are at configured for addresses 1..40 and 4 S88's feedback encoders are attached. The profile will look like:
2P18 2P18 20L 20F 34L 35L 35F 36L 40L 1F 1S 40S 1C 4C
The low bound of feedback encoders is always '1', like with Märklin.
This implementation of the Intellibox protocol (in DigiAPI) doesn't support automatich baudrate and protocol setting. Configure your Intellibox to 'mixed' protocol (6050 and IB), and the speed to 19200 bps before starting HANDIG1.

Internals

HANDIG1 is designed for system tests and on purpose kept simple. Although the underlying support routines are multi-tasking, HANDIG1 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), but with switch commands HANDIG1 waits approximately 100 msecs after a switch command before issuing the next command. 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). So you'll understand that also a 'stop' command (Esc-key) will only be executed after all previous commands have completed!

Requirements

HANDIG1 is a DOS-only program. It requires a VGA-screen (color preferred). The screen will be used in 34-lines mode, which allows up to 256 switches and 576 feedback contacts to be displayed.

Registration and shareware-fee

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

1. During startup of HANDIG1 a message reminds you about the free trial period of 45 days, and how long to go before registration is required to continue using HANDIG1 (DigiAPI).
2. About 20 minutes after startup an emergency STOP is issued, which will be shown in the upper right corner of the screen and HANDIG1 refuses to send any further commands to the modelrailroad.

Summary of changes

Miscellaneous information

HANDIG1 is a sample of the use of the package DigiAPI for Märklin Digital, Lenz Digital Plus, Trix Selectrix and the Uhlenbrock Intellibox (limited). DigiAPI offers a combination of an Application Programming Interface and communication drivers to simplify program development for Digital Modelrailroads. DigiAPI has been tested with C applications only. It may work with other languages if the same (Pascal) calling convention is used. You'll probably find DigiAPI on the same place where you found HANDIG1.

Other useful utilities when you are developing programs yourself for Märklin Digital, EDiTS, Lenz Digital Plus, Trix Selectrix, Uhlenbrock Intellibox and DigiTrax Loconet may be:

DigiScope

Analysis of the datastream between computer and Interface. Turns your PC into a datascope to monitor the data traffic between computer and digital model railroad.

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 digital modelrailroads.

Questions, remarks, appraisals and suggestions are welcome!

Please contact me by E-mail: Rob Hamerling
homepage: http://www.robh.nl/.

Computer controlled modelrailroading is fun! Rob Hamerling.