// Contains definitions specific to inverters.
//
// Copyright:
// Copyright 2022 Frequenz Energy-as-a-Service GmbH
//
// License:
// MIT

syntax = "proto3";

package frequenz.api.microgrid.inverter;

import "frequenz/api/microgrid/common.proto";

import "frequenz/api/common/components.proto";
import "frequenz/api/common/metrics.proto";
import "frequenz/api/common/metrics/electrical.proto";

// Enumerated inverter types.
enum Type {
  TYPE_UNSPECIFIED = 0;
  TYPE_BATTERY = 1;
  TYPE_SOLAR = 2;
  TYPE_HYBRID = 3;
}

// The inverter metadata.
message Metadata {
  // The inverter type.
  frequenz.api.common.components.InverterType type = 1;
}

// Enumerated inverter states.
enum ComponentState {
  // Default value.
  COMPONENT_STATE_UNSPECIFIED = 0;

  // Inverter is switched off.
  COMPONENT_STATE_OFF = 1;

  // The inverter is starting up and needs some time to become fully
  // operational.
  COMPONENT_STATE_SWITCHING_ON = 2;

  // The inverter is switching off and needs some time to fully shut down.
  COMPONENT_STATE_SWITCHING_OFF = 3;

  // The inverter is in a standby state, and is disconnected from the grid.
  // When connected to the grid, it run a few tests, and move to the `IDLE`
  // state.
  COMPONENT_STATE_STANDBY = 4;

  // The inverter is idle.
  COMPONENT_STATE_IDLE = 5;

  // The inverter is consuming electrical energy to charge batteries.
  // Applicable to `BATTERY` and `HYBRID` inverters only.
  COMPONENT_STATE_CHARGING = 10;

  // The inverter is generating electrical energy.
  COMPONENT_STATE_DISCHARGING = 11;

  // The inverter is in a faulty state.
  COMPONENT_STATE_ERROR = 14;

  // The inverter is online, but currently unavailable, possibly due to
  // a pre-scheduled maintenance.
  COMPONENT_STATE_UNAVAILABLE = 15;

  // The state is provided by the device, but it can not be parsed as any of the
  // above (known) states.
  COMPONENT_STATE_UNKNOWN = 16;
}

// Enumerated inverter error codes.
enum ErrorCode {
  // Unspecified.
  ERROR_CODE_UNSPECIFIED = 0;
}

// State message.
message State {
  // The state of the overall component.
  ComponentState component_state = 1;
}

// Error message.
message Error {
  // The error code.
  ErrorCode code = 1;

  // The error severity level.
  common.ErrorLevel level = 2;

  // The error message.
  string msg = 3;
}

// Inverter data.
message Data {
  // DC metrics for the inverter-battery linkage.
  // This is applicable to `BATTERY` and `HYBRID` inverters only.
  frequenz.api.common.metrics.electrical.DC dc_battery = 4;

  // DC metrics for the inverter-PV linkage.
  // This is applicable to `SOLAR` and `HYBRID` inverters only.
  frequenz.api.common.metrics.electrical.DC dc_solar = 5;

  // AC metrics of the inverter.
  frequenz.api.common.metrics.electrical.AC ac = 2;

  // The verall temperature of the inverter.
  // In degree Celsius (°C).
  frequenz.api.common.metrics.Metric temperature = 3;
}

// Inverter properties.
message Properties {
  // The firmware version of the component.
  string firmware_ver = 1;
}

// Inverter message definition.
message Inverter {
  // The component properties
  Properties properties = 1;

  // The inverter's state.
  State state = 2;

  // A list of errors encountered the component. An empty list implies no error.
  repeated Error errors = 3;

  // An inverter data object.
  Data data = 4;
}
