kernelvex 0.3.0

VEX Controls library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

//! Utility enums and helpers used across the library.
//!
//! This module provides common types and macros used throughout kernelvex:
//!
//! - [`Orientation`]: Left/right or CW/CCW direction indicators
//! - [`TrackingWheelOrientation`]: Vertical or horizontal wheel mounting with offset
//! - [`shared_motor!`]: Macro for creating shared motor arrays
//! - [`GroupErrors`]: Type alias for collections of port errors
use crate::util::si::QLength;

use vexide_devices::smart::PortError;
/// Represents the orientation or direction of a tracking wheel or component.
///
/// This enum is used in two contexts:
///
/// 1. **Spatial orientation**: `Left` and `Right` indicate which side of the
///    robot center a component is mounted on (determined by offset sign).
///
/// 2. **Rotational direction**: `CW` (clockwise) and `CCW` (counter-clockwise)
///    indicate rotation sense for turning operations.
///
/// # Example
///
/// ```
/// use kernelvex::util::utils::Orientation;
///
/// let wheel_side = Orientation::Left;
/// let turn_direction = Orientation::CW;
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Orientation {
    /// Left side of the robot (negative offset from center)
    Left,
    /// Right side of the robot (positive offset from center)
    Right,
    /// Clockwise rotation
    CW,
    /// Counter-clockwise rotation
    CCW,
}

/// Specifies the mounting orientation of a tracking wheel with its offset distance.
///
/// Tracking wheels can be mounted in two orientations:
///
/// - **Vertical**: Measures forward/backward movement. The offset is the
///   perpendicular distance from the robot's center to the wheel (positive = right).
///
/// - **Horizontal**: Measures lateral (sideways) movement. The offset is the
///   distance from the robot's center along the forward axis (positive = forward).
///
/// # Example
///
/// ```
/// use kernelvex::util::utils::TrackingWheelOrientation;
/// use kernelvex::util::si::QLength;
///
/// // Vertical wheel 5 inches to the right of center
/// let right_wheel = TrackingWheelOrientation::Vertical(QLength::from_inches(5.0));
///
/// // Horizontal wheel 3 inches behind center
/// let back_wheel = TrackingWheelOrientation::Horizontal(QLength::from_inches(-3.0));
/// ```
#[derive(Copy, Clone, Debug)]
pub enum TrackingWheelOrientation {
    /// Vertical (forward-facing) wheel with perpendicular offset from center
    Vertical(QLength),
    /// Horizontal (sideways-facing) wheel with forward offset from center
    Horizontal(QLength),
}

/// Creates a shared motor array wrapped in `Rc<RefCell<[Motor; N]>>`.
///
/// This macro simplifies creating motor arrays that can be shared between
/// multiple components (e.g., drivetrain and autonomous routines) while
/// allowing interior mutability.
///
/// # Arguments
///
/// Accepts one or more `Motor` instances, separated by commas.
///
/// # Returns
///
/// `Rc<RefCell<[Motor; N]>>` where `N` is the number of motors provided.
///
/// # Example
///
/// ```ignore
/// use kernelvex::shared_motor;
/// use vexide_devices::smart::motor::Motor;
///
/// let motors = shared_motor!(
///     Motor::new(port1, Gearset::Green, Direction::Forward),
///     Motor::new(port2, Gearset::Green, Direction::Forward),
/// );
/// ```
#[macro_export]
macro_rules! shared_motor {
    ($($motor:expr), + $(,)?) => {{
        const N: usize = <[()]>::len(&[$(shared_motor!(@replace $motor)),*]);

        let motors: [Motor; N] = [$($motor),+];
        Rc::new(RefCell::new(motors))
    }};
    (@replace $_:expr) => (());
}

/// A collection of port errors from group operations.
///
/// When performing operations on motor groups or solenoid groups, individual
/// devices may fail while others succeed. This type collects all errors that
/// occurred during a group operation.
///
/// # Example
///
/// ```ignore
/// use kernelvex::util::utils::GroupErrors;
///
/// async fn operate_group(group: &SolenoidGroup) -> Result<(), GroupErrors> {
///     group.extend().await
/// }
/// ```
pub type GroupErrors = Vec<PortError>;