Installation

1. Clone the repository:

   git clone https://github.com/GalacTechNyc/unitree-g1-autonomous.git
   cd unitree-g1-autonomous
   

2. Create virtual environment (recommended):

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   python install_dependencies.py
   # OR manually:
   pip install -r requirements.txt
   

4. Configure API key:

   export GEMINI_API_KEY="your_gemini_api_key_here"
   

5. Test installation:

   python run_tests.py
   

Quick Demo

Simulation Mode (no hardware required):

python autonomous_mode.py --sim

Hardware Mode (requires Unitree G1):

python autonomous_mode.py

Hardware Deployment

1. Connect to Unitree G1
2. Run on hardware:

   python autonomous_mode.py
   

📋 System Requirements

• Python: 3.8 or higher
• Hardware: Unitree G1 robot (optional for simulation)
• Dependencies: See requirements.txt
• API: Google Gemini API key

🔧 Configuration

Key settings in config.py:

# Safety Limits
MAX_FORWARD_SPEED = 0.3  # m/s
MAX_SIDE_SPEED = 0.2     # m/s  
MAX_YAW_SPEED = 0.3      # rad/s

# AI Settings
GEMINI_MODEL = "gemini-1.5-pro"
AI_QUERY_INTERVAL = 1.0  # seconds

# Camera Settings
FRAME_WIDTH = 640
FRAME_HEIGHT = 480
FPS = 30

🎮 Usage

Command Line Options

# Simulation mode
python autonomous_mode.py --sim

# Hardware mode with debug logging
python autonomous_mode.py --log-level DEBUG

# Get help
python autonomous_mode.py --help

Testing Individual Components

# Test camera
python camera_module.py

# Test AI vision  
python ai_vision.py

# Test robot control
python robot_control.py

# Run full test suite
python run_tests.py

🛡️ Safety Features

Hardware Safety

• Speed Limiting: Enforced at multiple system levels
• Balance Monitoring: Continuous orientation checking
• Battery Protection: Low battery detection and warnings
• Temperature Monitoring: Overheating protection
• Emergency Stop: Keyboard interrupt (Ctrl+C) support

AI Safety

• Fallback Logic: Defaults to stop if AI fails
• Conservative Decisions: Prioritizes safety in uncertain situations
• Rate Limiting: Prevents API overload
• Confidence Scoring: Evaluates decision reliability

Operational Safety

• Simulation First: Always test in simulation before hardware
• Graduated Deployment: Start with reduced speeds
• Environmental Awareness: Clear operating space required
• Human Oversight: Recommended for initial deployments

📊 Monitoring

Real-Time Metrics

• Frame processing rate (target: 10 FPS)
• AI query frequency (target: 1 Hz)
• Movement command execution
• Safety stop events
• System runtime statistics

Log Files

• Automatic timestamped log creation
• Console output for real-time monitoring
• Debug level logging available
• Structured error reporting

🔬 AI Decision Making

Input Processing

1. Image Capture: 640x480 RGB from front camera
2. Preprocessing: BGR to RGB conversion, PIL format
3. AI Analysis: Gemini 1.5-pro vision model
4. Decision Parsing: Structured command extraction

Output Commands

• move_forward: Clear path ahead (2m+)
• turn_left: Obstacle ahead, left path clear
• turn_right: Obstacle ahead, right path clear
• move_backward: Surrounded, need to retreat
• stop: Unsafe conditions or people nearby

Example AI Prompt

Analyze this image from a humanoid robot's front camera. Focus on:
1. Obstacles within 2 meters ahead
2. Clear paths for navigation  
3. Ground conditions and safety
4. Any people or animals that should be avoided

Respond with: ACTION: [command] REASON: [explanation]

🐛 Troubleshooting

Common Issues

Debug Commands

# Check camera
python -c "import cv2; print(cv2.VideoCapture(0).isOpened())"

# Test Gemini API  
python -c "import google.generativeai as genai; print('API OK')"

# Verify SDK
python -c "import unitree_sdk2py; print('SDK OK')"

📁 File Structure

G1SA/
├── autonomous_mode.py      # Main autonomous controller
├── camera_module.py        # Camera capture system
├── ai_vision.py           # Gemini API integration
├── robot_control.py       # Movement control  
├── config.py              # System configuration
├── install_dependencies.py # Setup script
├── run_tests.py           # Test suite
├── requirements.txt       # Python dependencies
├── development_plan.md    # Development documentation
└── README.md             # This file

🔮 Future Enhancements

Planned Features

• LiDAR Integration: Enhanced obstacle detection
• SLAM Implementation: Simultaneous localization and mapping
• Path Planning: Advanced navigation algorithms
• Multi-Robot Coordination: Swarm robotics capabilities
• Voice Interface: Natural language commands
• Mobile App: Remote monitoring and control

Performance Optimizations

• GPU Acceleration: Faster image processing
• Predictive Planning: Anticipatory movement
• Sensor Fusion: Multi-modal environmental understanding
• Edge AI: Reduced API dependency

📄 License

This project is developed as an educational and research tool. Please ensure compliance with:

• Unitree SDK licensing terms
• Google Gemini API usage policies
• Local robotics and AI regulations

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📞 Support

For issues and questions:

1. Check the troubleshooting section
2. Review the development plan
3. Run the test suite for diagnostics
4. Create an issue with detailed logs

🎯 Performance Targets

⚠️ Safety Notice: This system controls a physical robot. Always ensure proper safety measures, testing procedures, and human oversight during operation.

📜 License

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

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Install development dependencies (pip install -r requirements-dev.txt)
4. Make your changes and add tests
5. Run the test suite (python run_tests.py)
6. Commit your changes (git commit -m 'Add some AmazingFeature')
7. Push to the branch (git push origin feature/AmazingFeature)
8. Open a Pull Request

🙏 Acknowledgments

• Unitree Robotics for the G1 humanoid robot platform
• Google for the Gemini AI API
• OpenCV community for computer vision tools
• Claude Code for AI-assisted development

📞 Support

• 📋 Issues
• 💬 Discussions
• 🌐 Repository

🤖 Autonomous robotics made intelligent with AI - Generated with Claude Code assistance