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

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; 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)

Issue	Impact	Workaround
SUMO_HOME without trailing separator → launch failure (Windows)	P0 blocker	setenv('SUMO_HOME', [getenv('SUMO_HOME') filesep])
SpawnMethod='Position' passes wrong RouteFlag in internal moveToXY	Vehicle lands at edge start, not requested position	Use spawn-then-teleport pattern (Actor + Unit Delay + Writer(Vehicle/Position))

Common Mistakes

Mistake	Why It Fails	Fix
Reader/Writer on vehicle before it exists	S-function crash in mdlOutputs	Gate in Enabled Subsystem; use depart="0" for ego
Reader output -> Reader input	ID List is variable-length; Vehicle readers need single string	Use String Constant for Vehicle Id
ClientPort != ServerPort	Client can't connect	Match both (default '8813')
Variable-step solver	SUMO requires lockstep	Fixed-step, match step-length
Actor fires repeatedly	"Vehicle already exists"	Enabled Subsystem with one-shot logic
Writer(Vehicle/Speed) ungated for delayed-spawn vehicle	Crash at t=0	Gate with Clock >= spawnTime
Visualization Writer running every step	Wastes sim time; crashes if vehicle missing	One-shot Enabled Subsystem
Route entries not sorted by depart time	Silently dropped	Sort all entries by depart/begin
Route embedded in <flow>	Actor can't find it	Define standalone <route> elements
<stop> in ego route + Speed Writer	SUMO stop overrides Writer	Remove <stop>; use Simulink speed profile
Multiple Clock blocks	Clutter; all output same time	Single Clock, fan out to all consumers
double for Lane Index or Keep Route in Position Writer	Type mismatch rejection	int32(laneIdx), uint8(keepRoute)
Teleport into occupied lane	Pile-ups, stuck vehicles	Teleport to different lane from nearby traffic
Missing save_system before sim	"Unapplied changes" mask error	Always save after programmatic changes
Ego depart="2" with Reader at t=0	Garbage/crash from undefined vehicle	Set ego depart="0"
Spawning at fractional times with FixedStep=1.0	Solver never hits target time	Match FixedStep, step-length, and all SampleTime

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.

---