Apply the declared aircraft profile to the FC, then save and reboot.

On iNAV this is an ATOMIC operation: the commands are applied in one CLI session, backed up first, then SAVED to EEPROM (the only way changes persist) and the FC reboots. We reconnect automatically and verify by read-back. If any command fails, ALL changes are rolled back (nothing is saved).

Gates:

• A profile must be defined via define_aircraft().

• Connected and not armed.

• confirm=True required (dry-run by default).

Args: confirm: True to apply+save+reboot. Default False = dry-run (shows commands).

Map a multi-position switch's detents to flight modes in one call.

Computes the µs range for each detent and writes one 'aux' assignment per mode. Dry-run by default. Gates: connected, not armed, auto-backup before write.

Args: switch_channel: 1-based AUX number the switch is on (1 = AUX1 = RC channel 5). switch_positions: Number of detents on the switch: 2, 3, or 6. mode_per_position: Map of position → mode name. Position keys may be "low"/"mid"/"high" (for 2/3-pos) or "1".."N" / "pos1".., e.g. {"low": "ANGLE", "mid": "HORIZON", "high": "MANUAL"}. confirm: True to apply. Default False = dry-run.

Save the current FC config to a timestamped backup file.

Runs 'diff all' in the CLI and writes the output to ./backups/.txt.

NOTE: on iNAV, leaving the CLI reboots the FC, so this reboots and then auto-reconnects (~7s). The result includes 'rebooted': True.

Args: label: Optional suffix added to the filename for easy identification.

Read flight-controller identity over MSP.

Returns: FC variant (e.g. 'INAV'), firmware version, board/target name, API version, build date/time/git revision, and sensors detected.

Requires an active connection (call connect first).

Calibrate the accelerometer (zero-level). Fixes most 'not level' / 'accel not calibrated' arming blocks.

Sends MSP_ACC_CALIBRATION; iNAV samples for ~2s and saves to EEPROM automatically (no reboot).

BEFORE running: set the board/aircraft on a LEVEL surface in its normal flight orientation and DO NOT move it until this returns.

Gates: connected, not armed, confirm=True (dry-run otherwise).

Calibrate the compass (magnetometer). Only useful if a compass is installed.

Sends MSP_MAG_CALIBRATION; you then have ~30s to rotate the aircraft 360° around all three axes. iNAV saves the result automatically.

Gates: connected, not armed, confirm=True (dry-run otherwise).

Compare the FC's actual configuration against the declared aircraft profile.

Runs 'diff all' via CLI, parses key settings, and reports mismatches against the profile declared with define_aircraft(). Also checks if ARM mode is assigned to a switch.

Useful after apply_aircraft_setup() or to sanity-check a partially configured FC.

Read and explain the failsafe configuration (what happens on RC loss).

Reads all failsafe_* settings via CLI get failsafe, summarises the RC-loss procedure in plain English, and flags risky setups (procedure NONE; RTH without GPS).

NOTE: reads over CLI; exiting CLI reboots the FC, so this reboots and reconnects (~7s).

Remove all switch assignments for a flight mode (disables its slots via CLI 'aux').

Dry-run by default. Gates: connected, not armed, auto-backup before write.

Args: mode_name: Exact mode name (e.g. "HORIZON", "NAV RTH"). confirm: True to apply. Default False = dry-run.

Raw CLI escape hatch — run any iNAV CLI command directly.

Read-only commands (diff, get, status, dump, tasks, help, version) run and the FC reboots on CLI exit (auto-reconnected). Write commands (set, aux, feature, smix, ...) require confirm_for_writes=True and are SAVED (persist + reboot), since on iNAV exiting CLI without save discards changes.

SAFETY — motor commands: a 'motor ...' command drives a LIVE motor output and can spin a propeller. It is gated separately from ordinary writes: it requires props_removed=True (NOT confirm_for_writes), refuses if the board is armed, and is NEVER saved — it's a momentary bench test that stops when the FC reboots on CLI exit.

Prefer the dedicated write tools (they back up and verify). Use this for one-off commands the other tools don't cover.

Args: command: The CLI command to run (without trailing newline). confirm_for_writes: Set True to allow (and persist) write commands. props_removed: Set True to allow a live 'motor' test — ONLY after physically removing all propellers from the aircraft.

Run MANY CLI commands in ONE CLI session — a single reboot for the whole batch.

On iNAV, leaving the CLI ALWAYS reboots the FC, so every separate cli() call costs a full reboot + USB re-enumeration + reconnect (~7s). Doing a run of commands one cli() call at a time means one reboot PER command — the rapid reboot cadence is disruptive and can even knock the board into DFU/bootloader mode. This collapses N commands into ONE session = ONE reboot. Prefer it for any ad-hoc multi-command work (several get reads, or several set writes). (The dedicated write tools — apply_aircraft_setup, set_flight_mode, etc. — already batch internally; this is the escape hatch for everything else.)

Behaviour:

• All read-only batch (get/diff/dump/status/tasks/version): the session exits WITHOUT saving — no EEPROM write, nothing persists. Still one reboot (unavoidable on iNAV), but reads are free of a save.

• Any write (set/aux/feature/…): requires confirm_for_writes=True; a backup is taken first and the whole batch is SAVED once at the end (persist + reboot). If ANY command is rejected by the FC, the batch exits WITHOUT saving so nothing partial persists (all-or-nothing).

• Live motor commands and session-control verbs (save/exit/batch) are rejected up front — motor tests must never be saved (use cli(..., props_removed=True) / test_motor()), and the batch manages save/exit itself.

Args: commands: Ordered list of CLI commands to run in one session. confirm_for_writes: Set True to run and persist a batch containing writes.

Returns per-command output, whether it saved, the backup path (if it wrote), and the measured reboot/reconnect seconds for the single reboot.

Enable the GPS feature and set the receiver provider / SBAS (atomic CLI write).

Args: provider: GPS provider token — e.g. UBLOX | NMEA | MSP (the FC validates it). sbas: Optional SBAS mode — AUTO | EGNOS | WAAS | MSAS | GAGAN | NONE. confirm: True to apply (save+reboot). Dry-run otherwise.

Gates: connected, not armed, auto-backup. After applying, give the GPS time to acquire satellites and check read_gps().

Open the serial connection to the FC and return board identity.

Args: port: Serial port, e.g. 'COM3' (Windows) or '/dev/ttyACM0' (Linux). baud: Baud rate (default 115200 — matches iNAV's USB VCP default).

Returns board variant, firmware version, target name, API version, build info, and a summary of detected sensors.

Define the aircraft hardware profile and generate a configuration plan.

This is an OFFLINE planner — no FC connection required. Call it first to review the generated CLI commands, then call apply_aircraft_setup() to apply.

Args: name: A descriptive name for this aircraft (e.g., "My FPV Wing"). wing_type: One of: flying_wing, conventional, vtail, twin_tail, delta. esc_protocol: One of: DSHOT600, DSHOT300, DSHOT150, MULTISHOT, ONESHOT125, PWM. cells: LiPo battery cell count (e.g. 4 for 4S). fc_target: Optional FC board name (e.g. MATEKF405). Used for target hints. motor_kv: Optional motor KV rating (informational only). motor_poles: Motor pole count for RPM telemetry (default 14; verify with your motor). servo_count: Optional total servo count (informational). notes: Free text notes to store with the profile.

Returns a plan dict with: - profile: the stored profile - commands: the CLI commands to apply - summary: human-readable description - warnings: things to verify before/after applying

Full diagnostic sweep — the flagship troubleshooter.

Collects: arming flags, sensor health, RC channels, battery, GPS, attitude, and mode assignments. Runs all diagnostic rules and returns a prioritized problem list with concrete fixes for each issue found.

Use this when 'something is wrong but I'm not sure what.'

Close the serial connection to the FC.

Auto-detect which serial port has a flight controller, so you don't guess.

Briefly opens each likely USB-serial port and asks for MSP identity; returns the ports that answered as an FC (variant + firmware). Then call connect(port).

Args: baud: Baud to probe at (default 115200, iNAV's USB VCP default). probe_all: If True, probe EVERY serial port; otherwise only USB-serial-looking ones (safer — avoids poking unrelated devices like Bluetooth/modems).

Return the currently declared aircraft profile.

Call define_aircraft() first to set a profile.

Read FC status via both MSP and CLI.

Returns MSP_STATUS data (cycle time, sensor bits, CPU load, arming flags) plus the human-readable output of the CLI 'status' and 'tasks' commands.

List saved config backups under ./backups/, newest first. No FC needed.

Returns each backup's path, modified time, size, line count, and label — so you can pick one to replay with restore_config(path).

List all available flight modes and their current switch assignments.

Returns:

• all_modes: every mode the FC knows about (id + name + assigned flag)

• assigned_modes: which modes are on which aux channel and range

• unassigned_modes: mode names with no switch assignment yet

• arm_assigned: bool — critical to know before first flight

Tip: call read_rc_channels() to identify which channel your switches use, then use assign_switch() to map modes to them.

List all available serial ports.

Use this to find the COM port (Windows) or /dev/tty* (Linux/macOS) for the FC. Plug in the FC, run this, and look for a new entry (often labelled 'STM32' or 'CP210x' for iNAV boards).

Live GPS status: fix type, satellites, position, speed, HDOP + nav-readiness.

Read-only (MSP_RAW_GPS, no reboot). Use this before relying on RTH or any position-holding navigation mode.

Read live RC channel values via MSP.

Returns up to 16 channel values in microseconds (988–2012 µs typical).

Core UX: flip a switch and watch which channel value changes — that's the aux channel to use when assigning flight modes.

Read live sensor values: attitude, per-sensor health, and analog (battery).

Good for a quick sanity pass before flying:

• Attitude should read ~0°/0° when the aircraft is level.

• All required sensors (gyro, acc) should report OK.

• Battery voltage should match your pack's cell count.

Read fixed-wing PID gains, rates, and key filter cutoffs (via CLI).

Returns PIDs grouped by axis, plus rate and low-pass-filter settings.

NOTE: reads over CLI; exiting CLI reboots the FC, so this reboots and reconnects (~7s).

Restore FC config by replaying a backup file's CLI commands, then save+reboot.

On iNAV this is atomic: a pre-restore backup is taken, the file's commands are replayed in one CLI session, then SAVED to EEPROM and the FC reboots (we reconnect). If any line errors, all changes are rolled back.

Args: path: Path to a backup file (as returned by backup_config). confirm: Must be True to apply. Dry-run by default.

Save the running config to EEPROM and reboot the FC.

Takes a backup, then 'save' (persist + reboot), then auto-reconnects (~7s).

NOTE: the dedicated write tools already save automatically on iNAV, so you rarely need this — it's for persisting changes made via the raw cli() reads or to force a clean reboot.

Args: confirm: Must be True to proceed. Dry-run by default.

Set the core failsafe behaviour (atomic CLI write: backup → apply → save+reboot).

Only the arguments you pass are changed; dry-run by default. For other failsafe_* knobs (distances, angles) use cli('set failsafe_... = N', confirm_for_writes=True).

Args: procedure: RC-loss action — one of DROP | LAND | SET-THR | RTH | NONE. The exact accepted tokens depend on firmware; an invalid value is rejected by the FC and the whole write is rolled back. throttle_us: failsafe_throttle in µs (used by SET-THR / LAND). Clamped 1000–2000. delay_s: Guard time after RC loss before failsafe triggers (failsafe_delay). iNAV stores this in 0.1 s units, so this is converted ×10. off_delay_s: Time the failsafe stage runs before the motor is killed (failsafe_off_delay), also 0.1 s units (×10). confirm: True to apply (saves + reboots). Dry-run otherwise.

Gates: connected, not armed, auto-backup. RTH without GPS will not work — use DROP/LAND.

Assign a flight mode to an aux channel range (read-modify-write via CLI 'aux').

Finds an existing slot for this mode+channel (to modify) or the first free slot (to create), then writes the assignment. Dry-run by default.

Gates: connected, not armed, auto-backup before write. Requires confirm=True to apply.

Args: mode_name: Exact mode name as shown by list_flight_modes (e.g. "ANGLE", "NAV RTH"). aux_channel: 1-based AUX number (1 = AUX1 = RC channel 5), matching list_flight_modes. range_low: Range start in µs (900–2100). range_high: Range end in µs (must be > range_low, ≤ 2100). confirm: True to apply. Default False = dry-run (returns the command only).

Set core fixed-wing navigation / RTH parameters (atomic CLI write).

Only the arguments you pass are changed. Dry-run by default.

Args: rth_altitude_m: Return-to-home altitude, metres (nav_rth_altitude, stored cm). rth_climb_first: Climb to RTH altitude before heading home (nav_rth_climb_first). rth_allow_landing: NEVER | ALWAYS | FS_ONLY (nav_rth_allow_landing). loiter_radius_m: Fixed-wing loiter radius, metres (nav_fw_loiter_radius, stored cm). confirm: True to apply (save+reboot). Dry-run otherwise.

Gates: connected, not armed, auto-backup. RTH needs a working GPS and a home fix.

Set fixed-wing PID gains for ONE axis (atomic CLI write).

Changes only the terms you pass. Dry-run by default.

Args: axis: roll | pitch | yaw. p, i, d, ff: Gains for fw_p_ / fw_i_ / fw_d_ / fw_ff_. confirm: True to apply (save+reboot). Dry-run otherwise.

⚠ PID changes alter flight behaviour — change gradually and test carefully. Gates: connected, not armed, auto-backup.

Recommend a fixed-wing flight-mode/switch layout. Pure knowledge — no FC needed.

Suggests which switches to use for ARM, flight modes (ANGLE/HORIZON/MANUAL), and (with GPS) NAV RTH / NAV LAUNCH, with the exact aux channels and µs ranges.

Args: skill_level: beginner | intermediate | advanced (tailors the advice). num_switches: How many spare switches you have available. has_gps: True if a GPS module is installed (enables RTH suggestion).

Returns a layout plan you can hand to assign_switch() to apply.

Spin ONE motor briefly for a bench test (direction / wiring / response).

⚠ DANGER: this drives a LIVE motor output. REMOVE ALL PROPELLERS FIRST.

Safety gates (enforced in code):

• props_removed=True is REQUIRED (refuses otherwise),

• refuses if the FC reports armed,

• confirm=True is REQUIRED (dry-run preview otherwise),

• throttle clamped to 1000–2000 µs, duration clamped to 0.2–5.0 s,

• the motor is ALWAYS commanded back to stop (1000 µs) when the test ends.

The override is live (MSP, not saved); it also stops if the FC reboots or loses power.

Args: motor: 1-based motor number (1 = motor 1). Only this motor spins; all others are held at 1000 µs (stop). throttle_us: Output in µs (1000 = stop, ~1100 = gentle, 2000 = full). Keep it LOW for a direction check. duration_s: How long to hold the output (0.2–5.0 s). props_removed: MUST be True — confirms props are physically removed. confirm: MUST be True to actually run.

Decode the FC's arming-prevention flags into plain English.

This is the #1 question from new iNAV users. Each set bit is mapped to:

• A flag name

• A plain-language reason

• A concrete fix

Also checks whether ARM mode is assigned to a switch.