docs/tutorial_custom_controller.md

# Custom Controller Tutorial

Mobly enables users to control custom hardware devices (e.g., smart lights, switches) by creating custom controller modules. This tutorial explains how to implement a production-ready custom controller.

## Controller Module Interface

A Mobly controller module needs to implement specific top-level functions to manage the device lifecycle.

**Required functions:**

* **`create(configs)`**: Instantiates controller objects from the configuration.
* **`destroy(objects)`**: Cleans up resources when the test ends.

**Optional functions:**

* **`get_info(objects)`**: Returns device information for the test report. If not implemented, no controller information will be included in the result.

## Implementation Example

The following example demonstrates a custom controller for a **Smart Light**, featuring type hinting, input validation, and fault-tolerant cleanup.

### 1. Controller Module (`smart_light.py`)

Save this code as `smart_light.py`.

```python
"""Mobly controller module for a Smart Light."""

import logging
from typing import Any, Dict, List

# The key used in the config file to identify this controller.
MOBLY_CONTROLLER_CONFIG_NAME = "SmartLight"

class SmartLight:
    """A class representing a smart light device.
    
    Attributes:
        name: the name of the device.
        ip: the IP address of the device.
        is_on: True if the light is currently on, False otherwise.
    """

    def __init__(self, name: str, ip: str):
        self.name = name
        self.ip = ip
        self.is_on = False
        logging.info("Initialized SmartLight [%s] at %s", self.name, self.ip)

    def power_on(self):
        """Turns the light on."""
        self.is_on = True
        logging.info("SmartLight [%s] turned ON", self.name)

    def power_off(self):
        """Turns the light off."""
        self.is_on = False
        logging.info("SmartLight [%s] turned OFF", self.name)

    def close(self):
        """Simulates closing the connection."""
        logging.info("SmartLight [%s] connection closed", self.name)


def create(configs: List[Dict[str, Any]]) -> List[SmartLight]:
    """Creates SmartLight instances from a list of configurations.

    Args:
        configs: A list of dicts, where each dict represents a configuration
            for a SmartLight device.

    Returns:
        A list of SmartLight objects.

    Raises:
        ValueError: If a required configuration parameter is missing.
    """
    devices = []
    for config in configs:
        if "name" not in config or "ip" not in config:
            raise ValueError(
                f"Invalid config: {config}. 'name' and 'ip' are required."
            )
        
        devices.append(SmartLight(
            name=config["name"],
            ip=config["ip"]
        ))
    return devices


def destroy(objects: List[SmartLight]) -> None:
    """Cleans up SmartLight instances.
    
    Args:
        objects: A list of SmartLight objects to be destroyed.
    """
    for light in objects:
        try:
            if light.is_on:
                light.power_off()
            light.close()
        except Exception:
            # Catching broad exceptions ensures that a failure in one device
            # does not prevent others from being cleaned up.
            logging.exception("Failed to clean up SmartLight [%s]", light.name)


def get_info(objects: List[SmartLight]) -> List[Dict[str, Any]]:
    """Returns information for the test result.

    Args:
        objects: A list of SmartLight objects.

    Returns:
        A list of dicts containing device information.
    """
    return [{"name": light.name, "ip": light.ip} for light in objects]

```

### 2. Controller Module (`smart_light.py`)

To use the custom controller, register it in your test script.

```python
from mobly import base_test
from mobly import test_runner
import smart_light

class LightTest(base_test.BaseTestClass):
    def setup_class(self):
        # Register the custom controller
        self.lights = self.register_controller(smart_light)

    def test_turn_on(self):
        light = self.lights[0]
        light.power_on()
        
        # Verify the light is on
        if not light.is_on:
            raise signals.TestFailure(f"Light {light.name} should be on!")

if __name__ == "__main__":
    test_runner.main()
```

### 3. Configuration File (config.yaml)
Define the device in your configuration file using the SmartLight key.
```yaml
TestBeds:
  - Name: BedroomTestBed
    Controllers:
      SmartLight:
        - name: "BedLight"
          ip: "192.168.1.50"
```