Model Railroad System  2.2.1
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 : Sun Jul 12 15:21:38 2015
11 // Last Modified : <150801.1436>
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 
46 /**
47  * @mainpage Block Abstract Types (Classes)
48  *
49  * This folder contains a collection of Tcl code to implement block occupancy
50  * detection, using various methods. At the very least, block detection
51  * results in signal aspect updates. Code for managing signals is in in the
52  * Signals folder.
53  *
54  * There are two main ways to detect trains: using optical sensors or using
55  * current sensors. Optical sensors generally work via reflection (bouncing a
56  * light beam off the bottom of the train), although an across-the-tracks
57  * type is possible too. Current sensors work by sensing a current flow
58  * when a locomotive, lighted passenger car, or a freight car with resistors
59  * installed on its wheelsets passes onto an electrically isolated section of
60  * track. In any case, the sensor is connected to the computer somehow, either
61  * via USB or via a direct or indirect I/O bit or port.
62  *
63  * @section files Source Files
64  *
65  * There are several Tcl source files in this directory. Each contains a
66  * SNIT @b Abstract data type (also known as a @e Class). This abstract data
67  * type encapsulates a single @e block. All of these abstract data types
68  * include a method named @c occupiedp, which returns a true or false result
69  * indicating whether or not the block is occupied. The constructor for these
70  * types include options or arguments that define the I/O device(s) that
71  * connect to whatever sensors are being used to detect block occupancy.
72  *
73  * @subsection mrd2 MRD2U Sensor (USB connected optical sensor)
74  *
75  * MRD2_Block.tcl contains an abstract data type (MRD2_Block) that implements
76  * blocks using one Azatrax MRD2U Sensor for each block.
77  *
78  * @subsection c4tsr4 Circuits4Tracks Quad Occupancy Detector with a SR4 (USB connected I/O board)
79  *
80  * C4TSR4_Block.tcl contains an abstract data type (C4TSR4_Block) that
81  * implements blocks using Circuits4Tracks Quad Occupancy Detectors connected
82  * to Azatrax SR4 modules using SSRs. One Circuits4Tracks Quad Occupancy
83  * Detector and one SR4 will handle 4 blocks.
84  *
85  * @subsection c4tsmini Circuits4Tracks Quad Occupancy Detector connected to a C/MRI SMINI board
86  *
87  * C4TSMINI_Block.tcl contains an abstract data type (C4TSMINI_Block) that
88  * implements blocks using Circuits4Tracks Quad Occupancy Detectors connected
89  * to input pins of a Bruce Chubb C/MRI Super Mini (SMINI) board. A Bruce
90  * Chubb C/MRI Super Mini (SMINI) board has enough inputs to handle a number
91  * of Circuits4Tracks Quad Occupancy Detectors.
92  *
93  * @subsection c4ttb Circuits4Tracks Quad Occupancy Detector connected to a CTI Train Brain
94  *
95  * C4TTB_Block.tcl contains an abstract data type (C4TTB_Block) that
96  * implements blocks using Circuits4Tracks Quad Occupancy Detectors connected
97  * to the sensor inputs of a CTI Train Brain, Watchman, or Sentry board.Circuits4Tracks Quad Occupancy Detector connected to a
98  *
99  * @section Commmethods Common methods and functionality
100  *
101  * All three types have a common structure. The constructors take the form:
102  * @code
103  * typename objectname [optional options]
104  * @endcode
105  * Eg:
106  * @code
107  * MRD2_Block block2 -previousblock block1 -sensorsn 020001234 \
108  -forwardsignalobj signal2
109  * @endcode
110  *
111  * There are a pair of common options, @c -previousblock and @c -nextblock,
112  * which are the names of the previous block in the forward direction and the
113  * name of the previous block in the reverse direction. Another pair of
114  * common options, @c -forwardsignalobj and @c -reversesignalobj, are the
115  * names of signal objects. Also there is the option, @c -direction with sets
116  * the current operating direction for the block and can be @c forward or
117  * @c reverse. For blocks that only support traffic in one direction, use only
118  * the @c -previousblock and @c -forwardsignalobj options. The @c -direction
119  * defaults to @c forward. There are other object specific options that define
120  * how the sensor is accessed by the block object.
121  *
122  * There are four common methods, two public and two private (the private
123  * methods should not be used by external code). The public methods are
124  * @c occupiedp and @c propagate. The @c occupiedp method returns a true or
125  * false (logical) value that indicates whether the block is occupied or not.
126  * The @c propagate method takes a signal aspect to 'propagate' to the
127  * previous block. The @c occupiedp method is typically called from the
128  * occupied command script associated with a piece of track work.
129  *
130  * The two private methods, @c _entering and @c _exiting are used to implement
131  * special handling when entering or leaving a block. Presently, the
132  * @c _entering method sets the signal aspect and propagates signal aspects
133  * down to previous blocks and the @c _exiting method does nothing. These
134  * methods can be extended to add additional functionality, as needed.
135  *
136  */
137 
138 
139 #endif // __MAIN_H
140