108 lines
4.2 KiB
Markdown
108 lines
4.2 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
mkdir build && cd build
|
||
qmake ../nymea-energy-plugin-nymea.pro
|
||
make -j$(nproc)
|
||
```
|
||
|
||
Build with coverage instrumentation:
|
||
|
||
```bash
|
||
qmake CONFIG+=coverage ../nymea-energy-plugin-nymea.pro
|
||
make -j$(nproc)
|
||
```
|
||
|
||
Build translations:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
./tests/auto/charging/nymeaenrgytestcharging
|
||
./tests/auto/spotmarket/nymeaenrgytestspotmarket
|
||
./tests/auto/simulation/nymea-energy-simulation
|
||
```
|
||
|
||
Run simulations in Docker (produces plots in `results/`):
|
||
|
||
```bash
|
||
./docker-simulation.sh
|
||
```
|
||
|
||
Generate HTML coverage report after running tests with coverage build:
|
||
|
||
```bash
|
||
./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)
|