Metadata-Version: 2.4
Name: hex_driver_robot
Version: 0.1.0a1
Summary: HEXFELLOW Robot Driver
Author-email: Dong Zhaorui <dzr159@gmail.com>
Maintainer-email: jecjune <zejun.chen@hexfellow.com>, Dong Zhaorui <dzr159@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/hexfellow/hex_driver_mujoco
Project-URL: Repository, https://github.com/hexfellow/hex_driver_mujoco.git
Project-URL: Bug Tracker, https://github.com/hexfellow/hex_driver_mujoco/issues
Project-URL: Documentation, https://github.com/hexfellow/hex_driver_mujoco/wiki
Keywords: hex,driver,robot
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_util_runtime<0.1.0,>=0.0.0
Requires-Dist: hex_util_robot<0.1.0,>=0.0.0
Requires-Dist: hex_util_urdf<0.1.0,>=0.0.0
Requires-Dist: hex_device<1.5.0,>=1.4.0
Dynamic: license-file

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

<p align="center">
    <a href="https://github.com/hexfellow/hex_driver_robot/stargazers">
        <img src="https://img.shields.io/github/stars/hexfellow/hex_driver_robot?style=flat-square&logo=github" />
    </a>
    <a href="https://github.com/hexfellow/hex_driver_robot/forks">
        <img src="https://img.shields.io/github/forks/hexfellow/hex_driver_robot?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_robot/issues">
        <img src="https://img.shields.io/github/issues/hexfellow/hex_driver_robot?style=flat-square&logo=github" />
    </a>
</p>

---

# 📖 Overview

## What is `hex_driver_robot`

`hex_driver_robot` is a Python library for controlling HEXFELLOW robots with a unified interface. It supports the Hello Y6 (6‑DOF arm with 7‑DOF grip), Archer Y6 (6‑DOF arm with optional grip), and Firefly Y6 (6‑DOF arm with optional grip) robot models. The library runs each robot controller in a separate process, streams robot states via shared‑memory ring buffers, and exposes consistent readers (`get_arm_motor`, `get_grip_motor`, and on Archer/Firefly `get_arm_end`) plus model‑specific writers: MIT / joint position / Cartesian pose commands on Archer and Firefly, and grip RGB LEDs on Hello Y6.

## What problem it solves

- **Unified robot interface**: Use the same API for different robot models (Hello Y6, Archer Y6, Firefly Y6).
- **Background control**: Each robot controller runs in its own process; the main thread only reads the latest state when needed.
- **Low‑latency sharing**: States and commands are passed through shared‑memory ring buffers, avoiding serialization overhead.
- **Real‑time control**: Archer and Firefly support MIT impedance, joint position, Cartesian pose, and grip position commands; Hello Y6 focuses on motor telemetry and LED control on the grip.

## Target users

- Robotics researchers prototyping manipulation pipelines with HEXFELLOW robots.
- Developers who need a simple, consistent way to interface with real robot hardware.
- Anyone who wants to switch between different robot models without changing client code.

# 📦 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
  - `hex_util_robot` ≥ 0.0.0, < 0.1.0
  - `hex_util_urdf` ≥ 0.0.0, < 0.1.0
  - `hex_device` ≥ 1.4.0, < 1.5.0

## Install from PyPI

```bash
pip install hex_driver_robot
```

## Install from Source

For those who need examples, you can install the package from source code with examples.

**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. The `venv.sh` script expects [uv](https://github.com/astral-sh/uv).

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

   - `./venv.sh` — creates `.venv`, installs `hex_driver_robot` with example dependencies.
   - `./venv.sh --min` — installs the core package only (without example dependencies). 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 robot driver classes and parameters.

# 💡 Example

See [**Example**](docs/example.md) for usage aligned with [`example/archer_y6_example.py`](example/archer_y6_example.py), [`example/firefly_y6_example.py`](example/firefly_y6_example.py), and [`example/hello_y6_example.py`](example/hello_y6_example.py).

# 📚 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_robot&type=Date)](https://star-history.com/#hexfellow/hex_driver_robot&Date)

# 👥 Contributors

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