Application Programming Interface
and Driver
for Digital Modelrailroads



Design of DigiAPI

Rob Hamerling
Vianen, The Netherlands

E-mail: r.hamerling@hccnet.nl
homepage: http://www.robh.nl/

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


Table of Contents

Related publications


General Design Aspects

This chapter describes the design and implementation aspects of DigiAPI, such as:

Layered Structure

DigiAPI has a layered structure like many other datacommunications systems, based upon the ISO model for Open Systems Interconnect. The schematic below shows the different layers of DigiAPI.

Presentation Modelrailroad status (loc speed, turnout status, etc)
Channel Protocol
Transport Flow control
Link Data format, transmission speed
Physical Wiring, electrical signalling

The functionality of the DigiAPI layers is described in the following sections.

Presentation layer

This is the interface between application and DigiAPI. This is the 'public' interface for a normal user application to control a digital modelrailroad with DigiAPI. All lower layers are hidden for the application.

The primary function of this layer is to provide the application with an interface which is independent of the modelrailroad system. It provides the 'high-level' functions which should be avialable for any system, but which may be implemented diffently by the various systems, such as:

Channel layer

The concept of channels

DigiAPI allows control of a single modelrailroad via different interfaces. This makes it possible to send commands via one interface and monitor sensor activity by another interface.

Each path to the modelrailroad is called a Channel. Channels are completely independent from each other, but they use common datatables for the single modelrailroad. These tables are in the Channel

Channel Interface

The channels are accessed identical, independent of the system under control.

It hides decoder addressing, contact/sensor monitoring Commands are buffered (queued), but not delayed on purpose

Transport Layer

Queuing and buffering of commands and responses, monitoring of system status and sensor contacts

Link layer

Transmission of commands and receive of responses

Physical layer

Initialisation and monitoring of the physical connection between computer and modelrailroad Interface


Functional Specification

DigiAPI has 3 major components:

  1. User interface (DigiAPI.c), with common data
  2. A driver DLL for each protocol
  3. A common driver DLL for each protocol

DigiAPI

Major functions of the application programming interface component

Protocol drivers

Major functions of each protocol driver

Common Services

Major functions of each protocol driver

Definitions

Command Time
Time between (first) delivery to Interface and succesful acceptance
Service Time
Time system has been busy delivering the command
Loc Speed
Speed is stored internally as a value in the range +1..+127 for forward driving and in the range -1..-127 for backward driving. The values +1 and -1 mean effectively speed 0, but indicate the direction of a loc even with zero speed. The application should consider
Note: speed 1 is in many systems used for emergency stops (HALT command), but this is not supported by the DigiSetControlLoc() function. For an emergency stop the application should use the DigiHalt() function.

Conventions


Protocol Differences

Monitoring system status

Monitoring the state of the modelrailroad is performed by sending commands that will cause the modelrailroad system send back some reply. If no reply is received within the expected period, DigiAPI will try to determine the reason (no response, blocked output, etc.). Monitoring is always active.

For different systems different techniques are used, described briefly below.

DigiAPI is designed to control one single modelrailroad, even when more than one channel is being opened. Although it is not considered an error to enable feedback on all channels, it is not useful to enable feedback monitoring on more than one channel.

Command Queue

DigiAPI uses several queues. Commands to be delivered to the modelrailroad are put into a FiFo queue. Depending on the modelrailroad equipment, there may be more than one queue. For most systems there is one queue for loc commands and one queue for turnout commands per channel. For the Intellibox the are separate queues each of the loc decoder protocols (Marklin/Motorola, DCC and Selectrix).


Implementation

This chapter contains the OS/2-specific aspects if DigiAPI.


Miscellaneous

Miscellaneous information.