Repository navigation
Architecture
This page describes the internal code structure of the OpenEVSE integration for contributors and developers.
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
The integration uses Home Assistant's DataUpdateCoordinator pattern:
-
OpenEVSEUpdateCoordinator(in__init__.py): Polls the charger for all primary sensor data. Most entity platforms areCoordinatorEntitysubclasses that re-render on coordinator updates. -
OpenEVSEFWUpdateCoordinator(in__init__.py): A separate, less-frequent coordinator for firmware update checks (queries GitHub API).
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) -> boolused by platforms and services to gate firmware-dependent features.
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.
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 = NoneAll 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.
Entities and services check firmware versions in two ways:
-
Entities: The
min_versionfield on the entity description. Platforms check this field and either skip registering the entity (e.g., calendar) or setavailable = False(e.g., switches/sensors). -
Services:
version_check()is called explicitly at the top of each service handler inservices.py, raising aHomeAssistantErrorwith a standardized warning if the check fails.
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
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.
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.
| 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.