• Libtraci

Libtraci#

The main way to interact with a running simulation is TraCI which gives the complete flexibility of doing cross-platform, cross-language, and networked interaction with sumo acting as a server. To allow coupling with client code, bindings must be provided for each client language. Historically, this has led to a larger number of client implementations with varying levels of API completeness and only the python client was kept up-to-date by the core SUMO development team.

To avoid this problem, Libtraci is provided as a SWIG compatible C++ client library that is fully compatible with Libsumo. It even uses the same header files as Libsumo.

• C++ interface based on static functions and a few simple wrapper classes for results which can be linked directly to the client code
• Pre-built language bindings for Java and Python (using SWIG)
• Future support for other programming languages via SWIG

Unlike Libsumo, Libtraci allows

• multiple clients
• running with sumo-gui

Limitations#

The following things currently do not work (or work differently than with the TraCI Python client):

• subscriptions that require additional arguments (except for vehicle.getLeader)
• stricter type checking
  • the pure Python TraCI client sometimes accepts any iterable object where Libtraci wants a list
  • pure Python may accept any object where Libtraci needs a boolean value or a string
• there is no cleanup / waiting for the started subprocess (sumo)

Building and Installing it#

The binary windows release already contains the readily compiled libtraci for C++ and Java. For Python you should prefer the pure Python implementation anyway (pip install traci) but if you must you can install it via pip install libtraci. Only if your platform or language is not supported follow the steps below.

If swig and the developer packages for your target language (e.g. Python or Java) are installed the build should be enabled by default. For the Python bindings you will get a libtraci.py and a _libtraci.so (or .pyd on Windows) in SUMO_HOME/tools/libtraci. For Java the jar and .so (or .dlls) are placed in the bin dir. Please add the bin or tools dir to your relevant search paths. If you want to enable the experimental C# support, make sure that you have ENABLE_CS_BINDINGS set in your cmake configuration.

Using libtraci#

Python#

import libtraci
libtraci.start(["sumo", "-c", "test.sumocfg"])
libtraci.simulationStep()
libtraci.close()

Existing traci scripts can mostly be reused by calling

import libtraci as traci

In case you have a lot of scripts you can also set the environment variable LIBTRACI_AS_TRACI to a non empty value which will trigger the import as above.

C++#

Example Code (test.cpp)#

The example assumes you have the named sumocfg file in your current working directory and the SUMO bin directory included in the PATH environmental variable. Otherwise you need to provide the full file path.

#include <iostream>
#include <libsumo/libtraci.h>

using namespace libtraci;

int main(int argc, char* argv[]) {
    Simulation::start({"sumo", "-n", "net.net.xml"});
    for (int i = 0; i < 5; i++) {
        Simulation::step();
    }
    Simulation::close();
}

compiling on Linux (make sure SUMO_HOME is set and sumo has been built)#

g++ -o test -std=c++11 -I$SUMO_HOME/src test.cpp -L$SUMO_HOME/bin -ltracicpp

running on Linux#

LD_LIBRARY_PATH=$SUMO_HOME/bin ./test

Java#

You might want to use the available Maven package.

Example Code (APITest.java)#

import org.eclipse.sumo.libtraci.*;

public class APITest {
    public static void main(String[] args) {
        System.loadLibrary("libtracijni");
        Simulation.start(new StringVector(new String[] {"sumo", "-n", "net.net.xml"}));
        for (int i = 0; i < 5; i++) {
            Simulation.step();
        }
        Simulation.close();
    }
}

See also the information on casting subscription results.

compiling on Linux#

make sure SUMO_HOME is set and the jar / so / dll files are available

javac -cp $SUMO_HOME/bin/libtraci-1.8.0-SNAPSHOT.jar APITest.java

running on Linux#

java -Djava.library.path=$SUMO_HOME/bin -cp $SUMO_HOME/bin/libtraci-1.8.0-SNAPSHOT.jar:. APITest

Matlab#

Please install the Python package using pip install traci. You can then use all commands inside your Matlab scripts just as in Python by adding the py. prefix. (Please note that this is actually not using libtraci but the pure Python TraCI implementation.)

py.traci.start(["sumo", "-c", "test.sumocfg"])
py.traci.simulationStep()