Custom Gait
Custom Gait is Choreography Move that behaves like a gait that can be greatly customized in its appearance and can be actively steered during operation (e.g. via a joystick). It can represent any gait pattern that has one or two steps per gait cycle for each leg.
Behavior Within a Sequence
Custom Gait is integrated as a legs-track move within the Choreography API. It can therefore be combined with other moves that occupy the body, arm, gripper, and lights tracks. The Custom Gait move can be adjusted to occupy any number of slices within the timeline, however the sequence clock will not advance normally while Custom Gait is executing. Instead, the section of the sequence occupied by Custom Gait will represent one gait cycle (duration set by the cycle_duration parameter). This portion of the sequence, including moves in other tracks, will loop until Custom Gait is commanded to stop. This behavior is denoted by the black repeat symbols in the timeline view within Choreographer and will be reflected by the red cursor during execution.
This means that Body and Arm-track moves will result in a cyclic motion phase-locked to Custom Gait, providing further options for customizing the appearance of the behavior. It is not possible for other moves to span the beginning or end of Custom Gait within the timeline.
Driving Custom Gait
CustomGait responds to the ChoreographyCommand RPC. When operating through Choreographer with an attached XBox controller, steering commands will be sent based on joystick position (left joystick for translation, right for turning), and the d-pad down button will command Custom Gait to stop, allowing the sequence to proceed. Steering commands will be scaled by the CustomGaitCommandLimits message returned as part of the ChoreographyStatus RPC. Those will generally be the values specified for max_velocity and max_yaw_rate in the parameters, but may be limited based on a determination of what that gait pattern is capable of.
The custom gait move can also be driven through the tablet’s choreography drive screen using the tablet’s joysticks. See Tablet Choreography Mode for further details on playing choreography sequences through the tablet.
Gait Diagram
A Hildebrand-style gait diagram (see wikipedia is provided for Custom Gait as currently configured in the left panel of the Move Configuration tab in Choreographer. For each foot in the diagram (FL, FR, HL, HR), black regions of the diagram indicate periods of time when a foot is in contact with the ground, and white regions indicate periods of time when a foot is in the air. The phase sliders control the beginning and end of the white region. Some types of configuration errors will be indicated in red on the diagram.
Presets
Several preset gait patterns are provided in a pulldown menu where the “Reset to Default Parameters” button is for most moves. Select the desired preset, then click the “Apply” button. Note that presets only modify a subset of parameters. Presets with the prefix “gait” will only impact cycle_duration and phase parameters.
Animated Custom Gaits
Custom Gait can also be defined using animation data as input, which the controller will then seek to imitate.
If you create a valid .cha file with a Spot gait cycle (See section Valid CHA for custom gait cycles) you can then load it in Choreographer and choose that file as the basis for Custom Gait by clicking Show animated cycle params on a Custom Gait Move and picking the animation from the Animation name dropdown. The rest of the Animated Cycle section contains a number of checkboxes and sliders to enable/disable various components of the input animation and to make small adjustments to offsets and amplitude (See each parameter’s help text in Choreographer for more details). Enabling all checkboxes and leaving the sliders at their default values will make the Custom Gait controller do its best to match the input animation. However, be aware that most of the same limitations apply as if the gait was defined by sliders (e.g. duty cycle, body offset limits, and cycle duration).
A current limitation is that while animations can have 2 swing phases for each leg, only the 1st swing can currently be used for swing-xy motion from animation.
Valid CHA for custom gait cycles
See Animation File Specification for details about the CHA format and Animations In Choreographer for a high-level overview. Beyond that, a valid CHA file to use with custom gait requires the following:
The CHA file needs to have the
custom_gait_cycleoption set in the header.
NB: CHA files with thecustom_gait_cycleoption does NOT show up in theAnimationsection of the Choreographer library. It will instead show up in theanimated_cycle_params.animation_namedrop down menu of a CustomGait move.each foot must lift off and touch down at least once, but no more than twice
the first and last keyframe should match with the exception of base translate x, in case the animation moves forward.
unlike other cha files, it is valid for feet to be in the air at the first and last frame, which allows for swings to cross the transition point of the custom gait loop
the robot can be either translating forward or stepping in place with feet sliding backwards during the animated gait cycle cha, but for the best result the animation should be meant to translate at a constant velocity
Some swing data still can not be pulled from the cha, so you may still need to adjust swing velocities and velocity limits…”, “
Tips for Configuring Custom Gait
Fast stepping is often easier than slow stepping, especially when fewer feet are on the ground. Try starting with a faster
cycle_duration, then gradually increasing that value to slow the cadence to your preferred speed. Exact value will depend on gait pattern, especially the duty factor, butcycle_duration = 0.6 secondsor even faster may be required from some patterns.Swing Duration is
(touchdown_phase - liftoff_phase * cycle_duration).Individual swings shorter than 250 ms will make it difficult to operate off of flat ground.
Individual swings shorter than 150 ms will make it difficult to move quickly, even on flat ground.
Individual swings shorter than 60 ms will make it difficult to balance, even in place.
The maximum duration both front or both hind feet can be off the ground simultaneously is about 300ms.
The maximum duration both left or both right feet can be off the ground simultaneously is about 500ms.
The maximum duration a diagonal pair of feet can be off the ground simultaneously is about 800ms.
The “duty factor” is the fraction of the time that a foot is on the ground.
The average duty factor of either the two front legs or the two hind legs should be at least 30%. Increasing duty factor will generally improve stability (with decreasing returns after 65%).
More challenging gaits may only work well at low speeds and/or low accelerations. Consider lowering the speed limits using the
max_velocityandmax_yaw_ratesliders and lowering the acceleration limit with theacceleration_scalingslider during initial testing.
Parameter Reference
| Parameter | Effect |
|---|---|
| cycle_duration | The duration (s) of a full gait cycle. |
| liftoff_phase | When within the gait cycle a particular leg lifts off the ground. |
| touchdown_phase | When within the gait cycle a particular leg steps onto the ground. |
| two_LEG_swings | Determines whether that particular leg will have two steps within the gait cycle. If active, a second set of liftoff_phase and touchdown_phase must be specified. |
| max_velocity | The maximum translational velocity (m/s) command that will be accepted. |
| max_yaw_rate | The maximum turn rate (rad/s) command that will be accepted. |
| acceleration_scaling | How much to limit steering acceleration. 1 is normal. Smaller is less acceleration. |
| com_height | Height (m) of the Center-of-Mass above the ground. |
| body_translation_offset | Horizontal offset (m) of the Center-of-Mass from a neutral posture. (x-forward, y-left). This is a constant offset that is additive with any phase-dependent offset specified in a Body-track move. |
| body_rotation_offset | Orientation offset (rad) from a neutral posture. This is a constant offset that is additive with any phase-dependent offset specified in a Body-track move. |
| low_speed_body_fraction | How much to scale down the body motion when navigating at low speeds. |
| stance_shape | The relative position of the feet when they are on the ground. |
| stance_shape.length | Distance (m) between front and hind feet. |
| stance_shape.width | Distance (m) between left and right feet. |
| stance_shape.front_wider_than_hind | Difference (m) between the FL<-->FR distance and the HL<-->HR distance. Positive means front feet are wider. |
| stance_shape.left_longer_than_right | Difference (m) between the FL<-->HL distance and the FR<-->HR distance. Positive means the left feet are farther apart. |
| stance_shape.left_forward_of_right | Distance (m) to shift the FL and HL feet forward relative to the FR and HR feet. Negative means shifted backwards. |
| general_swing_params | Swing parameters that apply to all legs not configured to use leg-specific swing parameters. |
| use_LEG_swing_params | Configures a particular leg to use leg-specific swing parameters rather than the general set. |
| LEG_swing_params | Swing parameters used by a particular leg if configured to use leg-specific swing parameters. |
| SwingParams.height | How high (m) to lift the foot. Request may not be achievable due to configured vertical_speed, vertical_acceleration, and swing duration. |
| SwingParams.liftoff_speed | How fast (m/s) to start lifting the foot at the moment of liftoff. |
| SwingParams.vertical_speed | How fast (m/s) to lift and lower the foot. |
| SwingParams.vertical_acceleration | How fast to accelerate (m/s/s) the foot vertically to achieve the configured vertical_speed. |
| SwingParams.overlay_outside | How far (m) to swing the foot to the outside (negative for inside) relative to a straight-line step. |
| SwingParams.overlay_forward | How far (m) to swing the foot forward (negative for backward) relative to a straight-line step. |
| SwingParams.low_speed_fraction | How much to reduce the swing parameters when navigating at low speed. |
| mu | Estimated coefficient of friction between the ground and the feet. Setting this accurately will improve reliability. |
| timing_stiffness | How much the robot is allowed to deviate from the specified timing. 0 means no deviation. Otherwise, large values mean less deviation and small values mean more is acceptable. Too much timing adjustment (low, non-zero values) may make the gait unstable. At least a little timing adjustment is recommended for gaits with flight phases (periods with 0 feet on the ground). |
| step_position_stiffness | How much the robot is allowed to deviate from the specified stance shape. 0 means no deviation. Otherwise: large values mean less deviation and small values mean more is acceptable. Too much position adjustment (low, non-zero values) may make the gait unstable. |
| enable_perception_obstacle_avoidance | If enabled, CustomGait will attempt to avoid obstacles. More challenging gaits may require significant obstacle avoidance padding to reliably avoid collisions. |
| obstacle_avoidance_padding | How far (m) to stay away from obstacles. More challenging gaits may require significant padding to reliably avoid collisions. |
| enable_perception_terrain_height | If enabled, will use perception to determine the shape of the terrain. Can be disabled if operating on a flat floor. |
| enable_perception_step_placement | If enabled, will use perception to determine good vs bad locations to step. Can be disabled if operating on a flat floor. |
| maximum_stumble_distance | If Spot stumbles more than this distance (m), it will give up and freeze. |
| stand_in_place | Stand rather than stepping in place when not moving. |
| standard_final_stance | Go back to a standard rectangular stance when ending the gait. Otherwise maintains the customized stance shape. |
| trip_sensitivity | How sensitive we should be to trip detection. On the range [0, 1], where 1 is normal sensitivity and 0 is ignoring all trips. Useful for very aggressive gaits or when a costume is restricting leg motion. |
| animated_cycle_params.animation_name | Name of animation gait cycle file to use for extracting parameters. This list only shows CHA files that include the option: 'custom_gait_cycle'. |
| animated_cycle_params.enable_animation_duration | Use cycle duration from the animated gait cycle. This will overwrite the parameter: \n'Cycle duration'. |
| animated_cycle_params.enable_leg_timing | Use leg timing from the animated gait cycle. This will overwrite all swing parameters: \n['Fl swing', 'two fl swing', 'fr swing', 'two fr swing', 'hl swing', 'two hl swing', 'hr swing', 'two hr swing']. |
| animated_cycle_params.enable_stance_shape | Use stance shape from the animated gait cycle. This will overwrite all Stance Shape parameters: \n['length', 'width', 'front wider than hind', 'left longer than right', 'left forward of right']. |
| animated_cycle_params.enable_body_offset | The body offset refers to the offset from the nominal standing posture to the average of the animated position and orientation of the body. |
| animated_cycle_params.enable_body_motion | The body motion refers to the cyclic part of the body animation relative to the average body posture of the animation. |
| animated_cycle_params.enable_swing_xy | Use XY swing trajectories from the animated custom gait cycle. This will override the swing overlay sliders, both in General swing params, and those specific to each leg. |
| animated_cycle_params.body_x_multiplier | Multiplier for body animation on translational x in body frame. |
| animated_cycle_params.body_y_multiplier | Multiplier for body animation on translational y in body frame. |
| animated_cycle_params.body_z_multiplier | Multiplier for body animation on translational z in body frame. |
| animated_cycle_params.body_roll_multiplier | Multiplier for body animation on roll. |
| animated_cycle_params.body_pitch_multiplier | Multiplier for body animation on pitch. |
| animated_cycle_params.body_yaw_multiplier | Multiplier for body animation on yaw. |