release v0.9

components/actuator/actuator.h

@@ -118,6 +118,26 @@ extern "C" {
 /** 控制模式: 2 = 闭环位置模式 */
 #define ACTUATOR_CTRL_MODE       2
 
+/* ================================================================
+ * Z 旋转轴心 ↔ 工具末端 偏移补偿
+ *
+ * 终端执行机构 (工具末端) 与 Z 旋转机构不在同一条纵轴上,
+ * 旋转角度 θ 时, 工具末端的 XY 位置会绕旋转中心偏移。
+ *
+ * 补偿公式 (将工具末端定位到 target):
+ *   X_motor = X_tgt - (dx * cosθ - dy * sinθ)
+ *   Y_motor = Y_tgt - (dx * sinθ + dy * cosθ)
+ *
+ * dx, dy 为工具末端相对于 Z 旋转中心的 XY 偏移 (mm),
+ * 待机械测量后填入。
+ * ================================================================ */
+#ifndef ACTUATOR_OFFSET_X_MM
+#define ACTUATOR_OFFSET_X_MM     8.0f    /* angle=0° 时工具末端偏右 ~8mm */
+#endif
+#ifndef ACTUATOR_OFFSET_Y_MM
+#define ACTUATOR_OFFSET_Y_MM     -30.0f   /* angle=0° 时工具末端偏上 ~30mm */
+#endif
+
 /**
  * XY 平面左上零点坐标系 运动方向:
  *   X 轴正向 (→): CW  (dir=0)  ── 电机2
@@ -146,6 +166,32 @@ void actuator_init(void);
  */
 void actuator_set_scale(float x_scale, float y_scale, float angle_scale);
 
+/**
+ * @brief  设置 Z 旋转轴心 ↔ 工具末端 XY 偏移量 (mm)
+ * @param  offset_x_mm  工具末端相对于旋转中心的 X 偏移 (mm)
+ * @param  offset_y_mm  工具末端相对于旋转中心的 Y 偏移 (mm)
+ * @note   补偿会在每次 fragment 执行时自动应用;
+ *         未调用时默认使用 ACTUATOR_OFFSET_X_MM / ACTUATOR_OFFSET_Y_MM
+ */
+void actuator_set_offset(float offset_x_mm, float offset_y_mm);
+
+/**
+ * @brief  获取当前 XY 偏移量
+ * @param  offset_x_mm  [out] X 偏移 (mm), 可为 NULL
+ * @param  offset_y_mm  [out] Y 偏移 (mm), 可为 NULL
+ */
+void actuator_get_offset(float *offset_x_mm, float *offset_y_mm);
+
+/**
+ * @brief  对目标坐标应用 Z 旋转偏移补偿
+ * @param  target_x      [in/out] 目标 X 坐标 (mm)
+ * @param  target_y      [in/out] 目标 Y 坐标 (mm)
+ * @param  angle_deg     当前旋转角度 (度)
+ * @note   内部使用, 也可由上层在手动模式调用
+ */
+void actuator_apply_offset_compensation(uint16_t *target_x, uint16_t *target_y,
+                                        float angle_deg);
+
 /**
  * @brief  执行一个完整 Cycle (遍历所有 Fragment, 逐段运动)
  * @param  cycle  协议下发的 Cycle 数据
@@ -241,6 +287,12 @@ const edc_cycle_t *actuator_get_last_cycle(void);
  * @brief  最近 Cycle 是否有效
  */
 bool actuator_is_last_cycle_valid(void);
+
+/**
+ * @brief  清除最近 Cycle 记录 (用于等待新 Cycle)
+ */
+void actuator_clear_last_cycle(void);
+
 #ifdef __cplusplus
 }
 #endif