autocore_std/motion/axis_config.rs
1//! Axis configuration: unit conversion, jog defaults, limits.
2//!
3//! [`AxisConfig`] stores the encoder resolution and user-unit scaling,
4//! plus jog parameters, home position, and software position limits.
5//! It is used by [`Axis`](super::Axis) for all unit conversions.
6
7/// Configuration for a single motion axis.
8///
9/// Stores encoder resolution, user-unit scaling, jog defaults,
10/// and position limits. Used by [`Axis`](super::Axis) internally
11/// and also available for direct use (e.g. logging, HMI display).
12///
13/// # Examples
14///
15/// ```
16/// use autocore_std::motion::AxisConfig;
17///
18/// // ClearPath with 12,800 counts/rev, user units = degrees
19/// let cfg = AxisConfig::new(12_800).with_user_scale(360.0);
20/// assert!((cfg.to_counts(45.0) - 1600.0).abs() < 0.01);
21/// assert!((cfg.to_user(1600.0) - 45.0).abs() < 0.01);
22///
23/// // mm on a 5 mm/rev ballscrew
24/// let mm = AxisConfig::new(12_800).with_user_scale(5.0);
25/// assert!((mm.to_counts(5.0) - 12800.0).abs() < 0.01);
26/// ```
27#[derive(Debug, Clone)]
28pub struct AxisConfig {
29 // ── Unit conversion (private — use to_counts/to_user) ──
30 counts_per_rev: f64,
31 user_per_rev: f64,
32 /// When true, invert the sign of all position/velocity conversions.
33 /// Use when the motor counts in the opposite direction to your user-unit convention.
34 pub invert_direction: bool,
35
36 // ── Jog defaults ──
37
38 /// Jog speed in user units/s.
39 pub jog_speed: f64,
40 /// Jog acceleration in user units/s².
41 pub jog_accel: f64,
42 /// Jog deceleration in user units/s².
43 pub jog_decel: f64,
44
45 // ── Home ──
46
47 /// User-unit position assigned at the home reference point.
48 pub home_position: f64,
49 /// Homing search speed in user units/s.
50 pub homing_speed: f64,
51 /// Homing acceleration in user units/s².
52 pub homing_accel: f64,
53 /// Homing deceleration in user units/s².
54 pub homing_decel: f64,
55
56 // ── Timeouts ──
57
58 /// Timeout for general operations (enable, disable, halt, fault recovery) in seconds.
59 /// Default: 7s.
60 pub operation_timeout_secs: f64,
61 /// Timeout for homing operations in seconds. Default: 30s.
62 pub homing_timeout_secs: f64,
63
64 // ── Software position limits ──
65
66 /// Enable the maximum (positive) software position limit.
67 pub enable_max_position_limit: bool,
68 /// Enable the minimum (negative) software position limit.
69 pub enable_min_position_limit: bool,
70 /// Maximum position limit in user units.
71 pub max_position_limit: f64,
72 /// Minimum position limit in user units.
73 pub min_position_limit: f64,
74}
75
76impl AxisConfig {
77 /// Create a new configuration from encoder resolution.
78 ///
79 /// Default user units are revolutions (1.0 user unit = 1 revolution).
80 /// Call [`with_user_scale`](Self::with_user_scale) to change.
81 pub fn new(counts_per_rev: u32) -> Self {
82 Self {
83 counts_per_rev: counts_per_rev as f64,
84 user_per_rev: 1.0,
85 invert_direction: false,
86 jog_speed: 0.0,
87 jog_accel: 0.0,
88 jog_decel: 0.0,
89 home_position: 0.0,
90 homing_speed: 0.0,
91 homing_accel: 0.0,
92 homing_decel: 0.0,
93 operation_timeout_secs: 7.0,
94 homing_timeout_secs: 30.0,
95 enable_max_position_limit: false,
96 enable_min_position_limit: false,
97 max_position_limit: 0.0,
98 min_position_limit: 0.0,
99 }
100 }
101
102 /// Set user-units-per-revolution.
103 ///
104 /// - Degrees: `.with_user_scale(360.0)`
105 /// - mm on 5 mm/rev ballscrew: `.with_user_scale(5.0)`
106 pub fn with_user_scale(mut self, user_per_rev: f64) -> Self {
107 self.user_per_rev = user_per_rev;
108 self
109 }
110
111 // ── Conversion methods ──
112
113 /// Convert user units to encoder counts (f64).
114 ///
115 /// `to_counts(45.0)` on a 12800 cpr / 360° config → 1600.0
116 pub fn to_counts(&self, user_units: f64) -> f64 {
117 let sign = if self.invert_direction { -1.0 } else { 1.0 };
118 user_units * self.counts_per_user() * sign
119 }
120
121 /// Convert encoder counts to user units (f64).
122 ///
123 /// `to_user(1600.0)` on a 12800 cpr / 360° config → 45.0
124 pub fn to_user(&self, counts: f64) -> f64 {
125 let sign = if self.invert_direction { -1.0 } else { 1.0 };
126 counts * sign / self.counts_per_user()
127 }
128
129 /// Encoder counts per user unit (scale factor).
130 ///
131 /// For 12800 cpr / 360°: `counts_per_user() ≈ 35.556`
132 pub fn counts_per_user(&self) -> f64 {
133 self.counts_per_rev / self.user_per_rev
134 }
135}
136
137#[cfg(test)]
138mod tests {
139 use super::*;
140
141 #[test]
142 fn basic_conversion_degrees() {
143 let cfg = AxisConfig::new(12_800).with_user_scale(360.0);
144 assert!((cfg.to_counts(45.0) - 1600.0).abs() < 0.01);
145 assert!((cfg.to_counts(360.0) - 12800.0).abs() < 0.01);
146 assert!((cfg.to_user(1600.0) - 45.0).abs() < 0.01);
147 assert!((cfg.to_user(12800.0) - 360.0).abs() < 0.01);
148 }
149
150 #[test]
151 fn basic_conversion_mm() {
152 let cfg = AxisConfig::new(12_800).with_user_scale(5.0);
153 assert!((cfg.to_counts(5.0) - 12800.0).abs() < 0.01);
154 assert!((cfg.to_counts(2.5) - 6400.0).abs() < 0.01);
155 }
156
157 #[test]
158 fn counts_per_user() {
159 let cfg = AxisConfig::new(12_800).with_user_scale(360.0);
160 let cpu = cfg.counts_per_user();
161 assert!((cpu - 12800.0 / 360.0).abs() < 1e-9);
162 }
163
164 #[test]
165 fn default_revolutions() {
166 let cfg = AxisConfig::new(12_800);
167 // 1 rev = 12800 counts
168 assert!((cfg.to_counts(1.0) - 12800.0).abs() < 0.01);
169 assert!((cfg.to_counts(0.125) - 1600.0).abs() < 0.01);
170 }
171
172 #[test]
173 fn round_trip() {
174 let cfg = AxisConfig::new(12_800).with_user_scale(360.0);
175 let original = 45.0;
176 let counts = cfg.to_counts(original);
177 let back = cfg.to_user(counts);
178 assert!((back - original).abs() < 1e-9);
179 }
180
181 #[test]
182 fn defaults() {
183 let cfg = AxisConfig::new(12_800);
184 assert_eq!(cfg.jog_speed, 0.0);
185 assert_eq!(cfg.home_position, 0.0);
186 assert!(!cfg.enable_max_position_limit);
187 assert!(!cfg.enable_min_position_limit);
188 }
189}