Metadata-Version: 2.4
Name: bhuvanesh-aerospace-controls
Version: 0.5.0
Summary: Bhuvanesh Aerospace Controls: PID tools and attitude simulation for drone students.
Author: Bhuvanesh
License-Expression: MIT
Keywords: aerospace,drone,quadrotor,pid,flight-control
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Provides-Extra: plotting
Requires-Dist: matplotlib>=3.8; extra == "plotting"
Provides-Extra: all
Requires-Dist: matplotlib>=3.8; extra == "all"
Dynamic: license-file

# 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

```bash
# 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:

```bash
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

```python
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:

```bash
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:

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

Change the gains and add a constant wind disturbance:

```bash
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:

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

### Graph simulation results

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

```bash
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:

```text
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:

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

Add independent angular disturbances and export all axis telemetry:

```bash
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:

```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:

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