APIC Howto – How to Use the Simulation Engine API (ComInterface)

← Back to Howto Index Full reference doc →

Scope: Scripts Interface (external, no COM)

Scope: This is the Scripts Interface — a DLL-based automation API (no COM) for an external script or application to drive an already-running CoreEngine instance from outside. It's optional; CoreEngine runs standalone without it. For writing C++ that runs inside CoreEngine itself (models, states, streams, drivers), see the CoreEngine framework howto instead.

Overview

This guide walks through the typical sequence for driving the Sim Engine via its public API: starting a project, controlling simulation state, recording and playing back data, and reading or writing elements and blocks.

1. Start and Manage a Project

Use these functions to bring the simulation process up, wait for it to become ready, and shut it down cleanly.

Call ResetProject() to clear internal state and stop any active recording before loading a new project.
Call StartProject(string projectExe, string projectArgs) to launch the simulation executable if it isn't already running. Returns 0 on success, negative on error.
Call WaitForCoreEngineReady(int iTimeoutMS) to block until the engine reports ready (or timeout). A value <= 0 waits indefinitely.
Call WaitForCoreEngineConnectionReady(int iTimeoutMS) to wait until the client connection to the engine is ready/connected.
Use GetSimEngID() and GetSimEngProperties() to read the selected engine's ID and setup properties.
Call EndProject(string projectExe) to gracefully terminate the simulation process and release shared memory when finished.

Function	Purpose
`ResetProject()`	Reset internal project state and stop any active recording.
`StartProject(exe, args)`	Launch the simulation executable if not already running.
`WaitForCoreEngineReady(timeoutMS)`	Block until the engine is ready or timeout elapses.
`WaitForCoreEngineConnectionReady(timeoutMS)`	Block until the client connection is ready/connected.
`GetSimEngID()`	Return the currently selected engine ID, or null.
`GetSimEngProperties()`	Return setup path/property array for the selected engine.
`EndProject(exe)`	Terminate the simulation process and release resources.

MyApi.ResetProject();
int rc = MyApi.StartProject(@"C:\Program\Sim\sim.exe", "--config config.json");
if (!MyApi.WaitForCoreEngineReady(5000)) {
    Console.WriteLine("Engine didn't become ready in time");
}
// ... run simulation ...
MyApi.EndProject(@"C:\Program\Sim\sim.exe");

2. Control the Simulation

Once the project is running, drive its execution state with these calls (all return an int status code, 0 on success).

Function	Purpose
`Reset()`	Reinitialize internal states without reloading the project.
`Init()`	Prepare buffers/configuration before starting; usually required before Play or Step.
`Play()`	Start the engine running.
`Stop()`	Halt execution; use before state changes or Reset.
`Pause()`	Temporarily halt without resetting state; can resume without reinitializing.
`Step()`	Advance one step; generally only available while paused.
`Terminate()`	Shut the engine down and clean up resources.
`ActivateState()`	Commit queued/staged configuration changes.

Typical order: Init() → Play() → (Pause()/Step() as needed) → Stop() → Terminate().

if (MyApi.Init() != 0) Console.WriteLine("Initialization failed");
if (MyApi.Play() != 0) Console.WriteLine("Play command failed");
// step through 10 times while paused
for (int i = 0; i < 10; i++) MyApi.Step();
MyApi.Stop();

3. Record and Play Back Simulation Data

Function	Purpose
`StartRecordStr(string blocks, string streams)`	Start recording using comma-separated block/stream names.
`StartRecord(string[] blocksList, string[] streamsList)`	Start recording using arrays of block/stream names.
`StopRecord()`	Stop any ongoing recording or playback.
`RunPlayback()`	Replay previously recorded streams and blocks.

Call StopRecord() before starting a new recording session; both start functions stop any ongoing recording first.

string[] blocks = { "Block1", "Block2" };
string[] streams = { "StreamA" };
int rc = MyApi.StartRecord(blocks, streams);
// later
MyApi.StopRecord();
MyApi.RunPlayback();

4. Read and Write Elements

Elements represent individual simulation values. Use dataType of "eng" (engineering units) or "raw".

Function	Purpose
`WaitForElementValue(elementName, dataType, value, condition, timeoutMS)`	Block until an element reaches a value/condition (supports !, ==, !=, >, <, >=, <=) or timeout.
`SetElementValue(elementName, dataType, value)`	Set an element to a specific value.
`GetElementValue(elementName, dataType, ref value)`	Read the current value of an element.
`IsElementInjected(elementName, ref injectionVal)`	Check whether an element has an active injection.

int rc = MyApi.WaitForElementValue("Sensor[0]", "eng", "100", "==", 5000);
MyApi.SetElementValue("MotorSpeed", "eng", "150");

string? val = null;
MyApi.GetElementValue("MotorSpeed", "eng", ref val);
Console.WriteLine($"MotorSpeed = {val}");

Element names may include an array index, e.g. "Block[2]". All four functions return -1 on failure/timeout or if the element is not found.

5. Enable, Disable, and Trigger Blocks

Function	Purpose
`SetBlockState(blockName, bEnable)`	Enable or disable a simulation block to control which blocks participate in a run.
`SendBlock(blockName, bOnce)`	Trigger a block to send data/perform an action; `bOnce=true` sends once, `false` repeats.

MyApi.SetBlockState("EngineControl", true);
MyApi.SendBlock("TelemetryBlock", true);

6. Use Misc / Utility Functions

Function	Purpose
`GetSimLogText()`	Return project/log path information from the engine.
`GetLastRecorderFolder(ref version, ref lastRecordedFolder)`	Retrieve the last recorder folder and version; useful to keep the connection alive and avoid timeouts.
`GetDriversState()`	Return the list of all loaded drivers' states.

var states = MyApi.GetDriversState();
int rc = MyApi.GetLastRecorderFolder(ref version, ref folder);
if (rc != 0) Console.WriteLine("Engine connection is not responding.");