1 package org.opentrafficsim.trafficcontrol;
2
3 import org.djutils.event.EventListener;
4 import org.djutils.event.EventProducer;
5 import org.djutils.event.EventType;
6 import org.djutils.metadata.MetaData;
7 import org.djutils.metadata.ObjectDescriptor;
8 import org.opentrafficsim.base.Identifiable;
9 import org.opentrafficsim.core.object.NonLocatedObject;
10 import org.opentrafficsim.road.network.lane.object.trafficlight.TrafficLightColor;
11
12 /**
13 * Interface for traffic light controllers.
14 * <p>
15 * Copyright (c) 2013-2023 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
16 * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
17 * </p>
18 * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
19 * @author <a href="https://tudelft.nl/staff/p.knoppers-1">Peter Knoppers</a>
20 * @author <a href="https://dittlab.tudelft.nl">Wouter Schakel</a>
21 */
22 public interface TrafficController extends EventProducer, EventListener, NonLocatedObject, Identifiable
23 {
24 /**
25 * Retrieve the Id of the traffic light controller.
26 * @return String; the id of the traffic light controller
27 */
28 @Override
29 String getId();
30
31 /** Traffic controller is starting up. Particular traffic control programs may use additional states not listed here. */
32 String STARTING_UP = "starting up";
33
34 /** Traffic controller is being cloned. Particular traffic control programs may use additional states not listed here. */
35 String BEING_CLONED = "being cloned";
36
37 /** Traffic controller is running. */
38 String RUNNING = "running";
39
40 /** Traffic controller is shutting down. */
41 String SHUTTING_DOWN = "shutting down";
42
43 /** Traffic controller is off. */
44 String OFF = "off";
45
46 /** Constant to select variables that have no associated traffic stream. */
47 int NO_STREAM = -1;
48
49 /**
50 * The <b>timed</b> event type for pub/sub that a newly created traffic controller emits. <br>
51 * Payload: Object[] { String trafficControllerId, String initialState }
52 */
53 EventType TRAFFICCONTROL_CONTROLLER_CREATED = new EventType("TRAFFICCONTROL.CONTROLLER_CREATED",
54 new MetaData("Controller created", "Controller id, initial state",
55 new ObjectDescriptor("Controller id", "Id of the controller", String.class),
56 new ObjectDescriptor("Initial state", "Initial state", String.class)));
57
58 /**
59 * The <b>timed</b> event type for pub/sub that a traffic controller emits when it begins the computations to determine its
60 * response to the current input (detector states).<br>
61 * Payload: Object[] { String trafficControllerId }
62 */
63 EventType TRAFFICCONTROL_CONTROLLER_EVALUATING =
64 new EventType("TRAFFICCONTROL.CONTROLLER_EVALUATING", new MetaData("Controller eveluating", "Controller id",
65 new ObjectDescriptor("Controller id", "Id of the controller", String.class)));
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 new MetaData("Controller warning", "Controller id, warning message",
73 new ObjectDescriptor("Controller id", "Id of the controller", String.class),
74 new ObjectDescriptor("Message", "Message", String.class)));
75
76 /**
77 * The <b>timed</b> event for pub/sub emitted by a traffic control machine when it changes state (STARTING_UP, RUNNING,
78 * SHUTTING_DOWN, OFF, etc. The exact set of states may vary depending on the type of traffic control machine. <br>
79 * Payload: Object[] { String trafficControllerId, String oldState, String newState }
80 */
81 EventType TRAFFICCONTROL_STATE_CHANGED = new EventType("TRAFFIC_CONTROL.STATE_CHANGED",
82 new MetaData("Controller state changed", "Controller id, old state, new state",
83 new ObjectDescriptor("Controller id", "Id of the controller", String.class),
84 new ObjectDescriptor("Old state", "Old state", String.class),
85 new ObjectDescriptor("New state", "New state", String.class)));
86
87 /**
88 * The <b>timed</b>event that is fired by a traffic control program when a traffic light must change state. <br>
89 * Payload: Object[] { String trafficControllerId, Short stream, TrafficLightColor newColor }
90 */
91 EventType TRAFFIC_LIGHT_CHANGED = new EventType("TrafficLightChanged",
92 new MetaData("Controller state changed", "Controller id, old state, new state",
93 new ObjectDescriptor("Controller id", "Id of the controller", String.class),
94 new ObjectDescriptor("Stream", "Stream number", Short.class),
95 new ObjectDescriptor("Light color", "New traffic light color", TrafficLightColor.class)));
96
97 /**
98 * The <b>timed</b> event type for pub/sub indicating the creation of a traffic control program variable. <br>
99 * Listeners to this event can send <code>TRAFFICCONTROL_SET_TRACE</code> messages to set the tracing level of a
100 * variable.<br>
101 * Payload: Object[] {String trafficControllerId, String variableId, Short trafficStream, Double initialValue}
102 */
103 EventType TRAFFICCONTROL_VARIABLE_CREATED = new EventType("TRAFFICCONTROL.VARIABLE_CREATED",
104 new MetaData("Controller state changed", "Controller id, old state, new state",
105 new ObjectDescriptor("Controller id", "Id of the controller", String.class),
106 new ObjectDescriptor("Variable id", "Id of the variable", String.class),
107 new ObjectDescriptor("Stream", "Stream number", Short.class),
108 new ObjectDescriptor("Initial value", "Initial value", Double.class)));
109
110 /**
111 * The <b>timed</b> event type that instruct a traffic controller to change the tracing level of a variable. <br>
112 * Payload: Object[] { String trafficControllerId, String variableId, Short trafficStream, Boolean trace } <br>
113 * Remark 1: an empty string for the variableId sets or clears tracing for all variables associated with the traffic stream.
114 * <br>
115 * Remark 2: The stream number <code>NO_STREAM</code> selects variable(s) that are not associated with a particular traffic
116 * stream. <br>
117 * Remark 3: setting the tracing level of a variable changes the amount of
118 * <code>TRAFFICCONTROL_TRACED_VARIABLE_UPDATED</code> events sent to <b>all</b> listeners; i.e. it is not possible to
119 * affect tracing on a per listener basis.
120 */
121 EventType TRAFFICCONTROL_SET_TRACING = new EventType("TRAFFICCONTROL.SET_TRACING",
122 new MetaData("Controller state changed", "Controller id, old state, new state",
123 new ObjectDescriptor("Controller id", "Id of the controller", String.class),
124 new ObjectDescriptor("Variable id", "Id of the variable", String.class),
125 new ObjectDescriptor("Stream", "Stream number", Short.class),
126 new ObjectDescriptor("Trace", "Trace", Boolean.class)));
127
128 /**
129 * The <b>timed</b> event type for pub/sub indicating the update of a traced control program variable. <br>
130 * Payload: Object[] {String trafficControllerId, String variableId, Short trafficStream, Double oldValue, Double
131 * newValue, String expressionOrDescription} <br>
132 * Remark 1: for variable that are not associated with a particular traffic stream, the trafficStream value shall be
133 * <code>NO_STREAM</code> <br>
134 * Remark 2: if the variable is a timer that has just been initialized; newValue will reflect the duration in seconds
135 */
136 EventType TRAFFICCONTROL_TRACED_VARIABLE_UPDATED = new EventType("TRAFFICCONTROL.VARIABLE_UPDATED",
137 new MetaData("Controller state changed", "Controller id, old state, new state",
138 new ObjectDescriptor("Controller id", "Id of the controller", String.class),
139 new ObjectDescriptor("Variable id", "Id of the variable", String.class),
140 new ObjectDescriptor("Stream", "Stream number", Short.class),
141 new ObjectDescriptor("Old value", "Old value", Double.class),
142 new ObjectDescriptor("New value", "New value", Double.class),
143 new ObjectDescriptor("Expression", "Expression or description", String.class)));
144
145 /**
146 * The <b>timed</b> event for pub/sub emitted by a traffic control machine when it changes to another conflict group. <br>
147 * Payload: Object[] { String trafficControllerId, String oldConflictGroupStreams, String newConflictGroupStreams } <br>
148 * Remark 1: a conflict group is described as a space-separated list of traffic stream numbers. The traffic streams within a
149 * conflict group should be compatible; i.e. not conflicting. <br>
150 * 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
151 * the maximum number of traffic streams that occur in any conflict group.<br>
152 * Remark 3: The very first event of this type may use an empty string for <code>oldConflictGroupStreams</code>.<br>
153 * Remark 4: Some traffic control systems may not operate in a conflict group by conflict group fashion and therefore not
154 * emit these events.
155 */
156 EventType TRAFFICCONTROL_CONFLICT_GROUP_CHANGED = new EventType("TRAFFICCONTROL.CONFLICT_GROUP_CHANGED",
157 new MetaData("Controller state changed", "Controller id, old state, new state",
158 new ObjectDescriptor("Controller id", "Id of the controller", String.class),
159 new ObjectDescriptor("Old stream", "Old conflict group stream", String.class),
160 new ObjectDescriptor("New stream", "New conflict group stream", String.class)));
161
162 }