Metadata-Version: 2.4
Name: aerosim_drone
Version: 0.1.8
Summary: WebSocket drone client for AeroSim
Author: aerosim
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: websockets
Requires-Dist: asyncio

# 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)
- [navigate_global](#navigate_global)
- [set_altitude](#set_altitude)
- [set_attitude](#set_attitude)
- [set_position](#set_position)
- [set_rates](#set_rates)
- [set_velocity](#set_velocity)
- [set_yaw](#set_yaw)
- [set_yaw_rate](#set_yaw_rate)
- [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 last received 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 last received telemetry

Telemetry
├── frame_id: str
├── 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 frame_id: Coordinate system for values x, y, z and yaw. Example: map, body, aruco_map. Default value: map.
: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` | `` |
| `frame_id` | `str` | `map` |
| `auto_arm` | `bool` | `False` |

### Example

```python
from aerosim_drone import Drone

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

---

## navigate_global

``` 
Flying in a straight line to a point in the global coordinate system (latitude/longitude).

:param lat: Latitude
:param lon: Longitude
:param z: Altitude (m)
:param yaw: Yaw angle (radians)
:param speed: Flight speed (setpoint speed) (m/s)
:param frame_id: Coordinate system for values x, y, z and yaw. Example: map, body, aruco_map. Default value: map.
:param auto_arm: Switch the drone to OFFBOARD and arm automatically (the drone will take off)
:return: None
```

### Parameters

| Name | Type | Default |
|------|------|---------|
| `lat` | `float` | `` |
| `lon` | `float` | `` |
| `z` | `float` | `` |
| `yaw` | `float` | `` |
| `speed` | `float` | `` |
| `frame_id` | `str` | `map` |
| `auto_arm` | `bool` | `False` |

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.navigate_global(lat, lon, z, yaw, speed, frame_id, auto_arm)
```

---

## set_altitude

``` 
Change the desired flight altitude. The service is used to set the altitude and its coordinate system independently, after calling navigate or set_position.

:param z: Altitude
:param frame_id: Coordinate system for values x, y, z and yaw. Example: map, body, aruco_map. Default value: map.
:return: None
```

### Parameters

| Name | Type | Default |
|------|------|---------|
| `z` | `float` | `` |
| `frame_id` | `str` | `map` |

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.set_altitude(z, frame_id)
```

---

## set_attitude

``` 
Set roll, pitch, yaw and throttle level (similar to the STABILIZED mode). This service may be used for lower level control of the drone behavior, or controlling the drone when no reliable data on its position is available.

:param roll: Requested roll (radians)
:param pitch: Requested pitch (radians)
:param yaw: Requested yaw (radians)
:param thrust: Throttle level, ranges from 0 (no throttle, propellers are stopped) to 1 (full throttle).
:param frame_id: Coordinate system for values x, y, z and yaw. Example: map, body, aruco_map. Default value: map.
:param auto_arm: switch the drone to OFFBOARD and arm automatically (the drone will take off)
:return: None
```

### Parameters

| Name | Type | Default |
|------|------|---------|
| `roll` | `float` | `` |
| `pitch` | `float` | `` |
| `yaw` | `float` | `` |
| `thrust` | `float` | `` |
| `frame_id` | `str` | `map` |
| `auto_arm` | `bool` | `False` |

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.set_attitude(roll, pitch, yaw, thrust, frame_id, auto_arm)
```

---

## set_position

``` 
Set the setpoint for position and yaw. This service may be used to specify the continuous flow of target points, for example, for flying along complex trajectories (circular, arcuate, etc.).

:param x: Point coordinate x
:param y: Point coordinate y
:param z: Point coordinate z
:param yaw: Yaw angle (radians)
:param frame_id: Coordinate system for values x, y, z and yaw. Example: map, body, aruco_map. Default value: map.
: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` | `` |
| `yaw` | `float` | `` |
| `frame_id` | `str` | `map` |
| `auto_arm` | `bool` | `False` |

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.set_position(x, y, z, yaw, frame_id, auto_arm)
```

---

## set_rates

``` 
Set roll, pitch, yaw and throttle level (similar to the STABILIZED mode). This service may be used for lower level control of the drone behavior, or controlling the drone when no reliable data on its position is available.

:param roll_rate: Roll rate (rad/s)
:param pitch_rate: Pitch rate (rad/s)
:param yaw_rate: Yaw rate (rad/s)
:param thrust: Throttle level, ranges from 0 (no throttle, propellers are stopped) to 1 (full throttle).
:param auto_arm: Switch the drone to OFFBOARD and arm automatically (the drone will take off)
:return: None
```

### Parameters

| Name | Type | Default |
|------|------|---------|
| `roll_rate` | `float` | `` |
| `pitch_rate` | `float` | `` |
| `yaw_rate` | `float` | `` |
| `thrust` | `float` | `` |
| `auto_arm` | `bool` | `False` |

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.set_rates(roll_rate, pitch_rate, yaw_rate, thrust, auto_arm)
```

---

## set_velocity

``` 
Set the setpoint for position and yaw. This service may be used to specify the continuous flow of target points, for example, for flying along complex trajectories (circular, arcuate, etc.).

:param vx: Flight speed (m/s) x
:param vy: Flight speed (m/s) y
:param vz: Flight speed (m/s) z
:param yaw: Yaw angle (radians)
:param frame_id: Coordinate system for values x, y, z and yaw. Example: map, body, aruco_map. Default value: map.
:param auto_arm: Switch the drone to OFFBOARD and arm automatically (the drone will take off)
:return: None
```

### Parameters

| Name | Type | Default |
|------|------|---------|
| `vx` | `float` | `` |
| `vy` | `float` | `` |
| `vz` | `float` | `` |
| `yaw` | `float` | `` |
| `frame_id` | `str` | `map` |
| `auto_arm` | `bool` | `False` |

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.set_velocity(vx, vy, vz, yaw, frame_id, auto_arm)
```

---

## set_yaw

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

:param yaw: Yaw angle (radians)
:param frame_id: Coordinate system for computing the yaw. Default value: map.
:return: None
```

### Parameters

| Name | Type | Default |
|------|------|---------|
| `yaw` | `float` | `` |
| `frame_id` | `str` | `map` |

### Example

```python
from aerosim_drone import Drone

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

---

## set_yaw_rate

``` 
The the desired angular yaw velocity, keeping the previous command in effect.

:param yaw_rate: Angular yaw velocity (rad/s);
:return: None
```

### Parameters

| Name | Type | Default |
|------|------|---------|
| `yaw_rate` | `float` | `` |
| `frame_id` | `str` | `map` |

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.set_yaw_rate(yaw_rate, frame_id)
```

---
## take_off

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

### Parameters

| Name | Type | Default |
|------|------|---------|
| `y` | `float` | `` |

### Example

```python
from aerosim_drone import Drone

drone = Drone()
drone.take_off(y)
```

---
# Models
---

## Telemetry

```
Telemetry
├── frame_id: str
├── 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
- `frame_id` (str): Coordinate frame reference identifier.
- `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.
