{"id":6058,"library":"pymavlink","title":"MAVLink Protocol Library for Python","description":"pymavlink is the official Python MAVLink (Micro Air Vehicle Link) protocol implementation. It provides tools for parsing, generating, and communicating MAVLink messages, enabling Python applications to interact with drones, autopilots, and ground control stations. The library is actively maintained by the ArduPilot community and is currently at version 2.4.49, with frequent updates to add features and fix bugs.","status":"active","version":"2.4.49","language":"en","source_language":"en","source_url":"https://github.com/ArduPilot/pymavlink/","tags":["MAVLink","UAV","drone","robotics","autopilot","telemetry","ArduPilot"],"install":[{"cmd":"pip install pymavlink","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides Python 2/3 compatibility helpers, though modern pymavlink targets Python 3.","package":"future","optional":false},{"reason":"Required for parsing MAVLink XML definition files to generate message classes.","package":"lxml","optional":false},{"reason":"Commonly required for serial port communication with MAVLink devices.","package":"pyserial","optional":true}],"imports":[{"symbol":"mavutil","correct":"from pymavlink import mavutil"},{"note":"While `import mavlink` might sometimes work if generated files are in PYTHONPATH, the recommended way is `from pymavlink import mavlink` or accessing it via a `mavutil.mavlink_connection` instance, which ensures the correct dialect is loaded.","wrong":"import mavlink","symbol":"mavlink","correct":"from pymavlink import mavlink"},{"note":"MAVLink message definitions are generated into specific dialects (e.g., `ardupilotmega`, `common`, `minimal`). It's crucial to import messages from the correct dialect, or rely on `mavutil.mavlink_connection` to handle dialect loading implicitly.","wrong":"from pymavlink.mavlink import MAVLink_HEARTBEAT_MESSAGE","symbol":"dialects","correct":"from pymavlink.dialects import ardupilotmega as m"}],"quickstart":{"code":"import os\nimport time\nfrom pymavlink import mavutil\n\n# Define the connection string for your MAVLink device\n# Examples: 'udp:127.0.0.1:14550' (for SITL), 'serial:/dev/ttyACM0:115200' (for a USB serial device)\n# You can set the MAVLINK_CONNECTION_STRING environment variable or change this directly.\nconnection_string = os.environ.get('MAVLINK_CONNECTION_STRING', 'udp:127.0.0.1:14550')\n\nprint(f\"Attempting to connect to MAVLink device via: {connection_string}...\")\n\ntry:\n    # Establish a MAVLink connection. wait_ready=True blocks until the first HEARTBEAT is received.\n    master = mavutil.mavlink_connection(connection_string, baud=115200, wait_ready=True)\n    print(f\"Connection established! System ID: {master.target_system}, Component ID: {master.target_component}\")\n\n    # Request an ATTITUDE data stream at 1Hz\n    # MAV_DATA_STREAM_ALL for all streams, or specific ones like MAV_DATA_STREAM_EXTRA1 for ATTITUDE\n    # The last '1' is the rate in Hz, '0' would stop the stream.\n    master.mav.request_data_stream_send(\n        master.target_system, master.target_component, \n        mavutil.mavlink.MAV_DATA_STREAM_ALL, 1, 1\n    )\n    print(\"Requested data stream for all messages at 1Hz.\")\n\n    print(\"Listening for HEARTBEAT and ATTITUDE messages for 10 seconds...\")\n    start_time = time.time()\n    while (time.time() - start_time) < 10: # Listen for 10 seconds\n        # Non-blocking receive for specific message types\n        msg = master.recv_match(type=['HEARTBEAT', 'ATTITUDE'], blocking=False, timeout=0.1)\n        if msg:\n            print(f\"Received {msg.get_type()} - {msg}\")\n            if msg.get_type() == 'ATTITUDE':\n                print(f\"  Roll: {msg.roll:.2f} deg, Pitch: {msg.pitch:.2f} deg, Yaw: {msg.yaw:.2f} deg\")\n        time.sleep(0.01) # Small delay to prevent busy-waiting\n\n    print(\"Finished listening for messages.\")\n\nexcept Exception as e:\n    print(f\"Error during MAVLink communication: {e}\")","lang":"python","description":"This quickstart demonstrates how to establish a MAVLink connection, request a data stream, and receive and process messages from a MAVLink-enabled device (e.g., a drone autopilot or a SITL simulator). It connects to a configurable MAVLink endpoint, requests all data streams, and then listens for and prints HEARTBEAT and ATTITUDE messages for 10 seconds. Ensure a MAVLink source is available at the specified connection string for the script to function."},"warnings":[{"fix":"When creating a connection, explicitly set the dialect: `master = mavutil.mavlink_connection(connection_string, dialect='mavlink10')`. Ensure your target device is configured to use the correct protocol version.","message":"MAVLink protocol version 1 (MAVLink1) and version 2 (MAVLink2) are incompatible. MAVLink2 introduces message signing, longer message names, and expanded component IDs. pymavlink defaults to MAVLink2, but if connecting to an older MAVLink1 device, you must explicitly specify the protocol version.","severity":"breaking","affected_versions":"All versions (protocol specific)"},{"fix":"Identify the correct MAVLink dialect used by your target device. When creating a `mavutil.mavlink_connection`, the dialect is often auto-detected or can be explicitly set (e.g., `dialect='ardupilotmega'`). If manually constructing messages, import from the specific dialect: `from pymavlink.dialects.ardupilotmega import MAVLink_ATTITUDE_MESSAGE`.","message":"MAVLink message definitions are dialect-specific (e.g., 'ardupilotmega', 'common', 'minimal'). Messages or fields available in one dialect might not exist or have different structures in another. Using the wrong dialect can lead to `AttributeError` when accessing fields or `KeyError` if messages are missing.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate your environment to Python 3.6+ to ensure full compatibility, receive the latest updates, and benefit from ongoing support. The `future` dependency remains primarily for transitional compatibility.","message":"Python 2 support has been officially dropped. While older pymavlink versions might still have some Python 2 compatibility, active development, new features, and bug fixes are exclusively for Python 3. Attempting to use recent versions with Python 2 may result in unexpected errors or missing functionality.","severity":"deprecated","affected_versions":">=2.4.40"},{"fix":"For responsive applications, use `blocking=False` in conjunction with a `timeout` within a loop. This allows your program to perform other tasks or handle periods of no incoming data. Example: `msg = master.recv_match(type=['HEARTBEAT'], blocking=False, timeout=0.1)`.","message":"Using `master.recv_match(blocking=True)` can halt your application indefinitely if no message matches the criteria, especially in single-threaded contexts. This can lead to unresponsive interfaces or deadlocks.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}