Model Railroad System  2.2.1
CrossingInterchangeExample.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 : Thu May 10 15:47:38 2018
11 // Last Modified : <180519.1119>
12 //
13 // Description
14 //
15 // Notes
16 //
17 // History
18 //
19 /////////////////////////////////////////////////////////////////////////////
20 //
21 // Copyright (C) 2018 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 __CROSSINGINTERCHANGEEXAMPLE_H
44 #define __CROSSINGINTERCHANGEEXAMPLE_H
45 /** @page CrossingInterchangeExample Crossing Interchange Controlled by a Raspberry Pi with HATs and LCC
46  * This example illustrates how one might implement the control aspects of a
47  * simple interchange between two rail lines that meet at a level crossing.
48  * The layout module is shown here:
49  * @image html CrossingInterchange_Small.png
50  * @image latex CrossingInterchange.png "Crossing Interchange Layout" height=3.25in
51  * @latexonly
52  * \footnote{There is an XTrkCAD file, named \texttt{CrossingInterchange.xtc},
53  * and a PDF file, named \texttt{CrossingInterchange.pdf}, in the examples
54  * distribution directory.}
55  * @endlatexonly
56  * @htmlonly
57  * <h4 style="text-align:center;">Crossing Interchange Layout</h4>
58  * <br clear="all" />
59  * @endhtmlonly
60  *
61  * @section CrossingInterchangeExample_hw Hardware used.
62  *
63  * We will control the two turnouts with a SMCSenseHAT. This board uses 4
64  * GPIO pins on the Raspberry Pi, two to set the motors and two to sense the
65  * state of the switch motors.
66  *
67  * Signaling will be with 8 three color single head signals and with 2
68  * 3 over 2 double head signals at the point entrance to the turnouts. There
69  * is a total of twelve heads and we will use three QuadSignalCA HATs and
70  * common anode LED signals.
71  *
72  * We will be sensing occupancy of 8 blocks:
73  * -# @b OS1 Turnout SW1, at the northern entrance of the north-south rail line.
74  * -# @b OS2 Turnout SW2, at the eastern entrance of the east-west rail line.
75  * -# @b Crossing @b OS The level crossing itself.
76  * -# @b Interchange The interchange track connecting between the two
77  * turnouts.
78  * -# @b Main @b One The east-west mainline between SW2 and the Crossing.
79  * -# @b Main @b Two The north-south mainline between SW1 and the Crossing.
80  * -# @b Main @b One @b West The east-west mainline west of the Crossing.
81  * -# @b Main @b Two @b South The north-south mainline south of the Crossing.
82  *
83  * We can use a pair of Circuits 4 Tracks Quad Occupancy detector boards, with
84  * their outputs wired to 8 of the Raspberry Pi's GPIO pins.
85  *
86  * We will have a total of 5 HAT boards:
87  * - 1 @b SMCSenseHAT to manage the two turnouts.
88  * - 1 @b Adafruit @b Perma-Proto @b HAT to connect the occupancy detector
89  * boards.
90  * - 3 @b QuadSignalCA @b HATs to light the 12 signal heads.
91  *
92  * The @b SMCSenseHAT is hardwired to use Wiring Pi pins 0, 1, 2, and 3 (BCM
93  * pins 17, 18, 27, and 22). The PiGPIO XML file included with this example,
94  * maps Motor 1 (pin 0 for motor control and pin 2 for point sense) to SW1
95  * and motor 2 (pin 1 for motor control and pin 3 for point sense) to SW2.
96  *
97  * The @b SMCSenseHAT is connected as shown here:
98  * @image html CrossingInterchange_SMCSenseHAT_Small.png
99  * @image latex CrossingInterchange_SMCSenseHAT.png "Connecting the SMCSenseHAT" height=3.5in
100  * @htmlonly
101  * <h4 style="text-align:center;">Connecting the SMCSenseHAT</h4>
102  * <br clear="all" />
103  * @endhtmlonly
104  *
105  * The @b Adafruit @b Perma-Proto @b HAT is wired as shown below. The only
106  * components installed on this board are a pair of 6 position screw terminals.
107  * It is possible to use a board that simply has screw terminals for the GPIO
108  * pins (like the Adafruit Pi-EzConnect Terminal Block Breakout HAT) instead
109  * of wiring up a board like this. The PiGPIO XML file included with this
110  * example maps the GPIO pins like this:
111  * - WPi 4 (BCM 23) to OS2
112  * - WPi 5 (BCM 24) to Main One
113  * - WPi 6 (BCM 25) to Crossing OS
114  * - WPi 7 (BCM 4) to OS1
115  * - WPi 21 (BCM 5) to Interchange
116  * - WPi 22 (BCM 6) to Main Two
117  * - WPi 23 (BCM 13) to Main One West
118  * - WPi 26 (BCM 12) to Main Two South
119  *
120  * This is how the GPIOs are wired:
121  * @image html CrossingInterchange_OccupencyHAT_Small.jpg
122  * @image latex CrossingInterchange_OccupencyHAT.jpg "Wiring and connecting the Adafruit Perma-Proto HAT." height=3in
123  * @htmlonly
124  * <h4 style="text-align:center;">Wiring and connecting the Adafruit Perma-Proto HAT.</h4>
125  * <br clear="all" />
126  * @endhtmlonly
127  *
128  * The QuadSignal XML files included with this example maps the signals like
129  * this:
130  * - First board (i2c address 0):
131  * - S1S H1 and H2
132  * - S1MN H3
133  * - S1IN H4
134  * - Second board (i2c address 1):
135  * - S2ME H1
136  * - S2W H2 and H3
137  * - S2IE H4
138  * - Third board (i2c address 2):
139  * - S3W H1
140  * - S3N H2
141  * - S3E H3
142  * - S3S H4
143  *
144  * This is how the @b QuadSignalCA @b HATs are wired (be sure to take note of
145  * the address jumpers):
146  * @image html CrossingInterchange_CP1Signals_Small.png
147  * @image latex CrossingInterchange_CP1Signals.png "Connecting the signals at Control Point 1." height=2.75in
148  * @htmlonly
149  * <h4 style="text-align:center;">Connecting the signals at Control Point 1.</h4>
150  * <br clear=="all" />
151  * @endhtmlonly
152  * @image html CrossingInterchange_CP2Signals_Small.png
153  * @image latex CrossingInterchange_CP2Signals.png "Connecting the signals at Control Point 2." height=2.75in
154  * @htmlonly
155  * <h4 style="text-align:center;">Connecting the signals at Control Point 3.</h4>
156  * <br clear=="all" />
157  * @endhtmlonly
158  * @image html CrossingInterchange_CP3Signals_Small.png
159  * @image latex CrossingInterchange_CP3Signals.png "Connecting the signals at Control Point 3." height=2.75in
160  * @htmlonly
161  * <h4 style="text-align:center;">Connecting the signals at Control Point 3.</h4>
162  * <br clear=="all" />
163  * @endhtmlonly
164  *
165  * @section CrossingInterchangeExample_sw Software used.
166  *
167  * This example uses these 3 OpenLCB daemons:
168  * -# OpenLCB_QuadSignal (three instances, one for each QuadSignalDriverCA hat).
169  * -# OpenLCB_PiGPIO (for both the SMCSenseHat and the detector inputs)
170  * -# OpenLCB_Logic (to implement the signaling logic)
171  *
172  * This example also uses a CTC panel created by the Dispatcher program.
173  *
174  * Each deamon instance's configuration is taken from an XML file (included in
175  * this example's distribution directory) and the CTC panel exists as a
176  * Tcl/Tk source file (which is also included in this example's distribution
177  * directory).
178  */
179 
180 #endif // __CROSSINGINTERCHANGEEXAMPLE_H
181