MAVSDK-Python 프로그래밍 완벽 가이드 [제4편]: MAVSDK 라이브러리 주요 클래스 알아보기

안녕하세요! 자율비행 연구와 드론 애플리케이션 개발의 세계로 깊이 들어가고 계신 대학생, 그리고 연구원 여러분.

지난 3편에서는 원격 제어를 위한 MAVSDK Server 구축이라는 꽤 까다롭지만 중요한 인프라 설정을 마쳤습니다. 이제 통신 환경이 완벽하게 준비되었으니, 드론에게 어떤 명령어(단어)들을 사용하여 구체적인 명령을 내릴 것인지 알아야 할 차례입니다.

이번 **[제4편: MAVSDK 라이브러리 주요 클래스 알아보기]**에서는 MAVSDK-Python이 제공하는 풍부한 API 클래스(플러그인)들을 살펴보고, 각 클래스가 실제 연구와 비행 제어에서 어떻게 활용되는지 상세히 분석해 보겠습니다. 드론과 대화하기 위한 ‘어휘력’을 기르는 아주 중요한 시간이 될 것입니다.

1. MAVSDK 클래스 구조의 이해: 모든 것은 ‘System’에서 시작된다

MAVSDK는 MAVLink 통신 프로토콜의 복잡한 메시지들을 목적과 기능에 맞게 여러 개의 클래스(Class) 로 분류하여 직관적인 API로 제공합니다.

이러한 수많은 기능들을 하나로 묶어주는 최상위 객체가 바로 System 클래스입니다. 여러분은 파이썬 코드에서 가장 먼저 System() 객체를 생성(예: drone = System())하여 특정 기체(차량)와 연결하게 됩니다. 연결이 성공하고 나면, System 객체 내부에 포함된 다양한 하위 클래스(플러그인)들을 통해 드론을 조종하고 정보를 얻을 수 있습니다.

아래에서 연구원들이 가장 빈번하게 사용하게 될 핵심 클래스 5가지를 심층적으로 파헤쳐 보겠습니다.

2. 핵심 제어 클래스: Action (기본 동작 제어)

Action 클래스는 드론의 가장 기초적이고 필수적인 동작들을 명령할 때 사용합니다. 자율비행 알고리즘을 테스트하기 전, 기체를 이륙시키고 안전하게 착륙시키는 것은 모든 실험의 기본이겠죠?

이 클래스를 사용하면 복잡한 설정 없이 단 한 줄의 코드로 드론을 조작할 수 있습니다. Action 클래스의 주요 메서드는 다음과 같습니다.

• arm(): 드론의 모터에 시동을 겁니다(무장). 프로펠러가 회전하기 시작하므로 항상 안전에 유의해야 합니다.
• takeoff(): 드론이 이륙합니다. 기본적으로 지정된 이륙 고도(보통 2.5m~3m)까지 상승한 후 호버링(제자리 비행) 상태를 유지합니다.
• land(): 현재 위치에서 수직으로 하강하여 안전하게 착륙합니다.
• goto_location(latitude_deg, longitude_deg, absolute_altitude_m, yaw_deg): 특정 GPS 위도/경도 좌표와 고도를 지정하여 기체를 해당 위치로 바로 이동시킵니다.

[Action 클래스 활용 예제]

import asyncio
from mavsdk import System

async def test_action():
    drone = System()
    await drone.connect()
    
    print("모터 시동 (Arming)")
    await drone.action.arm() # Action 클래스 사용 [6]
    
    print("이륙 (Takeoff)")
    await drone.action.takeoff() # Action 클래스 사용 [6]
    await asyncio.sleep(10)
    
    print("착륙 (Landing)")
    await drone.action.land() # Action 클래스 사용 [6]

if __name__ == "__main__":
    asyncio.run(test_action())

import asyncio
from mavsdk import System

async def test_action():
    drone = System()
    await drone.connect()
    
    print("모터 시동 (Arming)")
    await drone.action.arm() # Action 클래스 사용 [6]
    
    print("이륙 (Takeoff)")
    await drone.action.takeoff() # Action 클래스 사용 [6]
    await asyncio.sleep(10)
    
    print("착륙 (Landing)")
    await drone.action.land() # Action 클래스 사용 [6]

if __name__ == "__main__":
    asyncio.run(test_action())

3. 정보 수집의 핵심: Telemetry (원격 측정 및 상태 모니터링)

논문을 쓰거나 비행 데이터를 분석해야 하는 연구원들에게 가장 중요한 클래스가 바로 **Telemetry**입니다. 이 클래스는 드론의 현재 위치, 배터리 상태, 비행 모드, 센서 상태 등 원격 측정 정보를 실시간으로 가져옵니다.

파이썬의 비동기 반복문인 async for 문법과 결합하여, 끊임없이 쏟아지는 센서 데이터 스트림을 효율적으로 구독(Subscribe)할 수 있습니다.

• position(): 위도, 경도, 절대 고도, 상대 고도 등의 정보를 제공합니다.
• battery(): 남은 배터리 전압 및 퍼센트(%) 정보를 제공합니다.
• flight_mode(): 기체가 현재 어떤 모드(HOLD, MISSION, OFFBOARD 등)에 있는지 반환합니다.
• health(): GPS 수신 상태나 자이로/가속도계 센서의 정상 작동 여부(Global Position Estimate 등)를 확인합니다. 비행 전 안전 체크에 필수적입니다.

[Telemetry 클래스 활용 예제]

async def print_telemetry(drone):
    # 드론의 실시간 배터리 정보를 비동기로 계속 수신 [8]
    async for battery in drone.telemetry.battery():
        print(f"현재 배터리: {battery.remaining_percent * 100:.1f}%")

async def print_telemetry(drone):
    # 드론의 실시간 배터리 정보를 비동기로 계속 수신 [8]
    async for battery in drone.telemetry.battery():
        print(f"현재 배터리: {battery.remaining_percent * 100:.1f}%")

4. 자율 비행의 꽃: Mission (웨이포인트 임무)

드론이 단순히 한 곳으로 이동하는 것을 넘어, 여러 경유지(Waypoint)를 거치며 사진을 촬영하거나 복잡한 경로를 순찰해야 한다면 Mission 클래스를 사용해야 합니다.

사용자는 MissionItem 객체를 여러 개 생성하여 하나의 미션 플랜(Mission Plan)으로 묶은 뒤, 기체에 업로드하여 자율비행을 수행할 수 있습니다. QGroundControl과 같은 지상국 소프트웨어에서 그리는 경로 비행을 코드로 직접 구현하는 기능입니다.

• upload_mission(mission_plan): 작성된 미션을 드론의 비행 제어기로 전송합니다.
• start_mission(): 업로드된 미션을 수행하도록 명령합니다.
• set_return_to_launch_after_mission(True/False): 미션이 끝난 후 이륙했던 출발지로 자동으로 돌아올지(RTL) 여부를 설정합니다.

5. 정밀 제어와 연구를 위한 고급 클래스: Offboard

학부생이나 대학원생 여러분이 컴퓨터 비전(Computer Vision) 기반의 객체 추적, 강화학습(RL) 기반의 장애물 회피 알고리즘 등을 연구하신다면, Offboard 클래스를 가장 많이 다루게 될 것입니다.

일반적인 GPS 기반의 이동이 아니라, 드론 외부에 있는 컴패니언 컴퓨터가 초당 수십 번씩 속도, 가속도, 위치 제어 신호(Setpoint)를 드론에게 직접 쏘아주어 정밀하게 움직이는 방식입니다.

• set_velocity_body(): 기체의 전/후/좌/우(Body 기준) 방향으로 목표 속도를 줍니다. (예: “앞으로 2m/s 속도로 전진해!”).
• set_position_ned(): 로컬 좌표계(NED: North-East-Down)를 기준으로 목표 위치로 이동합니다. (예: “현재 위치에서 북쪽으로 5m, 고도 10m 위치로 가!”).
• set_position_velocity_ned(): 위치와 속도를 동시에 제어하는 피드포워드(Feed-Forward) 방식을 통해 제어의 반응성과 정밀도를 극대화합니다.

이 클래스는 매우 빠르고 민첩한 반응을 보여주지만, 주기적으로 제어 신호(Heart-beat)를 주지 않으면 안전을 위해 드론이 즉각 연결을 끊고 착륙해 버리므로 세심한 프로그래밍이 요구됩니다.

6. 그 외 알아두면 유용한 기타 클래스들

MAVSDK는 위에서 소개한 핵심 클래스들 외에도 특수한 목적을 위한 다양한 클래스들을 지원합니다.

• Info: 기체 시스템의 하드웨어 식별자(UID) 및 소프트웨어 펌웨어 버전에 대한 기본 정보를 가져옵니다.
• Param: MAVLink 매개변수(Parameter)를 직접 가져오고 설정하기 위한 로우레벨(Raw) 접근을 제공합니다. 특정 기체 세팅값을 코드에서 동적으로 변경할 때 유용합니다.
• ManualControl: 조종기 스틱을 움직이듯, 코드에서 직접 롤(Roll), 피치(Pitch), 스로틀(Throttle), 요(Yaw) 값을 주입하여 수동 제어를 구현할 때 사용합니다. 키보드로 기체를 조종하는 예제에서 주로 사용됩니다.
• Camera 및 Gimbal: 드론에 탑재된 카메라의 사진/영상 촬영 트리거를 제어하고, 짐벌의 각도를 조절할 수 있습니다.
• MissionRaw 및 MavlinkPassthrough: 기존 MAVSDK API가 제공하지 않는 특수한 기능이 필요할 때, MAVLink 메시지를 직접 작성하여 통신할 수 있는 최하위 레벨의 통신로를 제공합니다.

7. 종합 예제: 클래스들의 협동 플레이

그렇다면 실제 코드에서는 이 클래스들이 어떻게 어우러져 작동할까요? System, Telemetry, Action 클래스가 함께 사용되는 전형적인 이착륙 로직을 살펴보겠습니다.

import asyncio
from mavsdk import System

async def run():
    # 1. System 클래스를 통한 드론 객체 생성 및 연결 [1, 18]
    drone = System()
    await drone.connect(system_address="udp://:14540")
    
    print("드론의 GPS 위치 신호가 안정화되기를 기다립니다...")
    # 2. Telemetry 클래스를 통해 기체 상태(health) 체크 [6, 9]
    async for health in drone.telemetry.health():
        if health.is_global_position_ok and health.is_home_position_ok:
            print("-- GPS 위치 확인 완료! 비행 가능 상태입니다.")
            break
            
    # 3. Action 클래스를 이용한 제어 [6]
    print("-- 모터 시동 (Arming)")
    await drone.action.arm()
    
    print("-- 이륙 (Takeoff)")
    await drone.action.takeoff()
    
    # 공중에서 5초간 대기 (비동기 지연)
    await asyncio.sleep(5)
    
    print("-- 착륙 (Landing)")
    await drone.action.land()

if __name__ == "__main__":
    asyncio.run(run())

import asyncio
from mavsdk import System

async def run():
    # 1. System 클래스를 통한 드론 객체 생성 및 연결 [1, 18]
    drone = System()
    await drone.connect(system_address="udp://:14540")
    
    print("드론의 GPS 위치 신호가 안정화되기를 기다립니다...")
    # 2. Telemetry 클래스를 통해 기체 상태(health) 체크 [6, 9]
    async for health in drone.telemetry.health():
        if health.is_global_position_ok and health.is_home_position_ok:
            print("-- GPS 위치 확인 완료! 비행 가능 상태입니다.")
            break
            
    # 3. Action 클래스를 이용한 제어 [6]
    print("-- 모터 시동 (Arming)")
    await drone.action.arm()
    
    print("-- 이륙 (Takeoff)")
    await drone.action.takeoff()
    
    # 공중에서 5초간 대기 (비동기 지연)
    await asyncio.sleep(5)
    
    print("-- 착륙 (Landing)")
    await drone.action.land()

if __name__ == "__main__":
    asyncio.run(run())

위 코드처럼 연구원 여러분은 drone.telemetry를 이용해 안전을 확인한 뒤, drone.action을 이용해 명령을 내리는 등 클래스들을 블록 장난감처럼 조립하여 복잡한 자율비행 논리를 완성하게 됩니다.

마치며

이번 제4편에서는 MAVSDK-Python이 제공하는 방대하고 강력한 기능들을 System, Action, Telemetry, Mission, Offboard 등의 주요 클래스를 통해 알아보았습니다. 드론에게 어떤 방식으로 명령을 내릴 수 있는지 감이 좀 잡히시나요?

오늘 예제 코드들을 자세히 살펴보면 async def, await, async for 등 일반적인 파이썬 코드에서는 자주 보지 못했던 문법들이 등장합니다. MAVSDK-Python은 실시간성이 생명인 드론 통신을 위해 철저하게 비동기(Asynchronous) 방식으로 설계되었기 때문입니다.

따라서 다음 **[제5편: MAVSDK 제어를 위한 Python ‘asyncio’ 완벽 이해]**에서는, 프로그래머들이 가장 어려워하지만 절대 피할 수 없는 ‘파이썬 비동기 프로그래밍’에 대해 아주 친절하고 속 시원하게 파헤쳐 보도록 하겠습니다.

오늘 배운 클래스들이 비동기 세상에서 어떻게 병렬로 춤을 추는지 기대해 주세요! 질문이 있으시다면 언제든 댓글 남겨 주시기 바랍니다. 감사합니다.

YouTube 강좌

Author: maponarooo, CEO of QUAD Drone Lab

Date: March 3, 2026