traci-rs

Short description

traci-rs is a pure-Rust client library for the SUMO TraCI (Traffic Control Interface) protocol. It provides the same functionality as the official C++ TraCIAPI library, translated to idiomatic Rust, enabling full programmatic control of SUMO traffic simulations from Rust applications.

Documentation

API documentation is available at docs.rs/traci-rs.

Pre-requisites

Supported platforms

Any platform supported by Rust's stable toolchain (Linux, macOS, Windows).

Dependencies

• Rust stable toolchain, edition 2021 or later
• SUMO ≥ 1.8 installed and available in $PATH (sumo.dlr.de/docs/Downloads.php)

This crate has zero external Rust dependencies beyond std.

Known Limitations

• The TraCI wire protocol does not provide a machine-readable schema; this library targets SUMO ≥ 1.8 and may require updates for future protocol revisions.

Installation

Add to your Cargo.toml:

[dependencies]
traci-rs = "0.1"

Or, to use a local checkout:

[dependencies]
traci-rs = { path = "../traci-rs" }

Launching SUMO with TraCI

SUMO must be started with the --remote-port flag before connecting:

sumo --net-file net.xml \
     --route-files routes.rou.xml \
     --remote-port 8813 \
     --num-clients 1

Use sumo-gui instead of sumo for a graphical window.

Usage

use traci_rs::TraciClient;

fn main() -> Result<(), traci_rs::TraciError> {
    // Connect to a running SUMO instance
    let mut client = TraciClient::connect("127.0.0.1", 8813)?;

    // Set client order (required for multi-client setups)
    client.set_order(1)?;

    // Check versions
    let (api_version, sumo_version) = client.get_version()?;
    println!("SUMO {sumo_version}, TraCI API {api_version}");

    // Run until SUMO signals end-of-simulation (simulation_step returns false)
    let mut step = 0u32;
    while client.simulation_step(0.0)? {
        step += 1;
        let ids = client.vehicle_get_id_list()?;
        for id in &ids {
            let pos   = client.vehicle_get_position(id)?;
            let speed = client.vehicle_get_speed(id)?;
            println!("  {id} @ ({:.1}, {:.1})  v={:.1} m/s", pos.x, pos.y, speed);
        }
    }
    println!("Simulation ended after {step} steps.");

    client.close()?;
    Ok(())
}

Run the bundled examples with:

# Basic per-step polling (runs until SUMO end-time)
cargo run --example simple_simulation

# Subscription example — zero extra round-trips per step
cargo run --example subscriptions

Supported SUMO domains

Scope	Type	Description
client.edge	EdgeScope	Road edge queries and travel-time adaptation
client.gui	GuiScope	GUI viewport and zoom control
client.induction_loop	InductionLoopScope	Single-lane loop detector data
client.junction	JunctionScope	Junction position/shape
client.lane	LaneScope	Lane attributes and allowed vehicle classes
client.lane_area	LaneAreaScope	Multi-lane area (E2) detector data
client.multi_entry_exit	MultiEntryExitScope	Multi-entry/exit (E3) detector data
client.person	PersonScope	Pedestrian/person control
client.poi	PoiScope	Point-of-interest management
client.polygon	PolygonScope	Polygon management
client.rerouter	RerouterScope	Rerouter queries
client.route	RouteScope	Route management
client.route_probe	RouteProbeScope	Route probe detector data
client.simulation	SimulationScope	Simulation control and coordinate conversion
client.traffic_lights	TrafficLightScope	Traffic-light state and program control
client.vehicle	VehicleScope	Full vehicle control + subscription filters
client.vehicle_type	VehicleTypeScope	Vehicle type parameter management

Error handling

All fallible operations return Result<T, TraciError>.

use traci_rs::TraciError;

match client.vehicle.get_speed(&mut client, "nonexistent") {
    Ok(speed) => println!("speed = {}", speed),
    Err(TraciError::Io(e))       => eprintln!("I/O error: {}", e),
    Err(TraciError::Protocol(s)) => eprintln!("TraCI protocol error: {}", s),
    Err(e)                       => eprintln!("Error: {}", e),
}

Developers

• Jordi Marias-i-Parella (jordi.marias@i2cat.net)

Source

This code has been developed within the following research and innovation projects:

• SPRINGTIME (PID2023-146378NB-I00) funded by the Spanish government (MCIU/AEI/10.13039/501100011033/FEDER/UE), this project focuses in techniques to get IP-based interconnection on multiple environments.

Copyright

This code has been developed by Fundació Privada Internet i Innovació Digital a Catalunya (i2CAT).

i2CAT is a non-profit research and innovation centre that promotes mission-driven knowledge to solve business challenges, co-create solutions with a transformative impact, empower citizens through open and participative digital social innovation with territorial capillarity, and promote pioneering and strategic initiatives. i2CAT aims to transfer research project results to private companies in order to create social and economic impact via the out-licensing of intellectual property and the creation of spin-offs. Find more information of i2CAT projects and IP rights at https://i2cat.net/tech-transfer/

License

This code is licensed under the terms of the Eclipse Public License 2.0 (EPL-2.0). Information about the license can be located at https://www.eclipse.org/legal/epl-2.0/.

If you find that this license doesn't fit with your requirements regarding the use, distribution or redistribution of our code for your specific work, please, don't hesitate to contact the intellectual property managers in i2CAT at the following address: techtransfer@i2cat.net

Attributions

This is a Rust translation of the TraCIAPI C++ library from the Eclipse SUMO project, which is also licensed under EPL-2.0.

Copyright (c) 2001-2024 German Aerospace Center (DLR) and others — Eclipse SUMO project
Original C++ source: https://github.com/eclipse-sumo/sumo