ace_sim/
can_bus.rs

1//! CAN-aware simulation bus
2//!
3//! Models a CAN bus between an ISO-TP node and one or more ECU nodes. CAN is connection-less -no
4//! session state, no handshake. The bus carries raw CAN frames with CAN-specific fault injection
5//! layered on top of the message-level faults from `FaultConfig`.
6//!
7//! CAN-specific faults:
8//!     - Bit error: a transmitted frame is corrupted at the bit level
9//!     - Arbitration loss: a frame is silently dropped as if lost to arbitration (another node won
10//!     the bus)
11//!     - Bus-off: the bus enters an error state and stops delivering frames until reset.
12
13// region: Imports
14
15use heapless::Vec;
16
17use crate::{
18    bus::{Envelope, SimBus},
19    clock::{Duration, Instant},
20    fault::FaultConfig,
21    io::NodeAddress,
22    rng::{Rng, Xorshift64},
23};
24
25// endregion: Imports
26
27// region: CanFaultConfig
28
29// CAN-level fault configuration.
30#[derive(Debug, Clone)]
31pub struct CanFaultConfig {
32    /// Underlying message-level fault config.
33    pub message: FaultConfig,
34
35    /// Probability a frame is dropped due to arbitration loss
36    pub arbitration_loss: (u32, u32),
37
38    /// Probability a frame triggers a bit error (corruption + retry drop).
39    pub bit_error: (u32, u32),
40
41    /// Probability the bus enters bus-off state on any given tick. When bus-off, all frames are
42    /// dropped until `reset_bus_off()`.
43    pub bus_off: (u32, u32),
44}
45
46impl CanFaultConfig {
47    pub fn none() -> Self {
48        Self {
49            message: FaultConfig::none(),
50            arbitration_loss: (0, 1),
51            bit_error: (0, 1),
52            bus_off: (0, 1),
53        }
54    }
55
56    pub fn light() -> Self {
57        Self {
58            message: FaultConfig::light(),
59            arbitration_loss: (1, 200),
60            bit_error: (1, 200),
61            bus_off: (1, 200),
62        }
63    }
64
65    pub fn chaos() -> Self {
66        Self {
67            message: FaultConfig::chaos(),
68            arbitration_loss: (1, 10),
69            bit_error: (1, 10),
70            bus_off: (1, 10),
71        }
72    }
73}
74
75// endregion: CanFaultConfig
76
77// region: CanBusState
78
79// The operational state of the simulated CAN bus.
80#[derive(Debug, Clone, PartialEq, Eq)]
81pub enum CanBusState {
82    /// Bus is operational - frames are delivered normally.
83    Active,
84
85    /// Bus is in error-passive state - frames may still be delivered but error counts are
86    /// elevated.
87    ErrorPassive,
88
89    /// Bus-off - no frames are delivered until the bus is reset.
90    BusOff { since: Instant },
91}
92
93impl CanBusState {
94    pub fn is_operational(&self) -> bool {
95        matches!(self, Self::Active | Self::ErrorPassive)
96    }
97}
98
99// endregion: CanBusState
100
101// region: CanEvent
102
103/// Events the `CanSimBus` delivers to nodes alongside messages.
104#[derive(Debug, Clone, PartialEq, Eq)]
105pub enum CanEvent {
106    /// Bus transitioned to bus-off state.
107    BusOff,
108
109    /// Bus recovered from bus-off state.
110    BusRecovered,
111
112    /// A bit error was detected on a frame from `src`.
113    BitError { src: NodeAddress },
114}
115
116// endregion: CanEvent
117
118// region: CanSimBus
119
120/// A CAN-aware simulation bus.
121///
122/// Wraps `SimBus` for message delivery and adds CAN bus state and CAN-specific fault injection.
123/// Connection-less - any node may send to any other node as long as the bus is operational.
124///
125/// `N` - max frame payload bytes (8 for classic CAN, 64 for CAN FD)
126/// `Q` - max frames in-flight simultaneously
127pub struct CanSimBus<const N: usize, const Q: usize> {
128    /// Underlying message bus.
129    inner: SimBus<N, Q>,
130
131    /// CAN fault configuration.
132    can_faults: CanFaultConfig,
133
134    /// Current bus state.
135    bus_state: CanBusState,
136
137    /// Accumulated CAN events for nodes to drain.
138    events: Vec<CanEvent, 16>,
139
140    /// Dedicated RNG for CAN-level fault decisions.
141    rng: Xorshift64,
142}
143
144impl<const N: usize, const Q: usize> CanSimBus<N, Q> {
145    /// Creates a new `CanSimBus`.
146    ///
147    /// `seed` - seeds both the message bus RNG and the CAN fault RNG. The CAN RNG uses
148    /// `seed.wrapping_add(2)` for independence.
149    pub fn new(seed: u64, faults: CanFaultConfig) -> Self {
150        Self {
151            inner: SimBus::new(seed, faults.message.clone()),
152            can_faults: faults,
153            bus_state: CanBusState::Active,
154            events: heapless::Vec::new(),
155            rng: Xorshift64::new(seed.wrapping_add(2)),
156        }
157    }
158
159    // region: Message Delivery
160
161    /// Enqueues a CAN frame - rejected if the bus is in bus-off state or CAN-level fault injection
162    /// drops it.
163    ///
164    /// Returns `true` if the frame was accepted.
165    pub fn send(&mut self, src: NodeAddress, dst: NodeAddress, data: &[u8]) -> bool {
166        if !self.bus_state.is_operational() {
167            return false;
168        }
169
170        if self.rng.chance(
171            self.can_faults.arbitration_loss.0,
172            self.can_faults.arbitration_loss.1,
173        ) {
174            return false;
175        }
176
177        if self
178            .rng
179            .chance(self.can_faults.bit_error.0, self.can_faults.bit_error.1)
180        {
181            let _ = self.events.push(CanEvent::BitError { src: src.clone() });
182            return false;
183        }
184
185        self.inner.send(src, dst, data)
186    }
187
188    // endregion: Message Delivery
189
190    // region: Bus State Management
191
192    /// Manually triggers bus-off - useful for DST fault injection.
193    pub fn trigger_bus_off(&mut self) {
194        let now = self.inner.now();
195
196        self.bus_state = CanBusState::BusOff { since: now };
197
198        let _ = self.events.push(CanEvent::BusOff);
199    }
200
201    /// Resets the bus from bus-off state back to Active.
202    pub fn reset_bus_off(&mut self) {
203        if matches!(self.bus_state, CanBusState::BusOff { .. }) {
204            self.bus_state = CanBusState::Active;
205            let _ = self.events.push(CanEvent::BusRecovered);
206        }
207    }
208
209    pub fn bus_state(&self) -> &CanBusState {
210        &self.bus_state
211    }
212
213    // endregion: Bus State Management
214
215    // region: Tick
216
217    /// Advances simulation time, delivers due frames, and checks bus-off fault injection.
218    pub fn tick(&mut self, duration: Duration) -> heapless::Vec<Envelope<N>, Q> {
219        if self.bus_state.is_operational() {
220            if self
221                .rng
222                .chance(self.can_faults.bus_off.0, self.can_faults.bus_off.1)
223            {
224                let now = self.inner.now();
225
226                self.bus_state = CanBusState::BusOff { since: now };
227
228                let _ = self.events.push(CanEvent::BusOff);
229            }
230        }
231
232        if !self.bus_state.is_operational() {
233            let _ = self.inner.tick(duration);
234            return heapless::Vec::new();
235        }
236
237        self.inner.tick(duration)
238    }
239
240    // endregion: Tick
241
242    // region: Accessors
243
244    pub fn now(&self) -> Instant {
245        self.inner.now()
246    }
247
248    /// Drains accumulated CAN events.
249    pub fn drain_events(&mut self) -> impl Iterator<Item = CanEvent> + '_ {
250        self.events.drain(..)
251    }
252
253    pub fn set_faults(&mut self, faults: CanFaultConfig) {
254        self.inner.set_faults(faults.message.clone());
255        self.can_faults = faults;
256    }
257
258    pub fn inner_mut(&mut self) -> &mut SimBus<N, Q> {
259        &mut self.inner
260    }
261
262    // endregion: Accessors
263}
264
265// endregion: CanSimBus
ace_sim/can_bus.rs

ace_sim/
can_bus.rs
