1 package org.opentrafficsim.trafficcontrol;
2
3 import org.opentrafficsim.core.object.InvisibleObjectInterface;
4
5 import nl.tudelft.simulation.event.EventListenerInterface;
6 import nl.tudelft.simulation.event.EventProducerInterface;
7 import nl.tudelft.simulation.event.EventType;
8
9 /**
10 * Interface for traffic light controllers.
11 * <p>
12 * Copyright (c) 2013-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
13 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
14 * <p>
15 * @version $Revision$, $LastChangedDate$, by $Author$, initial version Oct 14, 2016 <br>
16 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
17 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
18 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
19 */
20 public interface TrafficController extends EventProducerInterface, EventListenerInterface, InvisibleObjectInterface
21 {
22 /**
23 * Retrieve the Id of the traffic light controller.
24 * @return String; the id of the traffic light controller
25 */
26 @Override
27 public String getId();
28
29 /**
30 * Tell the traffic controller that the state of a detector has changed.
31 * @param detectorId String; id of the detector
32 * @param detectingGTU boolean;
33 */
34 public void updateDetector(String detectorId, boolean detectingGTU);
35
36 /** Traffic controller is starting up. Particular traffic control programs may use additional states not listed here. */
37 final String STARTING_UP = "starting up";
38
39 /** Traffic controller is being cloned. Particular traffic control programs may use additional states not listed here. */
40 final String BEING_CLONED = "being cloned";
41
42 /** Traffic controller is running. */
43 final String RUNNING = "running";
44
45 /** Traffic controller is shutting down. */
46 final String SHUTTING_DOWN = "shutting down";
47
48 /** Traffic controller is off. */
49 final String OFF = "off";
50
51 /** Constant to select variables that have no associated traffic stream. */
52 public final static int NO_STREAM = -1;
53
54 /**
55 * The <b>timed</b> event type for pub/sub that a newly created traffic controller emits. <br>
56 * Payload: Object[] { String trafficControllerId, String initialState }
57 */
58 EventType TRAFFICCONTROL_CONTROLLER_CREATED = new EventType("TRAFFICCONTROL.CONTROLLER_CREATED");
59
60 /**
61 * The <b>timed</b> event type for pub/sub that a traffic controller emits when it begins the computations to determine its
62 * response to the current input (detector states).<br>
63 * Payload: Object[] { String trafficControllerId }
64 */
65 EventType TRAFFICCONTROL_CONTROLLER_EVALUATING = new EventType("TRAFFICCONTROL.CONTROLLER_EVALUATING");
66
67 /**
68 * The <b>timed</b> event type for pub/sub that a traffic controller uses to convey warnings.<br>
69 * Payload: Object[] { String trafficControllerId, String message }
70 */
71 EventType TRAFFICCONTROL_CONTROLLER_WARNING = new EventType("TRAFFICCONTROL.CONTROLLER_WARNING");
72
73 /**
74 * The <b>timed</b> event for pub/sub emitted by a traffic control machine when it changes state (STARTING_UP, RUNNING,
75 * SHUTTING_DOWN, OFF, etc. The exact set of states may vary depending on the type of traffic control machine. <br>
76 * Payload: Object[] { String trafficControllerId, String oldState, String newState }
77 */
78 EventType TRAFFICCONTROL_STATE_CHANGED = new EventType("TRAFFIC_CONTROL.STATE_CHANGED");
79
80 /**
81 * The <b>timed</b>event that is fired by a traffic control program when a traffic light must change state. <br>
82 * Payload: Object[] { String trafficControllerId, Integer stream, TrafficLightColor newColor }
83 */
84 public static final EventType TRAFFIC_LIGHT_CHANGED = new EventType("TrafficLightChanged");
85
86 /**
87 * The <b>timed</b> event type for pub/sub indicating the creation of a traffic control program variable. <br>
88 * Listeners to this event can send <code>TRAFFICCONTROL_SET_TRACE</code> messages to set the tracing level of a
89 * variable.<br>
90 * Payload: Object[] {String trafficControllerId, String variableId, Integer trafficStream, Double initialValue}
91 */
92 EventType TRAFFICCONTROL_VARIABLE_CREATED = new EventType("TRAFFICCONTROL.VARIABLE_CREATED");
93
94 /**
95 * The <b>timed</b> event type that instruct a traffic controller to change the tracing level of a variable. <br>
96 * Payload: Object[] { String trafficControllerId, String variableId, Integer trafficStream, Boolean trace } <br>
97 * Remark 1: an empty string for the variableId sets or clears tracing for all variables associated with the traffic stream.
98 * <br>
99 * Remark 2: The stream number <code>NO_STREAM</code> selects variable(s) that are not associated with a particular traffic
100 * stream. <br>
101 * Remark 3: setting the tracing level of a variable changes the amount of
102 * <code>TRAFFICCONTROL_TRACED_VARIABLE_UPDATED</code> events sent to <b>all</b> listeners; i.e. it is not possible to
103 * affect tracing on a per listener basis.
104 */
105 EventType TRAFFICCONTROL_SET_TRACING = new EventType("TRAFFICCONTROL.SET_TRACING");
106
107 /**
108 * The <b>timed</b> event type for pub/sub indicating the update of a traced control program variable. <br>
109 * Payload: Object[] {String trafficControllerId, String variableId, Integer trafficStream, Double oldValue, Double
110 * newValue, String expressionOrDescription} <br>
111 * Remark 1: for variable that are not associated with a particular traffic stream, the trafficStream value shall be
112 * <code>NO_STREAM</code> <br>
113 * Remark 2: if the variable is a timer that has just been initialized; newValue will reflect the duration in seconds
114 */
115 EventType TRAFFICCONTROL_TRACED_VARIABLE_UPDATED = new EventType("TRAFFICCONTROL.VARIABLE_UPDATED");
116
117 /**
118 * The <b>timed</b> event for pub/sub emitted by a traffic control machine when it changes to another conflict group. <br>
119 * Payload: Object[] { String trafficControllerId, String oldConflictGroupStreams, String newConflictGroupStreams } <br>
120 * Remark 1: a conflict group is described as a space-separated list of traffic stream numbers. The traffic streams within a
121 * conflict group should be compatible; i.e. not conflicting. <br>
122 * Remark 2: The value <code>00</code> can be used as a place holder for a stream in a conflict groups that have fewer than
123 * the maximum number of traffic streams that occur in any conflict group.<br>
124 * Remark 3: The very first event of this type may use an empty string for <code>oldConflictGroupStreams</code>.<br>
125 * Remark 4: Some traffic control systems may not operate in a conflict group by conflict group fashion and therefore not
126 * emit these events.
127 */
128 EventType TRAFFICCONTROL_CONFLICT_GROUP_CHANGED = new EventType("TRAFFIC_CONTROL.CONFLICT_GROUP_CHANGED");
129
130 }