Layer 4: Coordination Engine

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:

EV Charger
Battery

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

5-state battery management:

IDLE ↔ CHARGING ↔ DISCHARGING
  ↕
STANDBY    FAULTED

Supports direct mode switching (charge → discharge without stopping). Triggers: charge, discharge, stop, standby, activate, fault, reset

Protocol Adapters

Translate abstract commands into device-specific payloads:

OCPP (EV Chargers)
Modbus (Batteries)

Maps command types to OCPP 1.6/2.0 actions:

Command Type	OCPP Action
`SET_CHARGE_RATE`	`SetChargingProfile`
`START_CHARGING`	`RemoteStartTransaction`
`STOP_CHARGING`	`RemoteStopTransaction`
`CHANGE_AVAILABILITY`	`ChangeAvailability`

Generates complete OCPP JSON payloads including charging profiles with power limits in watts.

Maps commands to Modbus register writes:

Command Type	Default Register
`SET_CHARGE_RATE`	40001
`SET_DISCHARGE_RATE`	40002
`SET_POWER_LIMIT`	40003
`SET_SOC_TARGET`	40004

Custom register maps supported per deployment.

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

Receive Schedule

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

Generate Commands

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

Validate State

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

Translate Protocol

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

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.

​Layer 4: Coordination Engine

​Available Features

Dispatch Engine

State Machines

Protocol Adapters

Event Bus

​Quick Start

​Installation

​Dispatch an Optimization Schedule

​Architecture

​Core Components

​Dispatch Engine

​State Machines

​Protocol Adapters

​Event Bus

​Integration with Qubit Stack

​Next Steps

Get Started

Dispatch Engine

State Machines

Protocol Adapters

GitHub Repository

Layer 4: Coordination Engine

Available Features

Quick Start

Installation

Dispatch an Optimization Schedule

Architecture

Core Components

Dispatch Engine

State Machines

Protocol Adapters

Event Bus

Integration with Qubit Stack

Next Steps