Extensions

Overview

Extensions allow you to add new components, sensors, and functionality to MudPi without modifying the core codebase. Each extension is a self-contained Python package with its own namespace and configuration.

Extension Basics

Every extension requires a namespace (a unique identifier) and can optionally define an update_interval to control how frequently the extension's components are updated.

Minimal Extension

from mudpi.extensions import Extension

class MyExtension(Extension):
    namespace = 'my_extension'
    update_interval = 30

Creating a New Extension

Let's build a simple "hello" extension step by step. Create a new directory for your extension and add an __init__.py file:

from mudpi.extensions import Extension

class HelloExtension(Extension):
    namespace = 'hello'
    update_interval = 60

    def init(self, config):
        """Initialize the extension with its config."""
        self.config = config

    def validate(self, config):
        """Validate configuration before loading."""
        if 'key' not in config:
            raise ValueError('Hello extension requires a key')
        return True

Extension Descriptor

Each extension should include an extension.json file that describes it:

{
  "name": "Hello Extension",
  "namespace": "hello",
  "description": "A simple example extension for MudPi.",
  "version": "0.1.0",
  "author": "Your Name"
}

Loading Extensions

Extensions are loaded through your MudPi configuration file. Add the extension's namespace to the config:

{
  "hello": [
    {
      "key": "hello_1",
      "name": "Hello World"
    }
  ]
}

Extension Interfaces

Extensions can define their own interfaces to provide different implementations of a component type. For example, a sensor extension might support both GPIO and I2C interfaces.

Example Extension Sensor

from mudpi.extensions import Component

class ExampleSensor(Component):
    """An example sensor provided by the hello extension."""

    def init(self):
        self.type = self.config.get('type', 'default')
        self.pin = self.config.get('pin')

    def update(self):
        """Read the sensor and update state."""
        reading = self._read_sensor()
        self.state = reading
        return reading

    def _read_sensor(self):
        """Perform the actual sensor read."""
        return 42

Loading Interfaces via Config

Specify the interface key in your configuration to select which interface implementation to use:

{
  "sensor": [
    {
      "key": "example_sensor_1",
      "interface": "hello",
      "type": "default",
      "pin": 4
    }
  ]
}