Bhuvanesh Aerospace Controls

bhuvanesh is a small, dependency-free Python library for learning and prototyping drone flight-control loops. It provides a bounded PID controller, an X-frame quadrotor attitude mixer, and deterministic roll and three-axis attitude simulators with CSV telemetry. Every demo identifies the project as Bhuvanesh Aerospace Controls.

Safety notice: This software is not flight-certified and is just a simulation; it is not intended to be connected directly to an operational aircraft.

A real flight-control system requires additional safety-critical components, including sensor validation, unit calibration, actuator checks, arming and disarming logic, watchdogs, failsafes, fault handling, hardware-in-the-loop testing, and vehicle-specific verification.

Install on Ubuntu

# Run these commands from the folder containing pyproject.toml.
cd /path/to/bhuvanesh-aerospace-controls
sudo apt update
sudo apt install -y python3 python3-venv python3-pip
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
python -m pytest

If Ubuntu reports that ensurepip is unavailable, install the venv package matching your Python minor version, then retry the venv command:

sudo apt install -y "python$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')-venv"
python3 -m venv .venv

Quick start

from bhuvanesh import Attitude, QuadrotorPID

controller = QuadrotorPID()
result = controller.update(
    target=Attitude(roll=5.0),
    measured=Attitude(roll=2.0),
    throttle=0.50,
    dt=0.01,
)
print(result.motors.as_tuple())

Run the included smoke demo:

python -m bhuvanesh.cli --roll 5 --throttle 0.5
# or, after installation:
bhuvanesh-demo --roll 5 --throttle 0.5

The PID output is bounded, integral windup is limited, and derivative action is based on measured motion to avoid a setpoint kick. Motor commands are normalized from 0 to 1.

Learn with the simulator

Run a 10-second roll step and print response metrics:

python -m bhuvanesh.simulation --target-roll 10 --seconds 10

Change the gains and add a constant wind disturbance:

python -m bhuvanesh.simulation --target-roll 10 --kp 0.12 --ki 0.02 --kd 0.04 --wind 3

Save telemetry for plotting in a spreadsheet or notebook:

python -m bhuvanesh.simulation --csv telemetry.csv

Graph simulation results

Install the optional plotting dependency and export a publication-ready PNG from either simulator:

python -m pip install 'bhuvanesh-aerospace-controls[plotting]'
python - <<'PY'
from bhuvanesh import plot_roll, simulate_roll

plot_roll(simulate_roll(), "roll-response.png")
PY

For three-axis results, use plot_attitude(simulate_attitude(), "attitude-response.png"). Plotting is optional; the controller and simulators remain dependency-free.

The simulator models rotational motion with three simple terms:

acceleration = (control × max_acceleration) + wind - (damping × roll_rate)
roll_rate    = roll_rate + acceleration × dt
roll         = roll + roll_rate × dt

At each timestep the PID sees the current roll, computes a correction, and the quadrotor mixer turns that correction into four normalized motor commands. This is an educational model, not a flight-certified physics engine.

Simulate roll, pitch, and yaw together

Version 0.4 adds a three-axis attitude simulator that reports both requested PID corrections and the control actually available after motor saturation:

bhuvanesh-attitude --roll 10 --pitch -5 --yaw 15 --seconds 12

Add independent angular disturbances and export all axis telemetry:

bhuvanesh-attitude --roll 10 --pitch -5 --yaw 15 \
  --roll-wind 2 --pitch-wind -1 --yaw-wind 0.5 \
  --csv attitude-telemetry.csv

The Python API exposes AttitudeSimulationConfig, simulate_attitude, response metrics, per-axis settling times, and CSV export. The simulator remains an educational control-loop model and does not model aerodynamics or rigid-body axis coupling.

Windows and macOS

The package is pure Python and uses the same commands on Windows and macOS.

Windows PowerShell:

py -m venv .venv
.venv\Scripts\Activate.ps1
py -m pip install bhuvanesh-aerospace-controls
py -m bhuvanesh --roll 5 --throttle 0.5

macOS Terminal:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install bhuvanesh-aerospace-controls
python3 -m bhuvanesh --roll 5 --throttle 0.5