feat: add use_iot optional feature axis

Adds `use_iot` (default false) to copier.yaml. When enabled:

- pyproject.toml: [iot] optional-deps group (pyserial, paho-mqtt,
  gpiozero, smbus2, bleak)
- src/{name}/drivers/: SerialPort, DigitalOutput/Input, MQTTClient
  Protocols with real implementations; lazy hardware imports so tests
  never require physical devices
- src/{name}/sensors/: empty package scaffold for sensor logic
- config/device.yaml.example: annotated template for MQTT, serial, GPIO
  config; device.yaml is gitignored
- tests/conftest.py: mock_serial fixture (patches serial.Serial) and
  autouse mock_gpio fixture (gpiozero MockFactory)
- tests/test_drivers.py: serial, GPIO, and MQTT smoke tests; MQTT
  connects to a real broker, serial/GPIO use mocks
- ci.yml: starts eclipse-mosquitto:2 before the test job when use_iot
- justfile: deploy recipe — rsync+systemd when use_docker=none,
  docker-pull+compose when use_docker=cpu/gpu

Co-Authored-By: Claude <noreply@anthropic.com>

Author: namitdeb739-aug

copier.yaml

@@ -89,6 +89,11 @@ use_devcontainer:
   default: false
   help: Include VS Code dev container config?
 
+use_iot:
+  type: bool
+  default: false
+  help: Include IoT/embedded setup (serial, GPIO, MQTT drivers, device config)?
+
 # --- Post-setup options ---
 
 init_dvc:
@@ -119,6 +124,10 @@ _tasks:
   # Remove disabled features
   - command: rm -rf .devcontainer/
     when: "{{ not use_devcontainer }}"
+  - command: rm -rf "src/{{ package_name }}/drivers/" "src/{{ package_name }}/sensors/" config/
+    when: "{{ not use_iot }}"
+  - command: rm -f tests/test_drivers.py
+    when: "{{ not use_iot }}"
   - command: rm -rf docker/ .dockerignore
     when: "{{ use_docker == 'none' }}"
   - command: rm -f docker/Dockerfile.gpu

template/.github/workflows/ci.yml.jinja

@@ -48,6 +48,13 @@ jobs:
           version: "0.11.3"
           python-version: ${{ '{{' }} matrix.python-version {{ '}}' }}
       - run: uv sync --dev
+{%- if use_iot %}
+      - name: Start MQTT broker
+        run: |
+          docker run -d --name mosquitto -p 1883:1883 eclipse-mosquitto:2 \
+            sh -c 'printf "allow_anonymous true\nlistener 1883\n" > /tmp/m.conf && mosquitto -c /tmp/m.conf'
+          sleep 2
+{%- endif %}
       - run: uv run pytest -v{% if testing != 'minimal' %} --cov=src --cov-report=xml{% endif %}
 
 {%- if testing != 'minimal' %}

template/.gitignore

@@ -52,6 +52,9 @@ output/
 .env
 .env.local
 
+# Device configuration (contains local IPs, pin numbers — not committed)
+config/device.yaml
+
 # OS
 .DS_Store
 Thumbs.db

template/config/device.yaml.example.jinja

@@ -0,0 +1,25 @@
+# Device configuration for {{ project_name }}
+#
+# Copy to config/device.yaml and fill in your values.
+# device.yaml is gitignored — never commit real device addresses or secrets.
+
+mqtt:
+  host: 192.168.1.100        # broker IP or hostname
+  port: 1883
+  client_id: {{ project_name }}-device
+  topics:
+    telemetry: "{{ project_name }}/telemetry"
+    commands:  "{{ project_name }}/commands"
+
+serial:
+  # Linux: /dev/ttyUSB0 or /dev/ttyAMA0 (UART on Pi GPIO header)
+  # macOS: /dev/cu.usbserial-XXXX
+  # Windows: COM3
+  port: /dev/ttyUSB0
+  baudrate: 115200
+  timeout: 1.0               # seconds
+
+gpio:
+  # BCM (Broadcom) pin numbers — not physical board numbers
+  led_pin: 17
+  button_pin: 27

template/justfile.jinja

@@ -137,6 +137,20 @@ dvc-init:
     uv run dvc config core.autostage true
 {% endif %}
 
+{% if use_iot %}
+{% if use_docker == 'none' %}
+# Deploy to device over SSH (rsync src + restart systemd service)
+deploy host:
+    rsync -av src/ pi@{{ '{{' }}host{{ '}}' }}:/opt/{{ project_name }}/src/
+    ssh pi@{{ '{{' }}host{{ '}}' }} sudo systemctl restart {{ project_name }}
+{% else %}
+# Deploy Docker image to device (pull latest and restart)
+deploy host tag="latest":
+    ssh pi@{{ '{{' }}host{{ '}}' }} docker pull ghcr.io/{{ github_user }}/{{ project_name }}:{{ '{{' }}tag{{ '}}' }}
+    ssh pi@{{ '{{' }}host{{ '}}' }} docker compose -f /opt/{{ project_name }}/docker-compose.yml up -d
+{% endif %}
+{% endif %}
+
 # Clean build artifacts
 clean:
     rm -rf dist/ build/{% if use_docs %} site/{% endif %} .pytest_cache/{% if use_typecheck %} .mypy_cache/{% endif %} .ruff_cache/ htmlcov/

template/pyproject.toml.jinja

@@ -32,9 +32,10 @@ dev = [
     "commitizen>=4.1",
     "copier>=9.0",
 ]
-{% if use_ml %}
+{% if use_ml or use_iot %}
 
 [project.optional-dependencies]
+{%- if use_ml %}
 ml = [
     # Uncomment the libraries you need:
     # "numpy>=1.26",
@@ -45,6 +46,16 @@ ml = [
     # "transformers>=4.40",
     # "dvc>=3.50",
 ]
+{%- endif %}
+{%- if use_iot %}
+iot = [
+    "pyserial>=3.5",     # UART / serial communication
+    "paho-mqtt>=2.0",    # MQTT messaging
+    "gpiozero>=2.0",     # GPIO abstraction with built-in mock support
+    "smbus2>=0.5",       # I2C sensor communication
+    "bleak>=0.21",       # Bluetooth LE (async, cross-platform)
+]
+{%- endif %}
 {% endif %}
 
 [project.scripts]

template/src/project_name/drivers/__init__.py

@@ -0,0 +1 @@
+"""Hardware driver abstractions."""

template/src/project_name/drivers/gpio.py.jinja

@@ -0,0 +1,58 @@
+"""GPIO driver — digital I/O abstraction via gpiozero.
+
+gpiozero ships a :class:`~gpiozero.pins.mock.MockFactory` that replaces real
+hardware in CI.  The ``mock_gpio`` fixture in ``conftest.py`` activates it
+automatically for all tests — no extra setup needed.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class DigitalOutput(Protocol):
+    """Abstract digital output pin (LED, relay, buzzer …)."""
+
+    @property
+    def value(self) -> int: ...
+    def on(self) -> None: ...
+    def off(self) -> None: ...
+    def toggle(self) -> None: ...
+    def close(self) -> None: ...
+
+
+class DigitalInput(Protocol):
+    """Abstract digital input pin (button, switch, sensor …)."""
+
+    @property
+    def value(self) -> int: ...
+    def close(self) -> None: ...
+
+
+def led(pin: int) -> DigitalOutput:
+    """Create a digital output on a BCM pin number.
+
+    Args:
+        pin: BCM pin number (e.g. ``17``).
+
+    Returns:
+        A :class:`DigitalOutput` backed by :class:`~gpiozero.LED`.
+    """
+    from gpiozero import LED  # type: ignore[import-untyped]
+
+    return LED(pin)  # type: ignore[return-value]
+
+
+def button(pin: int, pull_up: bool = True) -> DigitalInput:
+    """Create a digital input on a BCM pin number.
+
+    Args:
+        pin: BCM pin number (e.g. ``27``).
+        pull_up: Use internal pull-up resistor. Set to ``False`` for pull-down.
+
+    Returns:
+        A :class:`DigitalInput` backed by :class:`~gpiozero.Button`.
+    """
+    from gpiozero import Button  # type: ignore[import-untyped]
+
+    return Button(pin, pull_up=pull_up)  # type: ignore[return-value]

template/src/project_name/drivers/mqtt.py.jinja

@@ -0,0 +1,45 @@
+"""MQTT driver — publish/subscribe messaging via paho-mqtt.
+
+Use the :class:`MQTTClient` Protocol as the type annotation throughout the
+codebase.  Pass a real :func:`create_client` in production and a
+:class:`unittest.mock.MagicMock` in tests.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Protocol
+
+
+MessageCallback = Callable[[str, bytes], None]
+
+
+class MQTTClient(Protocol):
+    """Abstract MQTT client interface."""
+
+    def connect(self, host: str, port: int = 1883) -> None: ...
+    def disconnect(self) -> None: ...
+    def publish(self, topic: str, payload: str | bytes) -> None: ...
+    def loop_start(self) -> None: ...
+    def loop_stop(self) -> None: ...
+
+
+def create_client(client_id: str = "") -> MQTTClient:
+    """Create a paho-mqtt client satisfying :class:`MQTTClient`.
+
+    Args:
+        client_id: Optional client identifier. Auto-generated if empty.
+
+    Returns:
+        A configured paho MQTT client (not yet connected).
+
+    Example::
+
+        client = create_client("{{ project_name }}-device")
+        client.connect("192.168.1.100")
+        client.loop_start()
+        client.publish("{{ project_name }}/telemetry", '{"temp": 21.5}')
+    """
+    import paho.mqtt.client as mqtt  # type: ignore[import-untyped]
+
+    return mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=client_id)  # type: ignore[return-value]

template/src/project_name/drivers/serial.py.jinja

@@ -0,0 +1,41 @@
+"""Serial port driver — UART communication abstraction.
+
+Define all serial interactions through the :class:`SerialPort` Protocol so
+tests can swap in a mock without touching production code paths.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class SerialPort(Protocol):
+    """Abstract serial port interface."""
+
+    def write(self, data: bytes) -> int: ...
+    def read(self, size: int) -> bytes: ...
+    def readline(self) -> bytes: ...
+    def close(self) -> None: ...
+
+
+def open_serial(port: str, baudrate: int = 115200, timeout: float = 1.0) -> SerialPort:
+    """Open a real serial port.
+
+    Args:
+        port: Device path — e.g. ``/dev/ttyUSB0``, ``/dev/ttyAMA0``, or ``COM3``.
+        baudrate: Communication speed in bits/second.
+        timeout: Read timeout in seconds.
+
+    Returns:
+        An open :class:`SerialPort`.
+
+    Example::
+
+        port = open_serial("/dev/ttyUSB0", baudrate=9600)
+        port.write(b"AT\\r\\n")
+        response = port.readline()
+        port.close()
+    """
+    import serial  # pyserial — imported lazily so tests don't require hardware
+
+    return serial.Serial(port, baudrate=baudrate, timeout=timeout)  # type: ignore[return-value]