From d8cb6bb834bd2268b5342fe4de9eb6779f81fffd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Beat=20K=C3=BCng?= <beat-kueng@gmx.net>
Date: Wed, 3 Oct 2018 14:49:11 +0200
Subject: [PATCH] mc_pos_control_params: update jerk params (limits + defaults
 + description)

---
 .../tasks/Utility/ManualSmoothingXY.cpp       |  2 +-
 .../mc_pos_control/mc_pos_control_params.c    | 40 +++++++++++++------
 2 files changed, 28 insertions(+), 14 deletions(-)

diff --git a/src/lib/FlightTasks/tasks/Utility/ManualSmoothingXY.cpp b/src/lib/FlightTasks/tasks/Utility/ManualSmoothingXY.cpp
index d935adc29e..6908afeb13 100644
--- a/src/lib/FlightTasks/tasks/Utility/ManualSmoothingXY.cpp
+++ b/src/lib/FlightTasks/tasks/Utility/ManualSmoothingXY.cpp
@@ -140,7 +140,7 @@ ManualSmoothingXY::_setStateAcceleration(const Vector2f &vel_sp, const Vector2f
 				// very slow at low speed.
 				_jerk_state_dependent = 1e6f; // default
 
-				if (_jerk_max.get() > _jerk_min.get()) {
+				if (_jerk_max.get() > _jerk_min.get() && _jerk_min.get() > FLT_EPSILON) {
 
 					_jerk_state_dependent = math::min((_jerk_max.get() - _jerk_min.get())
 									  / _vel_max * vel.length() + _jerk_min.get(), _jerk_max.get());
diff --git a/src/modules/mc_pos_control/mc_pos_control_params.c b/src/modules/mc_pos_control/mc_pos_control_params.c
index 4f23b1cfa2..60cefbd8d0 100644
--- a/src/modules/mc_pos_control/mc_pos_control_params.c
+++ b/src/modules/mc_pos_control/mc_pos_control_params.c
@@ -483,33 +483,47 @@ PARAM_DEFINE_FLOAT(MPC_ACC_UP_MAX, 10.0f);
 PARAM_DEFINE_FLOAT(MPC_ACC_DOWN_MAX, 10.0f);
 
 /**
- * Maximum jerk in manual controlled mode for BRAKING to zero.
- * If this value is below MPC_JERK_MIN, the acceleration limit in xy and z
- * is MPC_ACC_HOR_MAX and MPC_ACC_UP_MAX respectively instantaneously when the
- * user demands brake (=zero stick input).
- * Otherwise the acceleration limit increases from current acceleration limit
- * towards MPC_ACC_HOR_MAX/MPC_ACC_UP_MAX with jerk limit
+ * Maximum jerk limit
+ *
+ * Limit the maximum jerk of the vehicle (how fast the acceleration can change).
+ * A lower value leads to smoother vehicle motions, but it also limits its
+ * agility (how fast it can change directions or break).
+ *
+ * Setting this to the maximum value essentially disables the limit.
+ *
+ * Note: this is only used when MPC_POS_MODE is set to a smoothing mode.
  *
  * @unit m/s/s/s
- * @min 0.0
- * @max 15.0
+ * @min 0.5
+ * @max 500.0
  * @increment 1
  * @decimal 2
  * @group Multicopter Position Control
  */
-PARAM_DEFINE_FLOAT(MPC_JERK_MAX, 0.0f);
+PARAM_DEFINE_FLOAT(MPC_JERK_MAX, 20.0f);
 
 /**
- * Minimum jerk in manual controlled mode for BRAKING to zero
+ * Velocity-based jerk limit
+ *
+ * If this is not zero, a velocity-based maximum jerk limit is used: the applied
+ * jerk limit linearly increases with the vehicle's velocity between
+ * MPC_JERK_MIN (zero velocity) and MPC_JERK_MAX (maximum velocity).
+ *
+ * This means that the vehicle's motions are smooth for low velocities, but
+ * still allows fast direction changes or breaking at higher velocities.
+ *
+ * Set this to zero to use a fixed maximum jerk limit (MPC_JERK_MAX).
+ *
+ * Note: this is only used when MPC_POS_MODE is set to a smoothing mode.
  *
  * @unit m/s/s/s
- * @min 0.5
- * @max 10.0
+ * @min 0
+ * @max 30.0
  * @increment 1
  * @decimal 2
  * @group Multicopter Position Control
  */
-PARAM_DEFINE_FLOAT(MPC_JERK_MIN, 1.0f);
+PARAM_DEFINE_FLOAT(MPC_JERK_MIN, 8.0f);
 
 /**
  * Altitude control mode.