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 following robot models:

The library runs each simulation in a background daemon thread, streams robot states and camera images via deque ring buffers, and exposes 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 (jnt_pos, jnt_vel, pose_pos, pose_quat, mit_kp, mit_kd, …) are consistent across robot models.
• Callback support: Every robot model provides a *Callback class that accepts user‑defined callables 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.

Project structure

hex_driver_mujoco/
├── hex_driver_mujoco/
│   ├── __init__.py                 # Package exports (all public classes)
│   ├── base.py                     # HexMujocoBase (abstract) & HexMujocoBaseParams
│   ├── mujoco_archer_y6/
│   │   ├── __init__.py
│   │   └── mujoco.py              # Archer Y6 simulation + callback + params
│   │   └── model/                 # MuJoCo model files (scene.xml, robot.xml, STL assets)
│   └── mujoco_e3_desktop/
│       ├── __init__.py
│       └── mujoco.py              # E3 Desktop simulation + callback + params
│       └── model/                 # MuJoCo model files (scene.xml, robot.xml, STL assets)
├── example/
│   ├── archer_y6_example.py
│   ├── archer_y6_callback_example.py
│   ├── e3_desktop_example.py
│   └── e3_desktop_callback_example.py
└── docs/
    ├── api.md                     # Full API reference
    └── example.md                 # Usage walkthroughs

📦 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