Migrate Sinexcel implementation to Battery-Inverter

cnf/checkstyle.xml

@@ -120,7 +120,7 @@
       <message key="name.invalidPattern" value="Local variable name ''{0}'' must match pattern ''{1}''."/>
     </module>
     <module name="ClassTypeParameterName">
-      <property name="format" value="(^[A-Z][0-9]?)$|([A-Z][a-zA-Z0-9]*[T]$)"/>
+      <property name="format" value="(^[A-Z][0-9]?)$|([A-Z][a-zA-Z0-9]$)"/>
       <message key="name.invalidPattern" value="Class type name ''{0}'' must match pattern ''{1}''."/>
     </module>
     <module name="MethodTypeParameterName">

io.openems.edge.battery.api/src/io/openems/edge/battery/api/Battery.java

@@ -115,12 +115,9 @@ public enum ChannelId implements io.openems.edge.common.channel.ChannelId {
 		 * <li>Interface: Battery
 		 * <li>Type: Integer
 		 * <li>Unit: A
-		 * <li>Usually positive, negative for force discharge mode; see
-		 * {@link ChannelId#FORCE_DISCHARGE_ACTIVE}
+		 * <li>Usually positive, negative for force discharge mode
 		 * </ul>
 		 */
-		// TODO every Battery-Inverter implementation needs to be adjusted accordingly!
-		// Usually this register might be UINT16 and not accept negative values!
 		CHARGE_MAX_CURRENT(Doc.of(OpenemsType.INTEGER) //
 				.unit(Unit.AMPERE)),
 
@@ -143,8 +140,7 @@ public enum ChannelId implements io.openems.edge.common.channel.ChannelId {
 		 * <li>Interface: Battery
 		 * <li>Type: Integer
 		 * <li>Unit: A
-		 * <li>Usually positive, negative for force charge mode; see
-		 * {@link ChannelId#FORCE_CHARGE_ACTIVE}
+		 * <li>Usually positive, negative for force charge mode
 		 * </ul>
 		 */
 		DISCHARGE_MAX_CURRENT(Doc.of(OpenemsType.INTEGER) //
@@ -199,6 +195,8 @@ public enum ChannelId implements io.openems.edge.common.channel.ChannelId {
 		MAX_CELL_VOLTAGE(Doc.of(OpenemsType.INTEGER) //
 				.unit(Unit.MILLIVOLT)),
 
+		// TODO FORCE_CHARGE_ACTIVE and FORCE_DISCHARGE_ACTIVE channels are
+		// deprecated/obsolete by BatteryProtection channels
 		/**
 		 * Force charge active.
 		 * 
@@ -235,6 +233,7 @@ public Doc doc() {
 
 	/**
 	 * Gets the ModbusSlaveNatureTable.
+	 * 
 	 * @param accessMode the {@link AccessMode}
 	 * @return ModbusSlaveNatureTable
 	 */
@@ -821,4 +820,5 @@ public default void _setForceDischargeActive(Boolean value) {
 	public default void _setForceDischargeActive(boolean value) {
 		this.getForceDischargeActiveChannel().setNextValue(value);
 	}
+
 }

io.openems.edge.battery.api/src/io/openems/edge/battery/protection/BatteryProtection.java

@@ -0,0 +1,312 @@
+package io.openems.edge.battery.protection;
+
+import io.openems.common.channel.Unit;
+import io.openems.common.types.OpenemsType;
+import io.openems.edge.battery.api.Battery;
+import io.openems.edge.battery.protection.currenthandler.ChargeMaxCurrentHandler;
+import io.openems.edge.battery.protection.currenthandler.DischargeMaxCurrentHandler;
+import io.openems.edge.battery.protection.force.AbstractForceChargeDischarge;
+import io.openems.edge.common.channel.Doc;
+import io.openems.edge.common.component.ClockProvider;
+import io.openems.edge.common.type.TypeUtils;
+
+/**
+ * This utility class provides algorithms to calculate maximum allowed charge
+ * and discharge currents for batteries.
+ * 
+ * <p>
+ * The logic uses:
+ * 
+ * <ul>
+ * <li>Allowed Current Limit provided by Battery Management System
+ * <li>Voltage-to-Percent characteristics based on Min- and Max-Cell-Voltage
+ * <li>Temperature-to-Percent characteristics based on Min- and
+ * Max-Cell-Temperature
+ * <li>Linear max increase limit (e.g. 0.5 A per second)
+ * <li>Force Charge/Discharge mode (e.g. -1 A to enforce charge/discharge)
+ * </ul>
+ */
+public class BatteryProtection {
+
+	public enum ChannelId implements io.openems.edge.common.channel.ChannelId {
+		/**
+		 * Charge Current limit provided by the Battery/BMS.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_CHARGE_BMS(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Discharge Current limit provided by the Battery/BMS.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_DISCHARGE_BMS(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Charge Current limit derived from Min-Cell-Voltage.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_CHARGE_MIN_VOLTAGE(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Discharge Current limit derived from Min-Cell-Voltage.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_DISCHARGE_MIN_VOLTAGE(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Charge Current limit derived from Max-Cell-Voltage.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_CHARGE_MAX_VOLTAGE(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Discharge Current limit derived from Max-Cell-Voltage.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_DISCHARGE_MAX_VOLTAGE(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Charge Current limit derived from Min-Cell-Temperature.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_CHARGE_MIN_TEMPERATURE(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Discharge Current limit derived from Min-Cell-Temperature.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_DISCHARGE_MIN_TEMPERATURE(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Charge Current limit derived from Max-Cell-Temperature.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_CHARGE_MAX_TEMPERATURE(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Discharge Current limit derived from Max-Cell-Temperature.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_DISCHARGE_MAX_TEMPERATURE(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Charge Max-Increase Current limit.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_CHARGE_INCREASE(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Discharge Max-Increase Current limit.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_DISCHARGE_INCREASE(Doc.of(OpenemsType.INTEGER) //
+				.unit(Unit.AMPERE)),
+		/**
+		 * Force-Discharge State.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_FORCE_DISCHARGE(Doc.of(AbstractForceChargeDischarge.State.values())), //
+		/**
+		 * Force-Charge State.
+		 * 
+		 * <ul>
+		 * <li>Interface: BatteryProtection
+		 * <li>Type: Integer
+		 * <li>Unit: Ampere
+		 * </ul>
+		 */
+		BP_FORCE_CHARGE(Doc.of(AbstractForceChargeDischarge.State.values())) //
+		;
+
+		private final Doc doc;
+
+		private ChannelId(Doc doc) {
+			this.doc = doc;
+		}
+
+		@Override
+		public Doc doc() {
+			return this.doc;
+		}
+	}
+
+	public static class Builder {
+
+		private final Battery battery;
+
+		private ChargeMaxCurrentHandler chargeMaxCurrentHandler;
+		private DischargeMaxCurrentHandler dischargeMaxCurrentHandler;
+
+		protected Builder(Battery battery) {
+			this.battery = battery;
+		}
+
+		/**
+		 * Applies all values from a {@link BatteryProtectionDefinition}.
+		 * 
+		 * @param def           the {@link BatteryProtectionDefinition}
+		 * @param clockProvider a {@link ClockProvider}
+		 * @return a {@link Builder}
+		 */
+		public Builder applyBatteryProtectionDefinition(BatteryProtectionDefinition def, ClockProvider clockProvider) {
+			return this //
+					.setChargeMaxCurrentHandler(
+							ChargeMaxCurrentHandler.create(clockProvider, def.getInitialBmsMaxEverChargeCurrent()) //
+									.setVoltageToPercent(def.getChargeVoltageToPercent()) //
+									.setTemperatureToPercent(def.getChargeTemperatureToPercent()) //
+									.setMaxIncreasePerSecond(def.getMaxIncreaseAmperePerSecond()) //
+									.setForceDischarge(def.getForceDischargeParams()) //
+									.build()) //
+					.setDischargeMaxCurrentHandler(
+							DischargeMaxCurrentHandler.create(clockProvider, def.getInitialBmsMaxEverDischargeCurrent()) //
+									.setVoltageToPercent(def.getDischargeVoltageToPercent())
+									.setTemperatureToPercent(def.getDischargeTemperatureToPercent()) //
+									.setMaxIncreasePerSecond(def.getMaxIncreaseAmperePerSecond()) //
+									.setForceCharge(def.getForceChargeParams()) //
+									.build()) //
+			;
+		}
+
+		/**
+		 * Sets the {@link ChargeMaxCurrentHandler}.
+		 * 
+		 * @param chargeMaxCurrentHandler the {@link ChargeMaxCurrentHandler}
+		 * @return a {@link Builder}
+		 */
+		public Builder setChargeMaxCurrentHandler(ChargeMaxCurrentHandler chargeMaxCurrentHandler) {
+			this.chargeMaxCurrentHandler = chargeMaxCurrentHandler;
+			return this;
+		}
+
+		/**
+		 * Sets the {@link DischargeMaxCurrentHandler}.
+		 * 
+		 * @param dischargeMaxCurrentHandler the {@link DischargeMaxCurrentHandler}
+		 * @return a {@link Builder}
+		 */
+		public Builder setDischargeMaxCurrentHandler(DischargeMaxCurrentHandler dischargeMaxCurrentHandler) {
+			this.dischargeMaxCurrentHandler = dischargeMaxCurrentHandler;
+			return this;
+		}
+
+		/**
+		 * Builds the {@link BatteryProtection} instance.
+		 * 
+		 * @return a {@link BatteryProtection}
+		 */
+		public BatteryProtection build() {
+			return new BatteryProtection(this.battery, this.chargeMaxCurrentHandler, this.dischargeMaxCurrentHandler);
+		}
+	}
+
+	/**
+	 * Create a {@link BatteryProtection} using builder pattern.
+	 * 
+	 * @param battery the {@link Battery}
+	 * @return a {@link Builder}
+	 */
+	public static Builder create(Battery battery) {
+		return new Builder(battery);
+	}
+
+	private final Battery battery;
+	private final ChargeMaxCurrentHandler chargeMaxCurrentHandler;
+	private final DischargeMaxCurrentHandler dischargeMaxCurrentHandler;
+
+	protected BatteryProtection(Battery battery, ChargeMaxCurrentHandler chargeMaxCurrentHandler,
+			DischargeMaxCurrentHandler dischargeMaxCurrentHandler) {
+		TypeUtils.assertNull("BatteryProtection algorithm is missing data", battery, chargeMaxCurrentHandler,
+				dischargeMaxCurrentHandler);
+		this.battery = battery;
+		this.chargeMaxCurrentHandler = chargeMaxCurrentHandler;
+		this.dischargeMaxCurrentHandler = dischargeMaxCurrentHandler;
+	}
+
+	/**
+	 * Apply the logic on the {@link Battery}.
+	 * 
+	 * <ul>
+	 * <li>Set CHARGE_MAX_CURRENT Channel
+	 * <li>Set DISCHARGE_MAX_CURRENT Channel
+	 * <li>Set FORCE_DISCHARGE_ACTIVE State-Channel if Charge-Max-Current < 0
+	 * <li>Set FORCE_CHARGE_ACTIVE State-Channel if Discharge-Max-Current < 0
+	 * <li>SET
+	 * </ul>
+	 */
+	public void apply() {
+		// Use MaxCurrentHandlers to calculate max charge and discharge currents.
+		// These methods also write debug information to BatteryProtection-Channels, so
+		// it is feasible to always execute them, even if battery is not started.
+		int chargeMaxCurrent = this.chargeMaxCurrentHandler.calculateCurrentLimit(this.battery);
+		int dischargeMaxCurrent = this.dischargeMaxCurrentHandler.calculateCurrentLimit(this.battery);
+
+		// Set max charge and discharge currents
+		this.battery._setChargeMaxCurrent(chargeMaxCurrent);
+		this.battery._setDischargeMaxCurrent(dischargeMaxCurrent);
+	}
+}