---

name: control-simulation description: "Operate gym-pybullet-drones headless or GUI control-simulation workflows for PID tracking, velocity control, downwash, and MRAC." disable-model-invocation: true metadata: disco-role: operating license: MIT

Control Simulation

Use this sub-skill when a task asks how to run, modify, or debug classic control simulations in gym-pybullet-drones: PID trajectory tracking, velocity-command control, downwash physics, MRAC hover/control, logger output, or PyBullet GUI/headless behavior.

Route here for

• Running the bundled control example runner for pid, pid_velocity, downwash, or mrac with short headless smoke defaults.
• Building custom loops with BaseAviary, CtrlAviary, VelocityAviary, BaseControl, DSLPIDControl, MRACControl, or CTBRControl.
• Choosing DroneModel and Physics values for control examples, including downwash-specific physics.
• Inspecting Logger outputs, sync(...) behavior, PyBullet client/drone IDs, action shapes, and frequency constraints.
• Troubleshooting pybullet, display/OpenGL, logger, action-shape, MRAC model, or timing-mismatch failures in control simulations.

Do not handle here

• Reinforcement-learning training, PPO playback, learn.py, play.py, BaseRLAviary, HoverAviary, or MultiHoverAviary; route back to the repo skill or the RL sub-skill when available.
• Betaflight SITL, BetaAviary, external Betaflight checkout/builds, UDP port setup, or beta.py; route back to the repo skill or the SITL sub-skill when available.
• Broad package installation policy beyond the control-specific pybullet/GUI/logger symptoms in this sub-skill.

Start here

1. Read workflows to choose the bundled runner mode and understand how each source control workflow was wrapped.
2. Use API reference for constructor signatures, action/observation shapes, controller signatures, enum values, logger arrays, and installed-package facts.
3. Use troubleshooting before changing physics, controller code, or dependency versions.
4. Prefer the bundled runner over the original repository example scripts:

python scripts/run_control_example.py pid --duration-sec 1 --output-folder /tmp/gpd-pid
python scripts/run_control_example.py pid_velocity --duration-sec 1 --output-folder /tmp/gpd-vel
python scripts/run_control_example.py downwash --duration-sec 1 --output-folder /tmp/gpd-dw
python scripts/run_control_example.py mrac --duration-sec 1 --output-folder /tmp/gpd-mrac

The runner defaults to gui=False, plot=False, record_video=False, and short durations so it is safe for headless smoke checks. Add --gui, --plot, --record-video, --csv, or longer --duration-sec only after the environment supports them.

Runtime guardrails

• CtrlAviary and VelocityAviary share the BaseAviary constructor shape and can run headless with gui=False.
• BaseAviary requires pyb_freq % ctrl_freq == 0; the bundled runner validates this before constructing the environment.
• CtrlAviary.step(action) expects motor RPM actions shaped (num_drones, 4); VelocityAviary.step(action) expects velocity commands shaped (num_drones, 4) with [vx, vy, vz, speed_fraction].
• DSLPIDControl is for DroneModel.CF2X or DroneModel.CF2P; MRACControl supports the current CF2X, CF2P, and RACE drone models.
• Logger.log(...) accepts one 20-value state snapshot and one 12-value control target per drone; use its saved arrays or optional CSV export to inspect runs.