Tutorials/TraCI4Traffic Lights

This tutorial wants to show how to use the Traffic Control Interface (in short TraCI) on a simple example. TraCI gives the possibility to control a running road traffic simulation. Therefore a TCP-based client/server architecture was established where SUMO acts as a server and the “controller” is the client. Our “controller” will be a Python-Script which receives informations about the actual state from the server and then sends instructions back.

It is assumed that road network building and routes definition is known from other tutorials, as Tutorials/Hello Sumo or Tutorials/Quick Start.

All files mentioned here can also be found in the /data/tutorial/traci_tls directory. The most recent version can be found in the SVN at /tests/complex/tutorial/traci_tls/.

= Example description = Our example plays on a simple signalized intersection with four approaches. We only have traffic on the horizontal axis and important vehicles (like trams, trains, fire engines, ...) on the vertical axis from north to south. On the approach in the north we have an induction loop to recognize entering vehicles. While no vehicle enters from the north we give all the time green on the horizontal axis but when a vehicle enters the induction loop we switch immediately the signal so the vehicle can cross the intersection without a stop.



= Running the example = To run the example you need to execute the script runner.py with python python runner.py

= Data preparation = The net-definition can be found in the files,  ,   and. The route data is generated randomly by the script. The vehicles leave the source according to a Poisson process approximated here by a binomial distribution. So a parameter  in the script means that a vehicle is generated every 30 seconds in average.

= Code = To start the simulation the script /docs/tutorial/traci_tls/runner.py has to be executed. It generates the routes, acts with the server and controls the traffic light. It makes use of the TraCI python API bundled with SUMO. The sources of the API can be found in /tools/traci/.

= Simulation = The main program is implemented in the script. There, we first generate the routes as described above. Then SUMO-GUI is started with the config file  wherein the server parameter is specified: ...   

In the next step the script connects with the server via a call to. Then we start to control the simulation. We let the server simulate one simulation step, read the induction loop and set the state of the traffic light until the end is reached where no vehicle exists on the road anymore. If we find a vehicle on the induction loop the  is started where the sequence of signal state for the Traffic Light is specified. At the end we close the connection.

= TraCI = We want to run this simulation in SUMO, acting as a server, and control the signal dependent on the actual simulation state. For this task TraCI offers commands which are described in the corresponding article TraCI in detail. For this example we will use only four commands: Simulation Step, Get Induction Loop Variable, Change Traffic Lights State and Close.

The commands are embedded in TCP messages but the direct client server communication is opaque to the user. The four commands needed in this tutorial are implemented in the methods,  ,   and.

=Further Notes= Below, you'll find a description about the format of the message to use for sending a complete tls program to SUMO: Single phase consists of:
 * 1) value type compound - should have the value 0x0F;
 * 2) item number - ignored; can be any integer;
 * 3) value type string - should have the value 0x0B;
 * 4) program ID - an ID for the program; if the program exists, it will be overwritten;
 * 5) value type integer (always 0) - ignored, can be any integer
 * 6) value type compound - should have the value 0x0F;
 * 7) compound length (always 0!) - ignored, can be any integer;
 * 8) value type integer - should have the value 0x09;
 * 9) phase index - number of the phase to start the program with;
 * 10) value type integer should have the value 0x09;
 * 11) phase number - number of phases;
 * 12) phases - phases, as described below.
 * 1) value type integer - should have the value 0x09;
 * 2) duration - the length of the phase in milliseconds;
 * 3) value type integer - should have the value 0x09;
 * 4) unused - can have any arbitrary value;
 * 5) value type integer - should have the value 0x09;
 * 6) unused - can have any arbitrary value;
 * 7) value type string - should have the value 0x0B;
 * 8) State (light/priority-tuple) - has to be a string defining states of each traffic light (signal) made of characters gGyYrGoO, where i-th character defines the state of the i-th traffic light (signal).

= Appendix = The methods for sending and receiving the messages,  and , respectively, are hidden in the script   and there is no need to call them directly. In this section we will show the composition of a command using the example of.

setRedYellowGreenState
This method sets the status of a traffic light, so it gets the ID of the traffic light and the status as parameter. The state of a string defining the signal colors, as described in Simulation/Traffic Lights. The command is described at TraCI/Change Traffic Lights State.