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) 연동법