If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/PX4/PX4-Autopilot shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 30+ active contributors
• Distributed ownership (top contributor 40% of recent commits)
• BSD-3-Clause licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live PX4/PX4-Autopilot repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/PX4/PX4-Autopilot.

What it runs against: a local clone of PX4/PX4-Autopilot — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in PX4/PX4-Autopilot | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of PX4/PX4-Autopilot. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/PX4/PX4-Autopilot.git
#   cd PX4-Autopilot
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of PX4/PX4-Autopilot and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "PX4/PX4-Autopilot(\\.git)?\\b" \\
  && ok "origin remote is PX4/PX4-Autopilot" \\
  || miss "origin remote is not PX4/PX4-Autopilot (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "Kconfig" \\
  && ok "Kconfig" \\
  || miss "missing critical file: Kconfig"
test -f ".github/workflows/build_all_targets.yml" \\
  && ok ".github/workflows/build_all_targets.yml" \\
  || miss "missing critical file: .github/workflows/build_all_targets.yml"
test -f "ROMFS/px4fmu_common/init.d-posix/rcS" \\
  && ok "ROMFS/px4fmu_common/init.d-posix/rcS" \\
  || miss "missing critical file: ROMFS/px4fmu_common/init.d-posix/rcS"
test -f ".github/instructions/control.instructions.md" \\
  && ok ".github/instructions/control.instructions.md" \\
  || miss "missing critical file: .github/instructions/control.instructions.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/PX4/PX4-Autopilot"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

PX4 is an open-source autopilot firmware stack for drones and unmanned vehicles that runs on NuttX, Linux, and macOS. It provides flight control, navigation, and mission execution for multirotors, fixed-wing, VTOL, rovers, and experimental platforms via a modular uORB publish-subscribe middleware architecture with DDS compatibility. Monorepo structure: src/ contains core autopilot modules (likely flight control, estimation, navigation); boards/ contains hardware-specific configurations for different autopilot hardware; platforms/ abstracts OS (NuttX/Linux/macOS); .github/workflows/ orchestrates multi-target CI; boards and px4_platform_common likely define HAL abstractions; msg/ or similar defines uORB message schemas via .proto or custom format.

Drone/robotics developers and engineers building custom autonomous vehicles; hardware manufacturers integrating Pixhawk autopilots; researchers implementing flight control algorithms; contributors to the Dronecode Foundation ecosystem who need vendor-neutral, BSD-licensed autopilot firmware.

Production-ready and extensively deployed. 21.6MB of C++ and 16MB of C code indicates a mature codebase; comprehensive CI workflows (build_all_targets.yml, clang-tidy.yml, commit_checks.yml), active GitHub Actions setup with board-specific builds, and presence of .github/instructions/ for multiple subsystems (control, estimation, drivers, simulation) signal active development and mature governance under the Linux Foundation.

Large dependency surface with 40+ Python packages (pymavlink, pyulog, sympy, lark, nunavut, etc.) requires careful version pinning; monolithic C/C++ core (37MB combined) means changes ripple across hardware targets; build system complexity spans CMake, Makefile, and shell scripts across .github/workflows/. Check .clang-tidy and .editorconfig for strict linting that may enforce style blockers on PRs.

Active CI expansion with build_all_targets.yml, failsafe_sim.yml (safety-critical sim testing), and docs-orchestrator.yml; Crowdin integration for i18n (docs_crowdin_upload/download); clang-tidy enforcement via GitHub Actions; dev container support (.devcontainer/devcontainer.json) for standardized dev environments. Multiple .github/instructions/ suggest ongoing subsystem documentation and contributor onboarding.

git clone https://github.com/PX4/PX4-Autopilot.git
cd PX4-Autopilot
pip install -r requirements.txt
make px4_sitl gazebo  # SITL simulation with Gazebo
# or: make px4_fmu-v5_default (for Pixhawk 4 hardware target)

Daily commands:

# SITL (Software-in-the-Loop) simulation with Gazebo:
make px4_sitl gazebo

# For specific hardware board (e.g., Pixhawk 4):
make px4_fmu-v5_default  # Compiles firmware binary

# Run with jMAVSim (lightweight simulator):
make px4_sitl jmavsim

# Interactive testing / parameter tuning:
# After build, use QGroundControl (external tool) or MAVProxy CLI

• CMakeLists.txt — Root build configuration defining all build targets, compilation flags, and module dependencies—essential for understanding how PX4 firmware is compiled for different platforms.
• Kconfig — Configuration system defining all PX4 compile-time options and hardware/platform selections—required reading for understanding feature flags and build variants.
• .github/workflows/build_all_targets.yml — CI/CD pipeline orchestrating compilation for all supported boards—reveals build matrix, test coverage, and deployment targets.
• ROMFS/px4fmu_common/init.d-posix/rcS — POSIX startup script that initializes the autopilot stack, loads airframe configs, and launches core modules—critical entry point for understanding system initialization.
• .github/instructions/control.instructions.md — High-level guidance for contributors modifying flight control and estimation logic—documents code review expectations and architectural patterns for core systems.
• CONTRIBUTING.md — Contribution guidelines covering commit conventions, PR process, and coding standards enforced by CI/CD checks.
• CLAUDE.md — Project-specific documentation for AI-assisted development, defining conventions, patterns, and tools used across the codebase.

Add a New Target Platform/Board

1. Define board-specific configuration in Kconfig hierarchy (Kconfig)
2. Add board-specific CMake target and compiler flags (CMakeLists.txt)
3. Create airframe definition for the new platform (ROMFS/px4fmu_common/init.d-posix/airframes/[NEW_AIRFRAME])
4. Add build target to CI/CD matrix (.github/workflows/build_all_targets.yml)

Add a New Flight Control Feature or Estimator Module

1. Implement module in appropriate source directory following PX4 module conventions (CMakeLists.txt)
2. Add Kconfig option to enable/disable the module (Kconfig)
3. Register module in airframe startup script (ROMFS/px4fmu_common/init.d-posix/rcS)
4. Create unit tests and add to SITL test pipeline (.github/workflows/sitl_tests.yml)
5. Document review expectations in control or estimation instructions (.github/instructions/control.instructions.md)

Modify CI/CD Build or Test Pipeline

1. Update build matrix or add new test job (.github/workflows/build_all_targets.yml)
2. Define custom build action if needed (.github/actions/[action-name]/action.yml)
3. Add linting or static analysis rules (.clang-tidy)
4. Document new CI requirements in contribution guidelines (CONTRIBUTING.md)

Create AI-Assisted Development Skill

1. Define skill documentation and parameters (.claude/skills/[skill-name]/SKILL.md)
2. Document skill usage in main project guidance (CLAUDE.md)

• CMake 3.16+ — Cross-platform build system enabling compilation for embedded ARM targets (STM32), POSIX (Linux/macOS), and SITL simulation with consistent build rules
• Kconfig (Linux kernel style) — Hierarchical configuration management supporting thousands of compile-time options for features, sensors, and platform variants without explosion of build permutations
• GitHub Actions — Native GitHub integration for CI/CD eliminating external tool overhead; supports matrix builds for parallel compilation of 50+ board targets
• ROMFS shell scripts — Lightweight startup system independent of Linux userspace, enabling initialization on bare-metal boards and headless embedded systems
• Python 3 (build system & tools) — Cross-platform scripting for code generation (message definitions via Jinja2), configuration management (YAML/TOML parsing), and testing automation

• Monolithic repository (600+ files) vs. modular subrepositories

  • Why: Tighter integration of flight control, estimation, and hardware layers requiring synchronized releases; simpler contributor experience
  • Consequence: Large CI/CD matrix overhead (~50 board targets) but guaranteed consistency between core modules

• ROMFS-based configuration over compiled defaults

  • Why: Enables runtime airframe/parameter loading on deployed hardware without reflashing
  • Consequence: Requires shell script interpretation overhead at boot, but provides flexibility for field updates

• Kconfig over simple feature toggles (defines.h)

  • Why: Prevents invalid configuration combinations through hierarchical dependencies and validation
  • Consequence: Steeper learning curve for new contributors but prevents CI/CD explosion

• Does not provide GCS (Ground Control Station) software—assumes external tools like QGroundControl
• Does not handle production user authentication or multi-tenant deployments
• Does not support Windows native compilation (POSIX simulator requires Linux/macOS or WSL)
• Does not include real-time OS (RTOS) kernel—assumes FreeRTOS or NuttX provided by HAL layer

1. Multi-target complexity: make px4_sitl gazebo builds for simulation, but make px4_fmu-v5_default targets hardware; wrong target wastes build time. 2. NuttX toolchain: Building for embedded boards requires arm-none-eabi-gcc and NuttX-specific build path; Linux/macOS SITL is more forgiving. 3. Message regeneration: Editing .msg files requires a rebuild to regenerate C++ headers — stale headers cause silent logic errors. 4. Hardware-specific configs: boards/px4fmu-v5/default.cmake vs boards/px4fmu-v4/default.cmake define pinouts, sensor configs; copy-paste errors here break hardware. 5. CI strictness: .clang-tidy + commit_checks.yml enforce formatting; PRs fail on whitespace/style alone, not just logic. 6. Gazebo plugin paths: SITL assumes Gazebo models in specific directories; misconfigured LD_LIBRARY_PATH or ROS_PACKAGE_PATH breaks sim. 7. Python version: requirements.txt pins empy and other generators; Python 3.8+ required, older versions may fail silently.

• uORB (Micro Object Request Broker) — PX4's core inter-process communication middleware enabling lock-free, parallelized modules; understanding uORB message publishing/subscription is essential to adding any new module or feature
• Publish-Subscribe Messaging (DDS-compatible) — Decouples flight control modules (sensor drivers, EKF, attitude control) so they can run on separate threads/cores without tight coupling; enables modularity and testability
• Extended Kalman Filter (EKF) for State Estimation — PX4's attitude/position estimation fuses IMU, GPS, barometer via EKF; understanding sensor fusion is critical for tuning stability and debugging estimation bugs
• Hardware Abstraction Layer (HAL) — PX4 abstracts sensor/actuator I/O (SPI, I2C, ADC, PWM) so the same control logic runs on NuttX, Linux, macOS; modifying drivers requires understanding HAL conventions
• Software-in-the-Loop (SITL) Simulation — px4_sitl gazebo runs the full autopilot firmware in userspace against a simulated vehicle/sensors; essential for safe prototyping before hardware testing
• MAVLink Telemetry Protocol — Standardized binary protocol for ground station (QGroundControl) ↔ drone communication; PX4 implements full MAVLink spec for mission upload, parameter tuning, log streaming
• Rate Controller vs Attitude Controller Hierarchy — PX4 uses cascaded control loops (attitude setpoint → body rate setpoint → motor commands); tuning or modifying control requires understanding this hierarchy and cross-coupling effects

• ArduPilot/ardupilot — Direct competitor autopilot stack; similar multirotors/fixed-wing support but different architecture (no uORB), useful for architectural comparison and feature parity analysis
• PX4/PX4-tools — Companion tools repo for PX4 analysis, QGroundControl plugins, and log parsing — essential for testing and debugging PX4-generated telemetry
• PX4/PX4-Matrix — Standalone header-only matrix library used by PX4 flight control math (attitude, control algorithms); separate so it can be used in external projects
• PX4/px4_msgs — ROS 2 message definitions that mirror PX4's uORB schema; enables DDS/ROS 2 bridge integration for robotics workflows
• PX4/PX4-gazebo-models — Gazebo simulation models (drone meshes, sensor plugins) used by px4_sitl gazebo builds; required for realistic SITL testing

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for message generation pipeline (pyros-genmsg/nunavut)

The repo has a complex message generation system (.github/instructions/messages.instructions.md exists) that depends on pyros-genmsg and nunavut>=1.1.0, but there's no dedicated test workflow for message schema validation and code generation. This is critical since message generation failures break the entire build. A new workflow and test suite would catch regressions early.

• [ ] Create .github/workflows/message_generation_tests.yml to test nunavut/pyros-genmsg pipeline
• [ ] Add unit tests in a new src/msg/test/ directory for YAML/DDS message validation
• [ ] Test cross-platform message generation (Linux/macOS) since .github/workflows/compile_macos.yml and compile_ubuntu.yml exist
• [ ] Add integration test verifying generated C++ headers compile correctly

Implement clang-tidy enforcement for Python files (.clang-tidy exists but only targets C++)

The repo has .clang-tidy config and clang-tidy.yml workflow, but Python is heavily used (empy, pyros-genmsg, pymavlink in dependencies). There's also python_checks.yml workflow that could be enhanced. Add pylint/flake8 enforcement similar to C++ clang-tidy to catch style issues in tools/scripts that generate code.

• [ ] Enhance .github/workflows/python_checks.yml to include pylint enforcement on src/modules/*/py/ and tools/
• [ ] Create .pylintrc/.flake8 config files matching PX4's C++ style standards
• [ ] Add pre-commit hooks in .github/ instructions for Python linting (similar to .editorconfig for C++)
• [ ] Test against pyros-genmsg, empy, and jinja2 template scripts in the build system

Add docstring coverage requirements for core autopilot modules (estimation.instructions.md, control.instructions.md exist)

The .github/instructions/ directory shows domain-specific modules (estimation, control, drivers, messages) but there's no documented requirement for API docstrings. The dependencies include sphinx/lxml (implied by lxml in list), suggesting documentation generation is valued. A CI check ensuring core modules have docstring coverage would improve maintainability.

• [ ] Create .github/workflows/docstring_coverage.yml to run pydocstyle on src/modules/estimation/ and src/modules/control/
• [ ] Add docstring validation to .clang-tidy or new doxygen configuration for C++ modules
• [ ] Update .github/instructions/code-review.instructions.md to mandate docstrings for modules listed in SKILL.md and instructions/
• [ ] Generate coverage report and post as PR comment using existing pr-comment-poster action

• Add missing unit tests for src/lib/ mathematical utilities (quaternion, matrix operations) — currently only integration-tested via SITL; implement GTest-based tests in src/lib/math/test/ matching existing test patterns: Low risk, isolated, improves code safety in critical flight math
• Expand .github/instructions/board-addition.instructions.md with a complete walkthrough example for a specific board (e.g., STM32F7) including CMake snippet, default.cmake template, and pin mapping checklist: Removes friction for hardware contributors; no code changes, pure documentation with high impact
• Audit and document which .msg files in msg/ are hardware-specific vs. cross-platform; add comments to msg/CMakeLists.txt explaining the message schema registry and deprecation policy: Clarifies the data contract between modules; helps new contributors avoid breaking changes to message formats

• High · Outdated and Vulnerable Dependencies — Dependencies/Package file - pycryptodome, pyserial, pymavlink, requests, lxml. Multiple dependencies have known security vulnerabilities and outdated versions. Notably: pycryptodome (cryptographic library), pyserial (serial communication), pymavlink (protocol handling), and requests (HTTP library) lack version pinning or are pinned to old versions. These are critical for an autopilot system handling UAV control. Fix: Implement strict version pinning with security audit. Use 'pip-audit' or 'safety' to identify CVEs. Update pycryptodome, requests, lxml, and pymavlink to latest secure versions. Implement automated dependency scanning in CI/CD pipeline.
• High · Insecure Setuptools Version Constraint — Dependencies/Package file - setuptools>=39.2.0,<=81.0.0. setuptools is pinned to <=81.0.0 with no lower bound enforcement, potentially allowing installation of severely outdated versions with known security vulnerabilities. Version constraints should be tighter for security-critical components. Fix: Update constraint to a more recent minimum version (e.g., setuptools>=65.0.0,<82.0.0). Use security scanning to identify safe version ranges.
• High · Unpinned Critical Cryptographic Library — Dependencies/Package file - pycryptodome (no version specified). pycryptodome is listed without version constraints, which is extremely risky for an autopilot system that may use cryptography for secure communications. This could allow installation of versions with known vulnerabilities. Fix: Pin to a specific secure version: 'pycryptodome>=3.18.0,<4.0.0'. Regularly audit for CVEs.
• Medium · Unpinned or Loosely Pinned Security-Relevant Libraries — Dependencies/Package file - pyyaml, lxml, requests. Libraries like PyYAML, lxml, and requests lack strict version constraints. These are commonly affected by deserialization, XML parsing, and HTTP security vulnerabilities respectively. Fix: Implement semantic versioning constraints with security audits. Example: pyyaml>=6.0,<7.0; lxml>=4.9.0,<5.0; requests>=2.31.0,<3.0
• Medium · Missing Security Headers and Configuration Management — SECURITY.md, .github configuration. No evidence of security.txt, SECURITY.md completeness, or security headers configuration in the file structure. The SECURITY.md is truncated and lacks full response process details. Fix: Complete SECURITY.md with full vulnerability disclosure timeline. Add security.txt file. Implement security headers in CI/CD and deployment configs.
• Medium · Fuzzing Infrastructure Without Clear Protection — .github/workflows/fuzzing.yml, .github/fuzzing_issue_template.md. Presence of fuzzing workflows (.github/workflows/fuzzing.yml) and fuzzing issue templates suggests fuzzing is performed, but there's no evidence of isolating fuzzing infrastructure or limiting fuzzing to sandboxed environments. Fix: Ensure fuzzing is performed on isolated, sandboxed systems. Implement resource limits and network isolation. Document fuzzing security procedures.
• Medium · Docker Build Without Explicit Security Scanning — .github/actions/build-deb/action.yml, .github/actions/build-gazebo-sitl/action.yml. Multiple GitHub Actions build Docker images (build-deb, build-gazebo-sitl) without evidence of image scanning or signing. No attestation visible for built artifacts. Fix: Add container image scanning (Trivy, Grype) to build pipeline. Implement artifact signing and SBOM generation. Use minimal base images.
• Low · SBOM and License Audit Workflow Present But No Visibility — .github/workflows/sbom_license_check.yml, sbom_monthly_audit.yml. SBOM and license check workflows exist but their failure/success criteria and handling of policy violations are not visible in the provided snippets. Fix: Ensure SBOM generation is mandatory in CI/CD. Publish SBOMs for each release. Document license policy

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.