Skip to main content

​
Layer 4: Coordination Engine

Production Ready Python License: MIT Layer 4 bridges the gap between Layer 3’s optimization schedules and real-world energy assets. It converts time-indexed dispatch plans into device-specific commands, manages asset state lifecycles, and provides event-driven coordination across the system.

​
Available Features

Dispatch Engine

Converts Layer 3 OptimizationResult schedules into timed commands with lifecycle tracking and retry logic

State Machines

OCPP-aligned EV charger and battery state machines with transition guards and event publishing

Protocol Adapters

OCPP adapter for EV chargers, Modbus adapter for batteries, with an extensible registry pattern

Event Bus

Typed synchronous pub/sub system for real-time coordination events across all components

​
Quick Start

​
Installation

pip install qubit-energy-coordinator

​
Dispatch an Optimization Schedule

from coordinator import DispatchEngine, EventBus, OCPPAdapter, AdapterRegistry

# Set up infrastructure
bus = EventBus()
registry = AdapterRegistry()
registry.register("ast_ev_001", OCPPAdapter("ocpp_site_1"))

engine = DispatchEngine(event_bus=bus, adapter_registry=registry)

# Convert a Layer 3 schedule to commands
commands = engine.schedule_to_commands(
    optimization_result.schedule,
    asset_map={"ev_001": "ast_ev_001"}
)

# Dispatch pending commands
for cmd in engine.get_pending_commands(now):
    adapter = registry.get(cmd.asset_id)
    engine.dispatch_command(cmd, adapter)

​
Architecture

​
Core Components

​
Dispatch Engine

The central orchestration component. It reads an OptimizationResult.schedule DataFrame (from Layer 3) and produces timed Command objects:
  • EV columns (ev_{vehicle_id}_kw) become SET_CHARGE_RATE commands
  • Battery columns (battery_charge_kw, battery_discharge_kw) become SET_CHARGE_RATE / SET_DISCHARGE_RATE commands
  • Only emits commands on value changes (avoids redundant setpoints)
  • Tracks command lifecycle: PENDING → DISPATCHED → COMPLETED (or FAILED / TIMED_OUT)
  • Automatic retry with configurable backoff

​
State Machines

Generic finite state machine with energy asset presets:
OCPP-aligned lifecycle with 7 states:
AVAILABLE → PREPARING → CHARGING → FINISHING → AVAILABLE
                ↕           ↕
            SUSPENDED   FAULTED
                          ↕
                      UNAVAILABLE
Triggers: plug_in, start_charge, suspend, resume, complete, unplug, fault, reset, disable, enable

​
Protocol Adapters

Translate abstract commands into device-specific payloads:
Maps command types to OCPP 1.6/2.0 actions:
Command TypeOCPP Action
SET_CHARGE_RATESetChargingProfile
START_CHARGINGRemoteStartTransaction
STOP_CHARGINGRemoteStopTransaction
CHANGE_AVAILABILITYChangeAvailability
Generates complete OCPP JSON payloads including charging profiles with power limits in watts.

​
Event Bus

Typed synchronous pub/sub with 8 event types: 
from coordinator import EventBus, EventType

bus = EventBus()

# Subscribe to state changes
bus.subscribe(EventType.STATE_CHANGED, lambda e: print(
    f"Asset {e.payload['asset_id']}: {e.payload['from_state']} → {e.payload['to_state']}"
))

# Subscribe to command failures for alerting
bus.subscribe(EventType.COMMAND_FAILED, lambda e: alert_oncall(e.payload))
Event types: COMMAND_CREATED, COMMAND_DISPATCHED, COMMAND_ACKNOWLEDGED, COMMAND_COMPLETED, COMMAND_FAILED, COMMAND_TIMED_OUT, STATE_CHANGED, SCHEDULE_RECEIVED

​
Integration with Qubit Stack

1

Receive Schedule

Layer 3 produces an OptimizationResult with a schedule DataFrame containing per-asset power setpoints
2

Generate Commands

DispatchEngine.schedule_to_commands() parses the DataFrame columns and creates timed Command objects
3

Validate State

State machines are checked before dispatch — commands to faulted or unavailable assets are held
4

Translate Protocol

The AdapterRegistry finds the correct protocol adapter and translates the command to device-specific format
5

Dispatch & Track

Commands are sent to assets, responses tracked, and events published for monitoring and re-optimization triggers

​
Next Steps

Get Started

Install and dispatch your first schedule in 5 minutes

Dispatch Engine

Deep dive into schedule-to-command conversion and lifecycle management

State Machines

EV charger and battery state machine details

Protocol Adapters

OCPP, Modbus, and custom adapter development

GitHub Repository

Explore source code and contribute
Layer 4 Coordination Engine bridges optimization intelligence with physical energy assets, enabling real-time dispatch and control.