SmartTune CLI (stune)

Multi-platform flight log analysis & tuning advisor. Supports ArduPilot (.bin/.log), Betaflight (.bbl/.bfl), and PX4 (.ulg).

Platform is auto-detected from the log file format.

Installation

cd ~/cli-tools/smarttune-cli
pip install -e .

Quick Reference

# Comprehensive analysis (recommended) — PID + FFT + Filter + Mag
stune analyze -i log.bin

# Log quality scoring — data completeness / excitation / sample rate
stune quality -i log.bin

# Individual analyses
stune pid -i log.bin -a roll
stune fft -i log.bin
stune filter -i log.bin --gyro-filter 40 --visual
stune sysid -i log.bin -a roll
stune hardware -i log.bin
stune magfit -i log.bin

# List supported platforms
stune platforms

Usage Rules

1. Check help first: stune <command> --help when unsure about flags

2. Terminal output by default: no -o flag → stdout only

3. Optional charts: add --visual for matplotlib plots

4. Cleanup after analysis: delete raw .bin/.log/.bbl/.ulg files after processing

5. ⚠️ MANDATORY: Validate parameters before recommending. After analysis generates tuning suggestions, you MUST verify each parameter exists in the target firmware by running:

   stune params --validate <PARAM_NAME> <VALUE> -p <platform>
   

   If validation fails (exit code 1), do NOT recommend that parameter — it may not exist in the firmware, the value may be outside [min, max], or (for an enum) not a defined member. When the rejection lists allowed values, pick from those. Find an alternative or tell the user the parameter is not available.

   This is critical because:

   • Betaflight 4.5+ renamed many parameters (e.g., d_min_roll → d_max_roll, gyro_lowpass_hz → gyro_lpf1_static_hz)
   • Parameter names differ between firmware versions
   • Some parameters have strict value ranges that must be respected

   Never blindly output parameter recommendations without validation.

⚠️ Analysis done = output results. No residual files needed.

Workflows

Getting Started

# 1. Hardware config check
stune hardware -i flight.bin

# 2. Log quality scoring
stune quality -i flight.bin

# 3. Comprehensive analysis
stune analyze -i flight.bin --visual

# 4. Targeted tuning
stune pid -i flight.bin -a roll
stune fft -i flight.bin --visual

Advanced

# System identification (ARX model)
stune sysid -i flight.bin -a roll --na 3 --nb 2

# Filter transfer function analysis
stune filter -i flight.bin --gyro-filter 40 --visual

# Before/after FFT comparison
stune fft -i flight.bin --visual

Multi-platform

# Auto-detect platform (default)
stune analyze -i flight.bbl

# Manual override
stune analyze -i flight.bin --platform ardupilot

Parameter Validation Workflow (MANDATORY)

After analysis produces recommendations, always validate:

# 1. Run analysis
stune pid -i flight.bin -a roll
# → Recommends: ATC_RAT_RLL_P: 0.12 → 0.15

# 2. Validate the parameter exists and value is in range
stune params --validate ATC_RAT_RLL_P 0.15 -p ardupilot
# → ✓ ATC_RAT_RLL_P: 0.150 within [0.010, 1.000]
# OK, proceed to recommend

# 3. If validation fails
stune params --validate XYZZY_PARAM 0.5 -p ardupilot
# → ✗ XYZZY_PARAM: NOT FOUND in ArduPilot parameter table
# DO NOT recommend — parameter doesn't exist in this firmware

# 4. Also search to find correct param name if unsure
stune params --search "feedforward" --platform betaflight
# → Shows actual BF 4.5+ parameter names (f_roll, etc.)

Rule: One stune params --validate call per recommended parameter before presenting results.

Command Reference

stune analyze

Comprehensive log analysis — PID + FFT + Filter + Mag tuning recommendations.

stune analyze -i flight.bin                          # Basic analysis
stune analyze -i flight.bin --visual                 # Generate plots
stune analyze -i flight.bin -a roll                  # Roll axis only
stune analyze -i flight.bin -o report.md --report md # Markdown report
stune analyze -i flight.bin --theme dark --visual    # Dark theme plots

stune quality

Log quality scoring — checks data completeness, excitation adequacy (number of PID step windows), sample rate consistency.

stune quality -i flight.bin
stune quality -i flight.bin -o quality.txt

stune pid

PID step response analysis — rise time, overshoot, settling time, oscillation count.

stune pid -i flight.bin                              # All axes
stune pid -i flight.bin -a roll                      # Single axis
stune pid -i flight.bin -a roll --visual             # Step response plot
stune pid -i flight.bin --visual --theme dark        # Dark theme

stune fft

FFT vibration spectrum analysis — identify dominant vibration frequencies, suggest notch filter parameters.

stune fft -i flight.bin
stune fft -i flight.bin --visual                     # Spectrum plot
stune fft -i flight.bin --visual --theme dark

stune filter

Filter transfer function analysis (Bode Plot) — two modes:

• Auto mode (default): derive filter config from log parameters
  • ArduPilot: reads INS_HNTCH_* params
  • Betaflight: reads gyro_lowpass_hz / notch params
• Manual mode: specify --gyro-filter / --notch-freq directly

stune filter -i flight.bin                           # auto-derive
stune filter -i flight.bin --no-auto --gyro-filter 20 --visual
stune filter -i flight.bin --notch-freq 80 --visual

stune sysid

ARX system identification — estimate transfer function from log data (natural frequency, damping ratio, time constant).

stune sysid -i flight.bin                            # All axes
stune sysid -i flight.bin -a roll                    # Single axis
stune sysid -i flight.bin -a roll --na 3 --nb 2     # Custom ARX order

stune hardware

Hardware configuration report — IMU, compass, filter, PID parameters at a glance.

stune hardware -i flight.bin
stune hardware -i flight.bin --platform ardupilot    # Force platform

stune magfit

Magnetometer calibration analysis — Fitness assessment, hard/soft iron interference diagnosis, flight coverage check.

stune magfit -i flight.bin

stune params

Browse, query and validate firmware parameter tables — generated from official firmware metadata, grouped the way the firmware groups them, with enum meanings.

# What tables exist
stune params                              # ArduPilot 2,839 / Betaflight 814 / PX4 1,908

# Browse by firmware parameter group
stune params ap --groups                  # 194 ArduPilot groups
stune params ap --group ATC_              # attitude controller parameters
stune params bf --group PID_PROFILE
stune params px4 --group "Multicopter Rate Control"

# Browse by topic
stune params ap -c pid                    # pid / filter / mag / battery / rate / …

# Show detail for a specific parameter (description + what each enum value means)
stune params ATC_RAT_RLL_P                # auto-detects platform
stune params BATT_MONITOR                 # → 4 = Analog Voltage and Current
stune params p_roll                       # Betaflight param

# Ranked search — names, descriptions and enum labels
stune params --search notch
stune params --search "analog voltage"    # finds BATT_MONITOR

# Validate a parameter recommendation (CRITICAL for agents)
stune params --validate ATC_RAT_RLL_P 0.15 -p ardupilot   # exit 0 if valid
stune params --validate BATT_MONITOR 99 -p ardupilot      # exit 1: not a valid value (lists allowed)
stune params --validate XYZZY_PARAM 0.0 -p ardupilot      # exit 1 if not found
stune params --validate p_roll 500 -p betaflight          # exit 1 if out of range

# Pick a firmware-version table (ArduPilot default is Copter-4.1)
stune params ap --fw-version copter-4.5 --group ATC_
stune params --validate ATC_RAT_RLL_P 0.45 -p ap --fw-version copter-4.5

# Validate a whole recommendation set in one call (exit 0 only if all valid)
echo '[{"param":"BATT_MONITOR","value":4}]' | stune params --validate-batch - -p ap

# Parameter-table health check (CI gate)
stune params --lint

# Any of the above as JSON
stune params ap --group ATC_ -f json

Tables are generated from official firmware metadata by tools/build_param_tables.py (ArduPilot apm.pdef.json, PX4 px4params JSON, Betaflight cli/settings.c). default: null means upstream publishes no default — it does not mean zero.

Parameter tables are loaded from knowledge base JSON files (smarttune/knowledge/params/). Update the JSON to refresh parameters without code changes. Parameters scraped from official firmware source code — ArduPilot from @Param annotations, Betaflight from settings.c, PX4 from YAML definitions.

Platform Support Matrix

Feature	ArduPilot	Betaflight	PX4
analyze	✅	✅	🔲
quality	✅	✅	🔲
pid	✅	✅	🔲
fft	✅	✅	🔲
filter	✅	✅	🔲
sysid	✅	✅	🔲
hardware	✅	✅	🔲
magfit	✅	—	🔲
Log format	.bin / .log	.bbl / .bfl	.ulg

Further Help

Rule: Always check --help before using a command you haven't run recently. Every subcommand has a detailed help block with examples and option descriptions.

Scenario	Action
Full parameter list	stune <command> --help
Usage examples	Built into each subcommand's help text
Parameter meaning reference	Knowledge base built into CLI (smarttune/knowledge/)

Comparison with WebTools

WebTools Tool	stune command	Status
PIDReview	pid + analyze	✅
FilterReview	filter + fft	✅
HardwareReport	hardware	✅
MAGFit	magfit	✅
SysID	sysid	✅
—	quality	✅ New

Capability Status

Capability	Command	Status
Log parsing	Multi-platform auto-detect	✅
PID analysis	stune pid	✅
FFT analysis	stune fft	✅
Magnetometer calibration	stune magfit	✅
Comprehensive analysis	stune analyze	✅
System identification	stune sysid	✅
Filter analysis	stune filter	✅
Hardware report	stune hardware	✅
Log quality scoring	stune quality	✅
Multi-platform support	AP + BF + PX4	✅