cu29_runtime/simulation.rs
1//! # `cu29::simulation` Module
2//!
3//! The `cu29::simulation` module provides an interface to simulate tasks in Copper-based systems.
4//! It offers structures, traits, and enums that enable hooking into the lifecycle of tasks, adapting
5//! their behavior, and integrating them with simulated hardware environments.
6//!
7//! ## Overview
8//!
9//! This module is specifically designed to manage the lifecycle of tasks during simulation, allowing
10//! users to override specific simulation steps and simulate sensor data or hardware interaction using
11//! placeholders for real drivers. It includes the following components:
12//!
13//! - **`CuTaskCallbackState`**: Represents the lifecycle states of tasks during simulation.
14//! - **`SimOverride`**: Defines how the simulator should handle specific task callbacks, either
15//! executing the logic in the simulator or deferring to the real implementation.
16//!
17//! ## Hooking Simulation Events
18//!
19//! You can control and simulate task behavior using a callback mechanism. A task in the Copper framework
20//! has a lifecycle, and for each stage of the lifecycle, a corresponding callback state is passed to
21//! the simulation. This allows you to inject custom logic for each task stage.
22//!
23//! ### `CuTaskCallbackState` Enum
24//!
25//! The `CuTaskCallbackState` enum represents different stages in the lifecycle of a Copper task during a simulation:
26//!
27//! - **`New(Option<ComponentConfig>)`**: Triggered when a task is created. Use this state to adapt the simulation
28//! to a specific component configuration if needed.
29//! - **`Start`**: Triggered when a task starts. This state allows you to initialize or set up any necessary data
30//! before the task processes any input.
31//! - **`Preprocess`**: Called before the main processing step. Useful for preparing or validating data.
32//! - **`Process(I, O)`**: The core processing state, where you can handle the input (`I`) and output (`O`) of
33//! the task. For source tasks, `I` is `CuMsg<()>`, and for sink tasks, `O` is `CuMsg<()>`.
34//! - **`Postprocess`**: Called after the main processing step. Allows for cleanup or final adjustments.
35//! - **`Stop`**: Triggered when a task is stopped. Use this to finalize any data or state before task termination.
36//!
37//! ### Example Usage: Callback
38//!
39//! You can combine the expressiveness of the enum matching to intercept and override the task lifecycle for the simulation.
40//!
41//! ```rust,ignore
42//! let mut sim_callback = move |step: SimStep<'_>| -> SimOverride {
43//! match step {
44//! // Handle the creation of source tasks, potentially adapting the simulation based on configuration
45//! SimStep::SourceTask(CuTaskCallbackState::New(Some(config))) => {
46//! println!("Creating Source Task with configuration: {:?}", config);
47//! // You can adapt the simulation using the configuration here
48//! SimOverride::ExecuteByRuntime
49//! }
50//! SimStep::SourceTask(CuTaskCallbackState::New(None)) => {
51//! println!("Creating Source Task without configuration.");
52//! SimOverride::ExecuteByRuntime
53//! }
54//! // Handle the processing step for sink tasks, simulating the response
55//! SimStep::SinkTask(CuTaskCallbackState::Process(input, output)) => {
56//! println!("Processing Sink Task...");
57//! println!("Received input: {:?}", input);
58//!
59//! // Simulate a response by setting the output payload
60//! output.set_payload(your_simulated_response());
61//! println!("Set simulated output for Sink Task.");
62//!
63//! SimOverride::ExecutedBySim
64//! }
65//! // Generic handling for other phases like Start, Preprocess, Postprocess, or Stop
66//! SimStep::SourceTask(CuTaskCallbackState::Start)
67//! | SimStep::SinkTask(CuTaskCallbackState::Start) => {
68//! println!("Task started.");
69//! SimOverride::ExecuteByRuntime
70//! }
71//! SimStep::SourceTask(CuTaskCallbackState::Stop)
72//! | SimStep::SinkTask(CuTaskCallbackState::Stop) => {
73//! println!("Task stopped.");
74//! SimOverride::ExecuteByRuntime
75//! }
76//! // Default fallback for any unhandled cases
77//! _ => {
78//! println!("Unhandled simulation step: {:?}", step);
79//! SimOverride::ExecuteByRuntime
80//! }
81//! }
82//! };
83//! ```
84//!
85//! In this example, `example_callback` is a function that matches against the current step in the simulation and
86//! determines if the simulation should handle it (`SimOverride::ExecutedBySim`) or defer to the runtime's real
87//! implementation (`SimOverride::ExecuteByRuntime`).
88//!
89//! ## Task Simulation with `CuSimSrcTask` and `CuSimSinkTask`
90//!
91//! The module provides placeholder tasks for source and sink tasks, which do not interact with real hardware but
92//! instead simulate the presence of it.
93//!
94//! - **`CuSimSrcTask<T>`**: A placeholder for a source task that simulates a sensor or data acquisition hardware.
95//! This task provides the ability to simulate incoming data without requiring actual hardware initialization.
96//!
97//! - **`CuSimSinkTask<T>`**: A placeholder for a sink task that simulates sending data to hardware. It serves as a
98//! mock for hardware actuators or output devices during simulations.
99//!
100//! ## Controlling Simulation Flow: `SimOverride` Enum
101//!
102//! The `SimOverride` enum is used to control how the simulator should proceed at each step. This allows
103//! for fine-grained control of task behavior in the simulation context:
104//!
105//! - **`ExecutedBySim`**: Indicates that the simulator has handled the task logic, and the real implementation
106//! should be skipped.
107//! - **`ExecuteByRuntime`**: Indicates that the real implementation should proceed as normal.
108//!
109
110use crate::config::ComponentConfig;
111
112use crate::cutask::{CuMsg, CuMsgPayload, CuSinkTask, CuSrcTask, Freezable};
113use crate::{input_msg, output_msg};
114use cu29_clock::RobotClock;
115use cu29_traits::CuResult;
116use std::marker::PhantomData;
117
118/// This is the state that will be passed to the simulation support to hook
119/// into the lifecycle of the tasks.
120pub enum CuTaskCallbackState<I, O> {
121 /// Callbacked when a task is created.
122 /// It gives you the opportunity to adapt the sim to the given config.
123 New(Option<ComponentConfig>),
124 /// Callbacked when a task is started.
125 Start,
126 /// Callbacked when a task is getting called on pre-process.
127 Preprocess,
128 /// Callbacked when a task is getting called on process.
129 /// I and O are the input and output messages of the task.
130 /// if this is a source task, I will be CuMsg<()>
131 /// if this is a sink task, O will be CuMsg<()>
132 Process(I, O),
133 /// Callbacked when a task is getting called on post-process.
134 Postprocess,
135 /// Callbacked when a task is stopped.
136 Stop,
137}
138
139/// This is the answer the simulator can give to control the simulation flow.
140#[derive(PartialEq)]
141pub enum SimOverride {
142 /// The callback took care of the logic on the simulation side and the actual
143 /// implementation needs to be skipped.
144 ExecutedBySim,
145 /// The actual implementation needs to be executed.
146 ExecuteByRuntime,
147 /// Emulated the behavior of an erroring task (same as return Err(..) in the normal tasks methods).
148 Errored(String),
149}
150
151/// This is a placeholder task for a source task for the simulations.
152/// It basically does nothing in place of a real driver so it won't try to initialize any hardware.
153pub struct CuSimSrcTask<T> {
154 boo: PhantomData<T>,
155}
156
157impl<T> Freezable for CuSimSrcTask<T> {}
158
159impl<'cl, T: CuMsgPayload + 'cl> CuSrcTask<'cl> for CuSimSrcTask<T> {
160 type Output = output_msg!('cl, T);
161
162 fn new(_config: Option<&ComponentConfig>) -> CuResult<Self>
163 where
164 Self: Sized,
165 {
166 Ok(Self { boo: PhantomData })
167 }
168
169 fn process(&mut self, _clock: &RobotClock, _new_msg: Self::Output) -> CuResult<()> {
170 unimplemented!("A placeholder for sim was called for a source, you need answer SimOverride to ExecutedBySim for the Process step.")
171 }
172}
173
174/// This is a placeholder task for a sink task for the simulations.
175/// It basically does nothing in place of a real driver so it won't try to initialize any hardware.
176pub struct CuSimSinkTask<T> {
177 boo: PhantomData<T>,
178}
179
180impl<T: CuMsgPayload> Freezable for CuSimSinkTask<T> {}
181
182impl<'cl, T: CuMsgPayload + 'cl> CuSinkTask<'cl> for CuSimSinkTask<T> {
183 type Input = input_msg!('cl, T);
184
185 fn new(_config: Option<&ComponentConfig>) -> CuResult<Self>
186 where
187 Self: Sized,
188 {
189 Ok(Self { boo: PhantomData })
190 }
191
192 fn process(&mut self, _clock: &RobotClock, _input: Self::Input) -> CuResult<()> {
193 unimplemented!("A placeholder for sim was called for a sink, you need answer SimOverride to ExecutedBySim for the Process step.")
194 }
195}