Chapter 16. PX4 펌웨어 소스 코드 구조 및 디렉토리 분석

# 1. PX4 최상위 디렉토리(Root) 및 빌드 생태계 구조
16.1.1 최상위 디렉토리 핵심 파일 분석 (CMakeLists.txt, Makefile)
16.1.2 Git Submodule 아키텍처 및 버전 관리 (.gitmodules)
16.1.2.1 platforms/nuttx/NuttX: NuttX RTOS 커널 소스 통합
16.1.2.2 mavlink/include/mavlink/v2.0: MAVLink 프로토콜 C/C++ 헤더
16.1.3 CI/CD 파이프라인 구조 (.github/workflows/)
16.1.4 정적 분석 및 포매팅 설정 파일 (.clang-format, .editorconfig)
# 1. 하드웨어 추상화 및 타겟 보드 설정: boards/ 및 platforms/
16.2.1 boards/ 디렉토리 계층 구조 (Vendor/Board/OS)
16.2.1.1 보드별 모듈 활성화 설정 (default.cmake의 타겟 매크로 분석)
16.2.1.2 하드웨어 핀맵 및 리소스 할당 (board_config.h 및 nuttx-config)
16.2.1.3 부트로더 연동 및 메모리 맵 설정 파일 분석
16.2.2 platforms/ 디렉토리: OS 추상화 계층(PX4 Architecture)
16.2.2.1 nuttx/: 임베디드 실시간 OS 바인딩 및 보드 부트스트랩(board_app_init.c)
16.2.2.2 posix/: SITL(소프트웨어 시뮬레이션) 및 리눅스 환경 추상화
16.2.2.3 common/: Work Queue 및 태스크 스케줄링 API (px4_work_queue, px4_tasks.h)
# 1. 최상위 상태 관리 및 미들웨어: src/modules/ (Part 1)
16.3.1 commander/: 기체 상태 및 모드 관리 알고리즘
16.3.1.1 Commander.cpp: 메인 루프, uORB 상태 구독 및 발행 구조
16.3.1.2 state_machine_helper.cpp: 비행 모드(Flight Mode) 전환 조건 검증 로직
16.3.1.3 시동(Arming) 및 비행 전 점검(Pre-flight Check) 검사 루틴 분석
16.3.1.4 failsafe.cpp: 배터리 부족, 통신 두절(RC/GCS) 시 비상 복구 트리거 로직
16.3.2 navigator/: 임무 및 궤적 생성 메인 로직
16.3.2.1 Navigator.cpp: 모드별(RTL, Mission, Loiter 등) 네비게이션 분기 제어
16.3.2.2 mission.cpp: MAVLink 웨이포인트 파싱 및 다음 웨이포인트 연산 구조
16.3.2.3 rtl.cpp 및 takeoff.cpp: 자동 복귀(Return To Launch) 및 이륙 경로 생성 알고리즘
16.3.3 uORB/: 미들웨어 통신 브로커 내부 구현
16.3.3.1 uORBManager.cpp 및 uORBDeviceNode.cpp: 토픽(Topic) 파일 디스크립터 관리 로직
# 1. 핵심 비행 제어 및 상태 추정: src/modules/ (Part 2)
16.4.1 제어기(Controllers) 아키텍처 및 구현 파일
16.4.1.1 mc_pos_control/: 멀티로터 위치 제어기 (PositionControl.cpp의 P-PID 캐스케이드 구조)
16.4.1.2 mc_att_control/: 멀티로터 자세 제어기 (AttitudeControl.cpp의 쿼터니언 에러 연산)
16.4.1.3 fw_pos_control_l1/: 고정익 L1 네비게이션 로직 (ecl/l1/ecl_l1_pos_controller.cpp)
16.4.2 ekf2/: 상태 추정기(Estimator) 아키텍처
16.4.2.1 EKF2.cpp: uORB 데이터 수집 및 EKF 래퍼(Wrapper) 모듈 스레드
16.4.2.2 EKF/ekf.cpp 및 EKF/covariance.cpp: 상태 행렬 업데이트 및 공분산 예측 수학 모델
16.4.2.3 센서 퓨전 분기: GPS, Optical Flow, VIO 데이터 통합(Fusion) 로직 분석
16.4.3 control_allocator/: 동적 제어 할당 및 믹서(Mixer)
16.4.3.1 ControlAllocation.cpp: 모멘트/추력 명령을 개별 모터 PWM으로 변환하는 알고리즘
16.4.3.2 ActuatorEffectiveness/: 기체 역학(Multirotor, Fixed-wing, VTOL)별 효율성 행렬 클래스
# 1. 하드웨어 드라이버 계층: src/drivers/ 상세
16.5.1 통신 버스 프레임워크 추상화
16.5.1.1 I2C.hpp 및 SPI.hpp: 버스 인터페이스 및 레지스터 읽기/쓰기 래퍼 클래스
16.5.2 관성 센서(IMU) 드라이버 구조
16.5.2.1 imu/: 벤더별(InvenSense, Bosch 등) 드라이버 디렉토리 (icm20689.cpp 예제 분석)
16.5.2.2 FIFO 버퍼 리드(Read) 및 하드웨어 인터럽트(DRDY) 기반 스케줄링 로직
16.5.3 포지셔닝 및 환경 인식 드라이버
16.5.3.1 gps/: u-blox 프로토콜 파서(ublox.cpp), RTCM 주입 및 NMEA 연동 로직
16.5.3.2 distance_sensor/ 및 barometer/: LiDAR, Sonar, 기압계 장치 드라이버
16.5.4 액추에이터 출력 및 텔레메트리 드라이버
16.5.4.1 pwm_out_sim/ 및 하드웨어 PWM 제어 타이머 로직
16.5.4.2 mavlink/: mavlink_receiver.cpp (수신 파서) 및 mavlink_messages.cpp (송신 스트림)
# 1. 시스템 공통 라이브러리 및 명령어: src/lib/ 및 src/systemcmds/
16.6.1 src/lib/: 핵심 수학 및 유틸리티 라이브러리
16.6.1.1 mathlib/: 쿼터니언(Quaternion), DCM 행렬 변환 및 회전 역학 함수
16.6.1.2 matrix/: 하드웨어 가속 및 메모리 최적화를 고려한 템플릿 기반 선형대수 라이브러리
16.6.1.3 perf/: 퍼포먼스 카운터, CPU 타임 측정 및 스레드 지연(Latency) 분석 API
16.6.2 src/systemcmds/: 진단 및 제어 CLI 시스템 명령어
16.6.2.1 param/: 파라미터 파일(BSON 포맷)의 플래시 메모리 저장 및 로드 매커니즘
16.6.2.2 top/, listener/: 실시간 스레드 점유율 및 uORB 토픽 디버깅 명령어 내부 구조
# 1. 시스템 부트스트랩 및 초기화 스크립트: ROMFS/px4fmu_common/
16.7.1 init.d/: 임베디드 부팅 시퀀스 분석
16.7.1.1 rcS: 파일 시스템 마운트, uORB 시작, 파라미터 로드 등 최상위 부트 흐름
16.7.1.2 rc.board_defaults: 타겟 보드별 I2C/SPI 버스 활성화 및 센서 시작 스크립트
16.7.1.3 rc.mc_apps, rc.fw_apps: 멀티로터/고정익 전용 제어기 데몬(Daemon) 실행 분기
16.7.2 init.d/airframes/: 기체 식별 및 환경 설정 매핑
16.7.2.1 SYS_AUTOSTART 파라미터와 기체 설정 스크립트 파일(예: 1001_rc_quad_x)의 매핑 원리
16.7.2.2 기체별 형상(Geometry) 변수 오버라이드 및 튜닝 파라미터 프리셋 구조
# 1. uORB 메시징 체계 및 빌드 자동화: msg/ 및 Tools/
16.8.1 msg/: uORB 메시지 정의 및 생성
16.8.1.1 .msg 파일 문법 구조 및 기본 자료형, 상수 선언 규칙
16.8.1.2 VehicleStatus.msg, ActuatorOutputs.msg 등 코어 시스템 메시지 구조 분석
16.8.1.3 msg/tools/genmsg.py: CMake 빌드 시 .msg를 C/C++ .h 헤더로 자동 변환하는 파이썬 스크립트 원리
16.8.2 Tools/ 및 build/: 빌드 및 시뮬레이션 환경 산출물
16.8.2.1 Tools/sitl_run.sh: Gazebo/jMAVSim 시뮬레이션 환경 실행 및 PX4 데몬 연동 스크립트
16.8.2.2 build/: 컴파일 캐시, 자동 생성된 헤더(uORB/topics/), 최종 바이너리(.px4) 파일 추적
16.8.2.3 .px4 펌웨어 파일 포맷 분석 (JSON 메타데이터 헤더 + 압축된 Zlib 바이너리 구조)
# 1. 사용자 정의 모듈 개발 아키텍처: src/examples/
16.9.1 Work Queue (WQ) 기반 커스텀 모듈 스레드 생성법 (px4_work_queue API 활용)
16.9.2 독립 스레드(Task) 기반 프로세스 모듈 작성 구조 차이 비교
16.9.3 CMakeLists.txt 타겟 추가 및 Kconfig를 이용한 파라미터(QGroundControl UI) 연동법