From Sumo
Jump to: navigation, search

Introduction to TraCI

TraCI is the short term for "Traffic Control Interface". Giving the access to a running road traffic simulation, it allows to retrieve values of simulated objects and to manipulate their behaviour "on-line".

Using TraCI

SUMO startup

TraCI uses a TCP based client/server architecture to provide access to SUMO. Thereby, SUMO acts as server that is started with additional command-line options: --remote-port <INT> where <INT> is the port SUMO will listen on for incoming connections. The number of clients which can connect can be given as an additional option --num-clients <INT>, where 1 is the default. Please note that in multi client scenarios you should explicity specify the execution order of the clients using the SetOrder-command

When started with the --remote-port <INT> option, SUMO only prepares the simulation and waits for all external applications to connect and take over the control. Please note, that the --end <TIME> option is ignored when SUMO runs as a TraCI server, SUMO runs until the client demands a simulation end.

When using SUMO-GUI as a server, the simulation must either be started by using the play button or by setting the option --start before TraCI commands will be processed.

Protocol specification

Please see the TraCI Protocol Specification (including Basic Flow, Messages, Data Types).

TraCI Commands

For the following APIs, the ID is equal to the ID defined in SUMO's input files. Here, you find their general structure.


When using TraCI, the --end option of SUMO is ignored. Instead the simulation is closed by issuing the close command. To detect whether all route files have been exhausted and all vehicles have left the simulation, one can check whether the command getMinExpectedNumber returns 0. The simulation will end as soon as all clients have sent the close command.

It is also possible to reload the simulation with a new list of arguments by using the load-command.

Example use


Interfaces by Programming Language

  • Python: the package tools/traci allows to interact with SUMO using Python (This library is tested daily and supports all TraCI commands)
  • Java, .NET, ... anything that can do SOAP. TraaS is a web-service adapter for TraCI which allows automatic API generation for multiple languanges. API completeness is high but usually lags behind the python client. TraaS may also be used as a standalone TraCI client.
  • Matlab TraCI4Matlab
  • C++: The C++ TraCIAPI is client library that is part of the SUMO-source tree.
  • C++: The Veins project provides a middle-ware for coupling SUMO with OMNET++. As part of the infrastructure it provides a C++ client library for the TraCI API (API completeness is a bit behind the python client).
  • TraCI4J is an outdated Java implementation of TraCI; It only supports a small portion of the API. API documentation is here

V2X simulation

TraCI allows to use SUMO in combination with communication network simulators vor simulating vehicular communication. See Topics/V2X for a list of available solutions.

Other Resources

  • SUMO's TraCI Server is a part of the plain distribution. The source code is located in the folder src/traci-server.



Using TraCI slows down the simulation speed. The amount of slow-down depends on many factors:

  • number of TraCI function calls per simulation step
  • types of TraCI functions being called (some being more expensive than others)
  • computation within the TraCI script
  • client language


As an example use-case consider retrieving the x,y position of each vehicle during every simulation step (using the python client):

   while traci.simulation.getMinExpectedNumber() > 0: 
       for veh_id in traci.vehicle.getIDList():
            position = traci.vehicle.getSpeed(veh_id)
  • This script is able to process about 25000 vehicles per second.
  • Using embedded python increases this to about 50000 vehicles per second
  • The same value retrieval can also be sped up to 50000 vehicles per second by using subscriptions:
   while traci.simulation.getMinExpectedNumber() > 0: 
       for veh_id in traci.simulation.getDepartedIDList():
           traci.vehicle.subscribe(veh_id, [traci.constants.VAR_POSITION])
       positions = traci.vehicle.getSubscriptionResults()

When using this script on the Bologna scenario (9000 vehicles, 5000 simulation steps) the following running times were recorded:

  • without TraCI 8s
  • plain position retrieval 90s
  • retrieval using subscriptions 42s
  • retrieval using embedded python 46s
  • retrieval using subscriptions and embedded python 34s

The C++ client performance is higher:

  • plain position retrieval 80s
  • retrieval using subscriptions 28s


Output files are not closed.

This problem occures if the client tries to access the output while the simulation is still closing down. This can be solved by letting the client wait for the simulation to shut down. The bug report was ticket524

Obsolete APIs

There used to be two "generations" of TraCI commands. The first one mainly uses an internal mapping between the string-typed IDs used in SUMO and an external representation of these which is int-based. The mapping was done internally (within TraCI).
The second "generation", the current one uses string-IDs equal to those SUMO reads. If you are bound to the first generation API (for instance if you want to use TraNS) you can only use SUMO up to version 0.12.3. See FAQ about obtaining an old version.