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

syntax = "proto3";

package frequenz.api.microgrid.ev_charger;

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";

// The EV charger metadata.
message Metadata {
  // The EV charger type.
  frequenz.api.common.components.EvChargerType type = 1;
}

// The possible states of an EV charging station.
enum ComponentState {
  // Default state.
  // This value is used only when the state information is not available.
  COMPONENT_STATE_UNSPECIFIED = 0;

  // The EV charging station is starting up.
  COMPONENT_STATE_STARTING = 1;

  // The EV charging station is unplugged or RFID is not working.
  COMPONENT_STATE_NOT_READY = 2;

  // The EV charging station is ready and waiting for a charging request
  COMPONENT_STATE_READY = 3;

  // The EV charging station is charging an EV.
  COMPONENT_STATE_CHARGING = 4;

  // The EV charging station is discharging from an EV into the local
  // microgrid.
  COMPONENT_STATE_DISCHARGING = 5;

  // The EV charging station is in an error state.
  COMPONENT_STATE_ERROR = 6;

  // The EV charging station rejected the last authorization.
  COMPONENT_STATE_AUTHORIZATION_REJECTED = 7;

  // The EV charging process hes been temporarily interrupted.
  COMPONENT_STATE_INTERRUPTED = 8;

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

// The possible states of the cable connecting an EV charging station and an
// EV.
enum CableState {
  // Default state.
  CABLE_STATE_UNSPECIFIED = 0;

  // No cable is connected to the EV charging station.
  CABLE_STATE_UNPLUGGED = 1;

  // A cable is connected to the EV charging station, but is not locked with
  // it.
  CABLE_STATE_CHARGING_STATION_PLUGGED = 2;

  // A cable is connected to and locked with the EV charging station.
  CABLE_STATE_CHARGING_STATION_LOCKED = 3;

  // A cable is connected to and locked with the EV charging station.
  // The same cable is connected to the EV, but is not locked with it.
  CABLE_STATE_EV_PLUGGED = 4;

  // A cable is connected to and locked with the EV charging station.
  // The same cable is connected to and locked with the EV.
  CABLE_STATE_EV_LOCKED = 5;
}

// Enumerated EV charger error codes.
enum ErrorCode {
  // Unspecified.
  ERROR_CODE_UNSPECIFIED = 0;

  // Something is preventing the DC contactor from being switched on.
  ERROR_CODE_SWITCH_ON_FAULT = 1;

  // AC supply voltage is lower than expected.
  ERROR_CODE_UNDERVOLTAGE = 2;

  // AC supply voltage is higher than expected.
  ERROR_CODE_OVERVOLTAGE = 3;

  // DC charging voltage is higher than expected.
  ERROR_CODE_OVERCURRENT = 4;

  // Temperature in the charging station is higher than expected.
  ERROR_CODE_OVERTEMPERATURE = 5;

  // EV has sent an unexpected pilot signal.
  ERROR_CODE_UNEXPECTED_PILOT_FAILURE = 6;

  // A fault current has been detected.
  ERROR_CODE_FAULT_CURRENT = 7;

  // A short circuit has been detected.
  ERROR_CODE_SHORT_CIRCUIT = 8;

  // The system is incorrectly configured.
  ERROR_CODE_CONFIG_ERROR = 9;

  // The system received a request to move to an illegal state.
  ERROR_CODE_ILLEGAL_COMPONENT_STATE_REQUESTED = 10;

  // The system cannot access the internal hardware.
  ERROR_CODE_HARDWARE_INACCESSIBLE = 11;

  // The system has detected an unspecified internal error.
  ERROR_CODE_INTERNAL = 12;

  // The charging cable was unplugged unexpectedly.
  ERROR_CODE_CABLE_LOST = 13;

  // The charging cable could not be locked.
  ERROR_CODE_CABLE_LOCK_FAILED = 14;

  // The charging cable could not be locked.
  ERROR_CODE_CABLE_INVALID = 15;

  // The charging cable has an unrecognised plug.
  ERROR_CODE_PLUG_UNKNOWN = 16;

  // The connected consumer is not a standard-compliant EV.
  ERROR_CODE_CONSUMER_NON_STANDARD = 17;
}

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

  // The state of the charging cable.
  CableState cable_state = 2;
}

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

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

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

// EV charger data.
message Data {
  // DC metrics of the EV charging station.
  // Contains data only if DC charging is supported by the EV charging station.
  // (in which case, the type of the EV charging station is TYPE_DC or
  // TYPE_HYBRID)
  frequenz.api.common.metrics.electrical.DC dc = 1;

  // AC metrics of the EV charging station.
  // Contains data only if AC charging is supported by the EV charging station.
  // (in which case, the type of the EV charging station is TYPE_AC or
  // TYPE_HYBRID)
  frequenz.api.common.metrics.electrical.AC ac = 2;

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

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

// EvCharger details
message EvCharger {
  // The component properties
  Properties properties = 1;

  // The EV charging station's state.
  State state = 2;

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

  // An EV charger data object.
  Data data = 4;
}
