GRL.TestSimulator 1.0.1

GRL.TestSimulator

Pluggable hardware simulation and DMA metadata-logging library for GRL backend projects.

Overview

GRL.TestSimulator provides two complementary modes for GRL backend projects:

• Metadata Logging Mode — records live DMA traffic from real hardware into compact golden report files on disk
• Simulation Mode — replays recorded golden reports in place of real hardware, enabling fully offline test execution

Only two types are exposed to consumer projects: SimulatorHub (the static entry point) and ISimulatorPlugin (Plugin to use the simulator mode and meta data logging mode). All implementation detail is internal.

Requirements

Installation

Package Manager Console:

Install-Package GRL.TestSimulator -Version 1.0.1 -Source "LocalPackages"

Upgrade from 1.0.0:

Update-Package GRL.TestSimulator

dotnet CLI:

dotnet add package GRL.TestSimulator --version 1.0.1 --source "D:\LocalNuGetPackages"

Public API

SimulatorHub — static entry point

// Activate a mode — call once at startup or when switching modes through any external APIs
ISimulatorPlugin SimulatorHub.Activate(
    bool isSimulationMode,
    bool isMetadataLoggingMode,
    bool isSkipDelayInSimulationMode = false   // true = skip inter-DMA timing delays
);

// Set device identity — call at connection setup
SimulatorHub.SetConnectionContext(
    string swType,
    string swVersion,
    string fwVersion,
    string basePath,
    string hwVersion   = "",   // optional
    string framVersion = ""    // optional
);

// Set test identity — call before Start Streamer
SimulatorHub.SetTestContext(string certification, string powerProfile, string testcase);

// Lifecycle
SimulatorHub.PrepareForTestStart();  // call after SetTestContext and before Start Streamer
SimulatorHub.NotifyTestStopped();    // call after Stop Streamer

ISimulatorPlugin - Contract interface for Consumer application

bool IsSimulationMode { get; }                                         // true = no HW needed
bool IsActive         { get; }                                         // true = either mode on
bool ReadSimulated(ref byte[] data, bool isDataRead);                  // replaces HW read
void TryLogDmaChunk(byte requestHeader, int dmaIndex, byte[] response); // records DMA chunk

Operation Modes

Step-by-Step Consumer Integration Guide

Integration touches four places in your application. Each step below shows exactly what to add and where.

Step 1 - Engine Where HW Read and Write methods are implemnted: declare the plugin and wrap ReadReg / WriteReg

This is the only project that needs to reference GRL.TestSimulator directly via NuGet. All other projects access the plugin indirectly through the static IsSimulationActive flag.

1a - Add the plugin field and static flag:

using GRL.TestSimulator;

// Field — stores the active plugin instance
private ISimulatorPlugin _plugin = null;

// Static helper — lets sibling projects check mode without a direct reference
public static bool IsSimulationActive => m_etherneteng?._plugin?.IsSimulationMode ?? false;

1b - Add RegisterPlugin() - call this from your API layer:

public void RegisterPlugin(bool isSimulationMode, bool isMetadataLoggingMode,
    bool isSkipDelayInSimulationMode = false)
{
    _plugin = SimulatorHub.Activate(isSimulationMode, isMetadataLoggingMode,
                  isSkipDelayInSimulationMode);
}

Set isSkipDelayInSimulationMode = true to skip the inter-DMA timing delays during playback for faster automated test execution. Leave false (default) for realistic hardware timing.

1c - Update ReadReg():

public bool ReadReg(ref byte[] data, string sApiDesc = "", bool isDataReadCommand = false)
{
    // Capture DMA header before any read so it is available for logging
    byte  reqHeader   = (data?.Length > 0) ? data[0] : (byte)0;
    int   reqDmaIndex = (data?.Length > 1) ? data[1] : -1;

    bool result = (_plugin?.IsSimulationMode == true)
        ? _plugin.ReadSimulated(ref data, isDataReadCommand)   // simulation: serve from file
        : ReadDatafromFW(ref data, sApiDesc, isDataReadCommand); // live: read from hardware

    _plugin?.TryLogDmaChunk(reqHeader, reqDmaIndex, data);     // logging: persist DMA chunk

    return result;
}

1d — Update WriteReg() — block hardware writes in simulation mode:

public bool WriteReg(byte[] dataBuffer, string sApiDesc = "")
{
    if (IsSimulationActive)
        return true;   // simulation: skip HW write silently

    // ... your existing write logic ...
    return true;
}

Step 2 — ConnectionSetup: set device context at connection

Call SetConnectionContext before and after the hardware connection is established so the simulator always has up-to-date version information.

using GRL.TestSimulator;

private void UpdateSimulatorContext()
{
    SimulatorHub.SetConnectionContext(
        swType:      /* your SW type string  */,
        swVersion:   /* your SW version      */,
        fwVersion:   /* your FW version      */,
        basePath:    /* root path for golden reports / recordings */,
        hwVersion:   /* your HW revision     */,   // optional — leave out if not applicable
        framVersion: /* your FRAM version    */    // optional — leave out if not applicable
    );
}

basePath is the root folder under which golden reports are stored. The library builds the full path as: basePath \ Simulator Golden Reports \ swType \ certification \ powerProfile \ testcase

Step 3 — DataStreamService: set test context and manage lifecycle

Call these in order around each test run:

using GRL.TestSimulator;

// ── Before Start Streamer ─────────────────────────────────────────────
SimulatorHub.SetTestContext(certification, powerProfile, testCaseName);
SimulatorHub.PrepareForTestStart();
// then start your streamer ...

// ── After Stop Streamer ───────────────────────────────────────────────
// ... stop your streamer, clear DMA tasks ...
SimulatorHub.NotifyTestStopped();

Step 4 — HW Initializer: bypass real hardware in simulation mode

In the method where your hardware port is opened, check IsSimulationActive and skip the real connection:

using GRL.TestSimulator;

public static void InitHWCommunication(string ipAddress)
{
    // ... your existing ping / pre-check logic ...

    if (EthernetEngine.IsSimulationActive)
    {
        // No hardware needed — mark as connected and continue
        FWAppObj.FWHost.EthernetConnectionStatus = EthernetConnectionState.CONNECTED;
    }
    else
    {
        EthernetEngine.EthernetCommunication.InitilizePort();
    }
}

Step 5 — API / UI Layer: expose mode switching at runtime

Expose an endpoint so developers can switch modes while the application is in READY state without restarting.

using GRL.TestSimulator;

[HttpPut("PutSimulatorVariables")]
public void PutSimulatorVariables(
    bool isSimulationMode,
    bool isMetadataLoggingMode,
    bool isSkipDelayInSimulationMode = false)
{
    if (FWAppObj.FWHost.HostState != HostState.READY)
        return;

    EthernetEngine.GetEthernetEngine(false)
                  .RegisterPlugin(isSimulationMode, isMetadataLoggingMode,
                      isSkipDelayInSimulationMode);
}

Integration Checklist

[ ] Step 1 — EthernetEngine
      [ ] ISimulatorPlugin _plugin field added
      [ ] IsSimulationActive static property added
      [ ] RegisterPlugin() method added
      [ ] ReadReg() updated — ReadSimulated + TryLogDmaChunk
      [ ] WriteReg() updated — IsSimulationActive guard added

[ ] Step 2 — ConnectionSetupController
      [ ] SetConnectionContext() called before and after connection

[ ] Step 3 — DataStreamService
      [ ] SetTestContext() called before Start Streamer
      [ ] PrepareForTestStart() called after SetTestContext
      [ ] NotifyTestStopped() called after Stop Streamer

[ ] Step 4 — HW Initializer
      [ ] IsSimulationActive bypass added in InitHWCommunication

[ ] Step 5 — API / UI Layer
      [ ] Mode-switch endpoint exposed and guarded by READY state check

Golden Report Structure

Each recorded session produces a ZIP file containing:

dataSize_bytes = 0 in a chunk entry means the full hardware buffer for that chunk was all zeros. The playback engine automatically reconstructs a zero-filled buffer — no bin file access needed. Use fileOffset_bytes to seek directly to a chunk's data in the bin file.

Version History

1.0.1 — March 2026

• Trailing zero bytes stripped per chunk before bin write — reduces golden report file size on disk; all-zeros chunks stored as dataSize_bytes = 0 and reconstructed on playback
• chunks array removed from master_metadata.json — stored only in per-DMA metadata_{id}.json; master file holds lightweight dataset references
• hwVersion and framVersion added to SetConnectionContext() as optional parameters
• JSON metadata field names updated to include units (_bytes, _ms)
• DMACount in session header is now derived dynamically from recorded DMA channels
• SimulatorHub.Activate() gains optional isSkipDelayInSimulationMode parameter
• All implementation classes are now internal — only SimulatorHub and ISimulatorPlugin are visible to consumers

1.0.0 — March 2026

• Initial release

License

MIT License — Copyright © GRL 2026