Skip to content

Architecture

firstof9 edited this page Sep 28, 2026 · 1 revision

Architecture

This page describes the internal code structure of the OpenEVSE integration for contributors and developers.


Directory Layout

custom_components/openevse/
├── __init__.py          # Entry setup, coordinator, state change listeners
├── manifest.json        # Integration metadata & dependencies
├── const.py             # All constants, entity descriptions, service names
├── entity.py            # Base entity classes and typed EntityDescription dataclasses
├── config_flow.py       # UI config flow (setup & options)
├── logger.py            # Custom logger adapter (adds device name prefix)
├── diagnostics.py       # HA diagnostics support
│
├── sensor.py            # Sensor platform
├── binary_sensor.py     # Binary sensor platform
├── switch.py            # Switch platform
├── select.py            # Select platform
├── number.py            # Number platform
├── light.py             # Light platform (LED brightness)
├── button.py            # Button platform
├── calendar.py          # Calendar platform (scheduling)
├── update.py            # Update platform (OTA firmware)
│
├── services.py          # Custom service handlers
├── services.yaml        # Service schema definitions (UI descriptions)
└── translations/        # Localization strings

Core Concepts

Coordinator Pattern

The integration uses Home Assistant's DataUpdateCoordinator pattern:

  • OpenEVSEUpdateCoordinator (in __init__.py): Polls the charger for all primary sensor data. Most entity platforms are CoordinatorEntity subclasses that re-render on coordinator updates.
  • OpenEVSEFWUpdateCoordinator (in __init__.py): A separate, less-frequent coordinator for firmware update checks (queries GitHub API).

OpenEVSEManager

A wrapper around the python-openevse-http library client (OpenEVSE). It:

  • Holds the active HTTP/WebSocket connection to the charger.
  • Exposes all charger command methods (e.g., set_override, toggle_override, set_current).
  • Provides version_check(min_version: str) -> bool used by platforms and services to gate firmware-dependent features.

Real-Time Updates via WebSockets

In addition to the polling coordinator, the integration subscribes to the charger's WebSocket feed for real-time push updates. When the charger broadcasts a state change, a handle_state_change callback in __init__.py updates the coordinator's data snapshot and triggers entity refresh without waiting for the next poll interval.


Entity Description Pattern

Entities are defined declaratively using typed EntityDescription dataclasses in entity.py:

@dataclass
class OpenEVSESensorEntityDescription(SensorEntityDescription):
    value_fn: Callable[[dict], Any] | None = None
    min_version: str | None = None
    is_async_value: bool = False
    value: str | None = None

All entity descriptions are instantiated as tuples of constants in const.py (e.g., SENSOR_TYPES, SWITCH_TYPES, BINARY_SENSORS). Each platform's async_setup_entry iterates over its constant tuple to create the entities.

Firmware Version Gating

Entities and services check firmware versions in two ways:

  • Entities: The min_version field on the entity description. Platforms check this field and either skip registering the entity (e.g., calendar) or set available = False (e.g., switches/sensors).
  • Services: version_check() is called explicitly at the top of each service handler in services.py, raising a HomeAssistantError with a standardized warning if the check fails.

Data Flow

Charger (HTTP + WebSocket)
        │
        ▼
  OpenEVSEManager (python-openevse-http)
        │
        ├─── Polling ──▶ OpenEVSEUpdateCoordinator ──▶ Entity state refresh
        │
        └─── WS Push ──▶ handle_state_change() ──▶ coordinator.async_set_updated_data()
                                                          └─▶ Entity state refresh

Service Registration

Services are registered in __init__.py during async_setup using hass.services.async_register(). The handler logic lives in services.py, which imports OpenEVSEManager from hass.data using the entry_id resolved from the service call's target entities or device IDs.

Service schemas are defined in services.yaml and consumed by the HA UI to generate the service call form.


Constants & Warning Templates

const.py contains all domain constants. Two shared warning string templates are used throughout the codebase for DRY logging:

FW_VERSION_WARN = "%s requires firmware version %s or higher."
NON_NUMERIC_WARN = "Non-numeric state for %s sensor: %s"

Use these constants rather than hardcoding warning strings in platform code.


Key Dependencies

Package Purpose
python-openevse-http Official OpenEVSE HTTP/WebSocket client library
homeassistant Home Assistant core (HA >= 2024.5)

The pinned version of python-openevse-http is in requirements.txt. The full test dependency set is in requirements_test.txt.

Clone this wiki locally