Documentation

Creating Interfaces

Add new interfaces to extend MudPi's core components with custom hardware support.

Overview

Interfaces provide specific implementations for MudPi components. A single component type (like a sensor) can have many interfaces (GPIO, I2C, serial, etc.), each handling different hardware or protocols. Creating a custom interface lets you add support for new hardware without modifying existing code.

File Structure

Interfaces live inside an extension directory. Here's the structure for a "counter" extension that provides a custom sensor interface:

Extension Structure

counter/
├── __init__.py       # Extension class
├── extension.json    # Extension descriptor
└── sensor.py         # Sensor interface implementation

Creating an Interface

First, define the extension in __init__.py:

counter/__init__.py

from mudpi.extensions import Extension

class CounterExtension(Extension):
    namespace = 'counter'
    update_interval = 10

Then create the interface class in sensor.py. The interface must implement load() and validate():

counter/sensor.py

from mudpi.extensions.sensor import Sensor

class CounterSensor(Sensor):
    """A sensor that counts up on each update cycle."""

    def load(self):
        """Load and prepare the sensor hardware."""
        self.count = 0

    def validate(self, config):
        """Validate the configuration for this interface."""
        if 'key' not in config:
            raise ValueError('CounterSensor requires a key')
        return True

    def init_sensor(self):
        """Initialize the counter."""
        self.count = self.config.get('start', 0)
        self.step = self.config.get('step', 1)
        self.state = self.count

    def read(self):
        """Increment the counter and return the new value."""
        self.count += self.step
        self.state = self.count
        return self.state

Click to expand code…

Loading the Interface

Reference the interface by its extension namespace in your configuration:

mudpi.config.json

{
  "sensor": [
    {
      "key": "cycle_counter",
      "interface": "counter",
      "start": 0,
      "step": 1,
      "name": "Update Cycle Counter"
    }
  ]
}

Tip

The interface value maps to the extension's namespace. MudPi locates the correct file by matching the component type (e.g., sensor) to a file in the extension directory (e.g., sensor.py).

Additional Resources

Extensions — Learn about the extension system
Creating Components — Understand the component lifecycle
Extending MudPi — Guides for building on MudPi

Previous ← Developers: Components Next API Reference →