Application Programming Interface
and Driver
for Digital Modelrailroads

Version 2.3



Introduction to DigiAPI

Rob Hamerling
Vianen, The Netherlands

E-mail: r.hamerling@planet.nl
homepage: http://www.geocities.com/digithalys/

Copyright © R. Hamerling, 1991, 2000
All Rights Reserved.


Table of Contents

Note: The documents of DigiAPI have a hierarchical link structure: clicking an item brings you to that item, and clicking a title brings you one level higher in the document structure.

Related publications


What is DigiAPI?

DigiAPI is a combination of:

DigiAPI reliefs a programmer from 'low level' tasks such as controlling the communication with the Interface, bothering about protocol specific differences, etc. It significantly simplifies programming for model-railroads which are controlled via a so called Interface or a 'direct driver'. With DigiAPI the developper of a modelrailroad control program can concentrate on the primary task: the logic of modelrailroad control.

DigiAPI is NOT a ready to use modelrailroad control program!

Purpose

The driver and API have been developed for the following purposes:

As a result a modelrailroad control program based on DigiAPI can be built relatively quickly and since it never has to wait for anything it can be very efficient.

Program Development Steps

To interact with a modelrailroad, a simple setup is as follows:

  1. Start communications with the DigiOpen function.
  2. Control the operation of trains and accessories with the various functions provided by DigiAPI.Lib.
  3. Terminate with the DigiClose function.

A more detailed C-language framework and QuickBasic framework can be found in the Application Programming Guide for DigiAPI.

The following categories of operational functions are provided:

  • Train management, for setting speed and functions
  • Accessory management, for switches, signals, decouplers, etc.
  • Feedback management, monitoring feedback contact points
  • Emergency management, generally called 'stop' and 'go'
  • Miscellaneous, for timing, sound, statistics and debugging.

    All these operational functions are 'asynchronous', which means that function calls return immediately, without waiting for any communications activity between computer and modelrailroad. A function call is handled internally in DigiAPI as a request for service. The requests are executed by the routines of DigiAPI independently and without putting the calling task in a wait.

    The available functions are described in more detail in Overview of available functions in the Programming Guide for DigiAPI. The Programming Reference manual for DigiAPI contains the specification details.

    Realisation

    This package offers a set of drivers with all the functionality listed in Functional Requirements. The internal differences between the OS/2 and DOS drivers the mainline of a modelrailroad control program can to a large extend be unaware of the underlying operating system and/or modelrailroad system.

    DigiAPI has built-in multi-tasking, which is highly desirable for a realtime ('process control') environment like a computer controlled modelrailroad. As a rule an application program never has to wait for physical I/O, all functions return immediately, but there are a few exceptions.

    The application programming interface (API) has an abstraction level which hides the differences between systems of different manufacturers.
    It uses a consistent nnumbering (in stead if addressing) scheme to access locs, magnetic or electric accessories and feedback information. The translation (forward and backward) between the component numbers and decoder addresses is all under the covers. This allows the creation of system independent application programs. The same version of a control program can be used for different systems.

    You may read about some differences of minor importance in Differences between OS/2 and DOS.

    DigiAPI is still under construction. Changes may be applied without notice, while the version number remains unchanged!

    When reporting problems, mention the file date of the library used. Even better: before reporting, please collect the latest version to see if the problem still exists!

    Registration

    This package is Shareware: The freely distributed version is a demo licence with some functional limitations:

    If you would like to use DigiAPI without these limitations you should register yourself and pay the requested shareware contribution. After registration, I'll send the following: You may receive the registration package by Internet or by mail on diskette.

    An additional registration is needed when are want to distribute the driver as part of your own railroad control application programs. Check with the author.

    Notes.

    DigiAPI may be distributed freely under the following conditions:

    The registration fee is 49 Dutch Guilders, or the equivalent of 30 US-Dollars. Banknotes of major countries are accepted as well. If you send cheques, please fill in your personal number, otherwise I'm afraid I have to refuse your registration, because of the extra costs.

    Please send comments and registration fee to:

         R. Hamerling
         Hogelandseweg 67
         4132 CV  Vianen
         The Netherlands
         Postbank account 2087285
    

    Mention the purpose of your payment ("DigiAPI"), and the destination address!