{"id":16023807,"url":"https://github.com/vikashplus/ezgripper_sim","last_synced_at":"2026-03-19T04:41:44.347Z","repository":{"id":112748405,"uuid":"353636212","full_name":"vikashplus/ezgripper_sim","owner":"vikashplus","description":"MuJoCo model for EZGripper from SAKE robotics","archived":false,"fork":false,"pushed_at":"2021-04-13T07:28:07.000Z","size":2772,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-13T23:10:35.128Z","etag":null,"topics":["mujoco","robosapien","robot","simualtion"],"latest_commit_sha":null,"homepage":"http://vikashplus.github.io/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vikashplus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-01T08:54:34.000Z","updated_at":"2023-08-15T20:00:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"e91295d4-5a63-4776-9ee6-859afcb59c45","html_url":"https://github.com/vikashplus/ezgripper_sim","commit_stats":{"total_commits":3,"total_committers":2,"mean_commits":1.5,"dds":"0.33333333333333337","last_synced_commit":"6defecfd4f10f2c4effbcc6f66d531bc7813538c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vikashplus/ezgripper_sim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikashplus%2Fezgripper_sim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikashplus%2Fezgripper_sim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikashplus%2Fezgripper_sim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikashplus%2Fezgripper_sim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vikashplus","download_url":"https://codeload.github.com/vikashplus/ezgripper_sim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikashplus%2Fezgripper_sim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28755563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T16:32:25.380Z","status":"ssl_error","status_checked_at":"2026-01-25T16:32:09.189Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mujoco","robosapien","robot","simualtion"],"created_at":"2024-10-08T19:02:57.650Z","updated_at":"2026-01-25T17:06:03.994Z","avatar_url":"https://github.com/vikashplus.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# EZGripper MuJoCo Simulation\n\nHigh-fidelity [MuJoCo](https://mujoco.org) model for the **SAKE Robotics EZGripper** robotic gripper with realistic tendon-driven physics.\n\n\u003cimg src=\"ezgripper.png\" alt=\"EZGripper MuJoCo simulation\" width=\"400\"/\u003e\n\n## Overview\n\nThis repository contains a physics-accurate MuJoCo model of the SAKE Robotics EZGripper Dual (Gen1/Gen2), featuring:\n\n- ✅ **Tendon-driven mechanism** - Realistic cable actuation matching real hardware\n- ✅ **Under-actuated fingers** - Single servo controls 2 opposing fingers\n- ✅ **Adaptive grasping** - Fingers wrap around objects independently\n- ✅ **Accurate meshes** - Real STL geometry from SAKE Robotics\n- ✅ **MuJoCo 3.0+ compatible** - Works with latest MuJoCo versions\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install MuJoCo (if not already installed)\npip3 install mujoco\n\n# Clone this repository\ngit clone https://github.com/SAKErobotics/ezgripper_sim.git\ncd ezgripper_sim\n\n# Test the model\npython3 test_gripper.py\n```\n\n### Interactive Viewer\n\n```bash\npython3 test_gripper.py\n```\n\nUse the MuJoCo viewer sliders to control the gripper actuator.\n\n## EZGripper Specifications\n\n### Mechanical Design\n\n**Architecture**: Under-actuated, tendon-driven\n- **Fingers**: 2 opposing fingers\n- **Links per finger**: 2 (proximal + distal)\n- **Joints per finger**: 2 (~110° range each)\n- **Actuation**: Single Dynamixel MX-64AR servo\n\n**Range of Motion**:\n- **Full range**: 2500 servo units (0 = closed, 2500 = open)\n- **Scaled range**: 0-100% (used in control interface)\n- **Joint angles**: ~110° per joint\n\n### Control Interface\n\nThe EZGripper uses two primary commands:\n\n#### 1. Calibrate\n```python\ncalibrate(servo)\n```\n- Moves gripper to closed position\n- Resets zero position\n- Should be run at startup\n\n#### 2. Goto_Position(effort, position)\n```python\ngoto_position(effort, position)\n```\n\n**Position Parameter** (0-100):\n- `0`: Fully closed (continuous close mode)\n- `1-100`: Specific position (% open)\n- `100`: Fully open\n\n**Effort Parameter** (0-100):\n- `0`: Torque off (fingers can be back-driven)\n- `1-100`: Torque level (% of max)\n\n**Control Modes**:\n- **Position = 0**: Torque control mode (best for grasping)\n- **Position \u003e 0**: Position control mode (best for positioning)\n\n**Automatic Back-off Algorithm**:\n- Closes until fingers stop moving\n- Drops to 10% torque to maintain grasp\n- Minimizes power and heat\n\n### Physics Model\n\n**Tendon System**:\n- Spatial tendon routing through pulleys\n- Realistic cable mechanics\n- Spring-loaded opening (tendon closes, springs open)\n\n**Contact Dynamics**:\n- **Mesh-based collision**: All finger/palm meshes provide collision surfaces\n- **L1-L2 hard stop**: Physical mesh collision defines preload position\n- **Intra-finger collision**: L1 and L2 links collide to create spring preload\n- **Grasping surfaces**: Palm, L1, L2, and finger tips all participate in grasping\n- **Adaptive wrapping**: Fingers conform to object shape via under-actuation\n\n**Spring Configuration (Preload Mechanism)**:\n\nThe gripper uses **collision-based preload** to simulate the real hardware behavior:\n\n1. **Palm-L1 Joint**:\n   - `stiffness=\"0.05114105365\"` (STRONG spring)\n   - `springref=\"-3.14\"` (-180°, outside joint range)\n   - Range: `-1.57075 to 0.27` (-90° to 15°)\n   - **Effect**: Constant force pulling joint toward open position\n\n2. **L1-L2 Joint**:\n   - `stiffness=\"0.02459949416\"` (WEAK spring)\n   - `springref=\"-1.57\"` (-90°, outside joint range)\n   - Range: `0.5236 to 1.7` (30° to 97°)\n   - **Effect**: Constant force pulling joint toward open position\n   - **Hard stop**: L1-L2 mesh collision stops opening at ~30°\n   - **Preload**: Spring compressed against collision creates resting force\n\n**Why This Works**:\n- MuJoCo doesn't have explicit preload parameters\n- Setting `springref` outside joint range creates constant force\n- Physical collision between L1 and L2 meshes acts as hard stop\n- Spring force compressed against hard stop = mechanical preload\n- This matches real hardware where springs are pre-compressed at assembly\n\n**Under-Actuation Sequence**:\n1. **Open state**: Springs pull joints open until L1-L2 collision stops them\n2. **Tendon pull**: Overcomes spring preload to close gripper\n3. **Contact**: L1 contacts object first, stops moving\n4. **Wrap**: L2 continues closing around object (progressive grasp)\n\n**Joint Properties**:\n- Damping: 0.005\n- Spring references outside ranges for constant preload force\n- Limited ranges matching real hardware\n- Collision filtering: `contype=3 conaffinity=3` for all grasping surfaces\n\n## Model Structure\n\n```\nezgripper.xml           # Main MuJoCo model\n├── mount               # Gripper base/mount\n├── F1_L1              # Finger 1, Link 1 (proximal)\n│   └── F1_L2          # Finger 1, Link 2 (distal)\n├── F2_L1              # Finger 2, Link 1 (proximal)\n│   └── F2_L2          # Finger 2, Link 2 (distal)\n└── flex_tendon        # Tendon connecting all links\n\nmeshes/\n├── SAKE_Single_Mount.stl\n├── SAKE_Palm_IM.stl\n├── SAKE_Finger_L1_IM.stl\n├── SAKE_Finger_L2_IM.stl\n└── SAKE_Finger_Pad_IM.stl\n```\n\n## Integration with Robots\n\n### Attaching to Robot Arm\n\nTo integrate the EZGripper into your robot model:\n\n1. **Include the gripper body** (without worldbody):\n```xml\n\u003cinclude file=\"ezgripper_body.xml\"/\u003e\n```\n\n2. **Attach to your end-effector**:\n```xml\n\u003cbody name=\"your_end_effector\"\u003e\n  \u003cbody name=\"ezgripper\" pos=\"0 0 -0.05\" quat=\"...\"\u003e\n    \u003c!-- Include gripper here --\u003e\n  \u003c/body\u003e\n\u003c/body\u003e\n```\n\n3. **Orient the gripper**:\n   - Default: Gripper X-axis points forward\n   - Rotate as needed for your application\n\n### Example: Minilift SCARA Integration\n\nSee `examples/minilift_integration.xml` for a complete example of integrating the EZGripper with a SCARA arm.\n\n## MuJoCo Version Compatibility\n\n- ✅ **MuJoCo 3.0+**: Fully tested and supported\n- ✅ **MuJoCo 2.x**: Should work (not actively tested)\n\n**Tested with**:\n- MuJoCo 3.3.7 on Ubuntu 24.04\n- Python 3.12\n\n## Files\n\n- `ezgripper.xml` - Complete standalone model with floor\n- `test_gripper.py` - Interactive test script\n- `meshes/` - STL mesh files\n- `ezgripper.png` - Preview image\n\n## Credits\n\n**Original Model**: [Vikash Kumar](https://github.com/vikashplus/ezgripper_sim) (2021)\n**Hardware**: [SAKE Robotics](https://sakerobotics.com/)\n**Maintained by**: SAKE Robotics\n\n## License\n\nApache License 2.0 - See LICENSE file\n\n## Resources\n\n- **SAKE Robotics**: https://sakerobotics.com/\n- **EZGripper Hardware**: https://sakerobotics.com/products\n- **Python Drivers**: https://github.com/SAKErobotics/libezgripper\n- **ROS 2 Drivers**: https://github.com/SAKErobotics/EZGripper_ros2\n- **MuJoCo Documentation**: https://mujoco.readthedocs.io/\n\n## Support\n\nFor questions or issues:\n- GitHub Issues: https://github.com/SAKErobotics/ezgripper_sim/issues\n- Email: support@sakerobotics.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvikashplus%2Fezgripper_sim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvikashplus%2Fezgripper_sim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvikashplus%2Fezgripper_sim/lists"}