# 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)