api

type CemCEVCInterface interface {
	api.UseCaseInterface

	// returns the current charging stratey
	//
	// parameters:
	//   - entity: the entity of the EV
	//
	// returns EVChargeStrategyTypeUnknown if it could not be determined, e.g.
	// if the vehicle communication is via IEC61851 or the EV doesn't provide
	// any information about its charging mode or plan
	ChargeStrategy(remoteEntity spineapi.EntityRemoteInterface) EVChargeStrategyType

	// returns the current energy demand
	//
	// parameters:
	//   - entity: the entity of the EV
	//
	// return values:
	//   - EVDemand: details about the actual demands from the EV
	//   - error: if no data is available
	//
	// if duration is 0, direct charging is active, otherwise timed charging is active
	EnergyDemand(remoteEntity spineapi.EntityRemoteInterface) (Demand, error)

	TimeSlotConstraints(entity spineapi.EntityRemoteInterface) (TimeSlotConstraints, error)

	// send power limits to the EV
	//
	// parameters:
	//   - entity: the entity of the EV
	//   - data: the power limits
	//
	// if no data is provided, default power limits with the max possible value for 7 days will be sent
	WritePowerLimits(entity spineapi.EntityRemoteInterface, data []DurationSlotValue) error

	// return the current incentive constraints
	//
	// parameters:
	//   - entity: the entity of the EV
	IncentiveConstraints(entity spineapi.EntityRemoteInterface) (IncentiveSlotConstraints, error)

	// send new incentives to the EV
	//
	// parameters:
	//   - entity: the entity of the EV
	//   - data: the incentive descriptions
	WriteIncentiveTableDescriptions(entity spineapi.EntityRemoteInterface, data []IncentiveTariffDescription) error

	// send incentives to the EV
	//
	// parameters:
	//   - entity: the entity of the EV
	//   - data: the incentives
	//
	// if no data is provided, default incentives with the same price for 7 days will be sent
	WriteIncentives(entity spineapi.EntityRemoteInterface, data []DurationSlotValue) error

	// return the current charge plan constraints
	//
	// parameters:
	//   - entity: the entity of the EV
	ChargePlanConstraints(entity spineapi.EntityRemoteInterface) ([]DurationSlotValue, error)

	// return the current charge plan of the EV
	//
	// parameters:
	//   - entity: the entity of the EV
	ChargePlan(entity spineapi.EntityRemoteInterface) (ChargePlan, error)
}

type CemEVCCInterface interface {
	api.UseCaseInterface

	// return the current charge state of the EV
	//
	// parameters:
	//   - entity: the entity of the EV
	ChargeState(entity spineapi.EntityRemoteInterface) (EVChargeStateType, error)

	// return if the EV is connected
	//
	// parameters:
	//   - entity: the entity of the EV
	EVConnected(entity spineapi.EntityRemoteInterface) bool

	// return the current communication standard type used to communicate between EVSE and EV
	//
	// parameters:
	//   - entity: the entity of the EV
	CommunicationStandard(entity spineapi.EntityRemoteInterface) (model.DeviceConfigurationKeyValueStringType, error)

	// return if the EV supports asymmetric charging
	//
	// parameters:
	//   - entity: the entity of the EV
	AsymmetricChargingSupport(entity spineapi.EntityRemoteInterface) (bool, error)

	// return the identifications of the currently connected EV or nil if not available
	// these can be multiple, e.g. PCID, Mac Address, RFID
	//
	// parameters:
	//   - entity: the entity of the EV
	Identifications(entity spineapi.EntityRemoteInterface) ([]IdentificationItem, error)

	// the manufacturer data of an EVSE
	// returns deviceName, serialNumber, error
	//
	// parameters:
	//   - entity: the entity of the EV
	ManufacturerData(entity spineapi.EntityRemoteInterface) (api.ManufacturerData, error)

	// return the minimum, maximum charging and, standby power of the connected EV
	//
	// parameters:
	//   - entity: the entity of the EV
	ChargingPowerLimits(entity spineapi.EntityRemoteInterface) (float64, float64, float64, error)

	// is the EV in sleep mode
	//
	// parameters:
	//   - entity: the entity of the EV
	IsInSleepMode(entity spineapi.EntityRemoteInterface) (bool, error)
}

type CemEVCEMInterface interface {
	api.UseCaseInterface

	// return the number of ac connected phases of the EV or 0 if it is unknown
	//
	// parameters:
	//   - entity: the entity of the EV
	PhasesConnected(entity spineapi.EntityRemoteInterface) (uint, error)

	// return the last current measurement for each phase of the connected EV
	//
	// parameters:
	//   - entity: the entity of the EV
	CurrentPerPhase(entity spineapi.EntityRemoteInterface) ([]float64, error)

	// return the last power measurement for each phase of the connected EV
	//
	// parameters:
	//   - entity: the entity of the EV
	PowerPerPhase(entity spineapi.EntityRemoteInterface) ([]float64, error)

	// return the charged energy measurement in Wh of the connected EV
	//
	// parameters:
	//   - entity: the entity of the EV
	EnergyCharged(entity spineapi.EntityRemoteInterface) (float64, error)
}

type CemEVSECCInterface interface {
	api.UseCaseInterface

	// the manufacturer data of an EVSE
	//
	// parameters:
	//   - entity: the entity of the EV
	//
	// returns deviceName, serialNumber, error
	ManufacturerData(entity spineapi.EntityRemoteInterface) (api.ManufacturerData, error)

	// the operating state data of an EVSE
	//
	// parameters:
	//   - entity: the entity of the EV
	//
	// returns operatingState, lastErrorCode, error
	OperatingState(entity spineapi.EntityRemoteInterface) (model.DeviceDiagnosisOperatingStateType, string, error)
}

type CemEVSOCInterface interface {
	api.UseCaseInterface

	// return the EVscurrent state of charge of the EV or an error it is unknown
	//
	// parameters:
	//   - entity: the entity of the EV
	StateOfCharge(entity spineapi.EntityRemoteInterface) (float64, error)
}

type CemOPEVInterface interface {
	api.UseCaseInterface

	// return the min, max, default limits for each phase of the connected EV
	//
	// parameters:
	//   - entity: the entity of the EV
	CurrentLimits(entity spineapi.EntityRemoteInterface) ([]float64, []float64, []float64, error)

	// return the current loadcontrol obligation limits
	//
	// parameters:
	//   - entity: the entity of the EV
	//
	// return values:
	//   - limits: per phase data
	//
	// possible errors:
	//   - ErrDataNotAvailable if no such limit is (yet) available
	//   - and others
	LoadControlLimits(entity spineapi.EntityRemoteInterface) (limits []LoadLimitsPhase, resultErr error)

	// send new LoadControlLimits to the remote EV
	//
	// parameters:
	//   - entity: the entity of the EV
	//   - limits: a set of limits containing phase specific limit data
	//   - resultCB: callback function for handling the result response
	//
	// Sets a maximum A limit for each phase that the EV may not exceed.
	// Mainly used for implementing overload protection of the site or limiting the
	// maximum charge power of EVs when the EV and EVSE communicate via IEC61851
	// and with ISO15118 if the EV does not support the Optimization of Self Consumption
	// usecase.
	//
	// note:
	// For obligations to work for optimizing solar excess power, the EV needs to
	// have an energy demand. Recommendations work even if the EV does not have an active
	// energy demand, given it communicated with the EVSE via ISO15118 and supports the usecase.
	// In ISO15118-2 the usecase is only supported via VAS extensions which are vendor specific
	// and needs to have specific EVSE support for the specific EV brand.
	// In ISO15118-20 this is a standard feature which does not need special support on the EVSE.
	WriteLoadControlLimits(
		entity spineapi.EntityRemoteInterface,
		limits []LoadLimitsPhase,
		resultCB func(result model.ResultDataType),
	) (*model.MsgCounterType, error)
}

type CemOSCEVInterface interface {
	api.UseCaseInterface

	// return the min, max, default limits for each phase of the connected EV
	//
	// parameters:
	//   - entity: the entity of the EV
	CurrentLimits(entity spineapi.EntityRemoteInterface) ([]float64, []float64, []float64, error)

	// return the current loadcontrol recommendation limits
	//
	// parameters:
	//   - entity: the entity of the EV
	//
	// return values:
	//   - limits: per phase data
	//
	// possible errors:
	//   - ErrDataNotAvailable if no such limit is (yet) available
	//   - and others
	LoadControlLimits(entity spineapi.EntityRemoteInterface) (limits []LoadLimitsPhase, resultErr error)

	// send new LoadControlLimits to the remote EV
	//
	// parameters:
	//   - entity: the entity of the EV
	//   - limits: a set of limits containing phase specific limit data
	//   - resultCB: callback function for handling the result response
	//
	// recommendations:
	// Sets a recommended charge power in A for each phase. This is mainly
	// used if the EV and EVSE communicate via ISO15118 to support charging excess solar power.
	// The EV either needs to support the Optimization of Self Consumption usecase or
	// the EVSE needs to be able map the recommendations into oligation limits which then
	// works for all EVs communication either via IEC61851 or ISO15118.
	WriteLoadControlLimits(
		entity spineapi.EntityRemoteInterface,
		limits []LoadLimitsPhase,
		resultCB func(result model.ResultDataType),
	) (*model.MsgCounterType, error)
}

type CemVABDInterface interface {
	api.UseCaseInterface

	// return the current (dis)charging power
	//
	// parameters:
	//   - entity: the entity of the inverter
	Power(entity spineapi.EntityRemoteInterface) (float64, error)

	// return the cumulated battery system charge energy
	//
	// parameters:
	//   - entity: the entity of the inverter
	EnergyCharged(entity spineapi.EntityRemoteInterface) (float64, error)

	// return the cumulated battery system discharge energy
	//
	// parameters:
	//   - entity: the entity of the inverter
	EnergyDischarged(entity spineapi.EntityRemoteInterface) (float64, error)

	// return the current state of charge of the battery system
	//
	// parameters:
	//   - entity: the entity of the inverter
	StateOfCharge(entity spineapi.EntityRemoteInterface) (float64, error)
}

type CemVAPDInterface interface {
	api.UseCaseInterface

	// return the current production power
	//
	// parameters:
	//   - entity: the entity of the inverter
	Power(entity spineapi.EntityRemoteInterface) (float64, error)

	// return the nominal peak power
	//
	// parameters:
	//   - entity: the entity of the inverter
	PowerNominalPeak(entity spineapi.EntityRemoteInterface) (float64, error)

	// return total PV yield
	//
	// parameters:
	//   - entity: the entity of the inverter
	PVYieldTotal(entity spineapi.EntityRemoteInterface) (float64, error)
}

type ChargePlan struct {
	Slots []ChargePlanSlotValue // Individual charging slot details
}

type ChargePlanSlotValue struct {
	Start    time.Time // The start time of the slot
	End      time.Time // The duration of the slot
	Value    float64   // planned power value
	MinValue float64   // minimum power value
	MaxValue float64   // maximum power value
}

type CsLPCInterface interface {
	api.UseCaseInterface

	// return the current consumption limit data
	//
	// return values:
	//   - limit: load limit data
	//
	// possible errors:
	//   - ErrDataNotAvailable if no such limit is (yet) available
	//   - and others
	ConsumptionLimit() (LoadLimit, error)

	// set the current loadcontrol limit data
	SetConsumptionLimit(limit LoadLimit) (resultErr error)

	// return the currently pending incoming consumption write limits
	PendingConsumptionLimits() map[model.MsgCounterType]LoadLimit

	// accept or deny an incoming consumption write limit
	//
	// parameters:
	//  - msg: the incoming write message
	//  - approve: if the write limit for msg should be approved or not
	//  - reason: the reason why the approval is denied, otherwise an empty string
	ApproveOrDenyConsumptionLimit(msgCounter model.MsgCounterType, approve bool, reason string)

	// return Failsafe limit for the consumed active (real) power of the
	// Controllable System. This limit becomes activated in "init" state or "failsafe state".
	//
	// return values:
	//   - value: the power limit in W
	//   - changeable: boolean if the client service can change the limit
	FailsafeConsumptionActivePowerLimit() (value float64, isChangeable bool, resultErr error)

	// set Failsafe limit for the consumed active (real) power of the
	// Controllable System. This limit becomes activated in "init" state or "failsafe state".
	//
	// parameters:
	//   - value: the power limit in W
	//   - changeable: boolean if the client service can change the limit
	SetFailsafeConsumptionActivePowerLimit(value float64, changeable bool) (resultErr error)

	// return minimum time the Controllable System remains in "failsafe state" unless conditions
	// specified in this Use Case permit leaving the "failsafe state"
	//
	// return values:
	//   - value: the power limit in W
	//   - changeable: boolean if the client service can change the limit
	FailsafeDurationMinimum() (duration time.Duration, isChangeable bool, resultErr error)

	// set minimum time the Controllable System remains in "failsafe state" unless conditions
	// specified in this Use Case permit leaving the "failsafe state"
	//
	// parameters:
	//   - duration: has to be >= 2h and <= 24h
	//   - changeable: boolean if the client service can change this value
	SetFailsafeDurationMinimum(duration time.Duration, changeable bool) (resultErr error)

	// this is automatically covered by the SPINE implementation
	//
	// returns true, if the last heartbeat is within 2 minutes, otherwise false
	IsHeartbeatWithinDuration() bool

	// return nominal maximum active (real) power the Controllable System is allowed to consume.
	//
	// If the local device type is an EnergyManagementSystem, the contractual consumption
	// nominal max is returned, otherwise the power consumption nominal max is returned.
	ConsumptionNominalMax() (float64, error)

	// set power nominal maximum active (real) power the Controllable System is allowed to consume.
	//
	// If the local device type is an EnergyManagementSystem, the contractual consumption
	// nominal max is set, otherwise the power consumption nominal max is set.
	//
	// parameters:
	//   - value: nominal max power consumption in W
	SetConsumptionNominalMax(value float64) (resultErr error)
}

type CsLPPInterface interface {
	api.UseCaseInterface

	// return the current loadcontrol limit data
	//
	// return values:
	//   - limit: load limit data
	//
	// possible errors:
	//   - ErrDataNotAvailable if no such limit is (yet) available
	//   - and others
	ProductionLimit() (LoadLimit, error)

	// set the current loadcontrol limit data
	SetProductionLimit(limit LoadLimit) (resultErr error)

	// return the currently pending incoming production write limits
	PendingProductionLimits() map[model.MsgCounterType]LoadLimit

	// accept or deny an incoming production write limit
	//
	// parameters:
	//  - msg: the incoming write message
	//  - approve: if the write limit for msg should be approved or not
	//  - reason: the reason why the approval is denied, otherwise an empty string
	ApproveOrDenyProductionLimit(msgCounter model.MsgCounterType, approve bool, reason string)

	// return Failsafe limit for the produced active (real) power of the
	// Controllable System. This limit becomes activated in "init" state or "failsafe state".
	//
	// return values:
	//   - value: the power limit in W
	//   - changeable: boolean if the client service can change the limit
	FailsafeProductionActivePowerLimit() (value float64, isChangeable bool, resultErr error)

	// set Failsafe limit for the produced active (real) power of the
	// Controllable System. This limit becomes activated in "init" state or "failsafe state".
	//
	// parameters:
	//   - value: the power limit in W
	//   - changeable: boolean if the client service can change the limit
	SetFailsafeProductionActivePowerLimit(value float64, changeable bool) (resultErr error)

	// return minimum time the Controllable System remains in "failsafe state" unless conditions
	// specified in this Use Case permit leaving the "failsafe state"
	//
	// return values:
	//   - value: the power limit in W
	//   - changeable: boolean if the client service can change the limit
	FailsafeDurationMinimum() (duration time.Duration, isChangeable bool, resultErr error)

	// set minimum time the Controllable System remains in "failsafe state" unless conditions
	// specified in this Use Case permit leaving the "failsafe state"
	//
	// parameters:
	//   - duration: has to be >= 2h and <= 24h
	//   - changeable: boolean if the client service can change this value
	SetFailsafeDurationMinimum(duration time.Duration, changeable bool) (resultErr error)

	// this is automatically covered by the SPINE implementation
	//
	// returns true, if the last heartbeat is within 2 minutes, otherwise false
	IsHeartbeatWithinDuration() bool

	// return nominal maximum active (real) power the Controllable System is allowed to produce.
	//
	// If the local device type is an EnergyManagementSystem, the contractual production
	// nominal max is returned, otherwise the power production nominal max is returned.
	ProductionNominalMax() (float64, error)

	// set power nominal maximum active (real) power the Controllable System is allowed to produce.
	//
	// If the local device type is an EnergyManagementSystem, the contractual production
	// nominal max is set, otherwise the power production nominal max is set.
	//
	// parameters:
	//   - value: nominal max power production in W
	SetProductionNominalMax(value float64) (resultErr error)
}

type Demand struct {
	MinDemand          float64 // minimum demand in Wh to reach the minSoC setting, 0 if not set
	OptDemand          float64 // demand in Wh to reach the timer SoC setting
	MaxDemand          float64 // the maximum possible demand until the battery is full
	DurationUntilStart float64 // the duration in s from now until charging will start, this could be in the future but usualy is now
	DurationUntilEnd   float64 // the duration in s from now until minDemand or optDemand has to be reached, 0 if direct charge strategy is active
}

type DurationSlotValue struct {
	Duration time.Duration // Duration of this slot
	Value    float64       // Energy Cost or Power Limit
}

type EVChargeStateType string

type EVChargeStrategyType string

type EgLPCInterface interface {
	api.UseCaseInterface

	// return the current consumption limit data
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//
	// return values:
	//   - limit: load limit data
	//
	// possible errors:
	//   - ErrDataNotAvailable if no such limit is (yet) available
	//   - and others
	ConsumptionLimit(entity spineapi.EntityRemoteInterface) (limit LoadLimit, resultErr error)

	// send new LoadControlLimits
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//   - limit: load limit data
	//   - resultCB: callback function for handling the result response
	WriteConsumptionLimit(
		entity spineapi.EntityRemoteInterface,
		limit LoadLimit,
		resultCB func(result model.ResultDataType),
	) (*model.MsgCounterType, error)

	// return Failsafe limit for the consumed active (real) power of the
	// Controllable System. This limit becomes activated in "init" state or "failsafe state".
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//
	// return values:
	//   - positive values are used for consumption
	FailsafeConsumptionActivePowerLimit(entity spineapi.EntityRemoteInterface) (float64, error)

	// send new Failsafe Consumption Active Power Limit
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//   - value: the new limit in W
	WriteFailsafeConsumptionActivePowerLimit(entity spineapi.EntityRemoteInterface, value float64) (*model.MsgCounterType, error)

	// return minimum time the Controllable System remains in "failsafe state" unless conditions
	// specified in this Use Case permit leaving the "failsafe state"
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//
	// return values:
	//   - negative values are used for production
	FailsafeDurationMinimum(entity spineapi.EntityRemoteInterface) (time.Duration, error)

	// send new Failsafe Duration Minimum
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//   - duration: the duration, between 2h and 24h
	WriteFailsafeDurationMinimum(entity spineapi.EntityRemoteInterface, duration time.Duration) (*model.MsgCounterType, error)

	// return nominal maximum active (real) power the Controllable System is
	// able to consume according to the contract (EMS), device label or data sheet.
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	ConsumptionNominalMax(entity spineapi.EntityRemoteInterface) (float64, error)
}

type EgLPPInterface interface {
	api.UseCaseInterface

	// return the current production limit data
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//
	// return values:
	//   - limit: load limit data
	//
	// possible errors:
	//   - ErrDataNotAvailable if no such limit is (yet) available
	//   - and others
	ProductionLimit(entity spineapi.EntityRemoteInterface) (limit LoadLimit, resultErr error)

	// send new LoadControlLimits
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//   - limit: load limit data
	//   - resultCB: callback function for handling the result response
	WriteProductionLimit(
		entity spineapi.EntityRemoteInterface,
		limit LoadLimit,
		resultCB func(result model.ResultDataType),
	) (*model.MsgCounterType, error)

	// return Failsafe limit for the produced active (real) power of the
	// Controllable System. This limit becomes activated in "init" state or "failsafe state".
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//
	// return values:
	//   - positive values are used for production
	FailsafeProductionActivePowerLimit(entity spineapi.EntityRemoteInterface) (float64, error)

	// send new Failsafe Production Active Power Limit
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//   - value: the new limit in W
	WriteFailsafeProductionActivePowerLimit(entity spineapi.EntityRemoteInterface, value float64) (*model.MsgCounterType, error)

	// return minimum time the Controllable System remains in "failsafe state" unless conditions
	// specified in this Use Case permit leaving the "failsafe state"
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//
	// return values:
	//   - negative values are used for production
	FailsafeDurationMinimum(entity spineapi.EntityRemoteInterface) (time.Duration, error)

	// send new Failsafe Duration Minimum
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	//   - duration: the duration, between 2h and 24h
	WriteFailsafeDurationMinimum(entity spineapi.EntityRemoteInterface, duration time.Duration) (*model.MsgCounterType, error)

	// return nominal maximum active (real) power the Controllable System is
	// able to produce according to the contract (EMS), device label or data sheet.
	//
	// parameters:
	//   - entity: the entity of the e.g. EVSE
	ProductionNominalMax(entity spineapi.EntityRemoteInterface) (float64, error)
}

type IdentificationItem struct {
	// the identification value
	Value string

	// the type of the identification value, e.g.
	ValueType model.IdentificationTypeType
}

type IncentiveDescription struct {
	// the id of the incentive
	Id uint

	// the type of the incentive
	Type model.IncentiveTypeType

	// the currency of the incentive, if it is price based
	Currency model.CurrencyType
}

type IncentiveSlotConstraints struct {
	MinSlots uint // the minimum number of slots, no minimum if 0
	MaxSlots uint // the maximum number of slots, unlimited if 0
}

type IncentiveTableDescriptionTier struct {
	// the id of the tier
	Id uint

	// the tiers type
	Type model.TierTypeType

	// each tear has 1 to 3 boundaries
	// used for different power limits, e.g. 0-1kW x€, 1-3kW y€, ...
	Boundaries []TierBoundaryDescription

	// each tier has 1 to 3 incentives
	//   - price/costs (absolute or relative)
	//   - renewable energy percentage
	//   - CO2 emissions
	Incentives []IncentiveDescription
}

type IncentiveTariffDescription struct {
	// each tariff can have 1 to 3 tiers
	Tiers []IncentiveTableDescriptionTier
}

type LoadLimit struct {
	Duration     time.Duration // the duration of the limit,
	IsChangeable bool          // if the value can be changed via write, ignored when writing data
	IsActive     bool          // if the limit is active
	Value        float64       // the limit
}

type LoadLimitsPhase struct {
	Phase        model.ElectricalConnectionPhaseNameType // the phase
	IsChangeable bool                                    // if the value can be changed via write, ignored when writing data
	IsActive     bool                                    // if the limit is active
	Value        float64                                 // the limit
}

type MaMGCPInterface interface {
	api.UseCaseInterface

	// return the current power limitation factor
	//
	// parameters:
	//   - entity: the entity of the device (e.g. SMGW)
	//
	// possible errors:
	//   - ErrDataNotAvailable if no such limit is (yet) available
	//   - and others
	PowerLimitationFactor(entity spineapi.EntityRemoteInterface) (float64, error)

	// return the momentary power consumption or production at the grid connection point
	//
	// parameters:
	//   - entity: the entity of the device (e.g. SMGW)
	//
	// return values:
	//   - positive values are used for consumption
	//   - negative values are used for production
	Power(entity spineapi.EntityRemoteInterface) (float64, error)

	// return the total feed in energy at the grid connection point
	//
	// parameters:
	//   - entity: the entity of the device (e.g. SMGW)
	//
	// return values:
	//   - negative values are used for production
	EnergyFeedIn(entity spineapi.EntityRemoteInterface) (float64, error)

	// return the total consumption energy at the grid connection point
	//
	// parameters:
	//   - entity: the entity of the device (e.g. SMGW)
	//
	// return values:
	//   - positive values are used for consumption
	EnergyConsumed(entity spineapi.EntityRemoteInterface) (float64, error)

	// return the momentary current consumption or production at the grid connection point
	//
	// parameters:
	//   - entity: the entity of the device (e.g. SMGW)
	//
	// return values:
	//   - positive values are used for consumption
	//   - negative values are used for production
	CurrentPerPhase(entity spineapi.EntityRemoteInterface) ([]float64, error)

	// return the voltage phase details at the grid connection point
	//
	// parameters:
	//   - entity: the entity of the device (e.g. SMGW)
	VoltagePerPhase(entity spineapi.EntityRemoteInterface) ([]float64, error)

	// return frequency at the grid connection point
	//
	// parameters:
	//   - entity: the entity of the device (e.g. SMGW)
	Frequency(entity spineapi.EntityRemoteInterface) (float64, error)
}

type MaMPCInterface interface {
	api.UseCaseInterface

	// return the momentary active power consumption or production
	//
	// parameters:
	//   - entity: the entity of the device (e.g. EVSE)
	//
	// possible errors:
	//   - ErrDataNotAvailable if no such limit is (yet) available
	//   - and others
	Power(entity spineapi.EntityRemoteInterface) (float64, error)

	// return the momentary active phase specific power consumption or production per phase
	//
	// parameters:
	//   - entity: the entity of the device (e.g. EVSE)
	//
	// possible errors:
	//   - ErrDataNotAvailable if no such limit is (yet) available
	//   - and others
	PowerPerPhase(entity spineapi.EntityRemoteInterface) ([]float64, error)

	// return the total consumption energy
	//
	// parameters:
	//   - entity: the entity of the device (e.g. EVSE)
	//
	//   - positive values are used for consumption
	EnergyConsumed(entity spineapi.EntityRemoteInterface) (float64, error)

	// return the total feed in energy
	//
	// parameters:
	//   - entity: the entity of the device (e.g. EVSE)
	//
	// return values:
	//   - negative values are used for production
	EnergyProduced(entity spineapi.EntityRemoteInterface) (float64, error)

	// return the momentary phase specific current consumption or production
	//
	// parameters:
	//   - entity: the entity of the device (e.g. EVSE)
	//
	// return values
	//   - positive values are used for consumption
	//   - negative values are used for production
	CurrentPerPhase(entity spineapi.EntityRemoteInterface) ([]float64, error)

	// return the phase specific voltage details
	//
	// parameters:
	//   - entity: the entity of the device (e.g. EVSE)
	VoltagePerPhase(entity spineapi.EntityRemoteInterface) ([]float64, error)

	// return frequency
	//
	// parameters:
	//   - entity: the entity of the device (e.g. EVSE)
	Frequency(entity spineapi.EntityRemoteInterface) (float64, error)
}

type TierBoundaryDescription struct {
	// the id of the boundary
	Id uint

	// the type of the boundary
	Type model.TierBoundaryTypeType

	// the unit of the boundary
	Unit model.UnitOfMeasurementType
}

type TimeSlotConstraints struct {
	MinSlots             uint          // the minimum number of slots, no minimum if 0
	MaxSlots             uint          // the maximum number of slots, unlimited if 0
	MinSlotDuration      time.Duration // the minimum duration of a slot, no minimum if 0
	MaxSlotDuration      time.Duration // the maximum duration of a slot, unlimited if 0
	SlotDurationStepSize time.Duration // the duration has to be a multiple of this value if != 0
}