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 /// CiA 402 homing method used when the axis needs to declare "current position
56 /// = home offset" — i.e. the terminal step of software homing (after a sensor
57 /// search) and the integrated [`HomingMethod::CurrentPosition`] variant.
58 ///
59 /// Methods 37 and 35 are functionally equivalent; 37 is the newer CiA 402
60 /// addition. Default: 37 (works on Teknic ClearPath and other modern drives).
61 /// Set to 35 for drives whose 6098h range stops at 35 (Inovance SV660N).
62 pub soft_home_method: i8,
63
64 /// Drive trait: does this drive refuse to assert set-point-acknowledge
65 /// (status word bit 12) while Halt (control word bit 8) is asserted?
66 ///
67 /// In CiA-402 Profile Position mode the cancel handshake that closes out a
68 /// halt issues a new set-point (current position, zero velocity) and waits
69 /// for the drive to acknowledge it. Drives disagree on whether that
70 /// acknowledge is produced while Halt is still active — and this is the
71 /// one behavioral split between the drives we support:
72 ///
73 /// - **`true`** — the drive will NOT acknowledge a set-point while halted,
74 /// so [`command_cancel_move`](super::axis::Axis::command_cancel_move)
75 /// must clear the halt bit while issuing the cancel set-point. The
76 /// Kollmorgen AKD and Inovance SV660N both behave this way. Two
77 /// independent, reference-grade CiA-402 implementations agreeing makes
78 /// this the *standard* behavior.
79 /// - **`false` (default)** — halt is held through the whole cancel
80 /// handshake. The Teknic ClearPath needs this: it acknowledges the
81 /// set-point while halted, and clearing halt early makes it resume the
82 /// prior move. Teknic is the oddball here.
83 ///
84 /// The default is `false` deliberately as the **safe fallback**, not
85 /// because it is the common case: if an unknown drive actually needs halt
86 /// cleared, the halt merely times out with the motor already stopped
87 /// (loud and safe), whereas defaulting to `true` on a Teknic-like drive
88 /// could provoke unexpected motion when halt drops mid-handshake.
89 ///
90 /// Typically not hand-set: the drive's extended-info default is seeded into
91 /// the axis's `options` in `project.json` (overridable there) and baked into
92 /// the generated drive handle by codegen, the same path as `invert_direction`.
93 pub halt_blocks_setpoint_ack: bool,
94
95 // ── Timeouts ──
96
97 /// Timeout for general operations (enable, disable, halt, fault recovery) in seconds.
98 /// Default: 7s.
99 pub operation_timeout_secs: f64,
100 /// Timeout for homing operations in seconds. Default: 30s.
101 pub homing_timeout_secs: f64,
102
103 // ── Software position limits ──
104
105 /// Enable the maximum (positive) software position limit.
106 pub enable_max_position_limit: bool,
107 /// Enable the minimum (negative) software position limit.
108 pub enable_min_position_limit: bool,
109 /// Maximum position limit in user units.
110 pub max_position_limit: f64,
111 /// Minimum position limit in user units.
112 pub min_position_limit: f64,
113}
114
115impl AxisConfig {
116 /// Create a new configuration from encoder resolution.
117 ///
118 /// Default user units are revolutions (1.0 user unit = 1 revolution).
119 /// Call [`with_user_scale`](Self::with_user_scale) to change.
120 pub fn new(counts_per_rev: u32) -> Self {
121 Self {
122 counts_per_rev: counts_per_rev as f64,
123 user_per_rev: 1.0,
124 invert_direction: false,
125 jog_speed: 0.0,
126 jog_accel: 0.0,
127 jog_decel: 0.0,
128 home_position: 0.0,
129 homing_speed: 0.0,
130 homing_accel: 0.0,
131 homing_decel: 0.0,
132 soft_home_method: 37,
133 halt_blocks_setpoint_ack: false,
134 operation_timeout_secs: 7.0,
135 homing_timeout_secs: 30.0,
136 enable_max_position_limit: false,
137 enable_min_position_limit: false,
138 max_position_limit: 0.0,
139 min_position_limit: 0.0,
140 }
141 }
142
143 /// Set user-units-per-revolution.
144 ///
145 /// - Degrees: `.with_user_scale(360.0)`
146 /// - mm on 5 mm/rev ballscrew: `.with_user_scale(5.0)`
147 pub fn with_user_scale(mut self, user_per_rev: f64) -> Self {
148 self.user_per_rev = user_per_rev;
149 self
150 }
151
152 // ── Conversion methods ──
153
154 /// Convert user units to encoder counts (f64).
155 ///
156 /// `to_counts(45.0)` on a 12800 cpr / 360° config → 1600.0
157 pub fn to_counts(&self, user_units: f64) -> f64 {
158 let sign = if self.invert_direction { -1.0 } else { 1.0 };
159 user_units * self.counts_per_user() * sign
160 }
161
162 /// Convert encoder counts to user units (f64).
163 ///
164 /// `to_user(1600.0)` on a 12800 cpr / 360° config → 45.0
165 pub fn to_user(&self, counts: f64) -> f64 {
166 let sign = if self.invert_direction { -1.0 } else { 1.0 };
167 counts * sign / self.counts_per_user()
168 }
169
170 /// Encoder counts per user unit (scale factor).
171 ///
172 /// For 12800 cpr / 360°: `counts_per_user() ≈ 35.556`
173 pub fn counts_per_user(&self) -> f64 {
174 self.counts_per_rev / self.user_per_rev
175 }
176}
177
178#[cfg(test)]
179mod tests {
180 use super::*;
181
182 #[test]
183 fn halt_blocks_setpoint_ack_defaults_to_safe_false() {
184 // The safe fallback: an unknown drive holds halt through the cancel
185 // handshake (Teknic-style) and fails loud rather than risking motion.
186 let cfg = AxisConfig::new(1_048_576);
187 assert!(!cfg.halt_blocks_setpoint_ack);
188 }
189
190 #[test]
191 fn basic_conversion_degrees() {
192 let cfg = AxisConfig::new(12_800).with_user_scale(360.0);
193 assert!((cfg.to_counts(45.0) - 1600.0).abs() < 0.01);
194 assert!((cfg.to_counts(360.0) - 12800.0).abs() < 0.01);
195 assert!((cfg.to_user(1600.0) - 45.0).abs() < 0.01);
196 assert!((cfg.to_user(12800.0) - 360.0).abs() < 0.01);
197 }
198
199 #[test]
200 fn basic_conversion_mm() {
201 let cfg = AxisConfig::new(12_800).with_user_scale(5.0);
202 assert!((cfg.to_counts(5.0) - 12800.0).abs() < 0.01);
203 assert!((cfg.to_counts(2.5) - 6400.0).abs() < 0.01);
204 }
205
206 #[test]
207 fn counts_per_user() {
208 let cfg = AxisConfig::new(12_800).with_user_scale(360.0);
209 let cpu = cfg.counts_per_user();
210 assert!((cpu - 12800.0 / 360.0).abs() < 1e-9);
211 }
212
213 #[test]
214 fn default_revolutions() {
215 let cfg = AxisConfig::new(12_800);
216 // 1 rev = 12800 counts
217 assert!((cfg.to_counts(1.0) - 12800.0).abs() < 0.01);
218 assert!((cfg.to_counts(0.125) - 1600.0).abs() < 0.01);
219 }
220
221 #[test]
222 fn round_trip() {
223 let cfg = AxisConfig::new(12_800).with_user_scale(360.0);
224 let original = 45.0;
225 let counts = cfg.to_counts(original);
226 let back = cfg.to_user(counts);
227 assert!((back - original).abs() < 1e-9);
228 }
229
230 #[test]
231 fn defaults() {
232 let cfg = AxisConfig::new(12_800);
233 assert_eq!(cfg.jog_speed, 0.0);
234 assert_eq!(cfg.home_position, 0.0);
235 assert!(!cfg.enable_max_position_limit);
236 assert!(!cfg.enable_min_position_limit);
237 }
238}