A comprehensive Python library for the SunFounder PiCar-X robot with enhanced educational examples and professional development practices.
This is an enhanced fork of the original SunFounder PiCar-X repository featuring structured learning paths, modern Python practices, and comprehensive examples.
- 9 organized categories with progressive difficulty
- 36+ educational examples from basics to advanced AI
- Professional coding practices with type hints and context managers
- Complete documentation with learning objectives and tutorials
- Context manager support for safe resource management
- Enhanced error handling with detailed diagnostics
- Type hints for better code clarity
- Comprehensive testing framework for quality assurance
- Structured learning progression from beginner to expert
- Interactive examples with clear explanations
- Best practices for robotics development
- Real-world applications and project ideas
Master the fundamentals of robot control
-
01_basics - Robot Fundamentals
- Hello World robotics
- Safe programming with context managers
- Robot status monitoring
-
02_movement - Movement Control
- Basic movement patterns
- Speed and direction control
-
03_sensors - Sensor Integration
- Reading sensor data
- Obstacle avoidance
- Cliff detection safety
Develop computer vision and behavior programming
-
04_vision - Computer Vision
- Camera basics and image processing
- Object detection and tracking
- Video recording and streaming
-
05_behaviors - Complex Behaviors
- State machine programming
- Face tracking and following
- Behavior coordination systems
Create intelligent systems and games
-
06_games - Interactive Games
- Game development concepts
- Bull fighting simulation
- Racing and treasure hunt games
-
07_ai_integration - AI & Machine Learning
- GPT integration for natural language
- Voice command processing
- Intelligent behavior systems
-
08_advanced - Expert Systems
- Multi-system integration
- Advanced navigation algorithms
- Performance optimization
-
09_testing - Professional Development
- Unit testing frameworks
- Hardware validation
- Integration testing
Prerequisites:
- Raspberry Pi 4 with PiCar-X hardware
- Python 3.7+ installed
- Required dependencies (robot_hat, vilib, etc.)
# Clone this enhanced fork
git clone -b v2.0 https://github.com/santsamu/picar-x.git
cd picar-x
# Install the library
sudo python3 setup.py install
# Set up your robot (first time only)
cd setup
python3 first_time_setup.py# examples/01_basics/01_hello_world.py
from picarx import Picarx
# Always use context manager for safety!
with Picarx() as px:
print("🤖 Hello, PiCar-X World!")
px.forward(50) # Move forward
px.sleep(1) # Wait 1 second
px.stop() # Stop automatically on exit# Start with basics
cd examples/01_basics
python3 01_hello_world.py
# Try interactive examples
cd ../02_movement
python3 01_basic_movement.py
# Experiment with computer vision
cd ../04_vision
python3 01_camera_basics.pypicar-x/
├── 📚 examples/ # Comprehensive learning examples
│ ├── 01_basics/ # Robot fundamentals
│ ├── 02_movement/ # Movement control
│ ├── 03_sensors/ # Sensor integration
│ ├── 04_vision/ # Computer vision
│ ├── 05_behaviors/ # Complex behaviors
│ ├── 06_games/ # Interactive games
│ ├── 07_ai_integration/ # AI & machine learning
│ ├── 08_advanced/ # Expert-level systems
│ └── 09_testing/ # Professional testing
├── 🔧 setup/ # Setup and calibration tools
├── 🧠 picarx/ # Core library code
├── 🎵 sounds/ # Audio files for TTS
├── 🎶 musics/ # Music files
└── 🧪 test/ # Hardware validation tests
| Category | What You'll Learn | Key Skills |
|---|---|---|
| 01_basics | Robot fundamentals, safety, status monitoring | Context managers, error handling |
| 02_movement | Precise movement control, navigation patterns | Motor control, coordinate systems |
| 03_sensors | Data acquisition, environmental awareness | Sensor fusion, obstacle avoidance |
| 04_vision | Image processing, object detection | OpenCV, computer vision algorithms |
| 05_behaviors | State machines, complex coordination | Behavior trees, multi-tasking |
| 06_games | Interactive systems, user engagement | Game loops, real-time interaction |
| 07_ai_integration | Modern AI, natural language processing | GPT integration, voice commands |
| 08_advanced | System integration, optimization | Performance tuning, fault tolerance |
| 09_testing | Professional development, quality assurance | Unit testing, validation frameworks |
# Automatic resource cleanup and safety
with Picarx() as px:
px.forward(50)
# Robot automatically stops and resets on exitdef move_robot(px: Picarx, speed: int, duration: float) -> bool:
"""Type-safe robot programming"""
return px.safe_move(speed, duration)try:
with Picarx() as px:
px.navigate_to_target()
except RobotHardwareError as e:
print(f"Hardware issue: {e}")
except NavigationError as e:
print(f"Navigation failed: {e}")Each example builds on previous knowledge, creating a natural learning progression from simple concepts to complex robotics systems.
Every concept is reinforced with practical, runnable examples that work on real hardware.
Learn industry best practices including testing, documentation, error handling, and code organization.
Examples demonstrate practical robotics applications including navigation, computer vision, AI integration, and interactive systems.
- Original SunFounder Docs - Hardware setup and basics
- Robot Hat Library - Low-level hardware control
- SunFounder Forum - Community support and discussions
We welcome contributions! Whether you're fixing bugs, adding examples, or improving documentation:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-example - Follow our coding standards (see examples for patterns)
- Add tests for new functionality
- Submit a pull request with clear description
- Follow the established example structure and naming conventions
- Include comprehensive docstrings and comments
- Add learning objectives and explanations
- Test on actual hardware when possible
- Update relevant documentation
Robot doesn't respond:
# Check hardware connections
cd setup
python3 first_time_setup.py
# Validate hardware
cd ../examples/09_testing
python3 01_hardware_validation.pyImport errors:
# Ensure all dependencies are installed
sudo pip3 install robot-hat vilib pygame opencv-python
# Verify installation
python3 -c "import picarx; print('✅ PiCar-X installed successfully')"Permission errors:
# Add user to required groups
sudo usermod -a -G dialout,gpio,i2c,spi $USER
# Logout and login again- Check the examples - Most questions are answered in the comprehensive examples
- Run diagnostics - Use the testing examples to identify issues
- Visit the forum - SunFounder Community Forum
- Open an issue - For bugs or enhancement requests
- 📁 9 Categories with progressive difficulty
- 📄 36+ Examples covering all aspects of robotics
- 📚 1000+ Lines of educational documentation
- 🧪 Professional Testing frameworks included
- 🎯 Learning Objectives clearly defined for each section
After completing all examples, you'll have mastered:
- ✅ Robot Programming - From basics to advanced systems
- ✅ Computer Vision - Object detection, tracking, and processing
- ✅ AI Integration - Modern AI and machine learning applications
- ✅ Professional Development - Testing, documentation, and best practices
- ✅ Project Development - Complete robotics project lifecycle
- ✅ Problem Solving - Debugging and optimization techniques
Ready to become a robotics expert? Start with the basics!
SunFounder is a technology company focused on Raspberry Pi and Arduino open source community development. Committed to the promotion of open source culture, we strive to bring the fun of electronics making to people all around the world and enable everyone to be a maker.
Products: Learning kits, development boards, robots, sensor modules, and development tools.
Community: High-quality products with video tutorials to help you build amazing projects.
Join Us: Whether you're interested in open source development or creating something cool, you're welcome to join our community!
- Website: www.sunfounder.com
- Forum: forum.sunfounder.com
- Docs: docs.sunfounder.com
- General Support: support@sunfounder.com
- Service Inquiries: service@sunfounder.com
- Community Forum: Technical discussions and help
- Bug Reports: GitHub Issues
- Feature Requests: GitHub Discussions
- Pull Requests: Contributing Guidelines
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- License: GNU General Public License v2.0
- Copyright: SunFounder, Inc.
- Fork Enhancements: Licensed under the same terms
- Commercial Use: Permitted under GPL terms
- 🌱 New to Robotics? → Start with Basics
- 🤖 Want to Build Games? → Explore Games
- 🧠 Interested in AI? → Try AI Integration
- ⚗️ Professional Development? → Learn Testing
- Share your projects on the SunFounder Forum
- Get help from the robotics community
- Contribute your own examples and improvements
Happy Robot Building! 🤖✨
This enhanced fork is maintained with ❤️ for the robotics learning community. Original PiCar-X by SunFounder.