ETM-Schurig
/
powersync-energy-plugin-etm
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
powersync-energy-plugin-etm/CLAUDE.md

4.2 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is a nymea energy plugin (Qt/C++ shared library) that extends the nymea energy experience with smart EV charging, spot market price-based charging scheduling, and overload protection. It links against libnymea and libnymea-energy and is loaded at runtime by the nymea daemon.

Build System

The project uses qmake. Build out-of-tree:

mkdir build && cd build
qmake ../nymea-energy-plugin-nymea.pro
make -j$(nproc)

Build with coverage instrumentation:

qmake CONFIG+=coverage ../nymea-energy-plugin-nymea.pro
make -j$(nproc)

Build translations:

make lupdate   # extract strings into .ts files
make lrelease  # compile .ts → .qm

Supports both Qt5 (C++11) and Qt6 (C++17). The .pri file detects the Qt version automatically.

Running Tests

Three test binaries are built under tests/auto/:

Test binary Source directory
nymeaenrgytestcharging tests/auto/charging/
nymeaenrgytestspotmarket tests/auto/spotmarket/
nymea-energy-simulation tests/auto/simulation/

Run a single test binary directly after building:

./tests/auto/charging/nymeaenrgytestcharging
./tests/auto/spotmarket/nymeaenrgytestspotmarket
./tests/auto/simulation/nymea-energy-simulation

Run simulations in Docker (produces plots in results/):

./docker-simulation.sh

Generate HTML coverage report after running tests with coverage build:

./generate-coverage-report.sh -b /path/to/build

Architecture

Plugin Entry Point

energyplugin/energypluginnymea.cpp — Implements EnergyPlugin. The init() method constructs and wires together all subsystems:

  • EnergyManagerConfiguration — loads runtime tuning parameters
  • SpotMarketManager — manages spot price data providers
  • SmartChargingManager — core charging orchestration
  • NymeaEnergyJsonHandler — registers the JSON-RPC API for clients (version 0–8)

Core Subsystems

SmartChargingManager (energyplugin/smartchargingmanager.*) — The central logic engine. On each update() tick it:

  1. Gathers state via prepareInformation()
  2. Calculates spot market charging schedules via planSpotMarketCharging()
  3. Calculates surplus solar charging via planSurplusCharging()
  4. Applies decisions to EV chargers via adjustEvChargers()
  5. Enforces overload protection via verifyOverloadProtection()

SpotMarketManager (energyplugin/spotmarket/) — Aggregates spot price data from registered SpotMarketDataProvider instances (currently SpotMarketDataProviderAwattar). Provides scheduleChargingTime() to calculate optimal time windows given weighted price scores.

NymeaEnergyJsonHandler (energyplugin/nymeaenergyjsonhandler.*) — JSON-RPC handler exposing charging config, spot market config, score entries, and schedules to UI clients.

RootMeter / EvCharger — Thin wrappers around nymea Thing objects, exposing typed accessors for power readings and charger state.

EnergyManagerConfiguration — Read-only configuration loaded from $NYMEA_ENERGY_MANAGER_CONFIG or /var/lib/nymea/energy-manager-configuration.json. Defaults are production-safe; the file exists only for test environment tuning.

Types (energyplugin/types/)

Value types used across subsystems: ChargingInfo, ChargingAction, ChargingSchedule, ChargingProcessInfo, ScoreEntry, SmartChargingState, TimeFrame.

Tests

  • tests/mocks/plugins/energymocks/ — nymea integration plugin mock (EV charger, meter thing types)
  • tests/mocks/spotmarketprovider/ — SpotMarketDataProviderMock with static JSON datasets
  • tests/auto/common/ — EnergyTestBase shared base class using nymea-tests framework
  • tests/auto/simulation/ — Time-accelerated simulation using ENERGY_SIMULATION define; the SmartChargingManager exposes simulationCallUpdate() hooks only when this define is active

Key pkgconfig Dependencies

  • nymea — core daemon API (Thing, ThingManager, JsonHandler, etc.)
  • nymea-energy — energy experience API (EnergyPlugin, EnergyManager, EnergyLogs)
  • nymea-core / nymea-tests — test utilities (test builds only)