# GENERAL

General Overview This section provides a technical overview of key components in Gremsy gimbal integration workflows:

Gimbal Configuration: Covers parameters related to motor tuning, axis behavior, stabilization modes, control input sources (SBUS, MAVLink, Serial), and follow/lock configurations. These settings define how the gimbal responds to aircraft motion and external commands.

LED Indicators: Gremsy gimbals share a unified LED signaling system that provides real-time status feedback. LED patterns reflect system states such as initialization, active stabilization, input recognition, IMU calibration, and fault detection.

Autopilot Setup: Outlines the standard integration process with flight controllers (e.g., ArduPilot, PX4) using MAVLink protocols. This includes configuring mount types, enabling gimbal control commands (e.g., MAV\_CMD\_DO\_MOUNT\_CONTROL), and ensuring proper orientation and feedback channels.

These foundational components are common across all supported Gremsy gimbals and are critical for both standalone and autopilot-based operations.

## Frame Control

***

#### GIMBAL\_DEVICE\_ATTITUDE\_STATUS – Firmware v787 Update

Starting from **Firmware v787**, several important changes have been introduced to improve compatibility with **QGroundControl (QGC)** and newer **Flight Controller (FC)** firmware.\
The most significant update affects the **`GIMBAL_DEVICE_ATTITUDE_STATUS`** message.\
This section explains the new behavior and how to handle it properly.

***

### 1. Relative Angle and Absolute Angle

#### 1.1 Relative Angle

The **relative angle** is measured based on the aircraft’s heading.

| Direction                       | Angle |
| ------------------------------- | ----- |
| Facing straight (aircraft nose) | 0°    |
| Turn left                       | –90°  |
| Turn right                      | +90°  |

When the aircraft rotates, the relative angle also changes.\
In other words, this angle is fixed relative to the aircraft’s body.

#### 1.2 Absolute Angle

The **absolute angle** is measured based on a fixed global reference — **True North**.

| Direction    | Angle |
| ------------ | ----- |
| Facing North | 0°    |

Even if the aircraft rotates, the absolute angle remains constant with respect to North.

#### 1.3 UAV–Gimbal Relationship

* **Relative angle:** Gimbal rotation relative to the aircraft heading.
* **Absolute angle:** Gimbal rotation relative to geographic North.

***

### 2. How the Gimbal Determines Orientation

1. **During startup**\
   When the gimbal is powered on, it does not yet know where North is.\
   It temporarily assumes that the aircraft’s heading equals North.\
   Therefore, at this point:

   > Absolute angle = Relative angle
2. **After Drone Angle Reference synchronization**\
   The gimbal can determine True North only after performing the **Drone Angle Reference** procedure.\
   ([Documentation link](https://docs.gremsy.com/gremsy-app/gtune-desktop/faq#what-are-the-conditions-for-the-drone-angle-ref...))

   Once synchronization is successful:

   * The gimbal recalibrates so that **0° absolute** corresponds to **True North**.
   * The gimbal then sends the flag:

     ```
     GIMBAL_DEVICE_FLAGS_ACCEPTS_YAW_IN_EARTH_FRAME
     ```

     This indicates that the gimbal is now ready to work in the Earth (absolute) frame.

***

### 3. Differences Between Old and New Firmware

#### 3.1 Before v787

* If the gimbal sent the flag `GIMBAL_DEVICE_FLAGS_YAW_LOCK`,\
  → `q[4]` represented the **absolute angle**.
* If operating in **Follow mode**,\
  → `q[4]` represented the **relative angle**.

#### 3.2 From v787 Onward

The meaning of `q[4]` is now determined by two dedicated flags:

| Flag                                       | Description                                                                                 |
| ------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `GIMBAL_DEVICE_FLAGS_YAW_IN_VEHICLE_FRAME` | Gimbal reports **relative angle** (0° = aircraft heading).                                  |
| `GIMBAL_DEVICE_FLAGS_YAW_IN_EARTH_FRAME`   | Gimbal reports **absolute angle** (0° = North, only available after Drone Angle Reference). |

> **Note:**\
> The flag `GIMBAL_DEVICE_FLAGS_YAW_LOCK` now only indicates **Lock/Follow mode** and no longer determines the content of `q[4]`.

***

### 4. Conversion Between Relative and Absolute Angles

#### 4.1 When the Gimbal Reports Relative Angles (Vehicle Frame)

You can calculate the **absolute angle** using the `delta_yaw` field in the message\
(`delta_yaw` = the difference between aircraft heading and North).

**Euler form:**

```
yaw_earth = delta_yaw + yaw_vehicle
```

**Quaternion form:**

```
q_earth = q_delta_yaw * q_vehicle
```

Where:

* `yaw_earth`: absolute yaw (relative to North)
* `yaw_vehicle`: relative yaw (relative to aircraft)
* `delta_yaw`: heading offset between aircraft and North
* `q_delta_yaw`: quaternion equivalent of \[0, 0, delta\_yaw]

***

#### 4.2 When the Gimbal Reports Absolute Angles (Earth Frame)

You can calculate the **relative angle** by subtracting `delta_yaw`.

**Euler form:**

```
yaw_vehicle = yaw_earth - delta_yaw
```

**Quaternion form:**

```
q_vehicle = q_delta_yaw_inverse * q_earth
```

Where:

* `q_vehicle`: quaternion of relative angle
* `q_earth`: quaternion of absolute angle
* `q_delta_yaw_inverse`: inverse of `q_delta_yaw`

***

### 5. Practical Application

In the current customer case, the gimbal is sending **angles in the relative frame**.\
When operating in **Lock mode**, these angles need to be **converted into the absolute frame** using the methods described in Section 4.