Developer Setup¶

Set up your development environment for Tinko plugin development.

Prerequisites¶

Before starting, ensure you have:

Computer running Windows, macOS, or Linux
Python 3.12 or higher installed
Git installed
Text editor or IDE (VS Code, PyCharm, etc.)
Optional: Raspberry Pi for hardware testing

Step 1: Install UV Package Manager¶

UV is the modern Python package manager used by Tinko.

macOS / Linux¶

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows¶

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Restart your terminal after installation.

Step 2: Clone the Repository¶

git clone https://github.com/rudolf-erdei/edu-pi.git
cd edu-pi

Step 3: Install Dependencies¶

Install base dependencies:

uv sync

This installs all required packages including Django, gpiozero, pygame, etc.

Step 4: Set Up Development Environment¶

Create .env File¶

Create a .env file in the project root:

# Development settings
DEBUG=True
SECRET_KEY=your-dev-secret-key-not-for-production
ALLOWED_HOSTS=localhost,127.0.0.1,0.0.0.0
TIME_ZONE=Europe/Bucharest

Replace your-dev-secret-key with a random string.

IDE Configuration¶

VS Code¶

Create .vscode/settings.json:

{
    "python.defaultInterpreterPath": ".venv/bin/python",
    "python.analysis.extraPaths": ["."],
    "python.testing.pytestEnabled": true,
    "python.testing.pytestArgs": ["tests"],
    "python.linting.enabled": true,
    "python.formatting.provider": "black",
    "editor.formatOnSave": true,
}

PyCharm¶

Open the project in PyCharm
Go to File > Settings > Project > Python Interpreter
Point to the .venv directory created by UV
Mark plugins/ as Sources Root

Step 5: Run Migrations¶

Set up the database:

uv run python manage.py migrate

Step 6: Create Superuser¶

Create an admin account:

uv run python manage.py createsuperuser

Follow the prompts.

Step 7: Start Development Server¶

uv run python manage.py runserver

Access the application at:

Dashboard: http://localhost:8000/
Admin Panel: http://localhost:8000/admin/

Development Workflow¶

Making Changes¶

Edit code in your IDE
Run server: uv run python manage.py runserver
Test changes in browser
Run tests: uv run pytest

Adding Dependencies¶

uv add package-name

This updates both pyproject.toml and uv.lock.

Running Tests¶

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_plugin.py

# Run with verbose output
uv run pytest -v

# Run with coverage
uv run pytest --cov=core

Code Formatting¶

If you have Black installed:

uv run black .

Mock Mode for Non-Pi Development¶

When developing on a non-Raspberry Pi system, GPIO operations are automatically mocked. This allows you to:

Develop plugins without hardware
Test logic without GPIO errors
Debug code on any platform

The system detects when gpiozero is not available and uses mock implementations instead.

Project Structure¶

Familiarize yourself with the project:

edu-pi/
├── config/              # Django configuration
├── core/                # Core functionality
│   └── plugin_system/  # Plugin framework
├── plugins/            # Plugin directory
│   └── edupi/         # Built-in plugins
├── templates/          # HTML templates
├── static/             # CSS/JS assets
├── tests/              # Test suite
└── docs/               # Documentation

Debugging Tips¶

Enable Debug Mode¶

Set DEBUG=True in your .env file for detailed error pages.

Django Shell¶

Access the Django shell for debugging:

uv run python manage.py shell

Example:

from core.plugin_system.base import plugin_manager
plugins = plugin_manager.get_all_plugins()
print(plugins)

Logging¶

Set logging level in config/settings.py:

LOGGING = {
    'version': 1,
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        '': {
            'handlers': ['console'],
            'level': 'DEBUG',
        },
    },
}

Browser DevTools¶

Use browser Developer Tools (F12) to:

View console logs
Inspect WebSocket connections
Debug JavaScript
Monitor network requests

Common Issues¶

Import Errors¶

If you see import errors:

Ensure UV virtual environment is activated
Check sys.path includes project root
Verify imports use correct module paths

Database Locked¶

SQLite may lock during development:

# Stop the server
# Wait a few seconds
# Restart
uv run python manage.py runserver

Port Already in Use¶

# Find process using port 8000
lsof -i :8000

# Kill process
kill -9 <PID>

Raspberry Pi Testing¶

When testing on actual hardware:

Copy code to Pi
Install Pi dependencies: uv sync --extra pi
Run as user with GPIO access: sudo usermod -a -G gpio pi
Test with actual hardware connected

Next Steps¶

Project Structure - Understand the codebase
Hardware Requirements - Connect GPIO components
Plugin Tutorial - Create your first plugin
Plugin API - Plugin development reference

Useful Commands¶

# Start development server
uv run python manage.py runserver

# Run tests
uv run pytest

# Run migrations
uv run python manage.py migrate

# Create superuser
uv run python manage.py createsuperuser

# Django shell
uv run python manage.py shell

# Check plugin loading
uv run python -c "from core.plugin_system.base import plugin_manager; print(plugin_manager.get_all_plugins())"

# Compile translations
python scripts/compile_translations.py

# Collect static files
uv run python manage.py collectstatic