simulink-instrument-real-time-application

Instrumenting Simulink Real-Time Applications

Use this skill to set up signal capture for a Simulink Real-Time application via slrealtime.Instrument — a runtime-configurable object that attaches to a target computer to stream, visualize, or file-log data from a running application. Instruments are dynamic: they are not stored in the SLX, and generateScript(inst) is the canonical persistence path.

Release compatibility: designed and validated for MATLAB R2026a and later. The addForFileLog/addForSDI/addForMATLAB bucket API was introduced in R2026a. For earlier releases, use that release's documentation.

When to Use

• Setting up signal capture for a Simulink Real-Time application via slrealtime.Instrument
• Test-pointing or badging signals before build so they survive code-gen and are picked up by addInstrumentedSignals()
• Adding signals by label, block path + port, block path + state name, or canvas badge
• Choosing a destination and attaching to the target (addForFileLog/addForSDI/addForMATLAB)
• Validating an instrument against an .mldatx, or configuring callback-driven MATLAB delivery
• Persisting an instrument as M-code, or detaching instruments from the target

When NOT to Use

If the task crosses one of these lines, load the named skill first, then come back.

• Target IP, credentials, RTOS, connect(tg) troubleshooting, status(tg), reboot(tg) → simulink-configure-real-time-target
• Model STF, fixed-step solver, Simulink Real-Time options → simulink-configure-real-time-model (SLRTFileLogMaxRuns only caps retained runs; it selects no signals)
• slbuild, load(tg, app), start, stop, tg.Stimulation, getparam/setparam, startRecording/stopRecording, import(tg.FileLog, app), slrealtime.exportRun → simulink-run-real-time-application. This skill picks which signals and where; it never starts or stops capture.
• UI binding (connectScalar, connectLine, connectXYPlot) — the App Designer path, not this skill

Prerequisites

• MATLAB R2026a or newer, with Simulink Real-Time installed (ver lists it)
• Support package for the hardware: Speedgoat → Speedgoat Add-On; Linux x86-64 devices → Embedded Coder Support Package for Real-Time Linux (requires Embedded Coder)
• Model configured for Simulink Real-Time and a fresh .mldatx in the build folder
• A configured, reachable target computer

API Forms

Use only the forms in references/instrument-api.md § API Signature Reference (instrument methods, addSignal shapes, model-tool calls for canvas prep) and references/destinations.md (bucket methods on tg.Instruments). Anything else is invented — the Never table in Guardrails lists the forms agents produce most often. addSignal takes only two Name-Value parameters, Decimation and BusElement; the settable properties are Name, Enable, AxesTimeSpan, and AxesTimeSpanOverrun.

Workflow

Steps 1–4 happen before slbuild when the canvas must change. Steps 5–11 happen after build. The run itself is owned by simulink-run-real-time-application.

1. Identify the Signals to Capture

Decide what to log and which addSignal shape expresses it: signal label, block path + outport index, or block path + state name. If the user gave a block path but no port, use model_read to list the block's output ports and show them.

• Bus leaf — Ask First. Gate only when the user wants a leaf inside a bus, uses BusElement, names a Bus Selector path as a leaf source, or asks for "one element" of a bus. Whole-bus streaming is not gated. Present both remedies from references/bus-elements.md — convert the source bus to non-virtual and rebuild, or instrument the upstream leaf — and wait for the user to choose. Probing virtuality is not a substitute for asking.
• Array of buses: prefix BusElement with (N). (1-based). If the user named the element, format it directly ("(2).signal1.signal2"); otherwise add the leaf path alone, and on BusElementRequiresDims / BusElementInvalidDims remove the signal, surface the warning, and ask which element. Never guess an index.
• Cannot be logged by name: optimized-away signals (fix: test-point, Step 3), complex or multiword types (hard limit), source blocks named only with spaces, and BusElement on a virtual bus. validate only warns, and generateScript still emits the signal — silence is not success.
• Conditional and Iteration subsystems: the instrument logs post-step, so it produces wrong data when gating or per-iteration values matter. Use a File Log block instead (model edit, rebuild — Ask First).

Details: references/instrument-api.md, references/bus-elements.md.

2. Decide the Destination

Each instrument attaches to one of three buckets:

Destination	Use when
File log (addForFileLog)	Target-side capture for post-run analysis, high-rate or long runs, or no development computer attached
SDI (addForSDI)	Live operator monitoring in the Simulation Data Inspector
MATLAB (addForMATLAB)	Custom MATLAB code reacting to samples via a callback

Decision tree, per-bucket constraints, and the "stream that signal" disambiguation: references/destinations.md.

3. Prep the Signal on the Canvas — Before Build (Ask First)

Get block IDs from model_read, then set both signal properties in one model_edit configure on the signal (blk_X.yN -> blk_Y.uM); verify with model_query_params:

• TestPoint: "on" — for any signal that might be optimized out and will be added by name or block path.
• DataLogging: "on" — for the canvas badge, addInstrumentedSignals() pickup, or the default SDI instrument.

Both are model edits: ask first, and say that a save and rebuild are needed. There is no rescuing an optimized-out signal after build. Payload, outport-without-destination exception, and DataLoggingSampleTime: references/canvas-prep.md.

4. Build the Application (route)

Building is owned by simulink-run-real-time-application (slbuild(model)). The resulting .mldatx is what the instrument validates against.

5. Construct the Instrument

inst = slrealtime.Instrument("myModel.mldatx");
inst.Name = "TargetInstrument";

Construct one when the user wants a controlled destination, a manual signal list, dynamic file logging, MATLAB delivery, or to suppress the transient default SDI instrument that otherwise streams DataLogging-badged signals at start(tg) (references/destinations.md).

6. Add Signals

addSignal(inst, "SigGen");
addSignal(inst, "myModel/Gain", 1, "Decimation", 10);
addSignal(inst, "myModel/Integrator", "x");

Decimation is an integer 1–256, default 1; anything else errors. State it explicitly when set.

Bulk-add finds different things: addInstrumentedSignals(inst) takes streaming-badged signals, addFileLogSignals(inst) takes signals wired to File Log blocks. Both return nothing and silently add nothing on a mismatch — confirm which the model contains, and check the result by counting addSignal lines in generateScript(inst) (references/instrument-api.md § Bulk-Add).

7. Set Capture Options

Set Name, Enable, AxesTimeSpan, or AxesTimeSpanOverrun as needed (references/instrument-api.md § Public Properties). For MATLAB delivery, register the callback now — before attaching:

connectCallback(inst, @onData);

function onData(srcInst, evt)
    [t, d] = getCallbackDataForSignal(srcInst, evt, "SigGen");
end

8. Attach to tg.Instruments

tg = slrealtime;
connect(tg);
addForFileLog(tg.Instruments, inst);    % or addForSDI / addForMATLAB

Once attached the instrument is locked — detach, edit, re-attach. SDI and MATLAB instruments can attach while the application runs. A file-log instrument can too, but only while recording is inactive: route stopRecording(tg) / attach / startRecording(tg) to simulink-run-real-time-application, and surface the recording gap first (references/destinations.md).

9. Hand Off to the Run Lifecycle

load(tg, app) and start(tg, ...) belong to simulink-run-real-time-application. Capture is automatic while the application runs; tell the user where the data lands (references/destinations.md § Where the Data Appears).

10. Persist the Instrument as an M-Script

txt = generateScript(inst);
writelines(txt, "createMyInstrument.m");

The script is bound to this build: after a model rebuild, reconstruct and re-validate the instrument against the fresh .mldatx. To keep only SDI streaming choices with the model, DataLogging badges are the saved-model alternative.

11. Tear Down

removeForFileLog(tg.Instruments, inst);   % one instrument
removeAllForFileLog(tg.Instruments);      % every instrument in the bucket — Ask First

Verification

unavail = validate(inst, "myModel.mldatx");
disp(getAllForFileLog(tg.Instruments));   % or getAllForSDI / getAllForMATLAB

validate returns a fresh instrument holding the signals that could not be resolved. Empty means everything resolved; anything listed is missing from the build — usually a missing test-point.

Guardrails

references/guardrails.md carries the reasoning behind each rule, the silent-wrong-data traps, and the hard limits.

Always:

• Tell the user the instrument's workspace variable name and where it was created (e.g. "created in the base workspace as inst").
• Apply TestPoint and canvas badges before slbuild.
• Run validate(inst, mldatx) before attaching and surface unresolved signals.
• Pick one destination per instrument.
• Save constructed instruments with generateScript().
• State Decimation explicitly when set — the default of 1 is otherwise silent.
• Reconstruct and re-validate the instrument after any model rebuild.

Ask first:

• Bus-leaf capture — any BusElement use, "log one element of this bus", or a Bus Selector path naming a leaf. Present both remedies and wait. Whole-bus streaming is not gated.
• Setting TestPoint or DataLogging on a signal — model edits needing a rebuild.
• removeAllForFileLog / removeAllForSDI / removeAllForMATLAB — affects every attached instrument, not just the user's.
• Hundreds of high-rate signals — warn about target CPU/SSD for file logging, network and development-computer load for streaming.
• Reconfiguring an attached instrument — it is locked; detach first.
• Attaching a file-log instrument to a running application — surface the recording gap.

Never invent function names, properties, Name-Value parameters, or destination methods. Every left-hand form below is a hallucination agents produce regularly — refuse it and use the right-hand column.

Never	Use instead
inst.attach(tg, "filelog")	addForFileLog(tg.Instruments, inst) / addForSDI / addForMATLAB
inst.signals.add("Sig")	addSignal(inst, "Sig")
inst.start() / inst.stop()	Capture begins with the application (start(tg, ...)) or with startRecording
inst.record() / inst.capture()	Attach to a bucket; capture is automatic
inst.getData() / inst.read()	connectCallback(inst, @onData) + getCallbackDataForSignal
inst.save() / inst.export()	generateScript(inst) + writelines
addSignal(..., "SampleRate"/"Period"/"RateLimit", N)	Decimation (integer 1–256), or DataLoggingSampleTime on the model
set_param(..., "TestPoint"/"DataLogging", "on")	model_edit → configure on the signal blk_X.yN -> blk_Y.uM
Simulink.sdi.markSignalForStreaming(port, "on")	model_edit → configure with DataLogging: "on"
Bus-expansion or bulk-add helpers for buses	Add leaves individually — see references/bus-elements.md

addInstrument / removeInstrument / getAllInstruments are real target functions, but they belong to the App Designer / UI-connector path. This skill uses the bucket API. Do not mix the two.

Also never:

• Try to rescue an optimized-out signal after build — test-point and rebuild instead.
• Use BusElement or capture a bus leaf without the Ask-First gate above.
• Guess an array index for an array-of-buses signal.
• Use slrealtime.Instrument for a signal inside a Conditional or Iteration subsystem when gating or per-iteration values matter — use a File Log block.
• Modify a locked instrument's signal list, or attach one instrument to two buckets.
• Conflate addInstrumentedSignals() with addFileLogSignals().
• Embed instrument logic in the SLX — use generateScript().

---

Copyright 2026 The MathWorks, Inc.

---