---

name: matlab-cosimulate-sumo-simulink description: > Build Simulink models that co-simulate with Eclipse SUMO traffic simulator. Use when creating SUMO-Simulink co-simulation, traffic simulation, TraCI connection, vehicle-in-the-loop testing, or ADAS scenario validation with SUMO. Covers Server/Client setup, Reader/Writer/Actor block configuration, random traffic generation, ego vehicle control, and SUMO file creation. Also use when the user mentions SumoInterfaceLibrary, .sumocfg files, or wants to connect Simulink to an external traffic simulator. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

Build SUMO-Simulink Co-simulation

Create Simulink models that run synchronized co-simulation with Eclipse SUMO using the SumoInterfaceLibrary blocks from the Automated Driving Toolbox Interface for Eclipse SUMO Traffic Simulator.

When to Use

• Building a Simulink model that connects to Eclipse SUMO
• Setting up traffic co-simulation for ADAS/AD controller testing
• Reading vehicle states (position, speed) from SUMO into Simulink
• Controlling an ego vehicle in SUMO from a Simulink controller
• Spawning or removing vehicles dynamically during simulation
• Generating random background traffic without writing route files

When NOT to Use

• Pure SUMO simulation without Simulink (use SUMO's CLI or Python TraCI directly)
• Vehicle dynamics modeling (use Vehicle Dynamics Blockset)
• Scenario design with Driving Scenario Designer (different workflow)

Prerequisites

1. Eclipse SUMO installed with SUMO_HOME environment variable set
2. Support package installed: "Automated Driving Toolbox Interface for Eclipse SUMO Traffic Simulator"
3. Windows: append trailing separator to SUMO_HOME — The Server block's launcher concatenates SUMO_HOME + "bin\..." without a separator. If SUMO_HOME lacks a trailing \ or /, every sim() fails with "Failed to launch Eclipse SUMO simulator" even though SUMO is installed correctly. Always run before building/simulating:

if ~endsWith(getenv('SUMO_HOME'), filesep)
    setenv('SUMO_HOME', [getenv('SUMO_HOME') filesep]);
end

4. Verify: getenv('SUMO_HOME') must return a valid path ending with a separator.

Preferred Construction Path

When mcp__matlab__model_edit (SATK) is available, prefer it over raw add_block/add_line. It applies auto-layout after every edit, produces clean wiring with no overlap, and lets you reference newly-added blocks by ref within the same call. The patterns below still apply — express them as add_block/connect/configure operations in a single JSON payload. Fall back to add_block/add_line only when SATK is unavailable or when the operation is not expressible in the schema (e.g., setting MATLAB Function Script via sfroot).

Note: When wiring EnablePort on a freshly-created Enabled Subsystem whose default In1/Out1 have been deleted, model_edit cannot resolve the Enable port. Workaround: add_line(model, 'Source/1', 'SubsystemName/Enable', 'autorouting','smart').

Workflow

Idempotent Build Template

modelName = 'sumo_cosim';
workDir = fileparts(mfilename('fullpath'));
% SUMO_HOME workaround (Windows)
sh = getenv('SUMO_HOME');
if ~endsWith(sh, filesep), setenv('SUMO_HOME', [sh filesep]); end
% Idempotent rebuild
if bdIsLoaded(modelName), close_system(modelName, 0); end
slxPath = fullfile(workDir, [modelName '.slx']);
if isfile(slxPath), delete(slxPath); end
new_system(modelName);
open_system(modelName);
set_param(modelName, 'StopTime','100', 'SolverType','Fixed-step', 'FixedStep','0.1');
% ... build model ...
save_system(modelName, slxPath);

1. Prepare SUMO Scenario Files

Ask the user for their existing .sumocfg. Only generate new files if explicitly requested. For quick networks use netgenerate:

sumoHome = getenv('SUMO_HOME');
cmd = sprintf('"%s" --grid --grid.number 2 --grid.length 200 --output-file "%s"', ...
    fullfile(sumoHome,'bin','netgenerate'), fullfile(pwd,'network.net.xml'));
system(cmd);

Minimal .sumocfg (route-files optional when using EnableRandomTraffic):

<configuration>
    <input><net-file value="network.net.xml"/></input>
    <time><begin value="0"/><end value="100"/><step-length value="0.1"/></time>
</configuration>

Route file rules: All <vehicle>, <person>, and <personFlow> entries MUST be sorted by depart time (begin for flows). Out-of-order entries are silently ignored. Routes used by Actor blocks must be standalone <route> elements — not embedded in <flow>.

OpenDRIVE import: Use netconvert --opendrive-files file.xodr -o network.net.xml. Note: SUMO applies a netOffset (visible in .net.xml <location> element) — all SUMO coordinates = OpenDRIVE coordinates + netOffset.

2. Create Server and Client

add_block('SumoInterfaceLibrary/Server', [modelName '/SUMO Server']);
set_param([modelName '/SUMO Server'], 'ServerFile',fullfile(pwd,'cosim.sumocfg'), ...
    'ServerPort','8813', 'ServerNumClients','1', 'EnablePacing','on', ...
    'PacingRate','1', 'SampleTime','0.1');
add_block('SumoInterfaceLibrary/Client', [modelName '/SUMO Client']);
set_param([modelName '/SUMO Client'], 'ClientAddress','127.0.0.1', ...
    'ClientPort','8813', 'ClientOrder','1', 'SampleTime','0.1');

Critical: ClientPort must equal ServerPort. FixedStep must match SUMO step-length. Enable pacing (EnablePacing='on') so the GUI doesn't flash by in 2 seconds.

3–6. Add Readers, Writers, Actors, Save and Run

See Block Reference and Patterns sections below. Always save_system(modelName) before sim(modelName) when the model has been modified programmatically.

Block Reference

Server Block

| Parameter | Purpose | Default | |-----------|---------|---------| | ServerFile | Path to .sumocfg | — | | ServerPort | TraCI port | '8813' | | ServerNumClients | Number of clients | '1' | | EnableRandomTraffic | Spawn vehicles without route file | 'off' | | RandomTraffic | Vehicle count when random traffic enabled | '0' | | EnablePacing | Real-time pacing (recommended for demos) | 'off' | | PacingRate | Pacing multiplier | '1' | | SampleTime | Step interval | '-1' |

Note: SUMO default time-to-teleport=300s — any vehicle stuck >300s gets teleported. This can surprise when deliberately stopping an ego at a bus stop.

Client Block

| Parameter | Purpose | Default | |-----------|---------|---------| | ClientAddress | Server IP | '127.0.0.1' | | ClientPort | Must match ServerPort | '8813' | | ClientOrder | Client priority | '1' |

Reader Block — Vehicle Topics

All Vehicle-topic Readers AND Writers crash if the target vehicle does not exist. Gate them in Enabled Subsystems when the vehicle spawns after t=0. See Safe Vehicle State Access.

| Topic | Input | Output | |-------|-------|--------| | Speed | Vehicle Id | Speed (scalar) | | Position | Vehicle Id | Position [x, y] | | Position3D | Vehicle Id | Position [x, y, z] | | Acceleration | Vehicle Id | Acceleration | | Angle | Vehicle Id | Heading (degrees, 0=north, CW) |

Vehicle Id inputs must come from a String Constant block — never from another Reader's output.

Reader Block — Simulation Topics (no input port)

| Topic | Output | |-------|--------| | ID list | Vehicle ID strings | | ID count | Scalar count | | Arrived list | IDs that reached destination | | Departed list | IDs that entered network |

Writer Block — Vehicle Topics

Writers crash if the target vehicle does not exist — same failure mode as Readers. Gate in Enabled Subsystems for delayed-spawn vehicles.

| Topic | Input Ports | Notes | |-------|------------|-------| | Speed | Vehicle Id, Speed | Sets desired speed; SUMO car-following still brakes for leaders | | Position (RouteFlag off) | Vehicle Id, X, Y, Angle | — | | Position (RouteFlag on) | Vehicle Id, Edge Id, Lane Index, X, Y, Angle, Keep Route | See type table below | | Min gap | Vehicle Id, Gap | — | | Speed mode | Vehicle Id, Mode | — |

Writer(Vehicle/Position, RouteFlag=on) port types — type mismatches silently fail:

| Port | Signal | Type | |------|--------|------| | 1 | Vehicle Id | string | | 2 | Edge Id | string | | 3 | Lane Index | int32 | | 4 | X | double | | 5 | Y | double | | 6 | Angle | double (degrees) | | 7 | Keep Route | uint8 (use uint8(1)) |

Warning: Writer(Vehicle/Position) does no collision-checking. Teleporting near other vehicles causes pile-ups. Place spawned vehicles in a different lane from nearby traffic.

Writer Block — Visualization Topics

Use TopicCategory='Visualization' with GUITopic parameter. Visualization commands are sticky — once SUMO receives Schema/Track/Zoom, it retains the setting. Always wrap in a one-shot Enabled Subsystem. Do NOT leave running every step.

| GUITopic | Input Ports | Valid Values | |----------|------------|--------------| | Track Vehicle | View Id, Vehicle Id | — | | Zoom factor | View Id, Zoom | — | | Schema | View Id, Schema | "standard", "real world", "fast standard", "fast real world" |

All Visualization topics require a View Id input on port 1. The default SUMO GUI view name is "View #0" — always use this exact string.

% Track Vehicle example (one-shot): camera follows ego
add_block('SumoInterfaceLibrary/Writer', [subsysPath '/Track Writer'], ...
    'TopicCategory','Visualization', 'GUITopic','Track Vehicle', 'SampleTime','0.1');
add_block('simulink/String/String Constant', [subsysPath '/View Id'], ...
    'String','"View #0"');  % Default SUMO GUI view — always "View #0"
add_block('simulink/String/String Constant', [subsysPath '/Vehicle Id'], ...
    'String','"ego_vehicle"');
add_line(subsysPath, 'View Id/1', 'Track Writer/1');
add_line(subsysPath, 'Vehicle Id/1', 'Track Writer/2');
% Wrap in one-shot Enabled Subsystem (Constant(0)->IC(1)->Enable)

% Schema example (one-shot): switch GUI to "real world"
add_block('SumoInterfaceLibrary/Writer', [modelName '/Set Schema'], ...
    'TopicCategory','Visualization', 'GUITopic','Schema', 'SampleTime','0.1');
add_block('simulink/String/String Constant', [modelName '/View Id'], ...
    'String','"View #0"');  % Default SUMO GUI view — always "View #0"
add_block('simulink/String/String Constant', [modelName '/Schema Name'], ...
    'String','"real world"');
% Wrap in one-shot Enabled Subsystem (Constant(0)->IC(1)->Enable)

Actor Block

| Parameter | Purpose | |-----------|---------| | VehicleState | 'Add' or 'Remove' | | SpawnMethod | 'Lane' (use this) or 'Position' (broken — see Known Issues) | | departLane | 'random', 'free', 'allowed', 'first', 'best' | | departSpeed | 'max' (recommended), 'random', 'desired', 'speedLimit' | | enableRouteID | 'on'/'off' | | routeID | Route ID from .rou.xml (requires enableRouteID='on') | | typeID | Vehicle type ID (default: 'DEFAULT_VEHTYPE') |

Always place Actor blocks inside Enabled Subsystems. Set Priority='1' on Spawn subsystem so it executes before Readers (Priority='10').

Patterns

Single-Shot Triggers

| Trigger | Pattern | |---------|---------| | Spawn at t=0 only | Constant(0) -> IC(Value=1) -> Enabled Subsystem | | Spawn at simulation time T | Clock -> MATLAB Function (persistent fired) -> Enabled Subsystem | | Continuous from T onward (e.g., speed writer) | Clock -> Compare To Constant (>=T) -> Enabled Subsystem | | Spawn when condition true | Clock/sensor -> MATLAB Function (persistent fired) checking condition |

Time-based one-shot (spawn at t=1.2):

% MATLAB Function code:
% function pulse = fcn(t)
% %#codegen
% persistent fired
% if isempty(fired), fired = false; end
% if (t >= 1.2) && ~fired, pulse = 1.0; f