HEXFELLOW YOCO DRIVER

📖 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)

  pip install hex_driver_yoco[all]
  

• Core install: only the core package (only USB cameras)

  pip install hex_driver_yoco
  

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

  pip install hex_driver_yoco[realsense]
  

Install from Source

Note: We use uv to manage the Python environment. Please install it first.

1. Clone and install in editable mode:

   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:

   source .venv/bin/activate
   

📑 API

See API for details of all Yoco driver classes and parameters.

💡 Example

See Example 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:

@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.

🌟 Star History

👥 Contributors