> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalrobotics.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# PX4 Integration

> Learn how to integrate GRID with PX4

## Overview

As PX4 is a popular open-source flight control software, GRID has been designed with PX4 integration in mind to make the jump from simulation to real flight as seamless as possible.
This page will cover the basic clients and communication structure used to deploy real world drones from GRID.

## `MavLinkClient`

To facilitate communication from GRID to a PX4-enabled drone, we have created a `MavLinkClient` class.
This client handles low-level communication via MavLink, the lightweight messaging protocol at the heart of PX4.
Features of the `MavLinkClient` include:

* It enables fundamental message exchange between GRID and drone with acknowledgment and error handling while also providing basic functionality such as position and velocity setpoint modification.
* With the breadth of PX4 development, we support the common MavLink message set out of the box but constructed the client with extensibility in mind. Any custom message types are parsed automatically and can be handled by the user as desired.
* The client handles [RTSP](https://en.wikipedia.org/wiki/Real-Time_Streaming_Protocol) video streams from the drone to allow video/image ingestion into GRID.

<Note>
  The `MavLinkClient` is typically used as part of a higher level class  to ease the deployment from the [AirGen](/simulation/airgen/overview) simulation environment while including any formfactor-specific functionality.

  An example of this is the [`ModalaiDrone`](/robot-api/reference/robot/aerial/modalai_drone/ModalaiDrone) which uses the `MavLinkClient` to replicates the functionality of [`AirGenDrone`](/robot-api/reference/robot/aerial/airgen_drone/AirGenDrone) for a ModalAI Starling 2 Max.
</Note>

### MavLink Connection Configuration

To configure the `MavLinkClient`, you need to provide the following connection parameters to match your drone's setup:

* `ground_control_station_ip`: IP address of the GRID-connected computer from which commands are to be sent to the drone, referred to as the ground control station (GCS) in MavLink terminology
* `mavlink_port`: port number for mavlink connection
* `communication_protocol`: communication protocol to use, *i.e.* 'udp', 'tcp'
* `vehicle_ip`: IP address of the drone where the RTSP video streams can be found
* `camera_streams`: dictionary of camera streams to be used, where the key is the stream name and the value is a dictionary containing the port and path for the RTSP stream
* `arm_enable`: whether to enable arming the drone
* `known_messages`: list of known MavLink messages which should be expected by the client. This is used to filter out unknown messages and can be useful for debugging.

```python theme={null}
client = MavlinkClient(
    ground_control_station_ip="192.168.8.10",
    mavlink_port="14550",
    vehicle_ip="192.168.8.1",
    camera_streams={
        "hires_front_small": {"port": 8900, "path": "/live"},
    },
    arm_enable=False,
    known_messages=["HEARTBEAT", "LOCAL_POSITION_NED", "COMMAND_ACK"],
)
```

<Note>
  The exact networking configuration of your drone is manufacturer-specific. Please refer to your drone's documentation for the correct networking information.
</Note>

### Utilities

In addition to establishing a connection and setting up continuous communication, the `MavLinkClient` provides several utility functions to simplify common tasks and ensure robust drone operations:

* **Robust Command Sending:**\
  The `attempt_command` method sends arbitrary MavLink commands with built-in retry logic, ensuring that critical commands (such as arming, setting offboard control, or custom message rates) are reliably executed.

* **Message Filtering and Handling:**\
  Incoming messages are processed and filtered based on a predefined list of known message types. This helps both to handle expected messages (like `HEARTBEAT`, `LOCAL_POSITION_NED`, and `COMMAND_ACK`) and to flag any unexpected communications, aiding in debugging and system monitoring.

* **Heartbeat and Component Discovery:**\
  Before enabling further operations, the client waits for a heartbeat from the drone. It then proceeds to automatically discover system components (e.g., the main drone and any associated camera module), dynamically configuring targets for subsequent commands.

* **Video Stream Management:**\
  Integrated with a `VideoStreamManager`, the client supports RTSP video streaming. The `get_single_frame` method, for example, captures a single image from a specified camera stream and converts it to a usable RGB format.

* **Setpoint Maintenance:**\
  A dedicated thread continually updates and transmits flight setpoints, providing smooth and consistent control during offboard operations. The `update_setpoint` utility further enables dynamic adjustment of key flight parameters on the fly.

Overall, these utilities ensure that the `MavLinkClient` can not only handle low-level communication tasks but also provide higher-level operational robustness and flexibility for real-world drone integration with GRID.

<Note>
  For full details on the `MavLinkClient` class, please refer to the [`MavLinkClient` API documentation](/robot-api/reference/robot/aerial/mavlink_client/MavlinkClient).
</Note>