inav-toolkit 2.15.0__py3-none-any.whl

inav_toolkit-2.15.0.dist-info/METADATA

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: inav-toolkit
+Version: 2.15.0
+Summary: Blackbox analyzer, parameter checker, and tuning wizard for INAV flight controllers
+License: MIT
+Project-URL: Homepage, https://github.com/agoliveira/INAV-Toolkit
+Project-URL: Issues, https://github.com/agoliveira/INAV-Toolkit/issues
+Keywords: inav,drone,blackbox,pid,tuning,flight-controller,multirotor
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: pyserial>=3.5
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# INAV Toolkit
+
+[![CI](https://github.com/agoliveira/INAV-Toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/agoliveira/INAV-Toolkit/actions/workflows/ci.yml)
+
+A suite of Python tools for analyzing, validating, and tuning INAV flight controller configurations. Built for the INAV long-range community - 7" to 15" multirotors with GPS navigation.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| **Blackbox Analyzer** | Decode blackbox logs, analyze PID performance, detect oscillation, recommend tuning changes |
+| **Guided Wizard** | Interactive session manager - connects to FC, backs up config, runs analysis, applies changes |
+| **Parameter Analyzer** | Validate `diff all` configs for safety, filter, PID, and navigation issues |
+| **VTOL Configurator** | Validate VTOL mixer profiles, motor/servo mixing, and transition setup |
+| **Flight Database** | SQLite storage for flight history, progression tracking across tuning sessions |
+| **MSP Communication** | Direct FC communication - download blackbox, pull config, identify hardware |
+
+## Quick Start
+
+### Install
+
+```bash
+pip install inav-toolkit
+```
+
+That's it. All dependencies (numpy, scipy, matplotlib, pyserial) are installed automatically.
+
+**Alternative install methods:**
+
+```bash
+# In a virtual environment
+python3 -m venv inav
+source inav/bin/activate
+pip install inav-toolkit
+
+# With pipx (auto-isolates CLI tools)
+pipx install inav-toolkit
+
+# From source (development)
+git clone https://github.com/agoliveira/INAV-Toolkit
+cd INAV-Toolkit
+pip install -e .
+```
+
+Python 3.8+ required.
+
+### Blackbox Analyzer
+
+Analyzes binary blackbox logs (`.bbl` / `.bfl`) from INAV. Decodes natively in Python - no `blackbox_decode` needed.
+
+```bash
+# Full pipeline: connect to FC, download blackbox, analyze (diff pulled automatically)
+inav-analyze --device auto
+
+# Download, analyze, and erase flash for next session
+inav-analyze --device auto --erase
+
+# Download only (saves to ./blackbox/, no analysis)
+inav-analyze --device auto --download-only
+
+# Analyze from file (auto-detects frame size, cells, platform)
+inav-analyze flight.bbl
+
+# Multi-log files are automatically split and analyzed individually
+inav-analyze dataflash_dump.bbl
+
+# Show flight history and progression for a craft
+inav-analyze flight.bbl --history
+
+# Override frame size if auto-detection doesn't apply
+inav-analyze flight.bbl --frame 10
+
+# Add motor KV for RPM noise prediction (cells auto-detected from vbatref)
+inav-analyze flight.bbl --kv 980
+
+# Navigation health analysis mode
+inav-analyze flight.bbl --nav
+
+# Compare two flights side-by-side
+inav-analyze flight_before.bbl --compare flight_after.bbl
+
+# Interactive replay with Plotly.js (spectrogram, synced zoom, flight modes)
+inav-analyze flight.bbl --replay
+
+# Quick log quality check (exit code 1 if unusable)
+inav-analyze flight.bbl --check-log
+
+# Generate Markdown report for forum/Discord
+inav-analyze flight.bbl --report md
+
+# Skip database storage for one-off analysis
+inav-analyze flight.bbl --no-db
+
+# Custom database path
+inav-analyze flight.bbl --db-path ~/my_flights.db
+```
+
+**What it measures:**
+- **Hover oscillation:** Detects oscillation during hover from gyro variance, classifies severity, identifies dominant frequency, diagnoses cause (P too high / PD interaction / D-term noise / filter gap)
+- **PID step response:** Overshoot percentage, settling time, delay
+- **Noise spectrum:** Identifies peak frequencies per axis
+- **Motor balance:** Detects thrust asymmetry
+- **Filter phase lag:** Total delay through the filter chain
+- **Tracking error:** RMS deviation between setpoint and gyro
+- **Navigation health** (`--nav`): Compass interference, GPS quality, barometer noise, position hold drift, altitude hold accuracy
+
+**Comparative analysis** (`--compare`): Side-by-side analysis of two flights with overlay noise spectra, PID response deltas, motor balance comparison, and overall score improvement/degradation arrow. Warns on craft/frame mismatches.
+
+**Interactive replay** (`--replay`): Standalone HTML with Plotly.js WebGL rendering. Panels: gyro vs setpoint (3 axes), motor outputs, noise spectrogram waterfall (sliding FFT heatmap), throttle. Synced zoom/pan across all panels. Flight mode overlay bar decoded from S-frame bitmask.
+
+**Log quality scoring** (`--check-log`): Pre-analysis validation that grades logs as GOOD/MARGINAL/UNUSABLE. Checks: duration, sample rate, field completeness, stick activity, all-zeros sensors, corrupt frames, NaN gaps. Also runs automatically during normal analysis.
+
+**Markdown reports** (`--report md`): Generates a forum/Discord-pasteable report with scores, findings, noise sources, PID metrics, and CLI commands in a fenced code block.
+
+**Multi-log splitting:** Dataflash dumps containing multiple arm/disarm cycles are automatically detected and split. Each flight is analyzed individually with per-flight progression tracking.
+
+**CLI diff merge:** When connected to the FC via `--device`, the analyzer automatically pulls the full `diff all` configuration. Settings not present in blackbox headers (motor_poles, nav PIDs, rates, level mode, antigravity) are enriched from the diff. Mismatches between what was flying and the current FC config are detected and displayed.
+
+**Flight database:** Every analysis is stored in a SQLite database (`inav_flights.db`). Scores, per-axis oscillation data, PID values, filter config, motor balance, and recommended actions are tracked per flight. The `--history` flag shows a progression table.
+
+**Auto-detection:** Frame size from craft name, battery cells from vbatref, platform type (quad/hex/tri) from motor count. Warns on conflicts between detected and user-specified values.
+
+**Oscillation-first enforcement:** When hover oscillation is detected, the analyzer generates aggressive P/D reductions as top-priority actions and defers regular PID recommendations on oscillating axes - you can't tune what you can't stabilize.
+
+**Filter-first enforcement:** When filter changes are needed, PID recommendations are deferred until after filters are fixed and a re-fly, preventing the common death spiral of raising D-term gains into wide-open filters.
+
+**Output:** Terminal report with actionable CLI commands, HTML report with plots, state JSON for cross-referencing, and SQLite database for history.
+
+### Guided Wizard
+
+Interactive session that orchestrates the full workflow: connect to FC, backup config, download blackbox, analyze, review changes, and apply.
+
+```bash
+# Start guided session (auto-detects FC)
+inav-toolkit
+
+# Specify serial port
+inav-toolkit --device /dev/ttyACM0
+```
+
+The wizard creates a timestamped backup before any changes and walks you through each step with safety gates.
+
+### Parameter Analyzer
+
+Validates an INAV `diff all` export for configuration issues.
+
+```bash
+# Analyze existing config
+inav-params my_diff.txt --frame 10
+
+# Generate starting PIDs for a new build
+inav-params --setup 10 --voltage 6S
+
+# Compare starting PIDs with current config
+inav-params --setup 10 --voltage 6S my_diff.txt
+
+# Cross-reference with blackbox results
+inav-params my_diff.txt --blackbox state.json
+```
+
+**What it checks:**
+- **Safety:** Beeper configuration, failsafe procedure, battery limits
+- **Motors:** Protocol validation, RPM filter + ESC telemetry consistency
+- **Filters:** Frame-appropriate gyro LPF, dynamic notch configuration
+- **PIDs:** Cross-profile consistency, iterm_relax, D-boost, antigravity
+- **Navigation:** RTH altitude, hover throttle, position PIDs, safehome
+- **GPS:** Multi-constellation, compass calibration quality (mag gain spread)
+- **Blackbox:** Logging rate, essential fields for analysis
+- **Battery:** Li-ion vs LiPo detection, voltage limits
+
+**Setup mode** generates conservative starting PIDs for 5/7/10/12/15" frames at 4S/6S/8S/12S.
+
+### VTOL Configurator
+
+Validates INAV VTOL configurations using mixer_profile switching.
+
+```bash
+# Validate VTOL config
+python3 -m inav_toolkit.vtol_configurator vtol_diff.txt
+
+# JSON output
+python3 -m inav_toolkit.vtol_configurator vtol_diff.txt --json
+```
+
+**What it checks:**
+- MC and FW mixer profiles present with correct `platform_type`
+- Motor role inference: tilt / lift-only / pusher by cross-referencing profiles
+- Tilt servo rules (smix source 38) for transition
+- Yaw authority: motor yaw mixing or tilt servo yaw
+- FW control surfaces: roll + pitch servo mixing
+- Mode assignments: MIXER PROFILE 2 (mode 62) and MIXER TRANSITION (mode 63)
+- Automated RTH transition: `mixer_automated_switch` in both profiles
+- Safety: `airmode_type` conflict with transition motors, compass for MC nav
+- Control profile linking between mixer profiles
+
+### MSP Communication
+
+Direct serial communication with INAV flight controllers over USB.
+
+```bash
+# Identify connected FC
+inav-msp --info-only
+
+# Download blackbox data
+inav-msp --device auto
+
+# Specify serial port
+inav-msp --device /dev/ttyACM0
+```
+
+**Capabilities:**
+- MSP v2 protocol with CRC-8 validation
+- FC identification (craft name, firmware, board, build date)
+- Dataflash summary, read, and erase
+- SD card blackbox detection with guidance
+- CLI mode for `diff all` config retrieval
+- Auto-detection of serial ports (Linux/macOS)
+- Binary blackbox download with progress bar and retry logic
+
+## Tuning Workflow
+
+The tools are designed to work together in a tuning pipeline:
+
+```
+1. NEW BUILD
+   └─ inav-params --setup 10 --voltage 6S
+      → Conservative starting PIDs, filters, settings
+      → Paste CLI commands into INAV Configurator
+
+2. FIRST FLIGHTS
+   └─ inav-params my_diff.txt --frame 10
+      → Catches safety issues, missing settings, profile inconsistencies
+      → Fix before flying
+
+3. BLACKBOX LOGGING
+   └─ Fly with blackbox enabled (GYRO_RAW, MOTORS, RC_COMMAND)
+      → Hover segment for oscillation detection
+      → Manual/acro segment for PID step response data
+      → Nav segment for position hold / RTH data
+
+4. PID TUNING (one-step with FC connected)
+   └─ inav-analyze --device auto --erase
+      → Downloads blackbox, pulls current config
+      → Splits multi-log files automatically
+      → Detects hover oscillation first
+      → Recommends filter fixes before PID changes
+      → Stores results in flight database
+      → Shows progression from previous flights
+
+5. GUIDED SESSION (interactive)
+   └─ inav-toolkit
+      → Connects, backs up, downloads, analyzes, applies
+      → Safety gates at every step
+
+6. ITERATE
+   └─ Apply CLI commands → fly → analyze → repeat
+      → Database tracks score progression across sessions
+      → --history shows the full tuning journey
+      → Mismatch detection catches config drift
+```
+
+## Frame Size Profiles
+
+The `--setup` mode provides conservative starting configurations:
+
+| Frame | P Roll | P Pitch | D | Gyro LPF | Dyn Notch Min |
+|-------|--------|---------|---|----------|---------------|
+| 5" 4S  | 44 | 46 | 30 | 120Hz | 100Hz |
+| 7" 4S  | 35 | 38 | 23 | 90Hz | 60Hz |
+| 10" 4S | 25 | 28 | 18 | 65Hz | 50Hz |
+| 12" 4S | 20 | 22 | 14 | 50Hz | 35Hz |
+| 15" 4S | 15 | 16 | 10 | 40Hz | 25Hz |
+
+Higher voltage (6S/8S/12S) scales P and D down proportionally.
+
+## INAV Version Support
+
+Developed and tested against **INAV 9.0.x**. The blackbox binary decoder handles the shared Cleanflight/INAV encoding format. MSP v2 protocol for FC communication. Parameter names are INAV-specific - this toolkit does not support Betaflight.
+
+## Project Structure
+
+```
+inav-toolkit/
+├── pyproject.toml                   # Package configuration (pip install)
+├── requirements.txt                 # Python dependencies
+├── README.md
+├── CHANGELOG.md
+├── LICENSE
+├── inav_toolkit/                    # Python package
+│   ├── __init__.py                  # Version: 2.14.1
+│   ├── blackbox_analyzer.py         # Blackbox log analyzer
+│   ├── param_analyzer.py            # Config validator + setup generator
+│   ├── msp.py                       # MSP v2 serial communication
+│   ├── wizard.py                    # Guided session manager
+│   ├── flight_db.py                 # SQLite flight history database
+│   ├── autotune.py                  # Experimental auto-tuning
+│   └── vtol_configurator.py         # VTOL mixer profile validator
+├── docs/
+│   ├── BLACKBOX_ANALYZER.md         # Detailed blackbox analyzer docs
+│   ├── NAV_ANALYZER.md              # Navigation health analysis docs
+│   ├── PARAM_ANALYZER.md            # Detailed parameter analyzer docs
+│   ├── VTOL_CONFIGURATOR.md         # Detailed VTOL configurator docs
+│   └── TUNING_WORKFLOW.md           # Step-by-step tuning guide
+├── tests/
+│   ├── test_smoke.py                # 50 tests across 11 test classes
+│   ├── conftest.py                  # Shared pytest fixtures
+│   ├── generate_fixtures.py         # Synthetic blackbox CSV generator
+│   ├── test_basic_diff.txt          # Sample diff for param_analyzer tests
+│   └── test_vtol_diff.txt           # Sample diff for VTOL tests
+└── .github/workflows/ci.yml        # CI: Python 3.8-3.13 test matrix
+```
+
+## Development
+
+```bash
+git clone https://github.com/agoliveira/INAV-Toolkit
+cd INAV-Toolkit
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[test]"
+
+# Generate synthetic test fixtures
+python3 tests/generate_fixtures.py
+
+# Run tests
+python3 -m pytest tests/ -v
+```
+
+CI runs automatically on every push and PR across Python 3.8-3.13.
+
+## Contributing
+
+This is an active project. Contributions welcome.
+
+## License
+
+GPL-3.0 License. See [LICENSE](LICENSE).
+
+## Acknowledgments
+
+- The INAV development team and community
+- QuadMeUp (Paweł Spychalski) for filter and RPM analysis research
+- The INAV Fixed Wing Group for modes documentation

inav_toolkit-2.15.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+inav_toolkit/__init__.py,sha256=xYBSE3hrzhfSQDdVTmcbe3iMspkJEm3Pn8co-QeFcFg,130
+inav_toolkit/autotune.py,sha256=LemxctIJvuaudsDKz3y9QwATgTmJeMU9-GhoeYZ7K9g,20514
+inav_toolkit/blackbox_analyzer.py,sha256=5aEKf7H5lYSv1bhohzeZty20mu0X73IQgzVJ8HoaHDI,351093
+inav_toolkit/flight_db.py,sha256=QC8zUXgfmuGaa8K8M-SpykGGn9FO_6xCZFGkNaljDJ4,16807
+inav_toolkit/msp.py,sha256=pmRyVeO7QnkMNwe-dXfnMBDsx0uj46WBGWsbFkmNeiI,40996
+inav_toolkit/param_analyzer.py,sha256=XOuQAOWOutG0Pra_YLpqj0YcxF4LNLHiHOHc3BdNUSY,122983
+inav_toolkit/vtol_configurator.py,sha256=el5SMjO1QkS2FZaWc3H-s034Yt_8Tt8TZZBJgwwcep8,35813
+inav_toolkit/wizard.py,sha256=x0KQRE7t6Cn3Jwhy7H4z8G444gDs_sMBkXbWLjFLQ7k,38154
+inav_toolkit-2.15.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+inav_toolkit-2.15.0.dist-info/METADATA,sha256=tKrhXLNwZs5I7wb5Cfa8n3zOc2LOn5FpL8JpEkL4MxM,15156
+inav_toolkit-2.15.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+inav_toolkit-2.15.0.dist-info/entry_points.txt,sha256=izJpHekrM3ENH1p27jNiKfmgdrAc9sOkH7N8AtGnXjg,189
+inav_toolkit-2.15.0.dist-info/top_level.txt,sha256=AkBMhOHRUgjHwR2VnYp4RcxB6NWeZtGYRdLgtzOUpH0,13
+inav_toolkit-2.15.0.dist-info/RECORD,,

inav_toolkit-2.15.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

inav_toolkit-2.15.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+inav-analyze = inav_toolkit.blackbox_analyzer:main
+inav-msp = inav_toolkit.msp:main
+inav-params = inav_toolkit.param_analyzer:main
+inav-toolkit = inav_toolkit.wizard:main