betaflight-claude-skill

A Claude skill for Betaflight: FPV drone configuration, PID tuning, blackbox log analysis, and troubleshooting.

A Claude skill that helps you configure, tune, analyze, and troubleshoot FPV drones running Betaflight firmware. It works from the artifacts you already have — CLI dumps, blackbox logs, and plain-language descriptions of how the quad flies — and can also read and write directly to a live flight controller via the MCP server.

Compute core. All the blackbox/chirp number-crunching (decode, FRF/Bode, step response, spectral noise, the self-contained HTML report) lives in a separate public package, betaflight-chirp-core (the exact pinned version lives in pyproject.toml — the single place it is declared) — the single source of truth, also shared with the FPVLogForge backend. The scripts in scripts/ are thin CLI wrappers over it. The release zip vendors the package (via build_skill_zip.py), so claude.ai / zip users need nothing extra; only a manual git clone run needs it installed (see Running the scripts manually).

What it does

Once loaded, the skill lets Claude:

• Diagnose flight issues from natural-language descriptions (wobbles, hot motors, oscillations, drift, propwash, jello)
• Resolve arming failures — decode every arming prevention flag (cause, fix, common pitfalls)
• Fix connection problems — MCU/USB driver and COM-port-not-found troubleshooting (Zadig, DFU, ImpulseRC Driver Fixer)
• Parse and analyze CLI diff/dump files you share
• Turn a chirp log into a complete tuning report (flagship) — closed-loop Bode (gain/phase/coherence) + step response per axis, a gyro noise spectrum with motor harmonics located from eRPM and the current filter cut-offs drawn on it, a chirp spectrogram, a before/after overlay of multiple logs, and plain-language tuning observations — all in one self-contained, bilingual (FR/EN) HTML report (debug_mode = CHIRP)
• Decode blackbox logs — full binary frame decode with per-field statistics and CSV export
• Analyze gyro and motor noise spectra — Welch PSD of gyroUnfilt vs gyroADC (filter effectiveness) and motor outputs; equivalent to the Blackbox Explorer noise tab
• Analyze step response — closed-loop system identification (setpoint → gyro) via Welch cross-spectral method; rise time, overshoot, settling time, coherence
• Generate paste-ready CLI configs for common build classes (5" freestyle, 3" cinewhoop, 7" longrange)
• Guide you through a setup wizard when configuring a new drone from scratch
• Read and write a live FC via the betaflight-mcp server (PIDs, filters, rates, ports — without a diff file)
• Detect RC channel mapping — passively sample the radio, identify Throttle/Aileron/Elevator/Rudder by function name, compare against Betaflight's rcmap and generate a correction if needed
• Assign switches to flight modes — flip a switch to the active position, Claude detects the channel and µs value and generates the aux command (ARM, BEEPER, ANGLE, etc.)
• Migrate configurations across major Betaflight versions (4.4 → 4.5 → 4.6 → 2025.12)
• Flag deprecated parameters that would error on import to newer firmware
• Recommend safe value ranges for PIDs, filters, rates, and ESC settings
• Fetch official presets from `betaflight/firmware-pr