29.4.1. 자세 목표 생성기(Attitude Setpoint Generator) 아키텍처 (`src/lib/FlightTasks/tasks/ManualPosition`)

1. 자세 목표 생성기의 역할 및 개요

PX4-Autopilot의 자세 목표 생성기(Attitude Setpoint Generator)는 조종기로부터 인가된 물리적 스틱 입력(Stick Input)을 기체가 추종해야 할 3차원 자세 목표(vehicle_attitude_setpoint)로 역산출하는 핵심 컴포넌트이다. 본 섹션에서는 PX4-Autopilot v1.14 소스 코드를 기준으로 src/lib/FlightTasks/tasks/ManualPosition 디렉토리에 위치한 제어 로직의 내부 아키텍처를 심도 있게 분석한다.

안정화(Stabilized) 모드 및 매뉴얼 제어 계통에서는 단순히 스틱의 입력값을 모터의 출력으로 직접 매핑(Direct Mapping)하지 않는다. 대신, 목표 생성기는 사용자의 의도를 수학적으로 체계화된 오일러 각(Euler Angle) 또는 쿼터니언(Quaternion)의 형태로 변환하는 전처리(Preprocessing) 과정을 수행한다. 지상 관제 시스템(GCS)인 QGroundControl v4.3을 통해 수동 명령 파라미터(Manual Command Parameters)를 설정할 때, 이 값들이 내부적으로 어떻게 파싱(Parsing)되어 비행 역학(Flight Dynamics)에 반영되는지를 이해하는 것은 제어기 튜닝 및 에지 케이스(Edge Case) 처리에 필수적이다.

2. 소프트웨어 아키텍처 및 클래스 다이어그램

PX4-Autopilot의 FlightTaskManualPosition 클래스는 FlightTask 기반 클래스로부터 상속받아 구현된다. 다형성(Polymorphism)을 활용한 이 구조는 비행 모드(Flight Mode)에 따라 동적으로 목표(Setpoint) 생성 알고리즘을 스위칭(Switching)할 수 있게 해준다.

classDiagram
    class FlightTask {
        +updateInitialize()
        +update()
        #_evaluateVehicleLocalPosition()
    }
    class FlightTaskManual {
        +scaleManualPenalty()
    }
    class FlightTaskManualPosition {
        - _tilt_setpoint : float
        - _yaw_setpoint : float
        - _thrust_setpoint : float
        + update()
        - _generateAttitudeSetpoint()
        - _applyBankAngleCompensation()
    }
    
    FlightTask <|-- FlightTaskManual
    FlightTaskManual <|-- FlightTaskManualPosition

    FlightTaskManualPosition --> "uORB Topic" manual_control_setpoint : Subscribe
    FlightTaskManualPosition --> "uORB Topic" vehicle_attitude_setpoint : Publish

FlightTaskManualPosition 내부 루틴에서는 manual_control_setpoint uORB 토픽을 정기적으로 폴링(Polling) 혹은 서브스크라이빙(Subscribing)하여 조종자의 스틱 변위값(-1.0 ~ 1.0 정규화된 값)을 실시간으로 취득한다.

3. 자세 목표 산출 알고리즘 분석

3.1 롤(Roll) 및 피치(Pitch) 입력의 변환 로직

안정화 모드 비행에서 조종기의 우측 스틱(Ail/Ele) 입력은 기체의 기울기 각도를 직관적으로 의미한다. 소스 코드 내부의 _generateAttitudeSetpoint() 루틴에서 변환 수식이 적용된다.

입력된 정규화 벡터는 구성 파라미터인 최대 허용 이탈 각도(Maximum Tilt Angle)인 MPC_MAN_TILT_MAX와 비례계산된다.
$\theta_{target} = u_{pitch} \cdot \theta_{max}$
$\phi_{target} = u_{roll} \cdot \phi_{max}$

여기서 제어 신호가 설정된 파라미터의 임계 범위를 초과하는 경우, 하드웨어적 혹은 공기역학적 한계를 방지하기 위해 구속 함수(Constrain Function)가 개입한다.
C++ 코드 레벨에서는 다음과 유사한 math::constrain 인터페이스가 사용된다.

// 피치 축 예시: 입력 스틱 값을 라디안(Radiant) 단위의 각도로 스케일링
float pitch_sp = _manual_control_setpoint.pitch * math::radians(MPC_MAN_TILT_MAX);
pitch_sp = math::constrain(pitch_sp, -math::radians(MPC_MAN_TILT_MAX), math::radians(MPC_MAN_TILT_MAX));

3.2 요(Yaw) 기동의 동적 변환

요(Yaw) 축의 경우 롤/피치 축과는 메커니즘이 전혀 다르다. 요 스틱 입력은 절대적인 각도(Absolute Angle)를 지시하는 것이 아니라 목표 각속도(Yaw Rate) 를 의미한다.
따라서 FlightTaskManualPosition은 요 축의 스틱 입력값을 적분(Integration) 연산하여 지속적인 회전각을 산출해야 한다.
주기 $dt$ 에 따른 요 적분 수식은 피드포워드(Feedforward) 계산 시 다음과 같이 반영된다.

// 요 적분 누적 로직 
_yaw_setpoint += _manual_control_setpoint.yaw * math::radians(MPC_MAN_Y_MAX) * dt;
_yaw_setpoint = matrix::wrap_pi(_yaw_setpoint); // -PI ~ PI 사이로 정규화 (짐벌 락 및 오버플로우 방지)

위 수식에서 보듯, matrix::wrap_pi 함수를 통해 계산된 라디안 단위의 기준점이 모호해짐을 막고 비행 안정성을 도모한다.

3.3 목표 오일러 각에서 쿼터니언 변환

최종적으로 변환된 롤, 피치, 요 각도는 짐벌 락(Gimbal Lock) 등 특이점(Singularity) 현상을 원천적으로 방지하기 위해 쿼터니언(Quaternion) 대수계로 변환된 뒤 vehicle_attitude_setpoint 메시지에 탑재된다.

// Euler to Quaternion 캐스팅 
matrix::Eulerf euler_sp(roll_sp, pitch_sp, _yaw_setpoint);
matrix::Quatf q_sp(euler_sp);

_vehicle_attitude_setpoint_pub.q_d[0] = q_sp(0);
_vehicle_attitude_setpoint_pub.q_d[1] = q_sp(1);
...

4. GCS 및 파라미터 기반 설정 방식

해당 생성기의 동적 응답성은 QGroundControl(QGC)을 통하여 개발자가 환경에 맞춰 정교하게 조율(Tuning)할 수 있다.

MPC_MAN_TILT_MAX (Manual tilt max): 기본값은 통상 35도 내외로 설정되며, 이 값이 작아지면 기체가 RC 응답에 둔감해지고 너무 크면 극단적 자세 변화로 공기역학적 실속(Stall)을 초래할 수 있다.
MPC_MAN_Y_MAX (Manual yaw rate max): 최고 회전 속도를 (deg/s) 단위로 구성하며, 영상 촬영 목적이라면 이 값을 낮추어 시네마틱(Cinematic)한 움직임을 연출할 수 있다.

이처럼 FlightTaskManualPosition 아키텍처는 사람의 부정확하고 단편적인 조종 입력을 무인항공기시스템(UAS) 제어기가 수용할 수 있는 체계적이고 엄밀한 데이터 규격(3D 쿼터니언 및 벡터)으로 전환하는 필수불가결한 역할을 성공적으로 수행하고 있다.
추후 ROS2 미들웨어 환경(uxrce_dds_client)을 통한 오프보드(Offboard) 개입 시에도 이러한 전방 변환 시스템 구조는 동일한 수학적 정합성을 제공한다.

출처 및 참고 문헌: PX4-Autopilot Source Code Repository (src/lib/FlightTasks)

29.4.1. 자세 목표 생성기(Attitude Setpoint Generator) 아키텍처 (src/lib/FlightTasks/tasks/ManualPosition)