# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gremsy.com/gimbals/general.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.