Navigation Parameters
Controllers
Determine the file location of the parameter
The parameters related to the controller, can be found here:
/opt/onav/<onav_version>/app/autonomy/params/<platform_type>/navigation/controls_general.yaml
/opt/onav/<onav_version>/app/autonomy/params/<platform_type>/navigation/mpc_controller.yaml
/opt/onav/<onav_version>/app/autonomy/params/<platform_type>/navigation/mpc_dock_controller.yaml
If they are not listed in the above file, it is because they are using the default values and are not being overwritten.
MPC Controller
MBF Plugins
Currently we have implemented a Move-Base Flex controller plugin named: OnavMbfMpcController
Two instances of this plugin are loaded at runtime by our navigation node (as seen in the table below). The parameters are equivalent for each instance of the plugin but the values of certain of these parameters are different.
| Controller name | Description |
|---|---|
mpc_controller | The controller used during normal navigation and applies to tracking the paths generated between all the mission waypoints. |
mpc_dock_controller | The controller used during docking and applies only to tracking the dock and undock paths. |
MPC State Machine
The MPC controller operates as a state machine that contains the following states:
| MPC State | Description | Condition |
|---|---|---|
DEFAULT | Standard tracking behavior. | Will revert to this state if none of the other state conditions are met. |
GOAL | Tracking behavior as the UGV approaches the goal. | Will enter GOAL mode when the goal_horizon_threshold parameter distance to the goal has been reached. |
PRECISE | State when more precision is required in the tracking. | At the start of the path, we begin in Precise mode to ensure that we have a good start to tracking. |
RESCUE | State to rescue the tracker when the UGV is stuck. | Will enter RESCUE mode when UGV is appraching a condition that make it stuck. |
HYSTERESIS | State when you the UGV requires compensation for tire flexion. | Will enter HYSTERESIS mode when the UGV detects that it will begin oscillating due to tire deformation. |
CORNER | State when there is a curve or a corner ahead. | Will enter CORNER mode when the UGV approaches, within a corner_lookahead parameter distance, to a corner with at least corner_detection_threshold of a curvature. |
Default State Parameters
The following list defines the default parameters that the MPC controller uses. For the most part, they apply to all states of the MPC controller.
| Parameter | Description | Namespace | SI Units |
|---|---|---|---|
vehicle_length | The length (longitudinally) of the UGV. | /navigation/<controller>/path_tracker | m |
mpc_horizon | The prediction horizon of the MPC. | /navigation/<controller>/path_tracker | s |
max_lookahead | Maximum distance along the path we seek to follow. Affects how far we do collision checks as well as the maximum velocity of the UGV. | /navigation/<controller>/path_tracker | m |
min_lookahead | Minimum distance along the path we seek to follow. Affects how far we do collision checks as well as the maximum velocity of the UGV. | /navigation/<controller>/path_tracker | m |
lookahead_smoother | Factor between 0 and 1 that determines the smoothness of the change in lookahead distance: 0 means only maximum velocity is used to determine the horizon (can be jumpy but speeds up the UGV faster); 1 means only averaged planned velocity is used to determine the horizon (smoother but speeds up the UGV slowly). | /navigation/<controller>/path_tracker | -- |
lookahead_factor | How aggressively do we want to increase the lookahead from min_lookahead to max_lookahead | /navigation/<controller>/path_tracker | -- |
mpc_opt_maxiteration | The maximum number of iterations that the solver will run. Increase this value for better performance, decrease for shorter computation time. | /navigation/<controller>/path_tracker | -- |
discretization_steps | Number of grid points along the MPC prediction; Lower: less accuracy, but faster | /navigation/<controller>/path_tracker | -- |
max_fwd_velocity | The maximum allowable linear velocity that the MPC controller can compute. | /navigation/<controller>/path_tracker | m/s |
min_fwd_velocity | The minimum allowable linear velocity, in any mode, that the MPC controller can compute. This can be used to overcome the different deadbands that different UGVs may have. | /navigation/<controller>/path_tracker | m/s |
max_rev_velocity | The maximum allowable reverse linear velocity (ie. positive value), in any mode, that the MPC controller can compute. By default this is set to the max_fwd_velocity, so only needed if your maximum linear reverse velocity is different than the forward linear velocity. | /navigation/<controller>/path_tracker | m/s |
max_ang_velocity | The maximum allowable angular velocity, in any mode, that the MPC controller can compute. This parameter bounds both positive and negative angular velocities. | /navigation/<controller>/path_tracker | rad/s |
max_accel | The maximum allowable linear acceleration, in normal navigation mode, that the MPC controller can compute. | /navigation/<controller>/path_tracker | m/s/s |
max_decel | The maximum allowable linear deceleration (ie. negative value), in any mode, that the MPC controller can compute. | /navigation/<controller>/path_tracker | m/s/s |
max_ang_accel | The maximum allowable angular acceleration, in any mode, that the MPC controller can compute. This parameter bounds both positive and negative angular accelerations. | /navigation/<controller>/path_tracker | rad/s/s |
max_lateral_accel | The maximum allowable lateral acceleration, in any mode, that the MPC controller can compute. This parameter bounds both positive and negative lateral accelerations. | /navigation/<controller>/path_tracker | m/s/s |
stiction_compensator_fwd | The minimum linear velocity for movement of the UGV. This should typically be the minimum linear velocity that the UGV requires for it to move. | /navigation/<controller>/path_tracker | m/s |
stiction_compensator_yaw | The minimum angular velocity for movement of the UGV. This should typically be the minimum angular velocity that the UGV requires for it to move. | /navigation/<controller>/path_tracker | m/s |
x_weight | Weight for state x in MPC cost function, in the MPC state: DEFAULT. | /navigation/<controller>/path_tracker | -- |
y_weight | Weight for state y in MPC cost function, in the MPC state: DEFAULT. | /navigation/<controller>/path_tracker | -- |
yaw_weight | Weight for state yaw in MPC cost function, in the MPC state: DEFAULT. | /navigation/<controller>/path_tracker | -- |
fwd_v_weight | Weight for state ẋ (forward velocity) in MPC cost function, in the MPC state: DEFAULT. | /navigation/<controller>/path_tracker | -- |
yaw_d_weight | Weight for state (yaw velocity) in MPC cost function, in the MPC state: DEFAULT. | /navigation/<controller>/path_tracker | -- |
fwd_a_weight | Weight for state ẍ (forward acceleration) in MPC cost function, in the MPC state: DEFAULT. | /navigation/<controller>/path_tracker | -- |
yaw_a_weight | Weight for state (yaw acceleration) in MPC cost function, in the MPC state: DEFAULT. | /navigation/<controller>/path_tracker | -- |
horizon_percent_change | The percentage factor used when shortening the MPC horizon. This will affect how quickly we want to speed up after a curvature slowdown. | /navigation/<controller>/path_tracker | -- |
error_slowdown_multiplier | The amount by which to increase the MPC horizon based on the crosstrack and/or heading error. This should be greater than 1.0 since increasing the MPC horizon will decrease the maximum MPC velocity. ** Less than 1.0 will result in the opposite behaviour which is not the expected behaviour for this parameter. | /navigation/<controller>/path_tracker | -- |
crosstrackerror_slowdown | Threshold on the amount of crosstrack error, above which to a slowdown the UGV. | /navigation/<controller>/path_tracker | |
headingerror_slowdown | Threshold on the amount of heading error, above which to a slowdown the UGV. | /navigation/<controller>/path_tracker | |
curvature_slowdown | Threshold on the path curvature, above which to a slowdown the UGV. | /navigation/<controller>/path_tracker | |
endpoint_multiplier | Weight multiplier of the very last point along the local plan segment in MPC state: DEFAULT. This value ensures convergence/stability of the optimizer by mimicking the MPCs infinite horizon by applying a terminal cost. | /navigation/<controller>/path_tracker | -- |
shrinking_horizon_min | The minimum horizon that will be used in the computation. This value will prevent the horizon from dropping below this value during all the horizon adjustments. | /navigation/<controller>/path_tracker | s |
crosstrack_tolerance | The amount of lateral error that the controller will handle before stopping the UGV and replanning a new path. | /navigation/<controller>/path_tracker | m |
reference_trajectory_factor | A factor that will skew the path parameter. This value should be between 0 and 1. Values closer to 0.0 will skew the path param closer to the UGV, decreasing speed but increasing the accuracy of the path tracking, and vice versa as you approach 1.0. | /navigation/<controller>/path_tracker | m |
Goal State Parameters
The following parameters can be modified to tune the controller as it approaches the goal point as well as its behavior around the goal point.
| Parameter | Description | Namespace | SI Units |
|---|---|---|---|
goal_horizon_threshold | The distance from the goal point which the MPC state will switch into state: GOAL , and begin reducing the horizon accordingly. | /navigation/<controller>/path_tracker | m |
goal_slowdown_multiplier | The multiplier by which to increase the MPC horizon during the MPCs GOAL state in order to slow the UGV down from its top speed. This value should be greater than 1.0. | /navigation/<controller>/path_tracker | |
max_speed_at_goal | The maximum allowable speed at the goal point for the controller to stop and consider the goal complete. On OEM UGVs, this value should be increased. | /navigation/<controller>/path_tracker | m/s |
x_weight_goal | Weight for state x in MPC cost function, in the MPC state: GOAL. | /navigation/<controller>/path_tracker | |
y_weight_goal | Weight for state y in MPC cost function, in the MPC state: GOAL. | /navigation/<controller>/path_tracker | |
yaw_weight_goal | Weight for state yaw in MPC cost function, in the MPC state: GOAL. | /navigation/<controller>/path_tracker | |
fwd_v_weight_goal | Weight for state ẋ (forward velocity) in MPC cost function, in the MPC state: GOAL. | /navigation/<controller>/path_tracker | |
yaw_d_weight_goal | Weight for state (yaw velocity) in MPC cost function, in the MPC state: GOAL. | /navigation/<controller>/path_tracker | |
fwd_a_weight_goal | Weight for state ẍ (forward acceleration) in MPC cost function, in the MPC state: GOAL. | /navigation/<controller>/path_tracker | |
yaw_a_weight_goal | Weight for state (yaw acceleration) in MPC cost function, in the MPC state: GOAL. | /navigation/<controller>/path_tracker | |
endpoint_multiplier_goal | Weight multiplier of the very last point along the local plan segment in MPC state: GOAL. This value ensures convergence/stability of the optimizer by mimicking the MPCs infinite horizon by applying a terminal cost. | /navigation/<controller>/path_tracker | |
goal_tolerance_xy_rtk | The (x, y) tolerance value (ie. radius) assigned to a goal, when RTK is enabled, in order to determine whether or not to consider the goal complete. | /navigation/<controller>/path_tracker | m |
goal_tolerance_yaw_rtk | The yaw tolerance value (ie. heading) assigned to a goal, when RTK is enabled, in order to determine whether or not to consider the goal complete. | /navigation/<controller>/path_tracker | rad |
goal_tolerance_xy_nortk | The (x, y) tolerance value (ie. radius) assigned to a goal, when RTK is disabled, in order to determine whether or not to consider the goal complete. | /navigation/<controller>/path_tracker | m |
goal_tolerance_yaw_nortk | The yaw tolerance value (ie. heading) assigned to a goal, when RTK is disabled, in order to determine whether or not to consider the goal complete. | /navigation/<controller>/path_tracker | rad |
Corner State Parameters
The following parameters can be modified to tune the behavior of the controller during and as it as it approaches corners.
| Parameter | Description | Namespace | SI Units |
|---|---|---|---|
corner_segment_slowdown | Flag to enable/disable the slowdown behaviour in MPC state: CORNER | /navigation/<controller>/path_tracker | bool |
corner_lookahead | The distance on the reference path from the UGVs current location, along which to determine if a corner is present. If a corner is present the MPC state will switch to CORNER state and begin reducing the horizon accordingly. | /navigation/<controller>/path_tracker | m |
corner_detection_threshold | Threshold on the path curvature, between the UGVs current location and the end of the corner_lookahead distance, above which to switch the MPC in state: CORNER, and begin reducing the horizon accordingly. | /navigation/<controller>/path_tracker | rad |
corner_slowdown_multiplier | The multiplier by which to increase the MPC horizon during the MPCs CORNER state in order to slow the UGV down from its top speed. This value should be greater than 1.0. | /navigation/<controller>/path_tracker | -- |
endpoint_multiplier_corner | Weight multiplier of the very last point along the local plan segment in MPC state: CORNER. This value ensures convergence/stability of the optimizer by mimicking the MPCs infinite horizon by applying a terminal cost. | /navigation/<controller>/path_tracker | -- |
OEM Specific Parameters
When tuning the controller on a third-party OEM UGV, there are several other considerations that we will not have taken into account during the tuning of our UGVs. Below, we define parameters that may be modified to tune the controller for your third-party OEM UGV.
UGV Dynamics
The following parameters can be used to modify the dynamics model that the contrller uses to compute command velocities.
| Parameter | Description | Namespace | SI Units |
|---|---|---|---|
no_turn_on_spot_motion | Flag to enable/disable turn on spot motion. By default, the MPC motion model is represented by a differential drive kinematics. This parameter will modify the MPC motion model to remove turn in place motions and bias the motion in the forward direction. | /navigation/<controller>/path_tracker | - |
min_fwd_turn | /navigation/<controller>/path_tracker | -- | |
pivot_point_offset_x | The longitudinal offset that can be applied to the MPC model in order to account for a particular UGVs center of rotation | /navigation/<controller>/path_tracker | - |
pivot_point_offset_y | The lateral offset that can be applied to the MPC model in order to account for a particular UGVs center of rotation | /navigation/<controller>/path_tracker | - |
min_fwd_turn | /navigation/<controller>/path_tracker | -- |
Delay Compensation
The following parameters can be used to compensate for any delays that are present in the system.
| Parameter | Description | Namespace | SI Units |
|---|---|---|---|
enable_delay_compensation | A boolean flag to enable/disable the delay compensation feature. The delay compensation feature is used to compensate for low-level dynamics delays that may be present in the UGV to be controlled. The user can apply an input controller delay and the feature will compute command velocities that compensate for such a delay. | /navigation/<controller>/path_tracker | bool |
controller_delay | The amount of controller delay that the delay compensation feature will attempt to compensate for, in ms. | /navigation/<controller>/path_tracker | ms |
Stop Distance
The following parameters can be used to set a specific stop distance away from obstacles.
| Parameter | Description | Namespace | SI Units |
|---|---|---|---|
enable_stop_distance | A flag to use enable/disable the stop distance feature. The stop distance feature forces the UGV to stop a specified distance in front of obstacles. | /navigation/<controller>/path_tracker | bool |
obstacle_stop_distance | The distance at which the UGV will stop in front of a detected obstacle. | /navigation/<controller>/path_tracker | m |
Path Planners
Information incoming in release 0.9. Please contact Clearpath customer support at support@clearpathrobotics.com to discuss the issue.