Metadata-Version: 2.4
Name: hex_driver_yoco
Version: 0.0.1a1
Summary: Unified interface for HEXFELLOW robots and cameras (simulation and real world)
Author-email: Dong Zhaorui <dzr159@gmail.com>
Maintainer-email: jecjune <zejun.chen@hexfellow.com>, Dong Zhaorui <dzr159@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/hexfellow/hex_driver_yoco
Project-URL: Repository, https://github.com/hexfellow/hex_driver_yoco.git
Project-URL: Bug Tracker, https://github.com/hexfellow/hex_driver_yoco/issues
Project-URL: Documentation, https://github.com/hexfellow/hex_driver_yoco/wiki
Keywords: hex,driver,yoco
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hex_driver_mujoco<0.1.0,>=0.0.0
Requires-Dist: hex_driver_robot<0.1.0,>=0.0.0
Requires-Dist: hex_driver_camera<0.1.0,>=0.0.0
Provides-Extra: berxel
Requires-Dist: berxel_py_wrapper>=2.0.182; extra == "berxel"
Provides-Extra: realsense
Requires-Dist: pyrealsense2>=2.56.5.9235; extra == "realsense"
Provides-Extra: all
Requires-Dist: berxel_py_wrapper>=2.0.182; extra == "all"
Requires-Dist: pyrealsense2>=2.56.5.9235; extra == "all"
Dynamic: license-file

<h1 align="center">HEXFELLOW YOCO DRIVER</h1>

<p align="center">
    <a href="https://github.com/hexfellow/hex_driver_yoco/stargazers">
        <img src="https://img.shields.io/github/stars/hexfellow/hex_driver_yoco?style=flat-square&logo=github" />
    </a>
    <a href="https://github.com/hexfellow/hex_driver_yoco/forks">
        <img src="https://img.shields.io/github/forks/hexfellow/hex_driver_yoco?style=flat-square&logo=github" />
    </a>
    <a href="https://doi.org/10.5281/zenodo.18309954">
        <img src="https://zenodo.org/badge/1088506315.svg" alt="DOI">
    </a>
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    <a href="https://github.com/hexfellow/hex_driver_yoco/issues">
        <img src="https://img.shields.io/github/issues/hexfellow/hex_driver_yoco?style=flat-square&logo=github" />
    </a>
</p>

---

# 📖 Overview

## What is `hex_driver_yoco`

`hex_driver_yoco` (You Only Control Once) is a Python library providing a unified interface for HEXFELLOW robots and cameras, allowing seamless switching between simulation (MuJoCo) and real‑world (robot hardware + cameras) environments with minimal code changes.

The library wraps existing drivers (`hex_driver_mujoco`, `hex_driver_robot`, `hex_driver_camera`) and exposes a consistent API, so that the same client code can run in simulation and on real hardware just by changing a `mode` parameter. Currently supports Archer Y6 (single‑arm) and E3 Desktop (dual‑arm) robot models.

## What problem it solves

- **Unified simulation/real interface**: Write your control/vision pipeline once, then switch between simulation and real hardware by changing one parameter.
- **Minimal code changes**: No need to rewrite robot commands or image‑acquisition logic when moving from simulation to real deployment.
- **Consistent API**: Offers a common subset of methods that work in both environments (e.g., `get_arm_motor`, `get_color_img`, `set_arm_mit_cmd`).
- **Optional‑dependency handling**: Automatically checks for the presence of underlying drivers and raises clear errors if they are missing.

## Target users

- Robotics researchers prototyping algorithms in simulation before deploying to real robots.
- Developers who want to test vision pipelines with simulated cameras before using real cameras.
- Anyone who needs to frequently switch between simulation and real hardware during development.

# 📦 Installation

## Requirements

- **Python** ≥ 3.10
- **OS**: `Linux` (macOS/Windows may work but are less tested)
- **Core dependencies**:
  - `hex_util_runtime` ≥ 0.0.0, < 0.1.0

## Optional dependencies (depending on mode)

- **Simulation mode**: `hex_driver_mujoco` (installs `mujoco` ≥ 3.3.0)
- **Real‑robot mode**: `hex_driver_robot` (installs `hex_device` ≥ 1.3.17)
- **Real‑camera mode**: `hex_driver_camera` (installs `opencv‑python` ≥ 4.10.0 and optional camera backends)

## Install from PyPI

- **Full install**: includes all optional cameras (Berxel, RealSense)

    ```bash
    pip install hex_driver_yoco[all]
    ```

- **Core install**: only the core package (only USB cameras)

    ```bash
    pip install hex_driver_yoco
    ```

- **Install with a specific extra** (e.g., only USB cameras and RealSense):

    ```bash
    pip install hex_driver_yoco[realsense]
    ```

## Install from Source

**Note**: We use [**uv**](https://github.com/astral-sh/uv) to manage the Python environment. Please install it first.

1. Clone and install in editable mode:

    ```bash
    git clone https://github.com/hexfellow/hex_driver_yoco.git
    cd hex_driver_yoco
    ./venv.sh
    ```

   - `./venv.sh` — creates `.venv`, installs `hex_driver_yoco` with all optional drivers (simulation, robot, camera).
   - `./venv.sh --min` — installs the core package only (no optional drivers). Some examples will not run.
   - `./venv.sh --pkg-only` — installs the package only, skips example‑related dependencies.

2. Activate before running examples:

    ```bash
    source .venv/bin/activate
    ```

# 📑 API

See [**API**](docs/api.md) for details of all Yoco driver classes and parameters.

# 💡 Example

See [**Example**](docs/example.md) for usage examples of both simulation and real‑world modes.

# 📚 Citation

If you want to cite this project in your work, you can use the following BibTeX entry:

```bibtex
@software{hex_zmq_servers,
  author    = {Dong, Zhaorui and Chen, Zejun},
  title     = {Hex ZMQ Servers: A ZeroMQ-Based Embodied AI Communication Framework},
  year      = {2025},
  publisher = {Zenodo},
  version   = {v1.0.0},
  doi       = {10.5281/zenodo.18309960},
  url       = {https://doi.org/10.5281/zenodo.18309960}
}
```

# 📄 License

Apache License 2.0. See [LICENSE](LICENSE).

# 🌟 Star History

[![Star History Chart](https://api.star-history.com/svg?repos=hexfellow/hex_driver_yoco&type=Date)](https://star-history.com/#hexfellow/hex_driver_yoco&Date)

# 👥 Contributors

<a href="https://github.com/hexfellow/hex_driver_yoco/graphs/contributors">
    <img src="https://contrib.rocks/image?repo=hexfellow/hex_driver_yoco" />
</a>
