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-2017 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 public String getId(); 27 28 /** 29 * Tell the traffic controller that the state of a detector has changed. 30 * @param detectorId String; id of the detector 31 * @param detectingGTU boolean; 32 */ 33 public void updateDetector(String detectorId, boolean detectingGTU); 34 35 /** Traffic controller is starting up. Particular traffic control programs may use additional states not listed here. */ 36 final String STARTING_UP = "starting up"; 37 38 /** Traffic controller is being cloned. Particular traffic control programs may use additional states not listed here. */ 39 final String BEING_CLONED = "being cloned"; 40 41 /** Traffic controller is running. */ 42 final String RUNNING = "running"; 43 44 /** Traffic controller is shutting down. */ 45 final String SHUTTING_DOWN = "shutting down"; 46 47 /** Traffic controller is off. */ 48 final String OFF = "off"; 49 50 /** Constant to select variables that have no associated traffic stream. */ 51 public final static int NO_STREAM = -1; 52 53 /** 54 * The <b>timed</b> event type for pub/sub that a newly created traffic controller emits. <br> 55 * Payload: Object[] { String trafficControllerId, String initialState } 56 */ 57 EventType TRAFFICCONTROL_CONTROLLER_CREATED = new EventType("TRAFFICCONTROL.CONTROLLER_CREATED"); 58 59 /** 60 * The <b>timed</b> event type for pub/sub that a traffic controller emits when it begins the computations to determine its 61 * response to the current input (detector states).<br> 62 * Payload: Object[] { String trafficControllerId } 63 */ 64 EventType TRAFFICCONTROL_CONTROLLER_EVALUATING = new EventType("TRAFFICCONTROL.CONTROLLER_EVALUATING"); 65 66 /** 67 * The <b>timed</b> event type for pub/sub that a traffic controller uses to convey warnings.<br> 68 * Payload: Object[] { String trafficControllerId, String message } 69 */ 70 EventType TRAFFICCONTROL_CONTROLLER_WARNING = new EventType("TRAFFICCONTROL.CONTROLLER_WARNING"); 71 72 /** 73 * The <b>timed</b> event for pub/sub emitted by a traffic control machine when it changes state (STARTING_UP, RUNNING, 74 * SHUTTING_DOWN, OFF, etc. The exact set of states may vary depending on the type of traffic control machine. <br> 75 * Payload: Object[] { String trafficControllerId, String oldState, String newState } 76 */ 77 EventType TRAFFICCONTROL_STATE_CHANGED = new EventType("TRAFFIC_CONTROL.STATE_CHANGED"); 78 79 /** 80 * The <b>timed</b>event that is fired by a traffic control program when a traffic light must change state. <br> 81 * Payload: Object[] { String trafficControllerId, Integer stream, TrafficLightColor newColor } 82 */ 83 public static final EventType TRAFFIC_LIGHT_CHANGED = new EventType("TrafficLightChanged"); 84 85 /** 86 * The <b>timed</b> event type for pub/sub indicating the creation of a traffic control program variable. <br> 87 * Listeners to this event can send <code>TRAFFICCONTROL_SET_TRACE</code> messages to set the tracing level of a 88 * variable.<br> 89 * Payload: Object[] {String trafficControllerId, String variableId, Integer trafficStream, Double initialValue} 90 */ 91 EventType TRAFFICCONTROL_VARIABLE_CREATED = new EventType("TRAFFICCONTROL.VARIABLE_CREATED"); 92 93 /** 94 * The <b>timed</b> event type that instruct a traffic controller to change the tracing level of a variable. <br> 95 * Payload: Object[] { String trafficControllerId, String variableId, Integer trafficStream, Boolean trace } <br> 96 * Remark 1: an empty string for the variableId sets or clears tracing for all variables associated with the traffic stream. 97 * <br> 98 * Remark 2: The stream number <code>NO_STREAM</code> selects variable(s) that are not associated with a particular traffic 99 * stream. <br> 100 * Remark 3: setting the tracing level of a variable changes the amount of 101 * <code>TRAFFICCONTROL_TRACED_VARIABLE_UPDATED</code> events sent to <b>all</b> listeners; i.e. it is not possible to 102 * affect tracing on a per listener basis. 103 */ 104 EventType TRAFFICCONTROL_SET_TRACING = new EventType("TRAFFICCONTROL.SET_TRACING"); 105 106 /** 107 * The <b>timed</b> event type for pub/sub indicating the update of a traced control program variable. <br> 108 * Payload: Object[] {String trafficControllerId, String variableId, Integer trafficStream, Double oldValue, Double 109 * newValue, String expressionOrDescription} <br> 110 * Remark 1: for variable that are not associated with a particular traffic stream, the trafficStream value shall be 111 * <code>NO_STREAM</code> <br> 112 * Remark 2: if the variable is a timer that has just been initialized; newValue will reflect the duration in seconds 113 */ 114 EventType TRAFFICCONTROL_TRACED_VARIABLE_UPDATED = new EventType("TRAFFICCONTROL.VARIABLE_UPDATED"); 115 116 /** 117 * The <b>timed</b> event for pub/sub emitted by a traffic control machine when it changes to another conflict group. <br> 118 * Payload: Object[] { String trafficControllerId, String oldConflictGroupStreams, String newConflictGroupStreams } <br> 119 * Remark 1: a conflict group is described as a space-separated list of traffic stream numbers. The traffic streams within a 120 * conflict group should be compatible; i.e. not conflicting. <br> 121 * 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 122 * the maximum number of traffic streams that occur in any conflict group.<br> 123 * Remark 3: The very first event of this type may use an empty string for <code>oldConflictGroupStreams</code>.<br> 124 * Remark 4: Some traffic control systems may not operate in a conflict group by conflict group fashion and therefore not 125 * emit these events. 126 */ 127 EventType TRAFFICCONTROL_CONFLICT_GROUP_CHANGED = new EventType("TRAFFIC_CONTROL.CONFLICT_GROUP_CHANGED"); 128 129 }