Module simulation

cu29::simulation Module

The cu29::simulation module provides an interface to simulate tasks in Copper-based systems. It offers structures, traits, and enums that enable hooking into the lifecycle of tasks, adapting their behavior, and integrating them with simulated hardware environments.

Overview

This module is specifically designed to manage the lifecycle of tasks during simulation, allowing users to override specific simulation steps and simulate sensor data or hardware interaction using placeholders for real drivers. It includes the following components:

• CuTaskCallbackState: Represents the lifecycle states of tasks during simulation.
• SimOverride: Defines how the simulator should handle specific task callbacks, either executing the logic in the simulator or deferring to the real implementation.

Hooking Simulation Events

You can control and simulate task behavior using a callback mechanism. A task in the Copper framework has a lifecycle, and for each stage of the lifecycle, a corresponding callback state is passed to the simulation. This allows you to inject custom logic for each task stage.

CuTaskCallbackState Enum

The CuTaskCallbackState enum represents different stages in the lifecycle of a Copper task during a simulation:

• New(Option<ComponentConfig>): Triggered when a task is created. Use this state to adapt the simulation to a specific component configuration if needed.
• Start: Triggered when a task starts. This state allows you to initialize or set up any necessary data before the task processes any input.
• Preprocess: Called before the main processing step. Useful for preparing or validating data.
• Process(I, O): The core processing state, where you can handle the input (I) and output (O) of the task. For source tasks, I is CuMsg<()>, and for sink tasks, O is CuMsg<()>.
• Postprocess: Called after the main processing step. Allows for cleanup or final adjustments.
• Stop: Triggered when a task is stopped. Use this to finalize any data or state before task termination.

Example Usage: Callback

You can combine the expressiveness of the enum matching to intercept and override the task lifecycle for the simulation.

let mut sim_callback = move |step: SimStep<'_>| -> SimOverride {
    match step {
        // Handle the creation of source tasks, potentially adapting the simulation based on configuration
        SimStep::SourceTask(CuTaskCallbackState::New(Some(config))) => {
            println!("Creating Source Task with configuration: {:?}", config);
            // You can adapt the simulation using the configuration here
            SimOverride::ExecuteByRuntime
        }
        SimStep::SourceTask(CuTaskCallbackState::New(None)) => {
            println!("Creating Source Task without configuration.");
            SimOverride::ExecuteByRuntime
        }
        // Handle the processing step for sink tasks, simulating the response
        SimStep::SinkTask(CuTaskCallbackState::Process(input, output)) => {
            println!("Processing Sink Task...");
            println!("Received input: {:?}", input);

            // Simulate a response by setting the output payload
            output.set_payload(your_simulated_response());
            println!("Set simulated output for Sink Task.");

            SimOverride::ExecutedBySim
        }
        // Generic handling for other phases like Start, Preprocess, Postprocess, or Stop
        SimStep::SourceTask(CuTaskCallbackState::Start)
        | SimStep::SinkTask(CuTaskCallbackState::Start) => {
            println!("Task started.");
            SimOverride::ExecuteByRuntime
        }
        SimStep::SourceTask(CuTaskCallbackState::Stop)
        | SimStep::SinkTask(CuTaskCallbackState::Stop) => {
            println!("Task stopped.");
            SimOverride::ExecuteByRuntime
        }
        // Default fallback for any unhandled cases
        _ => {
            println!("Unhandled simulation step: {:?}", step);
            SimOverride::ExecuteByRuntime
        }
    }
};

In this example, example_callback is a function that matches against the current step in the simulation and determines if the simulation should handle it (SimOverride::ExecutedBySim) or defer to the runtime’s real implementation (SimOverride::ExecuteByRuntime).

Task Simulation with CuSimSrcTask and CuSimSinkTask

The module provides placeholder tasks for source and sink tasks, which do not interact with real hardware but instead simulate the presence of it.

• CuSimSrcTask<T>: A placeholder for a source task that simulates a sensor or data acquisition hardware. This task provides the ability to simulate incoming data without requiring actual hardware initialization.

• CuSimSinkTask<T>: A placeholder for a sink task that simulates sending data to hardware. It serves as a mock for hardware actuators or output devices during simulations.

Controlling Simulation Flow: SimOverride Enum

The SimOverride enum is used to control how the simulator should proceed at each step. This allows for fine-grained control of task behavior in the simulation context:

• ExecutedBySim: Indicates that the simulator has handled the task logic, and the real implementation should be skipped.
• ExecuteByRuntime: Indicates that the real implementation should proceed as normal.

Structs

• CuSimSinkTask
  This is a placeholder task for a sink task for the simulations. It basically does nothing in place of a real driver so it won’t try to initialize any hardware.
• CuSimSrcTask
  This is a placeholder task for a source task for the simulations. It basically does nothing in place of a real driver so it won’t try to initialize any hardware.

Enums

• CuTaskCallbackState
  This is the state that will be passed to the simulation support to hook into the lifecycle of the tasks.
• SimOverride
  This is the answer the simulator can give to control the simulation flow.