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.
This chapter describes the design and implementation aspects of DigiAPI,
such as:
- Multitasking
- Multiple ports (devices)
- Multiple modelrailroad manufacturer specific protocols
- Priority for time-critical tasks
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:
- Train control, with smooth acceleration and decelleration
- Turnout control
- Sensor feedback signalling
- Emergency control
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:
- User interface (DigiAPI.c), with common data
- A driver DLL for each protocol
- A common driver DLL for each protocol
DigiAPI
Major functions of the application programming interface component
- Activate protocol driver at 'open' of a channel
- Initialise tables with open of first channel
- Pass user requests to protocol driver when it implies a change of the
current status of the system or components of the modelrailroad.
- Report on request status of system, loc, turnout and sensor status, use
data maintained by protocol driver(s).
Protocol drivers
Major functions of each protocol driver
- Create command queue(s) for different components (locs, turnouts, etc)
- Translate commands from DigiAPI into protocol dependent format
- Put command in a queue for trannmission to the modelrailroad system
- Process replies (update tables in DigiAPI)
- Update common tables after (probably) successful command execution
- Update common tables with information obtained with soliticied and
unsolicited feedback data
Common Services
Major functions of each protocol driver
- Create command queue(s) for different components (locs, turnouts, etc)
- Translate commands from DigiAPI into protocol dependent format
- Put command in a queue for trannmission to the modelrailroad system
- Process replies (update tables in DigiAPI)
- Update common tables after (probably) successful command execution
- Update common tables with information obtained with soliticied and
unsolicited feedback data
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
- Table updates should be done by the driver DLL's, not by DigiAPI.DLL,
unless of course it is an 'adminstrative' update.
An example of this might be to bring the direction information of a
Marklin-Old decoder in accordance with reality.
- With commands tables should be updated after transmission of the
command, not at the moment it is put in the transmission queue!
With systems reporting the result of a command the update should be done
after the command has apparently been accepted, otherwise it may be done
immediately after transmission.
- Tables should be updated as soons as the information is received
(of solicited or unsolicited status messages).
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.
- Märklin
Reading of S88 decoders is used for monitoring.
- Lenz
If no loc, turnout or sensor group is active, the 'Request System
Status' is used to monitor the state of the modelrailroad.
If a loc is active (a command has been sent), a 'request loc status'
command is used in round robin mode for all active locs.
The 'round robin' is restarted after each loc command with the last loc
being interrogated.
This means that the actual status of a loc is always present in DigiAPI.
Even when a loc is controlled by another device, it will be noticed by
DigiAPI (with some delay).
The above also applies to turnout decoders and feedback encoders.
If any feedback encoder information is ever sent or received each 'active'
encoder will be considered active and be interrogated regularly.
- Trix Selectrix
The monitoring process interrogates alternately active decoders
(successively cycling through all active locs and turnout decoders) and
active feedback encoders.
- Uhlenbrock Intellibox
The Intellibox is interrogated with the XEvent command to track system
status.
When a specific event is reported, the appropriate XEvt... command is issued
to obtain the event data.
- Digitrax Loconet
No active polling is performed.
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.
- Several threads are started by DigiOpen for the following tasks:
- Transmit of data to the output device
- Receive of data from the input device
- Monitoring
Although the monitoring thread is started by DigiOpen, the actual
monitoring is only activated with DigiEnableFeedback.
Until that time the monitor-thread is idling.
The threads run at a high priority (foreground server level) to ensure
proper execution.
- Each transmit task receives its data by means of a queue.
The data may come from the DigiApi functions, or from internal threads, in
particular the monitoring thread.
This construction - a separate thread with an input queue - has been chosen
to prevent blocking of the main thread (the user application!) while sending
data.
- A new command is only sent when the previous command had been
transmitted completely (check on line status) and when subsequently CTS is
true (check modem Status) or becomes ready within the timeout time.
Miscellaneous
Miscellaneous information.
- Traffic statistics recorded per channel.
Counting is performed by the protocol DLLs.
- All command count and bytes transmitted recorded in xxxCOM in the
command transmit function just befor physical transmission.
- Received bytes are counted in xxxEvt while perfoming the monitoring
function. In active monitoring commands are counted there.
- Trace records are counted in the SERVICE.DLL
-