Documentation

Event System

MudPi uses Redis and MQTT pub/sub for real-time communication between all system components.

Overview

MudPi's event system is the communication backbone that connects all components. Events are published to topics and any subscriber listening on that topic receives the message. MudPi supports both Redis pub/sub and MQTT as event transports.

Events & Topics

Events are messages published to named topics. Components publish events when their state changes, and other components subscribe to those topics to react. Topics use a dot-notation namespace format.

Subscribing to Events

You can subscribe to events from within MudPi or externally through Redis:

Python

import redis

r = redis.Redis(host='localhost', port=6379)
pubsub = r.pubsub()
pubsub.subscribe('mudpi:events')

for message in pubsub.listen():
    if message['type'] == 'message':
        print(message['data'])

Core Events

MudPi emits a set of core events throughout its lifecycle and operation:

System Lifecycle Events

Event	Description
`Loaded`	Configuration and extensions have been loaded
`Starting`	MudPi is initializing workers and components
`Started`	All workers are running and the system is operational
`Stopping`	Shutdown signal received, workers are being stopped
`Stopped`	All workers have stopped
`ShuttingDown`	Final cleanup is in progress
`Shutdown`	MudPi has fully shut down

Component Events

Event	Description
`StateUpdated`	A component's state has changed
`ActionCall`	An action has been requested
`ActionRegistered`	A new action has been registered
`ComponentRegistered`	A new component has been registered
`ExtensionRegistered`	A new extension has been loaded

Extension Events

Extensions can emit their own events. For example, the toggle extension emits ToggleUpdated when a toggle state changes:

JSON

{
  "event": "ToggleUpdated",
  "component_id": "led_indicator",
  "state": 1,
  "updated_at": "2024-03-15T10:30:00Z"
}

Multiple Event Systems

MudPi supports running multiple event systems simultaneously (e.g., Redis and MQTT). When multiple systems are active, events are broadcast to all of them. To prevent duplicate processing, each event includes a UUID that subscribers use for deduplication.

Note

When using multiple event systems, MudPi assigns a UUID to each event. Subscribers track seen UUIDs and skip duplicates automatically.

Tip

Use the Redis CLI to monitor all events during development: redis-cli PSUBSCRIBE "mudpi:*"

Previous ← State Next Data Storage →