WSF_ROTORCRAFT_MOVER¶
- mover WSF_ROTORCRAFT_MOVER¶
mover <name> WSF_ROTORCRAFT_MOVER Platform Part Commands ... // Rotorcraft Mover Commands update_interval ... update_time_tolerance ... // Rotorcraft Mover Commands weathercock_speed maximum_attitude_rate maximum_total_acceleration minimum_upward_acceleration body_rates_gain maximum_ground_speed maximum_rate_of_climb maximum_rate_of_descent maximum_impact_speed ... mode <name> // Mode Commands ... end_mode vertical_acceleration_rate_pid ... end_vertical_acceleration_rate_pid vertical_acceleration_value_pid ... end_vertical_acceleration_value_pid lateral_acceleration_rate_pid ... end_lateral_acceleration_rate_pid lateral_acceleration_value_pid ... end_lateral_acceleration_value_pid end_mover
Overview¶
WSF_ROTORCRAFT_MOVER is a Route Mover designed to model rotorcraft motion characteristics. It permits a decoupling of the desired platform heading (body pointing direction) from the velocity vector. At low speed, the platform may assume any desired heading, regardless of direction of translation, but at high speed the heading assumes the direction of flight. Scripted commands to assume a desired orientation or heading (body pointing direction) is taken as a request but may not be immediately honored. The mover will maintain a desired heading angle and, upon slowing to below weathercocking speed, will once again assume the desired heading. Orientation of the platform rotor plane in the North-East-Down frame is canted in the direction of the acceleration vector when accelerating laterally or turning but is horizontal under cruise conditions.
Some terminology discussion is necessary here (see comment at WsfPlatform SetHeading command). Much WSF infrastructure has inadvertently developed that incorrectly refers to Course angles (compass direction of the velocity vector) as Heading. So a scripted request to GoToHeading is actually honored as a request to go to Course. This will continue to be the case even in this WSF_ROTORCRAFT_MOVER type, but because this is the case it does raise ambiguity when commanding this Mover. There are two ways to insert a desired body pointing direction into this Mover type: Platform commands SetHeading() and SetOrientationNED(). Either of these will insert into the WSF_ROTORCRAFT_MOVER a desired true compass pointing angle, one that will be honored when below weathercocking speed. All other “Heading” related functions will match the implementations in the rest of the WSF Movers, and honored as a Course command.
WSF_ROTORCRAFT_MOVER is the first WSF Mover type to implement Mover “Modes”, see Mode Commands below. When a mover mode is changed, either in script or as a result of crossing a waypoint, all motion attributes change to those defined for that motion mode. For example, a script command ‘PLATFORM.Mover().SetMode(“CRUISE”)’ would immediately adopt speed, rates of climb, and acceleration values as predefined in motion mode “CRUISE.” One might define modes appropriate for “HOVER”, “LOITER”, “DASH”, or any other desired mover mode for the Rotorcraft Mover. If the Mode is not defined by the Mover the command is ignored.
Rotorcraft Mover Commands¶
- desired_heading <angle-value>¶
Sets the desired heading for the mover, which will take effect at speeds below the “weathercocking speed.”
- position_hold_capture_radius <length-value>¶
The rotorcraft mover uses a rate guidance mechanism when transiting from one location to another. When approaching a target point, guidance fundamentally changes to capture a position value, and so must decelerate in anticipation of capturing and holding the target position. This value determines the transition point from one guidance type to the other. The default value is set to 200 meters, which should suffice for the vast majority of Rotorcraft models.
- start_mode <mode-name>¶
Specifies the initial mover mode of the platform. The mover mode may be changed externally via script settings or at waypoint transitions. Mover modes are discussed separately.
- ned_filter_time_constant <time-value>¶
Specifies a filter time constant to apply to commanded acceleration values to smooth transient responses. A larger value will apply a greater amount of smoothing to the commands. Value must be greater than zero. The default is 1 second and is adequate for most purposes.
- altitude_error_to_rate_of_climb_gain <floating-point-value>¶
Specifies a gain to apply to an altitude error to arrive at a vertical acceleration value. The default is 1 and is adequate for most purposes.
- vertical_acceleration_rate_pid … end_vertical_acceleration_rate_pid¶
- vertical_acceleration_value_pid … end_vertical_acceleration_value_pid¶
- lateral_acceleration_rate_pid … end_lateral_acceleration_rate_pid¶
- lateral_acceleration_value_pid … end_lateral_acceleration_value_pid¶
Each of the above four input blocks may contain tuning parameters to apply to the Proportional Integral Derivative (PID) controllers, which determine acceleration values which drive the motion state of the platform. It is not necessary for the end-user to modify the default gains, unless a particular dynamic response is required. Tuning PID controllers is outside the scope of this document, but many separate resources are available to assist. PID controller response should be adequate for most purposes.
See PID Controller Commands for valid commands.
Mode Commands¶
- mode … end_mode¶
- weathercock_speed <speed_value>¶
Ground speed above which the platform will assume a heading that matches the course angle. Below this speed, the platform will assume a desired heading angle, as set by script commands.
- maximum_attitude_rate <angular_rate_value>¶
Maximum angular rate for body attitude changes. This is primarily used in concert with weathercock_speed to determine how quickly the platform will transition in and out of weathercocking mode.
- maximum_total_acceleration <acceleration_value>¶
Maximum magnitude of linear acceleration. Sets the upper limit during hard lateral accelerations.
- minimum_upward_acceleration <acceleration_value>¶
Minimum upward acceleration value. When aircraft is rising, and then a command is given to descend quickly, this value sets the minimum vertical acceleration constraint. Note that many rotorcraft with teetering rotor heads are not permitted to pull negative g, by design.
- body_rates_gain <floating_point_value>¶
Gain to apply to an angular heading error to obtain the rate at which the heading error is removed. Used primarily in removing a heading error when transitioning to fast forward flight, above weathercock speed.
- maximum_ground_speed <speed_value>¶
Maximum permitted ground speed in this motion mode. Typical use would be for <mode> speed constraint.
- maximum_rate_of_climb <speed_value>¶
Maximum permitted rate of climb in this motion mode. Typical use would be to set a realistic climb rate for <mode>.
- maximum_rate_of_descent <speed_value>¶
Magnitude of maximum permitted rate of descent in this motion mode. Value must be greater than zero but will be negated when applied. Typical use would be to set a realistic descent rate for <mode>.
PID Controller Commands¶
- proportional_gain <floating_point_value>¶
Gain to apply to current error to attempt to null the error to zero. Larger values will more forcibly attempt to null the error but are prone to induce oscillation in the output.
- derivative_gain <floating_point_value>¶
Gain to apply to current rate-of-change of error to attempt to prevent the error from overshooting the desired target value. Larger values will oppose any change in the output, causing drift.
- integral_gain <floating_point_value>¶
Gain to oppose a steady-state bias, which attempts to drive the bias to zero.
- input_threshold <floating_point_value>¶
Comparison value to determine whether to apply integral summing of the input error sample. While the input value differs more than <input_threshold> from the target value no input integration is performed. Once the input threshold is near the target value, a continuous integration is performed to discern and react to an input bias. If so, integral_gain is applied to the bias to remove it over time.
