Metadata-Version: 2.4
Name: hover-pilot
Version: 2.0.0
Summary: RealFlight Link client and Gymnasium hover environment
Author: Kyungwon Chun
License-Expression: MIT
Project-URL: Homepage, https://github.com/ruddyscent/hover-pilot
Project-URL: Repository, https://github.com/ruddyscent/hover-pilot
Project-URL: Issues, https://github.com/ruddyscent/hover-pilot/issues
Project-URL: Documentation, https://github.com/ruddyscent/hover-pilot/blob/main/docs/user-guide.md
Keywords: realflight,gymnasium,reinforcement-learning,ppo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gymnasium
Requires-Dist: numpy
Requires-Dist: pydantic
Requires-Dist: python-dotenv>=1.2.2
Provides-Extra: rl
Requires-Dist: tensorboard>=2.21.0; extra == "rl"
Requires-Dist: torch>=2.13.0; extra == "rl"
Dynamic: license-file

# HoverPilot

![License](https://img.shields.io/badge/license-MIT-green)

Minimal Python client to connect to RealFlight Link (TCP 18083), exchange RC
commands, and expose a Gymnasium-compatible hover environment.

## Quickstart

Recommended with `uv`:

```bash
uv sync
cp .env.example .env
uv run hoverpilot-demo
```

Install the optional reinforcement-learning dependencies to train or play a PPO
policy:

```bash
uv sync --extra rl
uv run hoverpilot-ppo train --timesteps 50000 --save-path ppo_hoverpilot.pt
```

By default HoverPilot connects to RealFlight Link at `127.0.0.1:18083`. Set
`RFLINK_HOST` when RealFlight runs on another host or outside the current network
namespace.

## Gymnasium Environment

```python
import numpy as np

from hoverpilot.config import HOST, PORT
from hoverpilot.envs import HoverPilotHoverEnv

env = HoverPilotHoverEnv(host=HOST, port=PORT, max_episode_steps=250)
observation, info = env.reset()
action = np.asarray([0.0, 0.0, 0.55, 0.0], dtype=np.float32)
observation, reward, terminated, truncated, info = env.step(action)
```

The action contains `aileron`, `elevator`, `throttle`, and `rudder`. See the user
guide for observation layouts, reward and termination behavior, and trainer modes.

## Documentation

- [User guide](docs/user-guide.md): setup, running, training, validation, and troubleshooting
- [RealFlight Link interface](docs/realflight-link-interface.md): client API and protocol reference

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
for details.
