BOOSTER.SYS is an OS/2 device driver to control your Märklin Digital
modelrailroad directly from the COM-port of the PC, without the need of an
Interface and Control Unit.
It replaces the regular driver for a COM-port (COM.SYS) and generates the
Digital signal from commands it receives from a regular model railroad
control program, as if the program was communicating with the Interface.
The output signal of the physical COM-port is input for a booster.
BOOSTER.SYS is designed to act like COM.SYS, in such a way that any
program that normally communicates with the Interface through COM.SYS should
notice no difference when using BOOSTER.SYS in stead.
BOOSTER.SYS has proven its functionality and proper working with several
digital control programs built on top of DigiAPI.
For the development of this driver I used information from several
sources, for which I am very grateful!
Both authors were kind enough to inform me about some details that I did
not understand.
Most of my time however was spent in learning how to write an OS/2 device
driver in C-language!
(*) Function decoder commands are only supported for the new protocol,
i.c. for loc decoders with the 4 extended functions
(see Customising Booster.Sys).
Booster.Sys has this support enabled by default, but when it is disabled
commands for Function Decoders are rejected.
Some extra functionality above what is supported by the regular hardware
(combination of Interface and Control Unit) is provided,
for details see Extra.
Booster.Sys is constantly transmitting data at 38400 bps, and has some
intensive processor-bound work.
Therefore the minimum recommended hardware looks like
Buffered COM-port (16550 UART)
Of course the system should run OS/2 Warp 3.0 or newer, with its own
requirements of memory, etc.
Booster.Sys itself takes less than 10 KB of memory during runtime.
Apart from making the device driver known to OS/2, you have to make a
physical connection between the COM-port and the booster.
You might have to make some modifications to your railroad control program.
All these aspects are described in this chapter.
You need to connect your booster directly to a COM-port.
Only 2 wires are needed
The following picture shows how the COM-port is connected to a booster.
+------------------+
transmit | |
COM-port ---------------- --------- Rail
of PC ---------------- BOOSTER ---------
ground | |
+------------------+
If you use an EDiTS booster no voltage adaptations are needed.
This booster may be controlled directly with RS232 voltage level
(usually -12V to +12V).
boosters work with TTL voltage levels (0 to 5 V).
The RS232 signal should be reduced to TTL level.
A possible circuit might be:
4.7 K_Ohm
transmit +------+
-----------| |-----+------------------
+------+ |
|----- to
from COM-port /|\ 5.1 V Zener M„rklin
/ | \ booster
-------
|
------------------------+------------------
signal ground
You may have a look at Froitzheims document on Internet.
Unpack the files from the package in a directory.
For the use of the BMODE command (see BMODE) a
directory which is part of your PATH statement in Config.Sys is preferred.
To active the Booster driver, you need to add a device-statement to
CONFIG.SYS after the specification of COM.SYS.
The statement should look like
DEVICE=[drive][path]BOOSTER.SYS [<port> [<base-address> [<IRQ>]]]
Drive and path should specify the location of Booster.Sys.
All parameters are optional, the following rules apply to their
specifications
- <port>
- digit in the range 1..4.
If none or a not acceptable value is specified the default COM1 will be
selected.
The base-address and IRQ level are set to the standard settings for this
port number (see below), which may overridden by parameters which follow.
- <base-address>
- Hexadecimal representation of the base-address of the COM-port (for
example 2F8 for COM2).
COMport address
1 03F8
2 02F8
3 03E8
4 02F8
- <IRQ>
- Hexadecimal value of the of IRQ level used by the COM-port
(for example 3 for the standard COM2).
The actually used values are displayed during driver initialization.
You may specify this statement more than once to install a device driver
for each booster to be controlled by your program(s).
The default settings for COM1 to COM4 are
COMport IRQ
1 4
2 3
3 4
4 3
See DosDevIOCtl and BMODE
for operational parameters and how to change these.
- When Booster.Sys examines the COM-port, it detects if it has the
hardware (FIFO) buffering facility.
If present it will use this feature for transmitting frames.
You cannot disable the use of this feature, nor force it to be used if
detection might fail.
When FIFO is available, Booster.Sys can also use it for the transmission
of 'idle' characters during the longer pauses between commands, like
described by Froitzheim.
Sinces some loc decoders don't function properly when this idle characters
are transmitted, this feature is by default disabled.
It can be enabled:
- before starting your railroad control program with the BMODE command
(see BMODE),
- from within your application via a private DosDevIOCtl category and
functions, see DosDevIOCTL.
- This driver does currently not support the old original function
decoders as used in the 'Panoramawagen' (Märklin 4999), and 'Tanzwagen'
(Märklin 4998).
Function decoder commands will be interpreted as setting of the 4 extended
functions in the new extended function loc decoders.
This feature is by default enabled, but may be disabled by your application
in a similar way as described above for the 'idle' characters.
- TxD
- As you would expect the Digital block pattern is transmitted on the
Transmit lead (TxD) of the UART.
- DTR
- Booster.Sys rises DTR at open, and drops it after close of the port.
It will also drop DTR with a STOP command and rise it with a GO command.
The purpose of this is to switch off the booster, otherwise a permanent
negative voltage will remain on the rail.
This lead is optional.
If you don't connect it, or if your booster has this facility not available,
then a STOP will just result in no transmission of frames, and your trains
will come to a halt (maybe slowly!).
- RTS
- The RTS-lead contains a trigger signal which is transmitted at the
beginning of the transmission of a new command.
This allows for (better) display of the data pattern on an oscilloscope with
external triggering, but is otherwise of no use (the RTS signal is not
connected to the booster).
- DSR
- DSR is monitored by Booster.Sys to detect overload or power-off
conditions of the booster.
This lead is also optional.
If you don't connect it, Booster.Sys will not detect any power problems and
your application will not be able to react!
- CTS
- The CTS lead is not physically connected, but its behaviour as observed
by the application program with DosDevIOCtl calls is like that of the CTS
lead of a real Interface (see also OS/2 Programming).
If you decide not to continue using Booster.Sys, or when it is the
suspected source of system problems, then deactivate it by:
- Remove the DEVICE-statement for Booster.Sys from Config.Sys
- Reboot OS/2
You may then erase all the Booster files.
This chapter covers the aspects of use of model railroad control programs
in combination with this BOOSTER driver.
Booster.Sys behaves like COM.SYS and the documentation for COM.SYS in the
OS/2 manuals applies equally well to Booster.Sys.
Because of its special purpose function, there are some specific details you
may need to know.
- The driver is developed for OS/2 Warp version 3 and higher.
- Booster.Sys has been tested with the DigiAPI package of the same
author.
It has also been tested with version 1.7 of MKLAPI (which is still
available, but not supported anymore).
- Write requests result in sending a loc speed command before returning
to the application ('blocked mode').
Normal write timeouts are respected, default 60 seconds,
but may be changed with a DosDevIOTCL call with category IOCTL_ASYNC
function ASYNC_SETDCBINFO.
During handling of write request the simulated CTS line is kept down for a
period of between 10 and 20 milliseconds.
- All kinds of DosDevIOTCL requests are handled mostly like COM.SYS, but
for some restrictions and specific differences
see Program Development.
- Although the driver is output only, DosRead requests are accepted and
handled normally, but always return zero bytes received.
Normal read timeouts are respected, default 60 seconds,
but may be changed with a DosDevIOTCL call with category IOCTL_ASYNC
function ASYNC_SETDCBINFO.
Read-timeouts are supported to prevent excessive 'polling' when DosReads are
issued in a closed loop by a separated thread of your existing application.
When you build your own control program, you should be aware of the
specific behaviour of BOOSTER.SYS.
In general all functions (open, read, write, close, etc. and DosDevIOCTL for
of category IOCTL_ASYNC) behave in the same way as if you would program
for COM.SYS for an connected to a COM-port.
But there are some differences, which may influence your design, such as:
- Booster.Sys accepts only a single open (single ComHandle).
- Writes requests return only after the command is physically transmitted,
the issuing thread is 'blocked' during this time.
- Only loc-commands (range 0..31), function decoder commands (range
64..79), switchpoint commands (32, 33 and 34) and start and stop commands
(96 and 97) are supported.
Write requests return immediately when an unsupported command is
attempted.
The returncode will be zero, BytesWritten will be zero to indicate a failing
write.
- The simulated CTS signal behaves as if a real Interface is connected.
But since writes only return after completion of the physical transmission,
the test for 'CTS true' by the user application before sending the next
command is not really necessary, unless performed by a separate thread!
This is in fact the same with the use of a real Interface and COM.SYS: you
would specify DosSetDcb with CTS flow control and would not have to care
about the status of CTS in your application.
This is the standard behaviour of Booster.Sys and cannot be changed.
An attempt to change the flow control parameters is accepted, but ignored.
- Read commands never deliver any data to the application, but return only
after the actual read-timeout period (according to DCB read timeout
setting).
The returncode will always be zero as well as BytesRead.
- If the used UART supports FIFO mode it is used automatically.
It is a highly desirable feature (the physical COM-port runs at 38400 bps!),
therefore the driver does not allow you to disabled it, neither with
the MODE command nor with your own DosDevIOCTL SetDCBINFO request!
- General DosDevIOCTL function handling:
- Only level 2 DosDevIOCTLs are supported, which means that only 32-bits
OS/2 programs will be able to use the Booster device driver.
Even when parameter values are not used (and not checked), a general failure
will be returned to the application if the parmpackets and/or datapackets
are not specified as documented for COM.SYS
(with some exceptions, see below).
- All standard IOCTL_ASYNC (class 1) DosDevIOCTL request categories are
supported, but queries don't always reflect the settings of the physical
COM-port.
In stead they will reflect the values as if a real Interface was being used.
New parameter settings are mostly ignored and builtin settings are
maintained.
- It is not required to specify a NULL pointer when either DataPacket or
ParmPacket are not required, this condition is not checked by the driver.
If ParmPacket and or DataPacket are required, these must have at least the
required length.
- Specific DosDevIOCTL function handling:
- The line interface will by default report 2400 bps, 8 databits, no
parity, 2 stop bits.
For flexibility a change of these parameters by the application or the Mode
command is accepted, but won't have any effect on the internal behaviour of
the driver.
The physical COM-port runs fixed at 38400 bps, 6 databits, no parity, 1
stopbit.
- Of the parameters controlled via the DCB only the values and flags
related to read- and write-timeouts are processed.
Other parameters cannot be changed.
- Transmit Byte Immediate is supported, but can only be used for single
byte commands of course, like GO (96), STOP (97) or switch-reset (32).
- Behave as if XOFF received (stop transmit) is handled as if the
application sent a STOP command.
- Behave as if XON received (start transmit) is handled as if the
application did sent a GO command.
- The following DosDevIOCTL category 1 (ASYNC) requests always return an
all zero value:
- Query COM error
- Query transmit data status
- Query COM error
- Query COM event information
NOTE DigiAPI does not use these status information fields.
As long as nobody asks for a change for a good reason, these status
information fields will not be implemented in Booster.Sys.
- Not supported DosDevIOCTL category 1 (ASYNC) functions are
- Set Break ON
- Set Break OFF
- Set Enhanced Mode Parameters
- Device monitors are not supported (no difference with COM.SYS!)
Using unsupported functions will have no effect at all (returncode zero).
All these design issues are aimed at the requirement to make any
well-behaving OS/2 railroad control program work with this driver without
any change.
NOTE Claims concerning incompatibility may be accepted, but will
certainly be taken care of for programs based on 'MKLAPI' by the same
author.
Booster.Sys has direct control over the booster.
This allows some more facilities than with a real Interface.
- A STOP command drops DTR.
If only the transmit and ground leads of the COM-port are connected to
the booster, a STOP command will terminate transmission of commands, but the
voltage on the transmit lead will remain negative.
So all power is still on the track!
If your booster has a lead to drop its output power, better connect this
to the DTR lead of your COM-port.
This will have required effect
- A failing booster is reported on DSR.
In case of a short-circuit condition, or a failing primary power,
commands from the Computer fall in a black hole.
Some booster signal a 'power-drop' condition.
If your booster has such a signal lead, then connect this to the DSR lead
of your COM-port.
Booster.Sys will then report a non-functioning booster in its COM-status
word that is returned with DosDevIOCTL category IOCTL_ASYNC, function
ASYNC_GETMODEMINPUT.
Your program will have to monitor this status by calling this function
regularly.
There is no means for 'interrupt driven' signalling.
NOTE Since this facility is not provided by a regular Interface,
this might be an exception to the 'compatibility rule'.
Therefore, in addition to signalling this condition in COMstatus,
Booster.Sys may also drop CTS, to indicate that no more commands are
acccepted, and subsequent Writes are returned with an errorcode.
To be able to change parameters without restarting the system, a private
DosDevIOCTL category has been defined, with functions to query and change
operating parameters.
The method of ASYNC_SETDCBINFO and ASYNC_GETDCBINFO is followed.
The category, functions and the BOOSTERINFO structure to be used for this
facility are defined in file 'boosterc.h'
- IOCTL_BOOSTER
- Private category DosDevIOCtl (0x91)
The category is an arbitrary choice.
It may conflict with other 'private' drivers (not with the standard OS/2
drivers).
It is extremely unlikely that this potential conflict will adversely
influence the proper working of your system, since also a private
DosDevIOCtl request needs the ComHandle of the COM-port which is controlled
by Booster.Sys.
This will prevent conflicts!
- BOOSTER_SETINFO
- FunctionCode for changing operating parameters (0x53).
Expects a Parameter Packet with new operating parameter values.
When not a complete Parameter Packet is passed the function will return
a general failure.
An 'invalid parameter' will be returned when one or more parameter values
are unacceptable.
In that case no parameter will be changed, even not the acceptable ones!
Supported parameters are:
- Set transmission of Idle characters during 'long' pause ON or OFF.
- DIP-switch settings of the simulated 6021 .
When the address field in the ParmPacket is set to 0, then the
parameters are considered as global and will be used for all loc decoders.
When the address field contains a valid loc-address then the parameters
are only used only for the specified decoder.
Currently only the settings for DIP switches 1 and 2 can be assigned on
address basis, other parameters values are ignored.
You cannot change global parameters with a local SET-request.
When a single parameter needs to be changed it is recommended to first
query the current state, then change the particular parameter in the
BoosterInfo and return the changed BoosterInfo block.
- BOOSTER_GETINFO
- Function Code to obtain current operating parameters (0x73).
Expects a Parameter Packet with the Address field set to zero to return
global parameters, and to a value in the range 1..256 for individual
parameters.
Returns a datapacket with the current state of the requested parameters.
When Parameter or Data Packets are too short, a general failure will be
returned.
When the ParmPacket contains a 0, then global parameters are returned.
When the ParmPacket contains a valid loc-address then the parameters
for the specific decoder are returned.
The returned datapacket contains also the current global settings.
- BOOSTER_GETSTATISTICS
- Function Code to obtain an array of statistics counters (0x74).
No Parameter Packet is expected.
Returns a datapacket with an array of 32-bits counters.
The DataPacket must be large enough to receive the complete array
(see the file BOOSTER.H for the actual number of 4-bytes entries).
If too short, a general failure will be returned.
See for the contents of the counters the file BMODE.H (BoosterCounterName)
Examples of use can be found in the source of the BMODE ('Booster-Mode')
command, which is provided as demonstration of these functions,
see also BMODE
BOOSTER.SYS is an OS/2 Physical device driver (PDD).
There no such a driver for DOS, and there is no Virtual Device Driver (VDD).
Therefore this driver is of no use for DOS-programs in a DOS-session under
OS/2 or Windows-programs in a WIN-OS2 session.
This chapter describes user characteristics of the Booster driver.
Booster.Sys should work flawlessly for most loc decoders,
but the older decoders may need some special parameters,
like no idle characters during command pauses,
and disabled support of extended functions.
- The newer loc decoders with 4 extra functions can be used!
The function bits of such a decoder are controlled by your application as if
it were a function decoder with the same address as the loc decoder
(6021 Switch 2 has to be ON).
The original function decoders are not supported!
- The Interface protocol (loc commands to the Interface) does not have an
option to control absolute direction as provided by the new protocol.
When the COM-port is opened by the application forward direction
is set for all locs.
Of course this works only for locs using the extended protocol (6021 Switch
2 ON).
Change of direction is controlled as usual (with command byte 15 or 31).
- EDiTS protocol is supported as far as it conforma to the Märklin
commandset.
- Switch/Signal decoder packets cannot be generated by BOOSTER.SYS with
exactly the same waveform as the hardware, but in practice these
decoders (K83 and K84 or compatible EDiTS decoders) react properly on
this approximated signal.
Most operational characteristics of Booster.Sys are fixed.
Some can be changed with the standard OS/2 MODE command, but normally this
is not necessary for proper operation.
Some booster-specific operating characteristics cannot be changed by the
standard MODE command, and for these cases a special mode command (called
BMODE) is provided.
This command allows for display and change of the 'Idle'-behaviour,
simulation of 6021 including the DIP switch settings of it.
The syntax of BMODE is:
BMODE <port> [Axx] [I+|I-]] [S1+|S1-]..[S3+|S3-]]
in which:
<port> - port number (1 for COM1, etc.)
Axx - 'xx' Address of loc to which command applies
(by default command applies to global parameters)
I - '+' Transmit Idle characters during long pauses
'-' Do not transmit Idle characters (default)
S1..3 - Act like DIP switches on Control Unit (6021)
'+' for ON, '-' for OFF (defaultsSys at COM2 protocol
See also file Boosterc.h for the meaning and effect of the DIP switches.
All parameters are optional.
If none is given, a short help-message is displayed.
The default port is '1', and if no new Idle or Extended Function support
state is given, the old state will be maintained.
When the Axx parameter is not specified, then all other
parameters are applied to all locs (BMODE has then a global scope).
The new global parameters overwrite also any previously set individual loc
parameters.
However when the Axx parameter is specified correctly, the parameters apply
only to the decoder with the indicated address, and all global parameters
are ignored.
For your operating environment you need first to set the global parameters,
then the individual loc parameters.
The 'R'epeat parameter is only active in old-protocol mode (DIP switch 2
OFF), and can be useful when checking the digital signal with a datascope.
BMODE can only be used when the COM-port is not currently in use by any
application.
This means you cannot use it while your model railroad control program is
running, but like with the MODE command the parameters set with BMODE will
be retained.
On the other hand your own control program can change parameters by itself,
see DosDevIOCtl).
- 0.9
- First publicly released version
- 1.0
- February 1998
- Faster repeat cycle by re-transmitting 1 double loc packet in stead of 2
(like the Märklin 6021).
- Improved packet scheduling when new command arrived.
- When it is a speed-command (incl auxiliary function) then a speed packet
will be the first to be transmitted.
When the new command is a function command then the extended function
command will be transmitted.
- new commands are transmitted with 4 double packets (6021 transmits 6
double packets).
- Change direction packet in old protocol format is now transmitted when
DIPSW1=OFF or DIPSW2=OFF (was 'new' format, but this is not always
understood by old loc decoders).
Note: Booster.Sys will NOT transmit change-direction packets for decoders
using new protocol format.
- Default DIP-switch setting is now: "1=OFF 2=ON 3=OFF".
- Removed the 'ballast' of 6020 emulation (repeat only very last loc
command), since nobody would want this stupid behaviour when a much better
facility is available!
- 1.1
- September 1998
- Stability improvements for the highest possible command processing.
Switch commands will take approx. 15 msecs, loc commands approx. 65 msecs
(with the new Märklin/Motorola protocol).
- BMODE has an extra information message to show if the COM-port's
extended hardware (FIFO) buffering is used or not.
- Output of BMODE has been extended with some statistical information.
- Documentation migrated to HTML format.
- 1.2
- February 1999
- Bug fix: support of IDLE-characters re-instated.
- Bug fix in read request handling, resulting in 'nowait' read timeout,
which was not what application expected!
- Statistics extended with count of received read requests (although
application is not supposed to issue read requests!)
- Documentation corrections and structure improvements.
- Supported loc address range now 1..255 (Uhlenbrock system).
- 1.3
- December 2000
When new decoders become available, their new functionality will be added
to the Booster driver if possible.
Most 'clone' decoders are compatible, so this should not be of a problem.
Other enchancements:
- registration to OS/2 Resource Manager
Currently Booster.Sys exists only in a version for OS/2 Warp.
When it has proven itself as functionally working well, there is a vague
plan to make a DOS implementation.
This program is shareware.
This means a couple of things: