aerosim-drone 0.1.15
WebSocket drone client for AeroSim
License: MIT
Requires Python: >=3.9

# aerosim_drone

Simple WebSocket client for AeroSim Drone.

## Installation
```bash
pip install aerosim_drone
```
## Usage
```python
from aerosim_drone import Drone

drone = Drone()
drone.connect()
drone.arm()
```

## Drone Class Methods

- [arm](#arm)
- [connect](#connect)
- [disconnect](#disconnect)
- [get_detections](#get_detections)
- [get_telemetry](#get_telemetry)
- [land](#land)
- [navigate](#navigate)
- [set_yaw](#set_yaw)
- [take_off](#take_off)

## Models

- [telemetry](#telemetry) 
- [detections](#detections) 


# Drone Class Methods

---

## arm

``` 
Arms the drone
:return: None
```

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.arm()
```

---

## connect

_No description provided._

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.connect()
```

---

## Disconnect

_No description provided._

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.disconnect()
```

---

## get_detections

``` 
Get current detections

Detections
└── detections: List[GateDetection]
    ├── index: int
    ├── distance: float
    ├── gate: Gate
    │   ├── type: GateType
    │   │   ├── Square (0)
    │   │   ├── Cone (1)
    │   │   ├── EmptySquare (2)
    │   │   └── Arc (3)
    │   └── color: GateColor
    │       ├── Red (0)
    │       └── Green (1)
    └── position: Position
        ├── x: float
        ├── y: float
        └── z: float
```

**Returns:** `Detections`

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.Connect()
drone.Arm()
detections = drone.get_detections()
```

---

## get_telemetry

``` 
Get current telemetry

Telemetry
├── connected: bool
├── armed: bool
├── mode: FlightMode
│   ├── StabilizedManual (0)
│   ├── Acro (1)
│   ├── Rattitude (2)
│   ├── Altctl (3)
│   ├── Posctl (4)
│   ├── Offboard (5)
│   ├── AutoMission (6)
│   ├── AutoRtl (7)
│   └── AutoLand (8)
├── x: float
├── y: float
├── z: float
├── lat: float
├── lon: float
├── alt: float
├── vx: float
├── vy: float
├── vz: float
├── roll: float
├── pitch: float
├── yaw: float
├── roll_rate: float
├── pitch_rate: float
├── yaw_rate: float
├── voltage: float
└── cell_voltage: float
```

**Returns:** `Telemetry`

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.Connect()
drone.Arm()
telemetry = drone.get_telemetry()
```

---

## land

``` 
Lands the drone
:return: None
```

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.land()
```

---

## navigate

``` 
Fly to the designated point in a straight line.

:param x: Coordinate x
:param y: Coordinate y
:param z:Coordinate z
:param speed: Flight speed (setpoint speed) (m/s)
:param auto_arm: Switch the drone to OFFBOARD and arm automatically (the drone will take off)
:return: None
```

### Parameters

| Name | Type | Default |
|------|------|---------|
| `x` | `float` | `` |
| `y` | `float` | `` |
| `z` | `float` | `` |
| `speed` | `float` | `` |
| `auto_arm` | `bool` | `False` |

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.navigate(x, y, z, speed, auto_arm)
```

---

## set_yaw

``` 
Change the desired yaw angle (and its coordinate system), keeping the previous command in effect.

:param yaw: Yaw angle (radians)
:return: None
```

### Parameters

| Name | Type | Default |
|------|------|---------|
| `yaw` | `float` | `` |

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.set_yaw(yaw)
```


---
## take_off

``` 
Take off drone
:param z: Coordinate z
:return: None
```

### Parameters

| Name | Type | Default |
|------|------|---------|
| `z`  | `float` | `` |

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.take_off(z=1.0)
```

---
# Models
---

## Telemetry

```
Telemetry
├── connected: bool
├── armed: bool
├── mode: FlightMode
│   ├── StabilizedManual (0)
│   ├── Acro (1)
│   ├── Rattitude (2)
│   ├── Altctl (3)
│   ├── Posctl (4)
│   ├── Offboard (5)
│   ├── AutoMission (6)
│   ├── AutoRtl (7)
│   └── AutoLand (8)
├── x: float
├── y: float
├── z: float
├── lat: float
├── lon: float
├── alt: float
├── vx: float
├── vy: float
├── vz: float
├── roll: float
├── pitch: float
├── yaw: float
├── roll_rate: float
├── pitch_rate: float
├── yaw_rate: float
├── voltage: float
└── cell_voltage: float
```

The `Telemetry` class is a data model designed to store and manage drone state information within the `aerosim_drone` library. 

### Data Attributes

#### System Info
- `connected` (bool): `True` if linked to the flight controller.
- `armed` (bool): `True` if motors are active/armed.
- `mode` (FlightMode): The current flight mode enum member.

#### Spatial Position & Velocity
- `x, y, z` (float): Local coordinates (m).
- `lat, lon` (float): Global WGS84 coordinates (deg).
- `alt` (float): Altitude (m).
- `vx, vy, vz` (float): Linear velocity (m/s).

#### Orientation & Dynamics
- `roll, pitch, yaw` (float): Orientation in Radians.
- `roll_rate, pitch_rate, yaw_rate` (float): Angular velocity in Rad/s.

#### Power Systems
- `voltage` (float): Main battery voltage (V).
- `cell_voltage` (float): Average per-cell voltage (V).

### FlightMode (Enum)
Defines the operational modes of the flight controller:

| Value | Name | Description |
| :--- | :--- | :--- |
| 0 | `StabilizedManual` | Manual control with self-leveling. |
| 1 | `Acro` | Rate control (no auto-level). |
| 2 | `Rattitude` | Combined rate/attitude control. |
| 3 | `Altctl` | Altitude hold mode. |
| 4 | `Posctl` | Position hold mode (GPS dependent). |
| 5 | `Offboard` | External API/Companion computer control. |
| 6 | `AutoMission` | Automatic waypoint navigation. |
| 7 | `AutoRtl` | Return to Launch. |
| 8 | `AutoLand` | Automated landing. |

---

## Detections

```
Detections
└── detections: List[GateDetection]
    ├── index: int
    ├── distance: float
    ├── gate: Gate
    │   ├── type: GateType
    │   │   ├── Square (0)
    │   │   ├── Cone (1)
    │   │   ├── EmptySquare (2)
    │   │   └── Arc (3)
    │   └── color: GateColor
    │       ├── Red (0)
    │       └── Green (1)
    └── position: Position
        ├── x: float
        ├── y: float
        └── z: float
```

This module defines the data structures for gate detection within the `aerosim_drone` simulation environment. It handles spatial data, gate classification, and collection of active detections.


### Enumerations

### `GateType`
Defines the physical shape of the detected gate.
- **Square (0)**: Standard square racing gate.
- **Cone (1)**: Obstacle or marker cone.
- **EmptySquare (2)**: Hollow square frame.
- **Arc (3)**: Curved/Arc-shaped gate.

### `GateColor`
Defines the visual color of the gate.
- **Red (0)**: Red colored gate.
- **Green (1)**: Green colored gate.

---

### Supporting Classes

### `Position`
Represents a 3D coordinate in the world frame.
- **Attributes**: `x`, `y`, `z` (float, meters).

### `Gate`
Describes the static physical properties of a gate.
- **Attributes**: `type` (GateType), `color` (GateColor).

### `GateDetection`
Represents a specific detection instance in the current frame.
- **Attributes**:
    - `gate` (Gate): The physical description.
    - `distance` (float): Distance from the drone to the gate (m).
    - `position` (Position): 3D center coordinates.
    - `index` (int): Gate index relative to the track order.