# Carlo Gavazzi EM580 Power Meter Driver

Driver module for the **Carlo Gavazzi EM580** power meter using Modbus via EVerest's `serial_communication_hub` interface.
It implements the standardized EVerest `powermeter` interface and supports **OCMF/Eichrecht** transaction flows.

## Overview

This is an **EVerest Hardware Driver** module that:

- **Implements**: `powermeter` interface
- **Communicates**: Modbus RTU (through `SerialCommHub`)
- **Provides**: Live meter values, OCMF transaction start/stop handling, public key publishing

## Features

- **Live measurements**: Publishes `powermeter` readings periodically (`live_measurement_interval_ms`)
- **OCMF transactions**:
  - `start_transaction`: writes OCMF identification fields + tariff text (TT) + start command
  - `stop_transaction`: ends transaction, waits for READY, reads OCMF file, confirms file read
- **Modbus protocol compliance**: transport splits writes into chunks (max 123 registers per request)
- **Resilience / retries**:
  - Separate initial connection retry settings vs. normal operation retry settings
  - Communication-fault raise/clear hooks
- **Device state monitoring**: periodic read of device state bitfield (`device_state_read_interval_ms`)
- **Signature key readout**: reads signature type and public keys; publishes public key (hex) via `public_key_ocmf`

## Hardware requirements & compatibility

### Supported devices

- **Carlo Gavazzi EM580** with **Modbus RTU** enabled/available.
- **OCMF/Eichrecht flow**: requires a meter variant/firmware that supports the OCMF register set used by this driver.

If you are unsure which EM580 variant you have, check the device documentation/ordering code and confirm:
- Modbus RTU via RS-485 is supported and enabled
- The meter is configured for a known Modbus **unit id** (device address)

- **Carlo Gavazzi EM300** with **Modbus RTU** enabled/available.
  These models do not support OCMF/Eichrecht and can only be used as usual power meter.
  All transaction related configuration etc. does not apply for such devices.


### Bus / physical layer

- **RS-485 (2-wire, half duplex)**: correct A/B wiring is essential.
- **Termination**: enable 120Ω termination at the ends of the RS-485 bus (and only at the ends).
- **Biasing**: ensure the bus has proper bias resistors (often provided by the adapter/master or by dedicated biasing).

### Host requirements

- A Linux host running EVerest with access to a serial device (e.g. `/dev/ttyUSB0`).
- A **USB-to-RS485** adapter (or equivalent RS-485 interface) supported by the OS.
- Permissions to access the serial device node (group membership / udev rules).

## Configuration

### Required connections

The module requires a `serial_communication_hub` implementation (typically `SerialCommHub`) via its `modbus` requirement.
`SerialCommHub` encapsulates the serial port settings (port, baudrate, parity, timeouts). The EM580 module only needs the
hub connection plus its Modbus unit id (`powermeter_device_id`).

### Example configuration (bringup)

See `config/bringup/config-bringup-CGEM580.yaml`:

```yaml
active_modules:
  cgem580:
    module: CarloGavazzi_EM580
    config_implementation:
      main:
        powermeter_device_id: 1
        communication_retry_count: 3
        communication_retry_delay_ms: 500
        communication_error_pause_delay_s: 10
        initial_connection_retry_count: 10
        initial_connection_retry_delay_ms: 2000
        timezone_offset_minutes: 60
        live_measurement_interval_ms: 1000
        device_state_read_interval_ms: 10000
    connections:
      modbus:
        - module_id: comm_hub
          implementation_id: main
```

### Multiple EM580 devices on one RS-485 bus

You can run multiple EM580 devices on the same RS-485 line by:
- Creating multiple `CarloGavazzi_EM580` module instances
- Pointing them all to the same `SerialCommHub`
- Giving each instance a unique `powermeter_device_id` (Modbus unit id)

### Configuration parameters

All parameters are defined in `modules/HardwareDrivers/PowerMeters/CarloGavazzi_EM580/manifest.yaml`:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `powermeter_device_id` | integer | `1` | Modbus device ID on the bus |
| `communication_retry_count` | integer | `3` | Retries for regular Modbus operations |
| `communication_retry_delay_ms` | integer | `500` | Delay between regular retries |
| `communication_error_pause_delay_s` | integer | `10` | Pause after a communication failure in the live measurement thread before retrying (also applies to initial communication) |
| `initial_connection_retry_count` | integer | `10` (0 = infinite) | Retries during initial device setup/signature config reads |
| `initial_connection_retry_delay_ms` | integer | `2000` | Delay between initialization retries |
| `timezone_offset_minutes` | integer | `0` | Timezone offset from UTC (minutes) |
| `live_measurement_interval_ms` | integer | `1000` | Interval for reading/publishing live measurements |
| `device_state_read_interval_ms` | integer | `10000` | Interval for reading device-state bitfield (VendorError reporting) |
| `public_key_format` | enum | `binary` | The key format to use for the public key.

### Parameter tuning notes

- **`initial_connection_*`**:
  - Used during module startup for device setup / signature config reads.
  - `initial_connection_retry_count: 0` means **retry forever**.
  - `initial_connection_retry_delay_ms` has a **minimum of 100ms** (see `manifest.yaml`).
- **`communication_*`**:
  - Used for regular Modbus operations during runtime.
  - `communication_retry_delay_ms` has a **minimum of 10ms** (see `manifest.yaml`).
- **`communication_error_pause_delay_s`**:
  - After a communication exception in the live thread, the module waits this long before retrying.
  - If the line is physically broken (wrong wiring / adapter unplugged), increasing this value reduces log spam.
- **`live_measurement_interval_ms` / `device_state_read_interval_ms`**:
  - Keep live measurements reasonable for your bus speed and number of devices.
  - For multi-drop RS-485, consider increasing intervals if you see bus contention/timeouts.

## Interfaces

### Provides

- `main`: `powermeter`

### Requires

- `modbus`: `serial_communication_hub`

## Transaction flow (OCMF)

### `start_transaction`

High-level flow:

1. Read OCMF state register and ensure it is `NOT_READY` before starting.
2. Write OCMF transaction registers:
   - Identification status/level/flags/type
   - Identification data (ID)
   - Charging point identifier type + value (EVSE ID)
   - Tariff text (TT) as `tariff_text + "<=>" + transaction_id`
     - Written as **0-terminated** and only the **used** portion (no full padding).
3. Write session modality (charging vehicle).
4. Write the start command (`'B'`).

### `stop_transaction`

High-level flow:

1. Write end command (`'E'`) if stopping the currently tracked transaction.
2. Wait for OCMF state `READY`.
3. Read OCMF file (size + content).
4. Confirm file read by writing `NOT_READY` to OCMF state.
5. Return OCMF report in `signed_meter_value` (with `public_key` attached).

## Signature validation (recommended)

For troubleshooting and integration testing, this module ships a small signature validation tool under:
`modules/HardwareDrivers/PowerMeters/CarloGavazzi_EM580/ocmf_validation/`.

It can validate EM580 OCMF signatures (`ECDSA-brainpoolP384r1-SHA256`) against the public key read from the meter.
See `ocmf_validation/README.md` for usage details.

## Troubleshooting

### No communication / timeouts

Common causes and checks:

- **Wrong unit id**:
  - Verify `powermeter_device_id` matches the meter’s Modbus address.
  - If you have multiple meters, ensure each has a unique id (1..247 are typical).
- **Wrong serial settings**:
  - Ensure `SerialCommHub` settings match the meter configuration (baudrate, parity).
  - If you are unsure, start with conservative settings and increase once stable.
- **RS-485 wiring / termination**:
  - Swap A/B if you see only timeouts.
  - Ensure termination is correct (only at bus ends).
  - Keep cables short / twisted pair; avoid star topologies where possible.
- **Adapter / permissions**:
  - Confirm the serial device path exists and is stable (`/dev/ttyUSB0` can change between boots).
  - Ensure the EVerest process has permissions to open the device node.

### Repeated `CommunicationFault` raises

The module raises a communication fault when Modbus operations fail and clears it once communication is restored.
If you see frequent toggling:

- Reduce bus load (increase `live_measurement_interval_ms`, especially with multiple meters)
- Increase `communication_retry_count` modestly (and keep `communication_retry_delay_ms` ≥ 10ms)
- Consider increasing `communication_error_pause_delay_s` to reduce retry storms on hard faults

### OCMF transaction does not complete / stuck waiting for READY

- Check that the meter is in the expected OCMF state and is not holding a previous transaction open.
- Ensure the transaction ids passed to `start_transaction` / `stop_transaction` match your intended flow.
- Inspect logs around OCMF state transitions and file readout to see which step fails.

### Tariff text (TT) is truncated

The EM580 TT field is limited to `CHAR[252]`. The driver logs a warning and truncates overlong strings.
Shorten `tariff_text` and/or the appended data (e.g. transaction id formatting).

### Signature verification fails

Use the validation tool in `ocmf_validation/` to validate the produced OCMF string against the published public key.
If it fails:
- Ensure public key and OCMF data come from the **same device** and **same transaction**
- Ensure the OCMF data is not modified (OCMF signatures are over compact JSON)

## Notes / Limitations

- **Write-multiple-registers limit**: the Modbus transport enforces the protocol limit by chunking into max 123 registers.
- **Tariff text length**: TT is a `CHAR[252]` field (126 words). The driver logs a warning and truncates if needed.

## References

- Module docs: `modules/HardwareDrivers/PowerMeters/CarloGavazzi_EM580/docs/index.rst`
- OCMF spec: see [SAFE-eV OCMF specification](https://github.com/SAFE-eV/OCMF-Open-Charge-Metering-Format)

## Unit tests

Unit tests live under `modules/HardwareDrivers/PowerMeters/CarloGavazzi_EM580/tests/` and include:

- Helper-level tests (`helper.hpp`)
- `powermeterImpl` behavior tests using a fake Modbus transport and small test hooks

Build/run example (target name may vary by build system settings):

```bash
ninja -C build everest-core_carlo_gavazzi_em580_helper_tests
./build/modules/HardwareDrivers/PowerMeters/CarloGavazzi_EM580/tests/everest-core_carlo_gavazzi_em580_helper_tests
```