Matlab Cosimulate Sumo Simulink

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

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

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.

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

Reader Block — Simulation Topics (no input port)

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.

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

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.

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

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

Patterns

Single-Shot Triggers

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; fired = true;
% else, pulse = 0.0; end
% end

Ego Vehicle Control (Route-File Approach — Recommended)

Define ego in .rou.xml with depart="0" so Readers work from t=0:

<routes>
    <vType id="ego_type" accel="2.6" decel="4.5" sigma="0" length="5" maxSpeed="25"/>
    <route id="ego_route" edges="B1B2 B2B3 B3B4 B4B1 B1B2 B2B3 B3B4 B4B1"/>
    <vehicle id="ego_veh" type="ego_type" route="ego_route" depart="0"
             departLane="free" departSpeed="max"/>
</routes>

If Simulink owns longitudinal control via Writer(Vehicle/Speed), do NOT put <stop> clauses in the ego's route — SUMO's stop directive overrides the Speed Writer.

Gated Writer(Vehicle/Speed) for Delayed-Spawn Vehicles

% Latched enable: HIGH from t >= spawnTime onwards
% Clock -> Compare To Constant (relop='>=', const=spawnTime) -> Enable
% Inside Enabled Subsystem:
%   String Constant("veh_1") -> Writer(Vehicle/Speed) port 1
%   Constant(desiredSpeed)   -> Writer(Vehicle/Speed) port 2

Use Compare To Constant >= spawnTime (stays HIGH) rather than one-shot — speed must be continuously asserted while the vehicle is alive.

Distinct Routes Per Vehicle (Dynamic Spawning)

<routes>
    <route id="ego_route"   edges="A0A1 A1A2 A2B2 B2C2 C2C1 C1C0"/>
    <route id="veh_1_route" edges="A1B1 B1B2 B2C2 C2C1 C1C0 C0B0"/>
    <route id="veh_2_route" edges="B0B1 B1A1 A1A2 A2B2 B2C2 C2C1"/>
</routes>

% Per Actor block: set_param(actorPath, 'routeID', sprintf('veh_%d_route', k));

Spawn-Then-Teleport (Position Workaround)

Since SpawnMethod='Position' is broken (see Known Issues), use this two-step pattern:

Step N:   Actor(Add, SpawnMethod='Lane', routeID=...) -> vehicle at edge start
Step N+1: Writer(Vehicle/Position, RouteFlag=on) with (VehId, EdgeId, int32(LaneIdx),
          X, Y, Angle, uint8(1)) -> vehicle teleports to (X,Y)

A one-step delay between Spawn and Move is mandatory — use a Unit Delay on the enable signal. The vehicle does not exist on the SUMO side until one step after the Actor fires.

Periodic Batch Spawn Near Moving Reference

Clock -> PulseGen (persistent, fires every 5s, increments batch id)
       -> SpawnBatch (Enabled SS, Priority=1): N IDGen -> N Actor(Add)
       -> [Unit Delay z^-1]
       -> MoveBatch (Enabled SS, Priority=10): N Writer(Vehicle/Position)
Reader(Vehicle/Position) on ego feeds PosGen so batch lands at egoPos + offset.

MATLAB Function with String Outputs

For dynamically generated vehicle IDs (e.g., "dyn_" + string(batch) + "_1"):

chart = sf.find('-isa','Stateflow.EMChart','Path',chartPath);
chart.ChartUpdate = 'DISCRETE';
chart.SampleTime = '0.1';
outData = chart.find('-isa','Stateflow.Data','Scope','Output');
outData.DataType = 'string';
outData.Props.Array.Size = '1';

Safe Vehicle State Access

All Vehicle-topic Readers AND Writers dereference the Vehicle Id at every step. They crash if the vehicle does not exist. This applies to Reader(Vehicle/...), Writer(Vehicle/...), AND Writer(Visualization/Track Vehicle).

For vehicles spawning after t=0, gate in an Enabled Subsystem:

% Clock -> Compare To Constant (>= spawnTime) -> Enabled Subsystem
% Inside: String Constant + Reader/Writer blocks

For ego defined in .rou.xml with depart="0" — no gating needed.

Random Traffic Quick-Start

set_param([modelName '/SUMO Server'], 'EnableRandomTraffic','on', 'RandomTraffic','10');

No <route-files> needed. Random vehicles are named SpawnedVehicle_1, SpawnedVehicle_2, etc.

Known Issues (Support Package Bugs)

Common Mistakes

Conventions

• Always use Fixed-step solver with step size matching SUMO step-length and all block SampleTime values

• Always save_system(modelName) before sim(modelName) after programmatic changes

• Always match ClientPort to ServerPort

• Use a single Clock at model root — fan out to all comparators/pulse generators

• Prefer defining ego in .rou.xml with depart="0" over Actor block

• Give ego a long/circular route to prevent mid-simulation removal

• Use departSpeed='max' as the practical default for vehicles that should land moving

• Writer(Speed) sets desired speed — SUMO handles gap maintenance via car-following

• Enable pacing (EnablePacing='on') for demos so the GUI doesn't flash by

• Wrap Visualization writers (Track, Schema, Zoom) in one-shot Enabled Subsystems — they are sticky

• Always place Actor blocks inside Enabled/Triggered Subsystems

• Every dynamically spawned vehicle needs a unique ID and a valid standalone route

• Validate .sumocfg with SUMO CLI before Simulink: system(sprintf('"%s" -c "%s" --end 0.1', sumoExe, cfgFile))

• When using mcp__matlab__model_edit, fall back to add_line for Enable port wiring

Copyright 2026 The MathWorks, Inc.