Controlling the fabric: vsiSim and every simulation control command

vsiSim starts the fabric server and every component of a generated twin, then hands you a control prompt called VSI Simulation Control. Everything about time, stepping, inspection and stopping goes through that prompt or through the options that pre-load it.

Starting a twin

From the twin folder, with the environment sourced (see getting-started):

vsiSim TWIN.dt --batch --run

• --batch (or -b) runs everything in the current terminal instead of one xterm per component. Alone, it gives you the interactive prompt in that terminal. Combined with --run or --cmdFile, the whole simulation runs unattended and exits when total simulation time elapses. EXERCISED: this is the form every verified run here used.
• --run (or -r) passes run to the prompt once every component has connected.
• --cmdFile FILE (or -do, -f) runs a file of prompt commands, one per line, the way a person would type them: for example run 5 ms, show, run, exit.
• --enableStats (-s) prints a wall-clock breakdown per component at the end; --logStats (-ls) also writes vsi_analysis/VSI_Performance_Analysis.csv for Innexis Codebench; --showStats (-ss) reprints the last banner. Profiling needs a graceful end (total time elapsed or exit). EXERCISED trap: on the 63-component twin the fabric server exits with code 0xC0000374 at teardown after the simulation has completed, the banner parse fails and vsiSim returns 1 for a run that succeeded. Judge a run by its traces and the fabric log's Total SystemC time line, never by the exit code.
• --record COMPONENT and --replay COMPONENT capture and replay a component's packets with timestamps (REC_remoteSessionN.dat in the twin folder). VENDOR: Ethernet components need a fixed socket port for replay to work; not exercised here.
• --verbose (-v) shows the internal commands and the PID of every process, useful when a component fails to connect. --hold (-xh) keeps xterms open after the end.
• --debug (-d) runs the debug build of components, optionally with gdb.
• --vsiRouteDataExchangePortNum, --vsiRouteSyncPortNum, --vsiRouteInterfacePortNum, --dynamicVsiRoutePorts concern VSI Route, the bridge to virtual platforms and virtual sensors. No twin here uses VSI Route.

What mingw32-make sim does: it runs vsiSim TWIN.dt with no options, which brings the components up and then waits at the prompt for a run. Under a redirected console it sits there forever with every client log at zero bytes. EXERCISED twice. Use the batch form.

The prompt commands (VENDOR, Builder and Simulator Guide 4-4 to 4-22)

Time and stepping:

command	what it does
run	run until total simulation time elapses
run 5 ms	run for a period; units ns (default), us, ms, s; positive integers
step	advance one simulation step
step 10	advance ten steps
set step 100 us	change the step period; each step is one pass of every component
get step	show the step period in nanoseconds
get time (or t)	show the current simulation time in nanoseconds
config FILE.cvsi	load a timing configuration: step, total time, sync period, exchange rate
exit (or e)	end the simulation and leave vsiSim; also what makes profiling valid

Inspection:

command	what it does
show	every component, every signal, its current value
show COMPONENT.SIGNAL	one signal
showFull	as show, plus type, size, last-change timestamp, direction and the connected signals
display clientInfo	every connected client and the total; per client on VSI Route also its sync ratio and mode
enable snooping / disable snooping	print every packet as it crosses, payload in hexadecimal little-endian
enable logging / disable logging	write signal values with timestamps to CSV files under vsi_analysis, per signal, one collective file, and one per protocol; accepts COMPONENT.SIGNAL or -p Ethernet, -p Can, -p CanFd
help (or h)	list the commands

Per-component pacing:

command	applies to
set stepRatio COMPONENT 2.0 and get stepRatio COMPONENT	C++, SystemC, FMU, Python, ROS and Simulink components: the ratio at which that client synchronises with the fabric server
set syncRatio COMPONENT 2.0 and get syncRatio COMPONENT	VSI Route clients only: virtual platforms, vSensor, VEOS, FMI master, HIL

VSI Route only, listed for completeness: set sync, get sync, enable periodicDataExchange, disable periodicDataExchange, set dataExchangeRate, get dataExchangeRate, get vsiRouteConnectionStatus, get vsiRouteParameter NAME, set vpAsyncMode COMPONENT, run vsiRouteAsync. None of these apply to a twin made only of generated C++ and Python components.

VENDOR limits on inspection: show, showFull, snooping and logging are not supported when AXI, GPIO or UART protocols are active, and the prompt prints a warning saying so at start. The twins generated from Teamcenter here fold UART and GPIO onto GenericPayload, so inspection works on them.

Driving a run from a command file

Put prompt commands one per line in a text file and pass it with --cmdFile. A file that runs the first half, dumps every signal, then finishes:

run 5 ms
showFull
run
exit

Because the twins here write their own per-component trace CSV every step through the glue (see stimulus-glue-and-rates), enable logging is rarely needed; it is the vendor's equivalent when a twin has no glue.

Where the output goes (EXERCISED)

• vsi.sim/_logs/check.TWIN.log is the fabric server's log. Simulation stopped by user followed by Total SystemC time = 10000000 is the signature of a complete 10 ms run.
• vsi.sim/_logs/check.COMPONENT.log is one log per component, from its own console.
• A C++ component runs with vsi.sim/_logs as its working directory; a Python component runs from the twin root. Anything a component writes relative to its working directory lands in a different place per language; the glue's Python trace writer compensates.
• After a batch run nothing should be left running. If a run was killed, look for FabricServer, VsiClient and vsiSim processes and stop them before the next run, because the fabric's ports are fixed.