Matlab Bridge

MATLAB Bridge

Drive the user's live MATLAB session on Windows. Nothing is clicked: commands go in over COM, results come back through files. MATLAB must already be running.

Locate the driver

$MLB = Join-Path $env:LOCALAPPDATA 'mlbridge\mlbridge.ps1'
if (-not (Test-Path $MLB)) {
    # not deployed yet: install from this skill's bundle, then read its DRIVER line
    powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\scripts\install.ps1"
}

Invoke it as:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File $MLB <args>

-Help (or no arguments) prints the full option list.

Hard rules

1. Never read Execute's return value — the driver already discards it. A 300x300 matrix costs 889 KB of text. Results arrive via the log tail.
2. diary does not work over COM (measured: the log stays 0 bytes). Output is captured with evalc and written to <bridge>\logs\<id>.log.
3. Use -Async for anything slow. A synchronous call blocks MATLAB and can hit the tool timeout. A COM round trip is only ~0.7 ms, so the real cost is your turns: batch N steps into one -Code script instead of N calls.
4. Keep bulk data out of stdout. -Pull uses GetVariable and returns a native .NET double[,] (200x200 in ~4 ms); big results should be written to .mat/CSV by MATLAB and read from disk.
5. Generated files are written as UTF-8 (MATLAB reports feature('DefaultCharacterSet') == UTF-8); GBK produces mojibake.
6. -Shot raises the figure window (brief focus steal). That is the only reliable way to capture MATLAB's OpenGL figure content.
7. Task scripts must be valid MATLAB identifiers: mlbtask_<id>.m. A name starting with a digit or containing - makes run() fail silently.
8. Never put clear (or clear all) in a script you run via -ScriptFile. The bridge runs it inside evalc in its own workspace, so clear wipes the bridge's bookkeeping variables (mlb_out, …). The task then never completes: the status file stays RUNNING with no log, and MATLAB looks idle (CPU flat). If the script needs clear, use the batch route instead — it gets a clean workspace of its own.
9. evalc only returns output when the body finishes, so a failure partway through loses everything printed before it. For anything multi-step, have the script append to its own log file (a fopen(...,'a') per line) — that survives a crash. scripts/prog.m is a ready-made helper: prog('step 2 done', fullfile(pwd,'run_progress.log')).
10. Do not let a caller-side timeout kill the monitor process. If the shell waiting on -Async -WaitSec N is itself killed (e.g. by a 120 s tool cap), the bridge never writes the final status and the task is stuck at RUNNING forever. Either give the wait less time than the outer cap, or run the wait as a background job.

Batch route (headless)

For work that must not touch the live session — a long model build, a clear-using script, a reproducible re-run — use scripts/batch_run.ps1 instead of COM. It starts a separate matlab -batch process and handles three measured traps for you:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  "C:\Users\<you>\.dsh\skills\matlab-bridge\scripts\batch_run.ps1" `
  -ScriptFile D:\work\build_model.m -WorkDir D:\work -TimeoutSec 1800

It prints STATE: OK|ERR|TIMEOUT, EXIT, ELAPSED, the progress-log tail, and the artifact list.

Simulink

Building/​running a Simulink model from code has its own class of traps — the worst being that an unconnected input port silently reads 0, so a model can build, save and simulate while producing nonsense. Read SIMULINK.md before scripting add_block / add_line / sim, and always run its connectivity audit before trusting results.

Workflows

Analyse data and report

1. -Push data.csv -PushName D -Code "<compute; fprintf summary>"
2. Check STATE: OK, read the log tail. On STATE: ERR the detail is included.

Long simulation

1. -Code "<run; save results to .mat/.csv>" -Async → keep the returned id.
2. Poll -Status -Id <id> until OK / ERR, then read the result files. (-Status only reads files, so polling works while MATLAB is busy.)

Iterate on a plot

1. -Code "<build figure with an explicit Name>"
2. -Shot, then inspect the PNG (e.g. with a vision tool).

Repair a wiped install

powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\scripts\install.ps1"

Troubleshooting

Design decisions, the full pitfall log, and path resolution: REFERENCE.md.