Simulink Debug Commandline

Command-Line Simulink Debugger (sldebug)

Text-based debugger that steps through the Simulink simulation loop at the engine method level — you see individual block methods (Outputs, Update, Derivatives, InitializeConditions, Enable, Disable) rather than just signal values. For enabled/triggered subsystems, pay special attention to Disable and Enable methods — these can reset or reinitialize block states and are a common source of unexpected behavior.

• Use sldebug when you've localized unexpected behavior to a few blocks or time steps and need to understand why — which method caused a state change, what the I/O was at that moment, or why the solver chose a particular step size.
• Don't use sldebug for big-picture analysis. Use signal logging first to identify which blocks and which time range are problematic, then switch to sldebug to zoom in.
• Decision rule: Use trace for continuous observation, break when you need to pause and decide, strace only for solver behavior.

Default Workflow (Trace + Step Top)

The preferred pattern uses trace points (auto-print block I/O on every method execution, without pausing) combined with step top. One step top shows the complete execution sequence for an entire time step in a single tool call — far more efficient than break → probe → continue loops.

1. Identify suspect blocks and time range — use model_read / model_overview + signal logging to find which blocks produce wrong output and around which time step.
2. sldebug('topModelName') — start the debugger in one evaluate_matlab_code call.
3. slist — find block IDs of suspect blocks. Note the model name prefix if inside a Model Reference.
4. trace (0)sysIdx:blkIdx for each suspect block — prints U/Y/DSTATE/CSTATE on every method execution. Multiple trace commands can be batched (newline-separated).
5. tbreak T if needed — skip ahead to the time range of interest.
6. step top — advance to next major time step. All traced blocks auto-print. Note: the first step top from @0 executes all initialization methods (SetupRunTimeResources, InitializeConditions, Enable) before the first Outputs.Major — watch for unexpected state resets during init.
7. Repeat step top to observe evolution across time steps. Especially powerful for For Iterator subsystems — one step top shows all iterations.
8. stop when done.

Use breakpoints (break + probe → step over → continue) only when you need to conditionally examine data at a specific iteration or method before deciding what to do next. Use break ... Outputs or break ... Update to filter to a specific method — without a method name, break catches every method including init.

Session Rules

sldebug is interactive and blocks the MATLAB command window. The session persists across evaluate_matlab_code calls.

• Batch non-stepping commands (trace, break, untrace, clear, status, probe) in a single call (newline-separated).
• Stepping/execution commands (step top, step over, continue, stop) should each be in their own call.

Block Addressing

Blocks are identified by (taskIdx)sysIdx:blkIdx — e.g., (0)0:1, (1)0:3. Use slist to find IDs. Always include the parenthesized task index.

| Component | Meaning | |---|---| | taskIdx | 0 for continuous, 1+ for discrete rates | | sysIdx | System index (0 = root) | | blkIdx | Block index in the sorted execution list |

Model References: Prefix commands with the referenced model name — break mRefChild (0)1:3, probe mRefChild (0)1:3. Without the prefix, the debugger reports "system not found".

Synthesized blocks: slist may show engine-generated blocks (e.g., OutportBufferForOut1). These cannot be traced or probed but appear in the execution order. Include them when reporting slist results so the user understands what the engine inserted.

Command Reference

Core commands

| Goal | Command | |---|---| | Start debugger | sldebug('modelName') | | Find block IDs | slist | | Trace block I/O (auto-print) | trace (0)sys:blk / untrace (0)sys:blk | | Probe block snapshot | probe (0)sys:blk | | Show all states | states | | Advance one major time step | step top | | Step over current method | step over | | Step into subsystem | step or step in | | Step out of subsystem | step out | | Break before method | break (0)sys:blk [Method] | | Break after method | bafter (0)sys:blk [Method] | | Break at time T (toggle) | tbreak T | | Resume to next breakpoint | continue | | Show breakpoints/settings | status | | Remove breakpoint | clear N or clear (0)sys:blk | | Current position in sim loop | where | | End session | stop |

Specialized breakpoints (all toggles — run again to disable)

| Command | Pauses when | |---|---| | nanbreak | Signal produces NaN or Inf | | zcbreak | Zero-crossing event occurs | | xbreak | State limits solver step size | | ebreak | Solver encounters an error | | rbreak | Solver requests a reset |

Solver debugging (advanced)

Use the simulink-solver-profiler-analyzer skill first to identify problematic time ranges. Then use strace 1 + tbreak to zoom in on why the solver behaves that way. Key solver trace prefixes: TM = major step, Ts - Hs = successful minor step, Err - Ix = normalized error (>1 = step fails, Ix identifies the limiting state — run states to map it). For zero-crossing analysis, use zcbreak + zclist.

Gotchas

• Do NOT call sim() while sldebug is active — sldebug already runs the simulation; concurrent sim() will error.
• Do NOT use bare sysIdx:blkIdx — always include the task index: (0)0:1, not 0:1.
• Do NOT fall back to signal logging — when this skill is requested, use the command-line debugger. Signal logging cannot reveal which block method caused a state change.
• Do NOT use break → probe → continue as the primary pattern — prefer trace + step top. Only use breakpoints when you need conditional pausing.
• tbreak is a toggle — run tbreak T again to disable it. Use status to verify active breakpoints.
• Multi-rate models — blocks in different rate groups have different task indices; verify with slist.
• Do NOT use emode — legacy command.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: simulink
• Source: simulink/skills
• License: BSD-3-Clause

Install and usage instructions live in the source repository linked above.