pid-tuner 0.1.2

FPV PID Tuner CLI tools

pid-tuner

🛠️ FPV PID Tuner — A professional CLI toolkit for analyzing and tuning PID on FPV drones. Plot gyro vs. PID outputs, zoom in on D‑term spikes, compare flight logs, and get data‑driven tuning suggestions.

---

🔍 Features

• Summary: runtime, total spikes, spike rate, avg & max |D‑term|, and avg throttle at spike times.
• Plot: gyro vs. PID output curves; zoomed views of D‑term spikes; optional throttle overlay.
• Spikes: detect, filter, page through spike events; export CSVs for detailed analysis.
• Future: compare multiple logs side‑by‑side; automated tuning recommendations; Betaflight integration.

---

1. Installation

Requires: Python 3.8+.

From PyPI

pip install pid-tuner

From Source (editable)

git clone [e-mail]:bmags73/pid-tuner.git
cd pid-tuner
pip install -e .

---

2. Quickstart Guide

Place your Blackbox CSV logs in any folder and run commands against them:

a) Summary of PID Spikes

pid-tuner summary \
  --log logs/sample1.csv \
  --axes roll,pitch \
  --window 50 \
  --threshold 2.0

b) Generate Plots

pid-tuner plot \
  --axes roll,pitch,yaw \
  --overlay-throttle \
  --out-dir graphs/

c) Browse Spike Details

pid-tuner spikes \
  --axes roll,pitch \
  --min-mag 30 \
  --time-window 0.5,2.0 \
  --page 1 \
  --per-page 20

---

3. Advanced Usage

3.1 Batch Processing Multiple Logs

You can quickly analyze a whole directory of Blackbox CSVs with a simple shell loop:

for log in logs/*.csv; do
  echo "Processing $log"
  pid-tuner summary --log "$log" --axes roll,pitch,yaw --window 50 --threshold 2.0
  pid-tuner plot    --log "$log" --axes roll,pitch,yaw --out-dir graphs/
  pid-tuner spikes  --log "$log" --axes roll,pitch,yaw --min-mag 30 --time-window 0.5,2.0
done

3.2 Configuration File Support (Upcoming)

Define your analysis parameters in config.yml or config.json to run as:

pid-tuner batch --config config.yml

# config.yml
logs:
  - logs/flight1.csv
  - logs/flight2.csv
axes: [roll, pitch, yaw]
threshold: 2.5
window: 60
out_dir: graphs/

(This feature is under development — contributions welcome!)## 4. Contribution & API Reference

API Docs

Generate API reference with Sphinx + mkdocstrings:

pip install sphinx mkdocstrings
sphinx-quickstart docs
# update docs/conf.py and index.rst as needed
sphinx-build docs docs/_build/html

Contributing

• Fork the repo and create feature branches.
• Run pytest to ensure all tests pass.
• Update/add docstrings and tests for new features.
• Submit a Pull Request with clear description and screenshots.

---

5. License

MIT © bMagSquatch