Chapter 18.1: TraCI Protocol

18.1.1 TraCI: Traffic Control Interface

TraCI (Traffic Control Interface) is the protocol through which external programs interact with a running SUMO simulation. Unlike file-based coupling (read outputs, modify inputs, restart), TraCI provides real-time bidirectional communication: you can query vehicle states and modify simulation parameters within the same timestep.

TraCI uses a custom TCP binary protocol. The server (SUMO) listens on a specified port, and clients connect to send commands and receive responses. This architecture enables:

Per-step queries: vehicle speed, position, emissions, waiting time
Per-step control: reroute vehicles, change traffic light phases, modify speed limits
Multi-client support: multiple controllers connected simultaneously
Language independence: any language that can open a TCP socket can speak TraCI

18.1.2 TCP Binary Protocol Structure

Every TraCI message follows a strict binary format. Understanding this format is essential for implementing clients in languages without official TraCI libraries (e.g., Java, Rust, C++).

Message Envelope

┌─────────────────────────────────────────────────────────┐
│  TraCI Message Format                                    │
├──────────────┬──────────────────────────────────────────┤
│  Bytes 0-3   │  Total message length (4 bytes, big-endian) │
├──────────────┼──────────────────────────────────────────┤
│  Byte 4      │  Command length (1 byte, or 0 → 4-byte)  │
├──────────────┼──────────────────────────────────────────┤
│  Byte 5      │  Command ID (1 byte)                     │
├──────────────┼──────────────────────────────────────────┤
│  Bytes 6+    │  Command content (variable)               │
└──────────────┴──────────────────────────────────────────┘

If command length byte = 0, next 4 bytes give extended length.
Multiple commands can be packed into one message.

Key Command IDs

Command	ID (hex)	Direction	Purpose
CMD_SIMSTEP	0x02	Client → Server	Advance simulation by one step
GET_VEHICLE_VARIABLE	0xa4	Client → Server	Query vehicle state
RESPONSE_GET_VEHICLE	0xb4	Server → Client	Vehicle state response
SET_VEHICLE_VARIABLE	0xc4	Client → Server	Modify vehicle state
GET_TL_VARIABLE	0xa2	Client → Server	Query traffic light state
SET_TL_VARIABLE	0xc2	Client → Server	Change traffic light phase
CMD_CLOSE	0x7f	Client → Server	Close connection gracefully

18.1.3 Variable IDs and Data Types

When querying a vehicle, the variable ID specifies which property to retrieve. The response includes a type byte indicating the data format:

Vehicle Variable IDs

Variable	ID (hex)	Return Type	Unit
Speed	0x40	double (0x0b)	m/s
Position 2D	0x42	position2D (0x01)	m, m
NOₓ emission	0x64	double (0x0b)	mg/s
PMₓ emission	0x65	double (0x0b)	mg/s
CO₂ emission	0x60	double (0x0b)	mg/s
Acceleration	0x72	double (0x0b)	m/s²
Route ID	0x53	string (0x0c)	—

Response Parsing

A response to a GET command follows this structure:

Response structure:
  [cmd_length: 1B] [response_id: 1B] [variable_id: 1B]
  [object_id: string] [type_byte: 1B] [value: variable]

Type bytes:
  0x08 = integer (4 bytes)
  0x09 = byte
  0x0b = double (8 bytes, IEEE 754)
  0x0c = string (4-byte length + UTF-8 bytes)
  0x01 = position2D (two doubles: x, y)
  0x0e = string list (4-byte count + strings)

18.1.4 Java SUMOController Outline

For production deployments, a Java controller provides type safety and performance. Here is the architectural outline:

public class SUMOController {
    private Socket socket;
    private DataOutputStream out;
    private DataInputStream in;

    public void connect(String host, int port) throws IOException {
        socket = new Socket(host, port);
        out = new DataOutputStream(socket.getOutputStream());
        in  = new DataInputStream(socket.getInputStream());
    }

    public void simulationStep() throws IOException {
        // CMD_SIMSTEP = 0x02
        byte[] cmd = buildCommand(0x02, new byte[0]);
        sendMessage(cmd);
        readResponse();
    }

    public double getVehicleSpeed(String vehId) throws IOException {
        // GET_VEHICLE_VARIABLE=0xa4, VAR_SPEED=0x40
        byte[] content = encodeString(vehId);
        byte[] cmd = buildCommand(0xa4, (byte)0x40, content);
        sendMessage(cmd);
        return parseDoubleResponse();
    }

    public void setTrafficLightPhase(String tlsId, int phase)
            throws IOException {
        // SET_TL_VARIABLE=0xc2, TL_PHASE_INDEX=0x22
        byte[] content = concat(encodeString(tlsId),
                               new byte[]{0x08},  // TYPE_INT
                               encodeInt(phase));
        byte[] cmd = buildCommand(0xc2, (byte)0x22, content);
        sendMessage(cmd);
        readResponse();
    }

    private byte[] buildCommand(int cmdId, byte varId, byte[] content) {
        int cmdLen = 1 + 1 + 1 + content.length;  // len + cmdId + varId + content
        ByteBuffer buf = ByteBuffer.allocate(cmdLen);
        buf.put((byte) cmdLen);
        buf.put((byte) cmdId);
        buf.put(varId);
        buf.put(content);
        return buf.array();
    }

    private void sendMessage(byte[] cmd) throws IOException {
        int totalLen = 4 + cmd.length;
        out.writeInt(totalLen);
        out.write(cmd);
        out.flush();
    }
}

18.1.5 Python: TraCI Message Builder/Parser

This implementation builds and parses TraCI binary messages from scratch, demonstrating the protocol at the byte level.

TraCI Binary Protocol Builder & Parser

Python

script.py211 lines

import struct
import io

# ─── TraCI Constants ───
CMD_SIMSTEP = 0x02
CMD_CLOSE = 0x7f
GET_VEHICLE_VARIABLE = 0xa4
RESPONSE_GET_VEHICLE = 0xb4
SET_VEHICLE_VARIABLE = 0xc4
GET_TL_VARIABLE = 0xa2
SET_TL_VARIABLE = 0xc2

VAR_SPEED = 0x40
VAR_POSITION = 0x42
VAR_NOX = 0x64
VAR_PMX = 0x65
VAR_CO2 = 0x60
VAR_ACCEL = 0x72
VAR_ROUTE_ID = 0x53

TYPE_BYTE = 0x09
TYPE_INT = 0x08
TYPE_DOUBLE = 0x0b
TYPE_STRING = 0x0c
TYPE_POSITION2D = 0x01
TYPE_STRINGLIST = 0x0e

class TraCIMessageBuilder:
    """Build TraCI binary messages from scratch."""

@staticmethod
    def encode_string(s):
        """Encode string as 4-byte length + UTF-8 bytes."""
        encoded = s.encode('utf-8')
        return struct.pack('!I', len(encoded)) + encoded

@staticmethod
    def build_command(cmd_id, content=b''):
        """Build a single TraCI command."""
        cmd_len = 1 + 1 + len(content)  # length_byte + cmd_id + content
        if cmd_len > 255:
            # Extended length: length_byte=0, then 4-byte length
            return struct.pack('!BBI', 0, cmd_len + 4, cmd_id) + content
        else:
            return struct.pack('!BB', cmd_len, cmd_id) + content

@staticmethod
    def build_message(commands):
        """Pack multiple commands into a single TraCI message."""
        payload = b''.join(commands)
        total_len = 4 + len(payload)  # 4 bytes for length prefix
        return struct.pack('!I', total_len) + payload

def get_vehicle_speed(self, vehicle_id):
        """Build GET_VEHICLE_VARIABLE(speed) command."""
        content = struct.pack('!B', VAR_SPEED) + self.encode_string(vehicle_id)
        cmd = self.build_command(GET_VEHICLE_VARIABLE, content)
        return self.build_message([cmd])

def set_tl_phase(self, tls_id, phase_index):
        """Build SET_TL_VARIABLE(phase) command."""
        content = (struct.pack('!B', 0x22) +  # TL_PHASE_INDEX
                   self.encode_string(tls_id) +
                   struct.pack('!Bi', TYPE_INT, phase_index))
        cmd = self.build_command(SET_TL_VARIABLE, content)
        return self.build_message([cmd])

def simulation_step(self):
        """Build CMD_SIMSTEP command."""
        # SUMO >= 1.0: no time argument needed (auto-advance by step-length)
        cmd = self.build_command(CMD_SIMSTEP)
        return self.build_message([cmd])

def close_connection(self):
        """Build CMD_CLOSE command."""
        cmd = self.build_command(CMD_CLOSE)
        return self.build_message([cmd])

def get_vehicle_nox(self, vehicle_id):
        """Build GET_VEHICLE_VARIABLE(NOx) command."""
        content = struct.pack('!B', VAR_NOX) + self.encode_string(vehicle_id)
        cmd = self.build_command(GET_VEHICLE_VARIABLE, content)
        return self.build_message([cmd])

def batch_get_vehicle(self, vehicle_id, variables):
        """Build multiple GET commands for one vehicle in a single message."""
        commands = []
        for var_id in variables:
            content = struct.pack('!B', var_id) + self.encode_string(vehicle_id)
            commands.append(self.build_command(GET_VEHICLE_VARIABLE, content))
        return self.build_message(commands)

class TraCIResponseParser:
    """Parse TraCI binary responses."""

def __init__(self, data):
        self.stream = io.BytesIO(data)

def read_message_length(self):
        return struct.unpack('!I', self.stream.read(4))[0]

def read_command(self):
        """Read one command from the response."""
        length_byte = struct.unpack('!B', self.stream.read(1))[0]
        if length_byte == 0:
            length = struct.unpack('!I', self.stream.read(4))[0]
            content_len = length - 1 - 4
        else:
            length = length_byte
            content_len = length - 1

cmd_id = struct.unpack('!B', self.stream.read(1))[0]
        content = self.stream.read(content_len - 1)
        return cmd_id, content

@staticmethod
    def parse_value(type_byte, data, offset=0):
        """Parse a typed value from response data."""
        if type_byte == TYPE_DOUBLE:
            return struct.unpack_from('!d', data, offset)[0], offset + 8
        elif type_byte == TYPE_INT:
            return struct.unpack_from('!i', data, offset)[0], offset + 4
        elif type_byte == TYPE_BYTE:
            return struct.unpack_from('!B', data, offset)[0], offset + 1
        elif type_byte == TYPE_STRING:
            str_len = struct.unpack_from('!I', data, offset)[0]
            s = data[offset+4:offset+4+str_len].decode('utf-8')
            return s, offset + 4 + str_len
        elif type_byte == TYPE_POSITION2D:
            x, y = struct.unpack_from('!dd', data, offset)
            return (x, y), offset + 16
        return None, offset

# ─── Demonstration ───
builder = TraCIMessageBuilder()

print("=== TraCI Protocol Message Builder ===\n")

# Build and inspect messages
messages = {
    "simulation_step": builder.simulation_step(),
    "get_speed(veh_0)": builder.get_vehicle_speed("veh_0"),
    "get_nox(veh_0)": builder.get_vehicle_nox("veh_0"),
    "set_tl_phase(tls_0, 2)": builder.set_tl_phase("tls_0", 2),
    "close": builder.close_connection(),
    "batch_get(veh_0, [speed, nox, co2])":
        builder.batch_get_vehicle("veh_0", [VAR_SPEED, VAR_NOX, VAR_CO2]),
}

for name, msg in messages.items():
    hex_str = msg.hex()
    # Format as grouped hex
    hex_groups = ' '.join(hex_str[i:i+2] for i in range(0, len(hex_str), 2))
    print(f"─── {name} ───")
    print(f"  Length: {len(msg)} bytes")
    print(f"  Hex:   {hex_groups}")

# Parse structure
    msg_len = struct.unpack('!I', msg[:4])[0]
    print(f"  Message length field: {msg_len}")
    pos = 4
    cmd_num = 0
    while pos < len(msg):
        cmd_len = msg[pos]
        if cmd_len == 0:
            cmd_len = struct.unpack('!I', msg[pos+1:pos+5])[0]
            cmd_id = msg[pos+5]
            pos += 5 + cmd_len - 5
        else:
            cmd_id = msg[pos+1]
            print(f"  Command {cmd_num}: id=0x{cmd_id:02x}, length={cmd_len}")
            pos += cmd_len
        cmd_num += 1
    print()

# ─── Simulate a mock response and parse it ───
print("=== Mock Response Parsing ===\n")

# Build a fake response for speed query
response_content = (
    struct.pack('!B', VAR_SPEED) +
    TraCIMessageBuilder.encode_string("veh_0") +
    struct.pack('!Bd', TYPE_DOUBLE, 8.33)
)
cmd_len = 1 + 1 + len(response_content)  # length + cmd_id + content
response_cmd = struct.pack('!BB', cmd_len, RESPONSE_GET_VEHICLE) + response_content
response_msg = struct.pack('!I', 4 + len(response_cmd)) + response_cmd

parser = TraCIResponseParser(response_msg)
msg_len = parser.read_message_length()
cmd_id, content = parser.read_command()

print(f"Response message length: {msg_len}")
print(f"Response command ID: 0x{cmd_id:02x} (RESPONSE_GET_VEHICLE)")
print(f"Variable ID: 0x{content[0]:02x} (VAR_SPEED)")

# Extract vehicle ID
str_len = struct.unpack('!I', content[1:5])[0]
veh_id = content[5:5+str_len].decode('utf-8')
print(f"Vehicle ID: {veh_id}")

# Extract value
offset = 5 + str_len
type_byte = content[offset]
value, _ = TraCIResponseParser.parse_value(type_byte, content, offset + 1)
print(f"Type: 0x{type_byte:02x} (double)")
print(f"Value: {value} m/s ({value * 3.6:.1f} km/h)")

Click Run to execute the Python code

Code will be executed with Python 3 on the server

18.1.6 Key Takeaways

TraCI is a TCP binary protocol with 4-byte big-endian length prefix, 1-byte command ID, and variable-length content.
Command IDs distinguish GET (0xa*) vs SET (0xc*) operations across domains (vehicles, traffic lights, edges, lanes).
Variable IDs (speed=0x40, NOx=0x64, position=0x42) specify which property to query or modify.
Response parsing requires reading the type byte to determine how to decode the value (double, int, string, position2D).
The protocol is language-agnostic: the Python and Java implementations shown here demonstrate that any language with socket and binary packing support can control SUMO.

← Module 18 Overview Bridge Architectures →