{"id":31686517,"url":"https://github.com/jimmynotjim/pi-thon","last_synced_at":"2026-05-18T04:15:20.181Z","repository":{"id":318399174,"uuid":"1070537675","full_name":"jimmynotjim/Pi-Thon","owner":"jimmynotjim","description":"A Pythonic starter for your Raspberry Pi projects.","archived":false,"fork":false,"pushed_at":"2025-10-07T00:35:41.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-07T01:13:30.027Z","etag":null,"topics":["gpio","iot","microcontroller","raspberry-pi","starter","template"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jimmynotjim.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-06T04:47:48.000Z","updated_at":"2025-10-07T00:41:43.000Z","dependencies_parsed_at":"2025-10-07T01:13:41.950Z","dependency_job_id":"dcaca6dd-68f1-4e54-b853-3b82d53f9c9b","html_url":"https://github.com/jimmynotjim/Pi-Thon","commit_stats":null,"previous_names":["jimmynotjim/pi-thon"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/jimmynotjim/Pi-Thon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmynotjim%2FPi-Thon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmynotjim%2FPi-Thon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmynotjim%2FPi-Thon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmynotjim%2FPi-Thon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jimmynotjim","download_url":"https://codeload.github.com/jimmynotjim/Pi-Thon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmynotjim%2FPi-Thon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33164686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"online","status_checked_at":"2026-05-18T02:00:06.436Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["gpio","iot","microcontroller","raspberry-pi","starter","template"],"created_at":"2025-10-08T09:27:30.997Z","updated_at":"2026-05-18T04:15:20.175Z","avatar_url":"https://github.com/jimmynotjim.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pi-Thon\n\nA Pythonic starter for your Raspberry Pi projects with GPIO support, pre-configured linting, type checking, and testing.\n\n## Features\n\n- **GPIO Libraries**: RPi.GPIO and gpiozero for hardware control\n- **Code Quality**: Ruff for linting and formatting\n- **Type Safety**: mypy for static type checking\n- **Testing**: pytest with coverage reporting\n- **Git Hooks**: pre-commit for automated code quality checks\n- **Camera Support**: picamera2 ready to use\n- **Configuration Management**: python-dotenv for environment variables\n\n## Prerequisites\n\n- Raspberry Pi (any model with GPIO)\n- Python 3.11 or higher\n- Git\n\n## Quick Start\n\n### 1. Create Your Project\n\n1. Click the **\"Use this template\"** button at the top of this page\n2. Name your new repository\n3. Clone your new repository:\n\n```bash\ngit clone https://github.com/YOUR-USERNAME/YOUR-PROJECT-NAME.git\ncd YOUR-PROJECT-NAME\n```\n\n4. Update project information in `pyproject.toml`:\n   - Change `name` to your project name\n   - Update `authors` with your information\n   - Update repository URLs in `[project.urls]`\n\n### 2. System Setup (Raspberry Pi only)\n\n**If you're setting this up outside a Pi for development, skip to step 3**\n\nFirst, update your system packages:\n\n```bash\nsudo apt update\nsudo apt upgrade -y\n```\n\nInstall Python development tools: (These may come installed with your OS)\n\n```bash\nsudo apt install -y python3-pip python3-venv git\n```\n\n#### Optional - Install ZSH and Oh My ZSH\n\n```bash\n# Install ZSH\nsudo apt-get update \u0026\u0026 sudo apt-get install zsh\n\n# Set default to ZSH\nchsh -s $(which zsh)\n\n# Install Oh My ZSH\nsh -c \"$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)\"\n\n# Install autosuggestions plugin\ngit clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions\n\n# Install syntax highlighting plugin\ngit clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting\n```\n\nThen edit the RC file:\n\n```bash\nnano ~/.zshrc\n```\n\nAdd these plugins:\n\n```zsh\nplugins=(git zsh-autosuggestions zsh-syntax-highlighting)\n```\n\n### 3. Setup Virtual Environment and Dependencies\n\nCreate and activate a virtual environment:\n\n```bash\nmake venv\nsource venv/bin/activate\n```\n\nInstall dependencies:\n\n```bash\n# On Mac (development only - skips Pi hardware libraries)\nmake install-dev\n\n# On Raspberry Pi (includes hardware libraries)\nmake install-pi\n```\n\n### 4. Configure Pre-commit Hooks\n\nInstall pre-commit hooks:\n\n```bash\nmake install-hooks\n```\n\nUpdate hook versions to latest (recommended for new projects):\n\n```bash\nmake update-deps\n```\n\nOptional - run hooks to verify setup:\n\n```bash\nmake pre-commit\n```\n\n### 5. Configure Environment Variables\n\nCreate a `.env` file for your configuration:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your settings (GPIO pins, API keys, etc.)\n\n## Project Structure\n\n```\nYOUR-PROJECT-NAME/\n├── .vscode/                # VSCode settings\n├── examples/               # Example scripts and wiring diagrams\n│   ├── blink.py           # Basic LED blink example\n│   ├── blink_env.py       # Advanced example with env vars\n│   └── button.py          # Button input example\n├── src/                    # Your application code\n│   └── your_package/\n├── tests/                  # Test files\n│   └── test_example.py    # Example test file\n├── typings/                # Custom type stubs for libraries without types\n├── .editorconfig           # Editor configuration\n├── .env.example            # Environment variable template\n├── .gitignore              # Git ignore rules\n├── .pre-commit-config.yaml # Pre-commit hooks\n├── LICENSE                 # MIT License\n├── Makefile                # Development commands\n├── pyproject.toml          # Project configuration\n└── README.md               # This file\n```\n\n## Development Workflow\n\n### Quick Reference\n\n```bash\nmake help          # Show all available commands\nmake format        # Format code with Ruff\nmake lint          # Check code with Ruff\nmake lint-fix      # Auto-fix linting issues\nmake typecheck     # Type check with mypy\nmake test          # Run tests\nmake test-cov      # Run tests with coverage report\nmake check         # Run all checks (lint + typecheck + test)\nmake pre-commit    # Run pre-commit hooks manually\n```\n\n### Running Code Quality Tools\n\n```bash\n# Format and lint your code\nmake format\nmake lint-fix\n\n# Type check\nmake typecheck\n\n# Run everything at once\nmake check\n```\n\n### Running Tests\n\n```bash\n# Run all tests\nmake test\n\n# Run with coverage report\nmake test-cov\n# Coverage report will be in htmlcov/index.html\n\n# Run specific test file\npytest tests/test_example.py\n```\n\n### GPIO Access\n\nMost GPIO operations require root privileges. Run your scripts with sudo:\n\n```bash\nsudo python3 your_script.py\n```\n\nAlternatively, add your user to the gpio group:\n\n```bash\nsudo usermod -a -G gpio $USER\n# Log out and back in for changes to take effect\n```\n\n## Common GPIO Pins\n\n| Pin       | Function               | Notes                        |\n| --------- | ---------------------- | ---------------------------- |\n| 18        | PWM0                   | Good for LED control, servos |\n| 12        | PWM0                   | Alternative PWM pin          |\n| 23, 24    | GPIO                   | General purpose I/O          |\n| 2, 3      | I2C (SDA, SCL)         | For sensors and displays     |\n| 10, 9, 11 | SPI (MOSI, MISO, SCLK) | For high-speed devices       |\n\n**Warning**: Always check your specific Raspberry Pi model's pinout. Use 3.3V logic levels unless using a level shifter.\n\n## Example Usage\n\nPi-Thon includes several ready-to-run examples in the `examples/` directory:\n\n- **`blink.py`** - Basic LED blink with proper cleanup and error handling\n- **`blink_env.py`** - Advanced example using environment variables, type hints, and input validation\n- **`button.py`** - Button input controlling an LED with event-driven programming\n\n### Running Examples\n\n```bash\n# Basic LED blink\npython3 examples/blink.py\n\n# Advanced example with .env configuration\npython3 examples/blink_env.py\n\n# Button-controlled LED\npython3 examples/button.py\n```\n\nSee the individual example files for wiring diagrams and detailed comments.\n\n## Development on Non-Pi Systems\n\nPi-Thon includes type stubs in the `typings/` directory that enable you to write and type-check GPIO code on your development machine (Mac, Linux, Windows) before deploying to your Raspberry Pi.\n\n### How It Works\n\nThe type stubs provide type information for `gpiozero` and `RPi.GPIO` without requiring the actual libraries to be installed. This means:\n\n- ✅ **Full IDE support**: Autocomplete, inline documentation, and type hints work in VSCode\n- ✅ **Type checking passes**: `make typecheck` works on any system\n- ✅ **Code runs unchanged**: Deploy the same code to your Pi without modifications\n- ✅ **Catch errors early**: Find type errors before running on hardware\n\n### Development Workflow\n\n1. **Write code on your Mac/PC** with full IDE support:\n\n   ```python\n   from gpiozero import LED  # Type hints work!\n   from time import sleep\n\n   led = LED(17)  # IDE knows what methods are available\n   led.on()       # Autocomplete works!\n   ```\n\n2. **Run type checking locally**:\n\n   ```bash\n   make typecheck  # Passes even without GPIO hardware\n   ```\n\n3. **Deploy to Raspberry Pi**:\n\n   ```bash\n   # On your Pi, install with hardware dependencies\n   make install-pi\n\n   # Run your code\n   python3 your_script.py\n   ```\n\n### Extending Type Stubs\n\nThe included stubs cover the most common GPIO components. If you need additional components, you can extend the stubs in `typings/gpiozero.pyi` or `typings/RPi/GPIO.pyi`. Just add the class or function signature - the implementation isn't needed since these are only for type checking!\n\n### VSCode Setup\n\n#### Install Recommended Extensions\n\nWhen you open the project in VSCode, you'll be prompted to install recommended extensions from [.vscode/extensions.json](.vscode/extensions.json). These include:\n\n- **Python** - Core Python language support\n- **Pylance** - Fast Python language server with type checking\n- **Ruff** - Fast Python linter and formatter\n- **mypy** - Static type checker integration\n- **Error Lens** - Inline error highlighting\n- **Remote SSH** - For working on your Raspberry Pi remotely\n- And more...\n\nIf you don't see the prompt, you can manually install them:\n\n1. Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)\n2. Type \"Extensions: Show Recommended Extensions\"\n3. Click \"Install All\" or install individually\n\n#### Select Python Interpreter\n\nYou need to select the correct Python interpreter for Pylance to recognize your installed dependencies:\n\n1. Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)\n2. Type \"Python: Select Interpreter\"\n3. Choose the interpreter from your virtual environment (should show `./venv/bin/python` or similar)\n\nYou can verify the active interpreter by checking the bottom-right corner of VSCode - it should show the Python version and environment path. If import errors persist after installing dependencies, make sure VSCode is using the correct interpreter.\n\n## Troubleshooting\n\n### Import Errors\n\nIf you get import errors for GPIO libraries, make sure you're running on a Raspberry Pi and have installed the dependencies:\n\n```bash\npip install RPi.GPIO gpiozero\n```\n\n### Permission Errors\n\nIf you get permission errors accessing GPIO:\n\n```bash\nsudo usermod -a -G gpio $USER\n# Then log out and back in\n```\n\n### mypy Errors for GPIO Libraries\n\nThe Raspberry Pi libraries don't have type stubs. These are configured to be ignored in `pyproject.toml`, but if you see warnings, they're expected and won't affect functionality.\n\n## Additional Resources\n\n- [Raspberry Pi GPIO Pinout](https://pinout.xyz/)\n- [gpiozero Documentation](https://gpiozero.readthedocs.io/)\n- [RPi.GPIO Documentation](https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/)\n- [Adafruit Learning Guides](https://learn.adafruit.com/)\n\n## Contributing\n\n1. Create a feature branch\n2. Make your changes\n3. Ensure all tests pass and pre-commit hooks succeed\n4. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimmynotjim%2Fpi-thon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjimmynotjim%2Fpi-thon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimmynotjim%2Fpi-thon/lists"}