{"id":38704751,"url":"https://github.com/laurigates/mcu-tinkering-lab","last_synced_at":"2026-01-17T10:54:39.242Z","repository":{"id":301853953,"uuid":"985724911","full_name":"laurigates/mcu-tinkering-lab","owner":"laurigates","description":"This repository contains projects for various embedded platforms (ESP32, Arduino, STM32).","archived":false,"fork":false,"pushed_at":"2025-11-23T10:46:53.000Z","size":4894,"stargazers_count":1,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-23T11:20:08.539Z","etag":null,"topics":["arduino","esp-idf","esp32","stm32"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laurigates.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-18T11:54:29.000Z","updated_at":"2025-11-23T10:46:31.000Z","dependencies_parsed_at":"2025-08-15T20:26:01.515Z","dependency_job_id":null,"html_url":"https://github.com/laurigates/mcu-tinkering-lab","commit_stats":null,"previous_names":["laurigates/mcu-tinkering-lab"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/laurigates/mcu-tinkering-lab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurigates%2Fmcu-tinkering-lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurigates%2Fmcu-tinkering-lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurigates%2Fmcu-tinkering-lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurigates%2Fmcu-tinkering-lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laurigates","download_url":"https://codeload.github.com/laurigates/mcu-tinkering-lab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurigates%2Fmcu-tinkering-lab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28506593,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T10:25:30.148Z","status":"ssl_error","status_checked_at":"2026-01-17T10:25:29.718Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["arduino","esp-idf","esp32","stm32"],"created_at":"2026-01-17T10:54:38.569Z","updated_at":"2026-01-17T10:54:39.234Z","avatar_url":"https://github.com/laurigates.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCU Tinkering Lab\n\n\u003e Production-ready embedded systems monorepo for ESP32, STM32, and Arduino platforms with AI-powered robotics projects\n\n[![ESP32 Build](https://github.com/laurigates/mcu-tinkering-lab/actions/workflows/esp32-build.yml/badge.svg)](https://github.com/laurigates/mcu-tinkering-lab/actions/workflows/esp32-build.yml)\n[![Tests](https://github.com/laurigates/mcu-tinkering-lab/actions/workflows/test.yml/badge.svg)](https://github.com/laurigates/mcu-tinkering-lab/actions/workflows/test.yml)\n\n## 🚀 Quick Start\n\nGet up and running in **under 5 minutes** using Docker, or 30 minutes with native setup.\n\n### Option 1: Docker (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/laurigates/mcu-tinkering-lab.git\ncd mcu-tinkering-lab\n\n# Build Docker images\nmake docker-build\n\n# Start interactive development shell\nmake docker-dev\n\n# Inside container: build all projects\nmake build-all\n```\n\n### Option 2: Native Setup\n\n**Prerequisites:**\n- ESP-IDF v5.4+ (for ESP32 projects)\n- Python 3.11+ (for simulation)\n- Git, Make, CMake\n\n```bash\n# Install ESP-IDF\nmkdir -p ~/repos\ncd ~/repos\ngit clone --recursive https://github.com/espressif/esp-idf.git\ncd esp-idf\ngit checkout v5.4\n./install.sh esp32\nsource export.sh\n\n# Clone this repository\ncd ~\ngit clone https://github.com/laurigates/mcu-tinkering-lab.git\ncd mcu-tinkering-lab\n\n# Install development tools\nmake install-dev-tools\n\n# Build all projects\nmake build-all\n```\n\n## 📁 Repository Structure\n\n```\nmcu-tinkering-lab/\n├── packages/\n│   ├── esp32-projects/\n│   │   ├── robocar-main/           # 🤖 AI robot car controller (Heltec WiFi LoRa 32)\n│   │   ├── robocar-camera/         # 📹 ESP32-CAM vision with Claude/Ollama AI\n│   │   ├── robocar-simulation/     # 🎮 Python 3.11 physics simulation\n│   │   ├── robocar-docs/           # 📚 Documentation and coordination Makefile\n│   │   ├── esp32cam-llm-telegram/  # 💬 Telegram bot with LLM vision\n│   │   ├── esp32-cam-webserver/    # 🌐 Live video streaming server\n│   │   └── esp32-cam-i2s-audio/    # 🔊 Camera + audio processing\n│   ├── arduino-projects/           # 🚧 Coming soon\n│   ├── stm32-projects/             # 🚧 Coming soon\n│   └── shared-libs/                # 📦 Shared code libraries (planned)\n├── .github/workflows/              # 🔄 CI/CD pipelines\n├── tools/                          # 🛠️ Build scripts and utilities\n├── docs/                           # 📖 Documentation\n└── Makefile                        # 🎯 Root build coordination (60+ targets)\n```\n\n## 🎯 Featured Projects\n\n### AI-Powered Robot Car (Primary Project)\nDual ESP32 autonomous robot with AI vision and physics simulation.\n\n**Components:**\n- **Main Controller:** Heltec WiFi LoRa 32 V1 - Motor control, LEDs, servos\n- **Vision System:** ESP32-CAM - Claude/Ollama AI backends, MQTT telemetry\n- **Simulation:** Python 3.11 with Pymunk 2D physics engine\n\n**Quick Start:**\n```bash\n# Build both controllers\nmake robocar-build-all\n\n# Flash main controller\nmake robocar-flash-main PORT=/dev/ttyUSB0\n\n# Flash camera (connect GPIO0 to GND first)\nmake robocar-flash-cam PORT=/dev/ttyUSB1\n\n# Start development workflow (build + flash + monitor)\nmake robocar-develop-main\n```\n\n### ESP32-CAM LLM Telegram Bot\nVision-enabled Telegram bot with Claude or Ollama AI integration.\n\n```bash\nmake llm-telegram-build\nmake llm-telegram-flash PORT=/dev/ttyUSB0\nmake llm-telegram-monitor\n```\n\n## 🏗️ Build System\n\nThe unified Makefile provides **60+ targets** for all projects:\n\n```bash\n# Show all available commands\nmake help\n\n# Build commands\nmake build-all              # Build all projects\nmake build-esp32            # Build all ESP32 projects\nmake robocar-build-all      # Build robocar main + camera\n\n# Development workflows (build + flash + monitor)\nmake robocar-develop-main   # Main controller\nmake robocar-develop-cam    # Camera module\n\n# Code quality\nmake lint                   # Run all linters\nmake format                 # Format all code\nmake format-check           # Check formatting without modifying\n\n# Docker\nmake docker-build           # Build development images\nmake docker-dev             # Interactive development shell\nmake docker-run CMD=\"make build-all\"  # Run command in container\n\n# Utilities\nmake list-projects          # Show all projects\nmake check-environment      # Verify development setup\nmake clean-all              # Clean all builds\n```\n\n## 🧪 Testing\n\n```bash\n# Run all tests\nmake test-all                  # (Coming soon)\n\n# Python simulation tests\ncd packages/esp32-projects/robocar-simulation\nuv sync\nuv run pytest tests/ --cov\n\n# ESP32 host-based tests (planned)\nmake test-host-all\n\n# Hardware-in-loop tests (planned)\nmake test-hil-all\n```\n\n## 🐳 Docker Development\n\n**Benefits:**\n- ✅ Zero manual ESP-IDF setup\n- ✅ Consistent environment across platforms\n- ✅ Works identically on Windows/Mac/Linux\n- ✅ Isolated from host system\n\n**Commands:**\n```bash\n# Build images\nmake docker-build\n\n# Interactive shell\nmake docker-dev\n\n# Run specific commands\nmake docker-run CMD=\"make build-all\"\nmake docker-run CMD=\"make robocar-build-main\"\n\n# Manage containers\nmake docker-up              # Start services in background\nmake docker-down            # Stop services\nmake docker-logs            # View logs\nmake docker-clean           # Remove containers and volumes\n```\n\n**USB Device Access (for flashing):**\nUncomment the `devices` section in `docker-compose.yml`:\n```yaml\ndevices:\n  - /dev/ttyUSB0:/dev/ttyUSB0\n  - /dev/ttyUSB1:/dev/ttyUSB1\n```\n\n## 🔧 Development Tools\n\n### Code Quality\n\n**C/C++ Tools:**\n- `clang-format` - Code formatting (Google style, 4-space indent)\n- `cppcheck` - Static analysis\n\n**Python Tools:**\n- `ruff` - Fast linting and formatting\n- `mypy` - Type checking\n- `pytest` - Testing framework\n\n### Pre-commit Hooks\n\nAutomatically run code quality checks before each commit:\n\n```bash\n# Install hooks\nmake install-dev-tools\n\n# Or manually\npip install pre-commit\npre-commit install\n\n# Run hooks manually\npre-commit run --all-files\n```\n\n**Checks:**\n- ✅ C/C++ formatting (clang-format)\n- ✅ Python formatting (ruff)\n- ✅ Trailing whitespace\n- ✅ YAML validation\n- ✅ Credential file detection\n- ✅ Build artifact detection\n\n## 📊 CI/CD Pipeline\n\nAutomated checks on every push and pull request:\n\n**Build Pipeline** (`.github/workflows/esp32-build.yml`):\n- ✅ Build all ESP32 projects in parallel\n- ✅ Generate size analysis reports\n- ✅ Archive firmware binaries (30-day retention)\n- ✅ Check binary size limits for OTA\n\n**Test Pipeline** (`.github/workflows/test.yml`):\n- ✅ Pre-commit hook validation\n- ✅ Python simulation tests with coverage\n- ✅ C/C++ linting (cppcheck)\n- ✅ Format checking (clang-format)\n- ✅ ESP32 host-based tests (when added)\n\n**Status Badges:**\nAdd to your PRs to see build status at a glance.\n\n## 🚧 Creating New Projects\n\n### ESP32 Project Template\n\n```bash\n# Copy template (manual for now)\ncp -r packages/esp32-projects/esp32-cam-webserver packages/esp32-projects/my-new-project\ncd packages/esp32-projects/my-new-project\n\n# Update CMakeLists.txt\nsed -i 's/esp32-cam-webserver/my-new-project/g' CMakeLists.txt\n\n# Build\nmake esp32-my-new-project-build\n```\n\n**Automated scaffolding tool coming soon!**\n\n## 📚 Documentation\n\n- [Architecture Overview](packages/esp32-projects/robocar-docs/README.md) - System design and communication protocols\n- [Hardware Connections](packages/esp32-projects/robocar-docs/hardware-connections.md) - Pin mappings and wiring\n- [WiFi Setup](packages/esp32-projects/robocar-main/WIFI_SETUP.md) - Network configuration\n- [OTA Updates](packages/esp32-projects/robocar-docs/PARTITION_UPDATE_NOTES.md) - Over-the-air firmware updates\n- [Simulation Guide](packages/esp32-projects/robocar-simulation/README.md) - Physics simulation setup\n\n## 🤝 Contributing\n\nWe welcome contributions! Please follow these guidelines:\n\n1. **Code Style:**\n   - C/C++: Run `make format-c` before committing\n   - Python: Run `make format-python` before committing\n   - All: Pre-commit hooks will enforce standards\n\n2. **Testing:**\n   - Add tests for new features\n   - Ensure existing tests pass\n   - Aim for \u003e70% coverage\n\n3. **Commit Messages:**\n   - Use conventional commits: `feat:`, `fix:`, `docs:`, etc.\n   - Be descriptive: \"feat: Add WiFi reconnection logic\" not \"update code\"\n\n4. **Pull Requests:**\n   - Create feature branches: `feat/my-feature`\n   - Ensure CI passes\n   - Request review from maintainers\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## 🛠️ Troubleshooting\n\n### ESP-IDF Not Found\n```bash\nexport IDF_PATH=$HOME/repos/esp-idf\nsource $IDF_PATH/export.sh\n```\n\n### Serial Port Permission Denied\n```bash\n# Linux\nsudo usermod -a -G dialout $USER\n# Log out and back in\n\n# Or use sudo\nsudo make robocar-flash-main\n```\n\n### Docker USB Device Not Found\nEnsure `privileged: true` is set in `docker-compose.yml` and devices are mapped correctly.\n\n### Build Fails with \"No Space Left\"\n```bash\n# Clean all builds\nmake clean-all\n\n# In Docker, clean volumes\nmake docker-clean\n```\n\n## 📈 Project Status\n\n| Platform | Status | Projects | Tests | CI/CD |\n|----------|--------|----------|-------|-------|\n| **ESP32** | ✅ Active | 7 projects | 🚧 In progress | ✅ Automated |\n| **Arduino** | 🚧 Planned | 0 | ❌ N/A | ❌ N/A |\n| **STM32** | 🚧 Planned | 0 | ❌ N/A | ❌ N/A |\n| **Simulation** | ✅ Active | Python 3.11 | ✅ pytest | ✅ Automated |\n\n## 🔗 Links\n\n- **Repository:** https://github.com/laurigates/mcu-tinkering-lab\n- **Issues:** https://github.com/laurigates/mcu-tinkering-lab/issues\n- **Discussions:** https://github.com/laurigates/mcu-tinkering-lab/discussions\n- **ESP-IDF:** https://docs.espressif.com/projects/esp-idf/en/latest/\n\n## 📄 License\n\nThis project is licensed under the MIT License - see individual project directories for specific licenses.\n\n## ⭐ Acknowledgments\n\n- **ESP-IDF** by Espressif Systems\n- **esp-idf-lib** component library\n- **Claude API** and **Ollama** for AI vision\n- **Pymunk** for 2D physics simulation\n- Open source community\n\n---\n\n**Happy tinkering! 🔧🤖**\n\nFor questions or support, please open an issue or discussion on GitHub.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaurigates%2Fmcu-tinkering-lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaurigates%2Fmcu-tinkering-lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaurigates%2Fmcu-tinkering-lab/lists"}