Unitree Z1 Robotic Arm - Complete Research Platform

Professional 6-DOF robotic arm with simulation, real robot control, and advanced SDK integration on Ubuntu 20.04.6 LTS.

🚀 Quick Start (30 seconds)

git clone https://github.com/amznhacker/Unitree-z1-Research.git
cd Unitree-z1-Research
chmod +x setup_and_run.sh
./setup_and_run.sh --install-ros

That's it! The system will install ROS, build the workspace, and start the robot simulation automatically.

🎮 Usage - Unified Control System

Control Center (Recommended) ⭐

./quick_start.sh web         # Opens unified Control Center

Features: Launch any script, switch simulation/real modes, system monitoring

Direct Control Options 🎯

./quick_start.sh keyboard    # Direct keyboard control (WASD keys)
./quick_start.sh mouse       # Mouse/Mudra band control
./quick_start.sh xbox        # Xbox controller support
./quick_start.sh gui         # Enhanced web GUI (direct)
./quick_start.sh visual      # Visual programmer (direct)

Professional Tools 🚀

./quick_start.sh enhanced    # Full SDK integration
./quick_start.sh api         # REST API service
./quick_start.sh pure        # Pure SDK (real robot)
./quick_start.sh professional # Industrial applications

🎯 What You Get

Simulation Environment

Gazebo Physics Simulation - Realistic robot dynamics
6-DOF Manipulation - Full arm + gripper control
Visual Feedback - Real-time 3D visualization
Safe Testing - No hardware risk

Control Methods

Keyboard Control - WASD + hotkeys for all joints
Mouse Control - Mouse/Mudra band with click and scroll
Xbox Controller - Gamepad support for intuitive control
Web Interface - Browser-based control panel
API Control - HTTP REST API for remote operation
Voice Commands - AI assistant integration

Demo Applications

Pick & Place - Object manipulation tasks
Drawing - Geometric shape drawing
Bartender - Cocktail mixing choreography
Chess Player - Chess piece movement
Magic Tricks - Entertainment performances

Professional Features

Force Control - Compliant manipulation
Trajectory Planning - Smooth motion generation
Kinematics/Dynamics - Full mathematical models
Real Robot Bridge - Connect to physical hardware
Research Tools - Academic research capabilities

🎯 Controls Reference

Keyboard Control (Default)

Key	Action	Key	Action
W/S	Shoulder Up/Down	Space	Open Gripper
A/D	Base Left/Right	X	Close Gripper
Z/E	Elbow Bend/Extend	ESC	Emergency Stop
R/F	Forearm Roll	Q	Quit Program
T/G	Wrist Pitch	H	Show Help
Y/H	Wrist Roll

Mouse/Mudra Control

Input	Action
Scroll Wheel	Switch control modes (3 modes)
Mouse X/Y	Control active joint pair
Left Click	Open gripper
Right Click	Close gripper
ESC Key	Emergency stop

Control Modes:

Mode 1: Base & Shoulder (Joint01/02)
Mode 2: Elbow & Forearm (Joint03/04)
Mode 3: Wrist Pitch & Roll (Joint05/06)

Xbox Controller

Left Stick - Base rotation & shoulder
Right Stick - Elbow & forearm
D-Pad - Wrist control
RT/LT - Gripper open/close
Back Button - Emergency stop

🏗️ System Architecture

Core Components

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Gazebo Sim    │◄──►│   ROS Control    │◄──►│  Z1 Hardware    │
│   (Physics)     │    │   (Middleware)   │    │  (Real Robot)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         ▲                        ▲                       ▲
         │                        │                       │
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Control Apps   │    │   Z1 SDK         │    │  Web Interface  │
│  (Python)       │    │  (C++/Python)    │    │  (Browser)      │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Available Interfaces

ROS Topics - Standard robotics communication
Z1 SDK - Direct hardware control (C++/Python)
Web API - HTTP REST interface
Command Line - Direct script execution

📁 Project Structure

Unitree-z1-Research/
├── 🚀 Quick Start Scripts
│   ├── setup_and_run.sh          # One-time setup + ROS installation
│   ├── quick_start.sh             # Main launcher (recommended)
│   └── system_check.sh            # Verify all components work
│
├── 🎮 Control Applications
│   ├── src/z1_tools/scripts/
│   │   ├── z1_simple_control.py   # Keyboard control
│   │   ├── z1_mouse_control.py    # Mouse/Mudra control
│   │   ├── z1_web_gui.py          # Browser interface
│   │   ├── z1_xbox_control.py     # Gamepad support
│   │   └── z1_visual_programmer.py # Drag-and-drop programming
│   │
├── 🎭 Demo Applications
│   │   ├── z1_demo_simple.py      # Pick & place demo
│   │   ├── z1_bartender.py        # Cocktail mixing
│   │   ├── z1_chess_player.py     # Chess playing
│   │   ├── z1_drawing.py          # Shape drawing
│   │   └── z1_magician.py         # Magic tricks
│   │
├── 🚀 Enhanced SDK Features
│   │   ├── z1_sdk_enhanced_control.py    # Full SDK integration
│   │   ├── z1_web_api_service.py         # HTTP API server
│   │   ├── z1_pure_sdk_control.py        # Production control
│   │   ├── z1_professional_suite.py      # Industrial applications
│   │   └── z1_jetson_ai_control.py       # AI-powered control
│   │
├── 🔧 Utilities
│   │   ├── z1_emergency_stop.py   # Safety stop
│   │   ├── z1_safe_limits.py      # Joint limit testing
│   │   └── z1_real_robot_bridge.py # Hardware connection
│   │
├── 🤖 Robot Definition
│   ├── src/unitree_ros/           # ROS packages
│   │   ├── robots/z1_description/ # Robot URDF/meshes
│   │   └── unitree_gazebo/        # Simulation world
│   │
├── 🧠 Z1 SDK
│   ├── src/z1_sdk/
│   │   ├── examples/              # C++ examples
│   │   ├── examples_py/           # Python examples
│   │   └── include/               # SDK headers
│   │
└── 📚 Documentation
    ├── README.md                  # This file
    ├── deployment_guide.md        # ROS vs SDK deployment
    ├── research_implementations.md # Academic research ideas
    ├── jetson_setup.md           # AI integration guide
    └── raspberry_pi_integration.md # Edge computing setup

🔧 Advanced Usage

Development Workflow

# 1. Start Control Center
./quick_start.sh web

# 2. Develop in simulation
# Use Control Center to launch and test scripts

# 3. Switch to real robot
# Click "Real Robot Mode" in Control Center

# 4. Deploy seamlessly
# Same scripts work with real hardware

Web API Server

# Start HTTP API server
./one_command_launcher.sh api

# Access API documentation
# Open: http://localhost:8000/docs

# Example API calls
curl -X POST http://localhost:8000/move/joint \
  -H "Content-Type: application/json" \
  -d '{"joints": [0, 0.5, -0.5, 0, 0, 0], "speed": 1.0}'

Custom Script Development

#!/usr/bin/env python3
# Template for new Z1 applications

import rospy
from std_msgs.msg import Float64

def my_custom_application():
    rospy.init_node('my_z1_app')
    
    # Publishers for joint control
    joint_pubs = {}
    for i in range(1, 7):
        topic = f"/z1_gazebo/Joint0{i}_controller/command"
        joint_pubs[f"Joint0{i}"] = rospy.Publisher(topic, Float64, queue_size=1)
    
    # Your custom logic here
    rate = rospy.Rate(10)  # 10 Hz
    while not rospy.is_shutdown():
        # Move joints
        joint_pubs["Joint01"].publish(Float64(0.5))
        rate.sleep()

if __name__ == "__main__":
    my_custom_application()

🚀 Hardware Integration

Real Robot Connection

# Method 1: Via Control Center (Recommended)
./quick_start.sh web
# Then click "Real Robot Mode" button

# Method 2: Direct SDK control
./quick_start.sh pure

Jetson AI Integration

# AI-powered autonomous control
./one_command_launcher.sh jetson

# Requires: Jetson Xavier NX + camera
# Features: Object detection, visual servoing, autonomous manipulation

Raspberry Pi Edge Computing

# Lightweight control on Pi
# See: raspberry_pi_integration.md

🔬 Research Applications

Academic Research Ready

Trajectory Optimization - Compare planning algorithms
Learning from Demonstration - Record and replay skills
Force Control - Compliant manipulation research
Human-Robot Collaboration - Safety and interaction studies
Simulation-to-Reality Transfer - Validate sim performance

Research Tools Included

# Research implementation guides
cat research_implementations.md     # Full research roadmap
cat arm_only_research.md           # Immediate research projects
cat deployment_guide.md            # Production deployment

🛠️ Troubleshooting

Common Issues

Gazebo won't start:

./fix_gazebo.sh
./system_check.sh  # Verify all components

Robot not moving:

# Check controllers are loaded
rostopic list | grep z1_gazebo
rostopic echo /z1_gazebo/joint_states

Permission errors:

sudo chown -R $USER:$USER ~/catkin_ws
chmod +x ~/catkin_ws/src/z1_tools/scripts/*.py

Build errors:

cd ~/catkin_ws
catkin_make clean
catkin_make

System Verification

./system_check.sh  # Comprehensive system test
# Tests: ROS, Gazebo, controllers, scripts, SDK, performance

🎯 Capabilities Summary

Control Modes

✅ Manual Control - Keyboard, mouse/Mudra, gamepad, web interface
✅ Programmatic Control - Python scripts, ROS topics
✅ API Control - HTTP REST interface
✅ Voice Control - AI assistant integration
✅ Visual Programming - Drag-and-drop interface

Applications

✅ Pick & Place - Object manipulation
✅ Drawing - Artistic applications
✅ Assembly - Precision manufacturing tasks
✅ Entertainment - Bartending, magic, chess
✅ Research - Academic studies and experiments

Deployment Options

✅ Simulation Only - Safe development environment
✅ Real Robot - Physical hardware control
✅ Hybrid - Develop in sim, deploy to hardware
✅ Edge Computing - Raspberry Pi, Jetson integration
✅ Cloud API - Remote operation capabilities

Professional Features

✅ Force Control - Compliant manipulation
✅ Trajectory Planning - Smooth motion generation
✅ Safety Systems - Emergency stops, workspace limits
✅ Kinematics/Dynamics - Full mathematical models
✅ Multi-modal Control - Position, velocity, force modes

📚 Documentation

Essential Guides

Document	Purpose
README.md	Main usage guide (this file)
START_HERE.md	Quick 3-step getting started
ARCHITECTURE_GUIDE.md	System design & critical decisions
DEVELOPER_KNOWLEDGE.md	Implementation details & patterns
SYSTEM_KNOWLEDGE.md	Complete operational guide

Specialized Guides

Document	Purpose
deployment_guide.md	ROS vs SDK deployment strategies
research_implementations.md	Academic research opportunities
jetson_setup.md	AI integration with Jetson
raspberry_pi_integration.md	Edge computing setup
arm_only_research.md	Research with current hardware

🤝 Contributing

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎉 Getting Started Now

New to robotics? Start here:

./quick_start.sh demo

Want to control manually? Try these:

./quick_start.sh keyboard    # Keyboard control
./quick_start.sh mouse       # Mouse/Mudra control

Ready for advanced features? Go with:

./leverage_everything.sh

Perfect for learning robotics - safe simulation with real robot capability!

🧠 System Knowledge

New to the system? Read these in order:

START_HERE.md - Quick 3-step setup
README.md - Complete feature overview (this file)
ARCHITECTURE_GUIDE.md - Understand the system design
DEVELOPER_KNOWLEDGE.md - Implementation details
SYSTEM_KNOWLEDGE.md - Operational procedures

Key Insights:

ROS vs SDK: Use ROS for development/simulation, SDK for production
Script Types: Some use rosrun, others use python3 directly
Performance: Simulation (50-100Hz), Real Robot (500+Hz)
Safety: Always use emergency stop, understand workspace limits

For questions, issues, or contributions, please visit our GitHub repository.

Name		Name	Last commit message	Last commit date
src		src
.gitignore		.gitignore
ARCHITECTURE_GUIDE.md		ARCHITECTURE_GUIDE.md
DEVELOPER_KNOWLEDGE.md		DEVELOPER_KNOWLEDGE.md
LICENSE		LICENSE
MOUSE_CONTROL_GUIDE.md		MOUSE_CONTROL_GUIDE.md
README.md		README.md
REAL_HARDWARE_GUIDE.md		REAL_HARDWARE_GUIDE.md
SIMULATION_VS_REAL.md		SIMULATION_VS_REAL.md
START_HERE.md		START_HERE.md
SYSTEM_KNOWLEDGE.md		SYSTEM_KNOWLEDGE.md
arm_only_research.md		arm_only_research.md
deployment_guide.md		deployment_guide.md
fix_gazebo.sh		fix_gazebo.sh
jetson_setup.md		jetson_setup.md
quick_start.sh		quick_start.sh
raspberry_pi_integration.md		raspberry_pi_integration.md
research_implementations.md		research_implementations.md
setup_and_run.sh		setup_and_run.sh
system_check.sh		system_check.sh

Latest commit

History

Folders and files

Repository files navigation

Unitree Z1 Robotic Arm - Complete Research Platform

🚀 Quick Start (30 seconds)

🎮 Usage - Unified Control System

Control Center (Recommended) ⭐

Direct Control Options 🎯

Professional Tools 🚀

🎯 What You Get

Simulation Environment

Control Methods

Demo Applications

Professional Features

🎯 Controls Reference

Keyboard Control (Default)

Mouse/Mudra Control

Xbox Controller

🏗️ System Architecture

Core Components

Available Interfaces

📁 Project Structure

🔧 Advanced Usage

Development Workflow

Web API Server

Custom Script Development

🚀 Hardware Integration

Real Robot Connection

Jetson AI Integration

Raspberry Pi Edge Computing

🔬 Research Applications

Academic Research Ready

Research Tools Included

🛠️ Troubleshooting

Common Issues

System Verification

🎯 Capabilities Summary

Control Modes

Applications

Deployment Options

Professional Features

📚 Documentation

Essential Guides

Specialized Guides

🤝 Contributing

📄 License

🎉 Getting Started Now

🧠 System Knowledge

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages