APIC – Simulation Engine API — Public Interface

Definition

public static void ResetProject()

Short description: Reset internal project state and stop any active recording.

Parameters

None.

Returns

void — no return value.

Example

// Reset the current project state before starting a new project
MyApi.ResetProject();

Remarks

Resets in-process state that the API manages (for example: stops recordings, clears selected engine ID, and releases or nulls internal caches if implemented). This function is typically used before loading or starting a new project to ensure a clean state. It does not start or stop the external simulation process by itself beyond stopping local recordings or monitors.

Definition

public static int StartProject(string projectExe, string projectArgs)

Short description: Initialize project resources and ensure the simulation executable is running (starts it if missing).

Parameters

• projectExe — Full path to the simulation executable (string).
• projectArgs — Command-line arguments to pass when starting the executable (string).

Returns

int — status code: 0 on success; negative on error (for example, -1 on failures such as LRU DB load error or exceptions).

Example

// Try to start the project executable (non-blocking)
int rc = MyApi.StartProject(@"C:\Program\Sim\sim.exe", "--config config.json");
if (rc != 0) {
    Console.WriteLine("Failed to start project");
}

Remarks

This function performs several initialization steps: it resets internal state, attempts to load LRU (lookup) databases, starts internal monitors, checks whether a process with the executable name is already running, and if not — launches the process on a background thread and waits for it to exit only inside that thread (non-blocking for the caller). Errors in preparing the environment (for example failing to load required DB files) produce a negative return code and do not launch the executable. Use the returned code and lastError (if available) to diagnose failures.

Definition

public static bool WaitForCoreEngineReady(int iTimeoutMS)

Short description: Block until the simulation engine reports ready state or timeout expires.

Parameters

• iTimeoutMS — Timeout in milliseconds. If <= 0 the function will wait indefinitely.

Returns

bool — true if the engine became ready before the timeout; false if the timeout elapsed.

Example

// Wait up to 5000 ms for the sim engine to be ready
if (!MyApi.WaitForCoreEngineReady(5000)) {
    Console.WriteLine("Engine didn't become ready in time");
}

Remarks

The readiness check typically depends on internal signals such as a selected engine ID and an initialized report structure. The function periodically polls those conditions and yields the thread (via Thread.Sleep(0)). Use appropriate timeout values to avoid blocking the calling thread for too long. If you call with a zero or negative timeout, behavior depends on implementation (commonly treated as an unlimited wait).

Definition

public static bool WaitForCoreEngineConnectionReady(int iTimeoutMS)

Short description: Wait for the client connection to the simulation engine to reach a ready/connected state or until timeout.

Parameters

• iTimeoutMS — Timeout in milliseconds. Non-negative values bound the wait; negative may indicate indefinite wait depending on implementation.

Returns

bool — Implementation-dependent. Expected: true if connection became ready/connected; false on timeout or if not running. Check the calling code's semantics.

Example

// Wait up to 10000 ms for connection readiness
bool connected = MyApi.WaitForCoreEngineConnectionReady(10000);
if (!connected) {
    Console.WriteLine("Connection did not become ready");
}

Remarks

This routine typically polls a connection-status helper (for example an enum with states like eNotRunning, eNotInitialized, and eConnected). Depending on the internal implementation it may return false if the engine is not running, or if the timeout elapses. The caller should examine the actual connection state API if more detailed handling is required.

Definition

public static int? GetSimEngID()

Short description: Return the currently selected simulation engine ID, if any.

Parameters

None.

Returns

int? — Nullable integer: the selected simulation engine ID, or null if none is selected.

Example

int? simId = MyApi.GetSimEngID();
if (simId.HasValue) Console.WriteLine($"Selected engine ID: {simId.Value}");
else Console.WriteLine("No engine selected");

Remarks

The returned ID is usually sourced from a shared selection variable updated by other components (for example, engine discovery or user selection). The caller should handle the null case gracefully.

Definition

public static string[]? GetSimEngProperties()

Short description: Return setup path or property array for the currently selected simulation engine.

Parameters

None.

Returns

string[]? — Array of properties (for example paths) or null if no engine is selected.

Example

var props = MyApi.GetSimEngProperties();
if (props != null) {
    Console.WriteLine("Engine setup paths:");
    foreach (var p in props) Console.WriteLine(p);
} else {
    Console.WriteLine("No engine selected or properties unavailable");
}

Remarks

The function typically delegates to an internal registry or ID-to-properties mapping. The exact content and ordering of the returned array depends on the implementation (for example: [installPath, configPath, dataPath]). The caller should not assume a fixed length unless the API guarantees it elsewhere.

Definition

public static int EndProject(string projectExe)

Short description: Attempt to gracefully terminate the running simulation process, clean up resources, and release shared memory.

Parameters

• projectExe — Full path to the simulation executable (string). Used to derive process name for termination.

Returns

int — status code: 0 on success; negative on failure (for example -1 if an exception occurred).

Example

// End the project and cleanup
int rc = MyApi.EndProject(@"C:\Program\Sim\sim.exe");
if (rc != 0) Console.WriteLine("EndProject failed");

Remarks

This routine typically finds processes by the executable name, calls into any in-process termination helper, attempts to kill the process if it does not terminate, and releases internal resources such as shared memory objects and internal caches. It may retry termination a few times and then force-kill remaining processes. Use care when calling this function on systems where other unrelated processes might share the same executable name.

Definition

public static int Reset()

Short description: Request a reset of the simulation state.

Parameters

None.

Returns

int — Status code (0 on success, non-zero on failure).

Example

int rc = MyApi.Reset();
if (rc != 0)
    Console.WriteLine("Reset failed");

Remarks

A typical implementation reinitializes internal states in the simulation engine, clearing runtime data without reloading the project. This operation usually causes all elements to revert to their initial state. The caller should check the returned status before issuing new commands.

Definition

public static int Init()

Short description: Perform initialization phase prior to starting the simulation.

Parameters

None.

Returns

int — Status code (0 on success).

Example

if (MyApi.Init() != 0)
    Console.WriteLine("Initialization failed");

Remarks

Initialization may include preparing internal buffers, validating configuration, refreshing elements list, or transitioning the simulation engine into an initialized state. This is typically required before starting play or stepping the engine.

Definition

public static int Play()

Short description: Request the simulation engine to begin running.

Parameters

None.

Returns

int — 0 on success, non-zero otherwise.

Example

if (MyApi.Play() != 0)
    Console.WriteLine("Play command failed");

Remarks

After issuing Play, the engine typically transitions into a running state. Timing, block execution, element updates, and other continuous processes begin. Some engines require Init() to be executed successfully first.

Definition

public static int Stop()

Short description: Stop the simulation from running.

Parameters

None.

Returns

int — 0 if the stop request is accepted; non-zero if it fails.

Example

MyApi.Stop();

Remarks

This halts the simulation engine's execution loop. Typically used before performing state changes, element injections, or before calling Reset() to avoid race conditions during active run.

Definition

public static int Pause()

Short description: Temporarily halt simulation progress without resetting state.

Parameters

None.

Returns

int — 0 on success.

Example

MyApi.Pause();

Remarks

Pausing keeps the simulation engine in a state where it can resume without reinitializing. All active values and partial computations are preserved. The paused state is often used for debugging or for synchronized stepping.

Definition

public static int Step()

Short description: Advance the simulation forward by a single step.

Parameters

None.

Returns

int — Result code (0 indicates success).

Example

// Step through the simulation 10 times
for (int i = 0; i < 10; i++)
    MyApi.Step();

Remarks

Step mode is generally available only while the simulation is paused. Each call advances the simulation clock or engine by one unit of logical time or execution block, depending on implementation. Useful for debugging or deterministic validation.

Definition

public static int Terminate()

Short description: Request the simulation engine to shut down.

Parameters

None.

Returns

int — Status of termination request.

Example

if (MyApi.Terminate() != 0)
    Console.WriteLine("Engine termination failed");

Remarks

Termination usually transitions the engine into a shutdown state, stopping all execution and cleaning internal resources. Depending on the engine, this may close IPC channels, flush logs, or release memory buffers. Some implementations may require Stop() to be issued first.

Definition

public static int ActivateState()

Short description: Apply or activate a pending internal state transition.

Parameters

None.

Returns

int — 0 on success.

Example

if (MyApi.ActivateState() != 0)
    Console.WriteLine("Failed to activate state");

Remarks

This function typically commits queued or staged configuration changes before the engine begins or resumes execution. The meaning of “activate state” varies by implementation; it may refer to initializing domains, resolving pending updates, or selecting a runtime profile.

Definition

public static int StartRecordStr(string blocks, string streams)

Short description: Start recording simulation data for specified blocks and streams using comma-separated strings.

Parameters

• blocks — Comma-separated names of simulation blocks to record.
• streams — Comma-separated names of data streams to record.

Returns

int — 0 on success; negative if recording could not start.

Example

int rc = MyApi.StartRecordStr("Block1,Block2", "StreamA,StreamB");
if (rc != 0) Console.WriteLine("Recording failed to start");

Remarks

This method splits the input strings into arrays and calls StartRecord. It stops any ongoing recording first and initializes internal recording structures. Each recorded block or stream generates a unique internal identifier for playback purposes.

Definition

public static int StartRecord(string[] blocksList, string[] streamsList)

Short description: Start recording simulation data for given arrays of blocks and streams.

Parameters

• blocksList — Array of block names to record.
• streamsList — Array of stream names to record.

Returns

int — 0 on success; -1 if recording could not start (for example, streams are null).

Example

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

Remarks

This function sets up the internal recording map and serializes it into a format understood by the simulation engine. It can handle both raw data and engine-specific data injections. Recording begins immediately after calling this method.

Definition

public static int StopRecord()

Short description: Stop any ongoing recording or playback.

Parameters

None.

Returns

int — 0 if stop was successful.

Example

MyApi.StopRecord();

Remarks

Stops any recording or playback session initiated via StartRecord or RunPlayback. Use this function to safely terminate recording before performing other simulation operations.

Definition

public static int RunPlayback()

Short description: Execute playback of previously recorded simulation data.

Parameters

None.

Returns

int — 0 on success.

Example

int rc = MyApi.RunPlayback();
if (rc != 0) Console.WriteLine("Playback failed");

Remarks

Initiates the replay of all recorded streams and blocks that were recorded previously. The simulation engine receives these playback commands and replays the values as they were recorded. StopRecord should be called before starting a new recording session.

Definition

public static int WaitForElementValue(string elementName, string dataType, string value, string condition, int timeoutMS)

Short description: Wait until a simulation element reaches a specified value or condition.

Parameters

• elementName — Name of the element, may include array index (e.g., "Block[2]").
• dataType — Type of data to compare ("eng" or "raw").
• value — Target value to wait for.
• condition — Comparison operator (!, ==, !=, >, <, >=, <=).
• timeoutMS — Timeout in milliseconds; 0 or negative means wait indefinitely.

Returns

int — 0 if condition met; -1 on timeout or error.

Example

int rc = MyApi.WaitForElementValue("Sensor[0]", "eng", "100", "==", 5000);
if (rc != 0) Console.WriteLine("Timeout waiting for element");

Remarks

The method continuously polls the element value, converting to numeric types if necessary. It supports both raw and engine values. Invalid array syntax or missing elements return -1. Use this function for synchronization or testing conditions in simulations.

Definition

public static int SetElementValue(string elementName, string dataType, string value)

Short description: Set a simulation element to a specific value.

Parameters

• elementName — Name of the element to set.
• dataType — Type of value injection ("eng" or "raw").
• value — Value to assign to the element.

Returns

int — 0 on success; -1 if the element was not found or value could not be set.

Example

int rc = MyApi.SetElementValue("MotorSpeed", "eng", "150");

Remarks

Updates both shadow and engine memory areas. The method handles injection flags for raw or engine-level data. Use carefully to avoid conflicting injections during active simulation runs.

Definition

public static int GetElementValue(string elementName, string dataType, ref string? value)

Short description: Retrieve the current value of a simulation element.

Parameters

• elementName — Name of the element to read.
• dataType — Type of value ("eng" or "raw").
• value — Output parameter receiving the element value.

Returns

int — 0 on success; -1 if element not found or value cannot be retrieved.

Example

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

Remarks

Retrieves the value from engine memory (not the shadow). Returns -1 if the element does not exist or if type conversion fails. Suitable for monitoring element states in real-time or during debugging.

Definition

public static int IsElementInjected(string elementName, ref string? injectionVal)

Short description: Check whether a simulation element has an active injection.

Parameters

• elementName — Name of the element to check.
• injectionVal — Output receiving current injection status.

Returns

int — 0 if no injection; -1 if injected or element not found.

Example

string? injected = null;
int rc = MyApi.IsElementInjected("MotorSpeed", ref injected);
if (rc != 0) Console.WriteLine($"Element is injected: {injected}");

Remarks

Reads the shadow control memory to determine injection flags. Returns -1 if the element has active injections or is invalid. Useful for debugging or conditional automation based on element control status.

Definition

public static int SetBlockState(string blockName, bool bEnable)

Short description: Enable or disable a specific simulation block.

Parameters

• blockName — Name of the simulation block.
• bEnable — true to enable the block, false to disable.

Returns

int — 0 on success.

Example

MyApi.SetBlockState("EngineControl", true);

Remarks

This method sends a message to the simulation engine to change the execution state of the specified block. Use this to dynamically control which blocks participate in simulation runs, allowing selective enabling/disabling during testing.

Definition

public static int SendBlock(string blockName, bool bOnce)

Short description: Trigger a block to send data or perform an action.

Parameters

• blockName — Name of the simulation block.
• bOnce — true to send data once; false for repeated operation.

Returns

int — 0 if the send request is successful.

Example

MyApi.SendBlock("TelemetryBlock", true);

Remarks

Sending a block causes the simulation engine to execute or transmit the block's current data. Repeated sends allow continuous updates, whereas single sends are useful for testing or triggering events without continuous processing.

Definition

public static string GetSimLogText()

Short description: Returns the full path of the currently loaded project.

Parameters

None.

Returns

string — Full absolute project path; empty string if unavailable.

Example

string projectPath = MyApi.GetProjectPath();
Console.WriteLine(projectPath);

Remarks

This method queries the internal engine state to retrieve the project’s root path. The path is typically set during LoadProject or initialization. It does not verify whether the directory exists on disk.

Definition

public static int GetLastRecorderFolder(ref string? version, ref string? lastRecordedFolder)

Short description:.

Parameters

None.

Returns

int — 0 on success; -1 if communication failed.

Example

int rc = MyApi.GetLastRecorderFolder();
    if (rc != 0) Console.WriteLine("Engine connection is not responding.");

Remarks

This function is used to prevent timeouts when the engine expects regular communication. It sends a lightweight request with no payload. Useful in long automated tests or external monitoring applications that may remain idle for long periods.

Definition

public static sting[] GetDriversState()

Short description: return list of all loaded drivers states.

Parameters

• None

Returns

list of all loaded drivers states.

Example

    var states = MyApi.GetDriversState();

Remarks