hex-driver-mujoco 0.1.1a4

HEXFELLOW Mujoco Driver

HEXFELLOW MUJOCO DRIVER

      

---

📖 Overview

What is hex_driver_mujoco

hex_driver_mujoco is a Python library for MuJoCo robot simulation with a unified interface. It supports the E3 Desktop (dual‑arm) and Archer Y6 (6‑DOF arm) robot models. The library runs each simulation in a background thread, streams robot states and camera images via deque buffers, and provides simple get_*_state/get_*_color_img/get_*_depth_img APIs. A callback variant is also available for each robot model.

What problem it solves

• Unified simulation interface: Use the same API for different robot models (E3 Desktop, Archer Y6).
• Background simulation: Each simulation runs in its own daemon thread; the main thread only reads the latest state when needed.
• Low‑latency sharing: States and images are passed through deque buffers within the same process, avoiding serialization overhead.
• Real‑time control: Supports joint position, Cartesian pose, and MIT commands; command dict field names (motor_pos, motor_vel, trans_pos, trans_quat, mit_kp, mit_kd, …) are consistent across robot models.
• Callback support: Each robot model provides a *Callback class that accepts user‑defined callbacks for state and image streams.

Target users

• Robotics researchers prototyping manipulation pipelines with MuJoCo simulations.
• Developers who need a simple, consistent way to interface with simulated robots.
• 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_util_msg ≥ 0.0.0, < 0.1.0
  • opencv-python ≥ 4.10.0
  • mujoco ≥ 3.3.0

Install from PyPI

pip install hex_driver_mujoco

Install from Source

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

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

1. Clone and install in editable mode. The venv.sh script expects uv.

   git clone https://github.com/hexfellow/hex_driver_mujoco.git
   cd hex_driver_mujoco
   ./venv.sh
   

   • ./venv.sh — creates .venv, installs hex_driver_mujoco in editable mode.

2. Activate before running examples:

   source .venv/bin/activate
   

📑 API

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

💡 Example

See Example for usage examples of each robot model.

📚 Citation

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

@software{hex_driver_mujoco,
  author    = {Dong, Zhaorui and Chen, Zejun},
  title     = {Hex Driver MuJoCo: A MuJoCo-Based Robot Simulation Driver},
  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