Model Railroad System  2.2.2
main.h
1 // -!- c++ -!- //////////////////////////////////////////////////////////////
2 //
3 // System :
4 // Module :
5 // Object Name : $RCSfile$
6 // Revision : $Revision$
7 // Date : $Date$
8 // Author : $Author$
9 // Created By : Robert Heller
10 // Created : Tue Jul 14 12:40:17 2015
11 // Last Modified : <150816.1142>
12 //
13 // Description
14 //
15 // Notes
16 //
17 // History
18 //
19 /////////////////////////////////////////////////////////////////////////////
20 //
21 // Copyright (C) 2015 Robert Heller D/B/A Deepwoods Software
22 // 51 Locke Hill Road
23 // Wendell, MA 01379-9728
24 //
25 // This program is free software; you can redistribute it and/or modify
26 // it under the terms of the GNU General Public License as published by
27 // the Free Software Foundation; either version 2 of the License, or
28 // (at your option) any later version.
29 //
30 // This program is distributed in the hope that it will be useful,
31 // but WITHOUT ANY WARRANTY; without even the implied warranty of
32 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
33 // GNU General Public License for more details.
34 //
35 // You should have received a copy of the GNU General Public License
36 // along with this program; if not, write to the Free Software
37 // Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
38 //
39 //
40 //
41 //////////////////////////////////////////////////////////////////////////////
42 
43 #ifndef __MAIN_H
44 #define __MAIN_H
45 /** @mainpage Switch (Turnout) Abstract Types (Classes)
46  *
47  * This folder contain a collection of Tcl code to implement switches (aka
48  * turnouts), using various actuator hardware. Included is OS detection and
49  * point position detection, along with code to operate switch motors.
50  *
51  * @section files Source Files
52  *
53  * There are several Tcl source files in this directory. Each contains a
54  * SNIT @b Abstract data type (also known as a @e Class). This abstract data
55  * type encapsulates a single @e switch (turnout). All of these abstract data
56  * types a method named @c occupiedp, which returns a true or false result
57  * indicating whether or not the OS is occupied. Also included are a
58  * @c pointsense method which returns the state of the points and a @c motor
59  * method which operates the switch machine to move the points.
60  *
61  * @subsection sr4_mrd2 SR4 as actuator and pointsense with a MRD2U for OS detection
62  *
63  * SR4_MRD2_Switch.tcl contains an abstract data type (SR4_MRD2_Switch) that
64  * implements switches using one half of a Azatrax SR4 for the actuator and
65  * pointsense and a Azatrax MRD2U Sensor for OS detection.
66  *
67  * @subsection sr4_c4tsr4 SR4 as actuator and pointsense with a Circuits4Tracks Quad Occupancy Detector with a SR4 (USB connected I/O board).
68  *
69  * SR4_C4TSR4_Switch.tcl contains an abstract data type (SR4_C4TSR4_Switch)
70  * that implements switches using one half of a Azatrax SR4 for the actuator
71  * and 1/4 of a Circuits4Tracks Quad Occupancy Detector connected to another
72  * Azatrax SR4 for OS detection.
73  *
74  * @subsection smini_c4t Chubb SMINI board as actuator and pointsense with a Circuits4Tracks Quad OD as OS sensor
75  *
76  * C4TSMINI_Switch.tcl contains an abstract data type (C4TSMINI_Switch) that
77  * implements switches using a Chubb SMINI board as actuator and pointsense
78  * with a Circuits4Tracks Quad OD as OS sensor.
79  *
80  * @subsection tb CTI Yardmaster as actuator and Train Brain as pointsense with a Circuits4Tracks Quad OD as OS sensor
81  *
82  * TB_Switch.tcl contains an abstract data type (TB_Switch) that implements
83  * switches using a CTI Yardmaster as actuator and a Train Brain for
84  * pointsense with a Circuits4Tracks Quad OD as OS sensor.
85  *
86  * @section Commmethods Common methods and functionality
87  *
88  * All three types have a common structure. The constructors take the form:
89  * @code
90  * typename objectname [optional options]
91  * @endcode
92  * Eg:
93  * @code
94  * SR4_MRD2_Switch switch1 -motorobj turnoutControl1 -motorhalf lower \
95  * -pointsenseobj turnoutControl1 \
96  * -pointsensehalf lower -plate SwitchPlate1 \
97  * -ossensorsn 0200001234
98  * @endcode
99  *
100  * There are a trio of common options, -previousblock, -nextmainblock,
101  * and -nextdivergentblock which are the names of the previous block in the
102  * forward direction and the name of the previous blocks in the reverse
103  * direction. Another trio of common options, -forwardsignalobj,
104  * -reversemainsignalobj, and -reversedivergentsignalobj are the
105  * names of signal objects. Also there is the option, -direction with sets
106  * the current operating direction for the block and can be forward or
107  * reverse. For blocks that only support traffic in one direction, use only
108  * the -previousblock and -forwardsignalobj options. The -direction
109  * defaults to forward. There are other object specific options that define
110  * how the sensor is accessed by the block object.
111  *
112  * There are six common methods, four public and two private (the private
113  * methods should not be used by external code). The public methods are
114  * occupiedp, propagate, pointstate, and motor. The occupiedp
115  * method returns a true or false (logical) value that indicates whether the
116  * switch is occupied or not. The pointstate method returns the state if
117  * the points. The motor method activates the switch motor to move the
118  * points. The propagate method takes a signal aspect to 'propagate' to the
119  * previous block. The occupiedp method is typically called from the
120  * occupied command script associated with a piece of track work. The
121  * @c pointstate method is typically called from the state sense script
122  * associated with the switch track work. And the motor method is assocated
123  * with the normal and reverse scripts for the switch's switch plate on the
124  * CTC panel.
125  *
126  * The two private methods, _entering and _exiting are used to implement
127  * special handling when entering or leaving a block. Presently, the
128  * _entering method sets the signal aspect and propagates signal aspects
129  * down to previous blocks and the _exiting method does nothing. These
130  * methods can be extended to add additional functionality, as needed.
131  *
132  *
133  */
134 
135 #endif // __MAIN_H
136