Metadata-Version: 2.4
Name: quadsim-sdk
Version: 0.13.0
Summary: Python SDK for QuadSim drone simulation
Project-URL: Repository, https://github.com/ninonick0607/QuadSimLib
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pyzmq>=25.0
Requires-Dist: msgpack>=1.0
Provides-Extra: px4
Requires-Dist: pymavlink>=2.4; extra == "px4"

<p align="center">
  <h1 align="center">QuadSim Python SDK</h1>
  <p align="center">
    Research-oriented drone simulation control for Python.
    <br />
    High-level flight commands, raw low-level control, deterministic stepping, and live visualization.
  </p>
</p>

<p align="center">
  <a href="#getting-started">Getting Started</a> •
  <a href="#quick-example">Quick Example</a> •
  <a href="#control-modes">Control Modes</a> •
  <a href="#lockstep-control">Lockstep Control</a> •
  <a href="#coordinate-frame">Coordinate Frame</a> •
  <a href="#api-overview">API Overview</a> •
  <a href="#project-structure">Project Structure</a>
</p>

---

## What is QuadSim?

QuadSim is a research-oriented quadrotor simulation platform built in Unity for controls research, autonomy development, and sim-to-real workflows.

This package is the **Python SDK**. It connects to a running QuadSim Unity scene over ZeroMQ and lets Python code command drones, read sensors, switch control modes, step the simulator deterministically, and stream live visualization data.

The Unity runtime is installed separately:

- Unity plugin: [github.com/ninonick0607/Unity-QuadSim-Plugin](https://github.com/ninonick0607/Unity-QuadSim-Plugin)

The SDK exposes two layers through one simple object model:

```text
QuadSim       ← sim/world entry point, owns the connection
  └─ Drone    ← high-level flight, raw commands, sensors, telemetry, stepping
```

You can move from `takeoff()` to raw `send_command()` or lockstep `step_with_*()` calls without changing objects.

---

## Getting Started

### Requirements

- Python 3.8+
- A running QuadSim Unity scene or headless build
- RPC enabled in Unity through `ExternalRpcAdapter`
- Unity command port, default `5555`
- Unity telemetry port, default `5556`

### Install

From PyPI:

```bash
pip install quadsim-sdk
```

From source:

```bash
git clone https://github.com/ninonick0607/QuadSimLib.git
cd QuadSimLib
pip install -e .
```

This installs the Python dependencies, including `pyzmq` and `msgpack`.

### Verify Connection

Start the Unity scene or headless build first, then run:

```python
from quadsim import QuadSim

with QuadSim() as sim:
    print(sim.get_status())
```

If it prints status information, the SDK is connected.

---

## Quick Example

```python
from quadsim import QuadSim

with QuadSim() as sim:
    drone = sim.drone()

    drone.takeoff(altitude=3.0)
    drone.fly_to(x=5, y=0, z=3)
    drone.hover(duration=2.0)
    drone.yaw_to(heading_deg=180)
    drone.fly_path([(5, 5, 3), (0, 5, 3), (0, 0, 3)])
    drone.land()
```

---

## Control Modes

QuadSim supports high-level scripted flight, cascaded controller modes, motor passthrough, allocated wrench control, and direct wrench control.

The detailed control-mode documentation lives in:

- [docs/control_modes.md](docs/control_modes.md)

That page covers:

- When to use each mode.
- Exact `send_command(...)` layouts.
- How to call `set_mode(...)`.
- How to use one-shot commands versus lockstep `step_with_*` commands.
- Difference between position, velocity, angle, rate, passthrough, allocated wrench, direct wrench, and acceleration helper APIs.
- How to read sensors and telemetry after each command.

Minimal raw example:

```python
import time
from quadsim import QuadSim

with QuadSim() as sim:
    drone = sim.drone()

    drone.takeoff(3.0)

    drone.set_mode("velocity")
    for _ in range(100):
        drone.send_command(vx=1.0, vy=0.0, vz=0.0, yaw_rate=10.0)
        time.sleep(0.02)

    drone.hover(duration=2.0)
    drone.land()
```

---

## Lockstep Control

For tuning, learning, and deterministic experiments, pause the simulator and advance it one control tick at a time.

```python
from quadsim import QuadSim

CONTROL_HZ = 50.0

with QuadSim() as sim:
    drone = sim.drone()
    sim.pause()

    status = sim.get_status()
    steps_per_tick = max(1, round((1.0 / CONTROL_HZ) / status.fixed_dt))

    sensors = drone.get_sensors()
    for _ in range(2500):
        tx, ty, tz, thrust = my_controller(sensors)
        sensors = drone.step_with_wrench(
            tx=tx,
            ty=ty,
            tz=tz,
            thrust=thrust,
            count=steps_per_tick,
        )

    sim.resume()
```

A composite step call applies a command, advances Unity physics, and returns the post-step sensor snapshot in one RPC round trip.

At the default Unity physics rate of 250 Hz, `count=5` gives one 50 Hz controller update.

---

## Async Flight with Polling

High-level methods also have `_async` variants that return a future-like handle:

```python
import time
from quadsim import QuadSim

with QuadSim() as sim:
    drone = sim.drone()
    drone.takeoff(3.0)

    future = drone.fly_to_async(x=10, y=0, z=3, speed=2.0)

    while not future.done:
        pos = drone.get_position()
        print(f"Position: ({pos[0]:.1f}, {pos[1]:.1f}, {pos[2]:.1f})")
        time.sleep(0.5)

    drone.land()
```

---

## Coordinate Frame

Everything the Python SDK exposes uses **FLU** unless an advanced bridge explicitly documents another frame:

| Axis | Direction | Example |
|------|-----------|---------|
| `X` | Forward | `fly_to(x=5, ...)` moves forward |
| `Y` | Left | `fly_to(y=3, ...)` moves left |
| `Z` | Up | `fly_to(z=3, ...)` means 3 meters altitude |

`Z` is altitude for positions and vertical commands.

Common conventions:

| Data | Frame |
|------|-------|
| `gps_position` | World FLU |
| `imu_vel` | Body FLU |
| `imu_ang_vel` | Body FLU |
| `imu_accel` | Body FLU |
| `wrench` torques | Body FLU |
| `position` commands | World FLU |
| `velocity` commands | SDK FLU command convention |
| `passthrough` motors | Motor order: FL, FR, BL, BR |

The Unity adapter handles Unity-frame conversion internally.

---

## Environment / Disturbance

Toggle the scene wind/disturbance field from Python:

```python
drone.set_wind(enabled=True)
drone.set_wind(enabled=True, wind_speed=8.0)
drone.set_wind(enabled=False)
```

With no `wind_speed`, each Unity `WindModule` keeps its scene-configured speed.

---

## Headless Visualization

The SDK includes `UdpViz`, a fire-and-forget UDP sender for live headless visualization.

```python
from quadsim import UdpViz

viz = UdpViz(source="my-run")
viz.path(planned_points)

# inside the loop
viz.sample(t, pos, target=target_pos, err=err, speed=speed, trial=trial_id)
```

Run the viewer separately:

```bash
python live_viewer.py --port 14660
```

Positions are FLU `[x, y, z]`, z-up. If no viewer is listening, packets are dropped and the run continues.

---

## API Overview

### `QuadSim` — Sim / World

| Method | Description |
|--------|-------------|
| `connect()` | Connect to Unity server |
| `disconnect()` | Clean disconnect |
| `drone()` | Get a `Drone` handle |
| `get_status()` | Sim time, fixed dt, pause state, authority |
| `pause()` / `resume()` | Pause/resume simulation |
| `step(count)` | Advance N physics steps |
| `set_time_scale(scale)` | Speed up / slow down free-run mode |
| `reset()` | Reset entire simulation |

### `Drone` — Flight / Control

| Method | Description |
|--------|-------------|
| `takeoff(altitude, speed)` | Climb and stabilize |
| `land(speed)` | Descend to ground |
| `hover(duration)` | Hold position |
| `fly_to(x, y, z, speed, yaw)` | Fly to a position |
| `fly_path(waypoints, speed)` | Follow a waypoint sequence |
| `yaw_to(heading_deg)` | Rotate to heading |
| `set_mode(mode)` | Set raw goal mode |
| `set_controller(controller)` | Switch controller kind |
| `send_command(...)` | Send raw Axis4 command |
| `send_motors(...)` | Send motor passthrough command |
| `send_wrench(...)` | Send allocated wrench command |
| `send_wrench_bypass(...)` | Send direct Rigidbody wrench |
| `step_with_*` | Apply command + step + return sensors |
| `get_sensors()` | Full sensor snapshot |
| `get_telemetry()` | Controller state and motor outputs |
| `reset_pose(...)` | Teleport pose |
| `reset_physics()` | Zero velocities |
| `reset_controller()` | Clear controller state |

### Streaming

| Method | Description |
|--------|-------------|
| `subscribe_sensors(callback, hz)` | Push-based sensor data |
| `subscribe_telemetry(callback, hz)` | Push-based telemetry |
| `subscribe(callback, topics, hz)` | Raw topic subscription |
| `unsubscribe()` | Stop streaming |

---

## API Reference

### SensorData Fields

```python
sensors = drone.get_sensors()

sensors.gps_position
sensors.imu_attitude
sensors.imu_vel
sensors.imu_accel
sensors.imu_ang_vel
sensors.imu_orientation
sensors.gps_lat
sensors.gps_lon
sensors.gps_alt
sensors.gps_vel_ned
sensors.baro_pressure_hpa
sensors.baro_temperature_c
sensors.mag_field
```

### Telemetry Fields

```python
telem = drone.get_telemetry()

telem.drone_id
telem.mode
telem.controller
telem.motors
telem.motor_thrusts
telem.desired_rates_deg
telem.desired_angles_deg
telem.desired_vel
telem.external_cmd
```

### SimStatus Fields

```python
status = sim.get_status()

status.is_paused
status.time_scale
status.sim_time
status.fixed_dt
status.authority
status.client_connected
```

### Tuning Parameters

Set these on the `Drone` object before or during high-level flight:

```python
drone.position_tolerance = 0.5
drone.altitude_tolerance = 0.3
drone.landing_altitude = 0.15
drone.default_speed = 2.0
drone.control_loop_hz = 50.0
drone.default_leg_timeout = 30.0
drone.use_velocity_mode_navigation = False
```

### Exceptions

```python
from quadsim import QuadSimError, ConnectionError, CommandError, TimeoutError, ProtocolError
```

| Exception | When |
|-----------|------|
| `ConnectionError` | Not connected or connection denied |
| `CommandError` | Authority rejected, invalid drone, invalid mode |
| `TimeoutError` | RPC timeout or flight command timeout |
| `ProtocolError` | Wire-level serialization issue |

All inherit from `QuadSimError`.

---

## How It Works

The SDK communicates with QuadSim's Unity runtime over ZeroMQ:

| Socket | Default port | Purpose |
|--------|--------------|---------|
| REQ/REP | `5555` | Commands, queries, mode changes, composite steps |
| PUB/SUB | `5556` | Streaming telemetry |

Messages are serialized with MessagePack. A background heartbeat keeps the connection alive. Socket handling is internal to `_transport.py`.

---

## Project Structure

```text
QuadSimLib/
├── quadsim/
│   ├── __init__.py
│   ├── sim.py
│   ├── drone.py
│   ├── viz.py
│   ├── _transport.py
│   ├── _control_loops.py
│   ├── types.py
│   ├── exceptions.py
│   └── future.py
├── docs/
│   └── control_modes.md
├── live_viewer.py
├── Examples/
│   ├── flight_demo.py
│   └── async_demo.py
├── Testing/
│   ├── quadsim_test_client.py
│   ├── quadsim_test_commands.py
│   └── test_high_level.py
└── pyproject.toml
```

---

## Related

- Unity runtime/plugin: [github.com/ninonick0607/Unity-QuadSim-Plugin](https://github.com/ninonick0607/Unity-QuadSim-Plugin)
- Main Unity development repo: [github.com/ninonick0607/Unity_QuadSim](https://github.com/ninonick0607/Unity_QuadSim)

---

## License

MIT
