Documentation

Creating Components

Learn how to create custom components with state, update cycles, and lifecycle hooks.

Overview

Components are the building blocks of MudPi. Every sensor, control, camera, and display is a component. Understanding the component structure lets you create custom functionality that integrates seamlessly with MudPi.

Component Structure

Every component has three core properties:

  • id — A unique identifier (set via the key in config)
  • state — The current value or status of the component
  • update() — Called on each update cycle to refresh the component
Example Component 
from mudpi.extensions import Component

class MyComponent(Component):
    """A minimal custom component."""

    def init(self):
        self.state = None

    def update(self):
        self.state = self._read_value()
        return self.state

    def _read_value(self):
        return 42

The should_update Property

The should_update property controls whether the component's update() method runs on a given cycle. Override it to add custom logic, such as skipping updates when the component is disabled:

Python 
@property
def should_update(self):
    """Only update if the component is active."""
    return self.active and self.connected

Lifecycle Methods

Components support the following lifecycle hooks:

Method When It's Called
init() Once when the component is first created
update() On each update cycle (controlled by should_update)
reload() When the component's configuration is changed at runtime
unload() When the component is being shut down or removed

Note

The lifecycle follows the pattern: init → update (repeating) → unload. The reload() method is only called if the configuration changes while MudPi is running.

Additional Properties

Components can define additional metadata properties:

  • name — A human-readable name for the component
  • metadata — A dictionary of arbitrary metadata
  • classifier — A classification tag that determines state key prefixes

Classifiers

The classifier property categorizes your component for consistent state key naming:

Classifier Prefix Example State Key
battery battery_ battery_level
current current_ current_draw
humidity humidity_ humidity_greenhouse
temperature temperature_ temperature_outdoor
moisture moisture_ moisture_bed_1
power power_ power_panel
pressure pressure_ pressure_tank
signal_strength signal_ signal_node_1
voltage voltage_ voltage_battery
Previous ← Extending MudPi Next Developers: Interfaces →