Battery Protection Algorithm

io.openems.common/src/io/openems/common/types/ChannelAddress.java

@@ -2,6 +2,7 @@
 
 import io.openems.common.exceptions.OpenemsError;
 import io.openems.common.exceptions.OpenemsError.OpenemsNamedException;
+import io.openems.common.utils.StringUtils;
 
 public class ChannelAddress implements Comparable<ChannelAddress> {
 
@@ -79,4 +80,39 @@ public boolean equals(Object obj) {
 		ChannelAddress other = (ChannelAddress) obj;
 		return this.toString().equals(other.toString());
 	}
+
+	/**
+	 * Match two ChannelAddresses, considering wildcards.
+	 * 
+	 * <ul>
+	 * <li>if {@link #equals(Object)} is true -> return 0
+	 * <li>if both {@link ChannelAddress}es match via wildcards -> return value > 1;
+	 * bigger values represent a better match
+	 * <li>if both {@link ChannelAddress}es do not match -> return -1
+	 * </ul>
+	 * 
+	 * <p>
+	 * See {@link StringUtils#matchWildcard(String, String)} for implementation
+	 * details.
+	 * 
+	 * @param source  the source {@link ChannelAddress}
+	 * @param pattern the pattern {@link ChannelAddress}
+	 * @return an integer value representing the degree of matching
+	 */
+	public static int match(ChannelAddress source, ChannelAddress pattern) {
+		int componentIdMatch = StringUtils.matchWildcard(source.componentId, pattern.componentId);
+		int channelIdMatch = StringUtils.matchWildcard(source.channelId, pattern.channelId);
+		if (componentIdMatch < 0 || channelIdMatch < 0) {
+			return -1;
+		} else if (componentIdMatch == 0 && channelIdMatch == 0) {
+			return 0;
+		}
+		if (componentIdMatch == 0) {
+			return Integer.MAX_VALUE / 2 + channelIdMatch;
+		} else if (channelIdMatch == 0) {
+			return Integer.MAX_VALUE / 2 + componentIdMatch;
+		} else {
+			return componentIdMatch + channelIdMatch;
+		}
+	}
 }

io.openems.common/src/io/openems/common/utils/StringUtils.java

@@ -23,4 +23,37 @@ public static String toShortString(JsonElement j, int length) {
 	public static String capitalizeFirstLetter(String s) {
 		return s.substring(0, 1).toUpperCase() + s.substring(1);
 	}
+
+	/**
+	 * Match two Strings, considering wildcards.
+	 * 
+	 * <ul>
+	 * <li>if {@link #equals(Object)} is true -> return 0
+	 * <li>if 'pattern' matches 'source' -> return value > 1; bigger values
+	 * represent a better match
+	 * <li>if both Strings do not match -> return -1
+	 * </ul>
+	 * 
+	 * <p>
+	 * Implementation note: only one wildcard is considered. Either the entire
+	 * string is "*" or the wildcard is at the beginning or at the end of the
+	 * pattern String. The the JUnit test for details.
+	 * 
+	 * @param source  the String to be evaluated
+	 * @param pattern the pattern String, i.e. "meter*"
+	 * @return an integer value representing the degree of matching
+	 */
+	public static int matchWildcard(String source, String pattern) {
+		if (source.equals(pattern)) {
+			return 0;
+		} else if (pattern.equals("*")) {
+			return 1;
+		} else if (pattern.startsWith("*") && source.endsWith(pattern.substring(1))) {
+			return pattern.length();
+		} else if (pattern.endsWith("*") && source.startsWith(pattern.substring(0, pattern.length() - 1))) {
+			return pattern.length();
+		} else {
+			return -1;
+		}
+	}
 }

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

@@ -3,10 +3,12 @@
 import org.osgi.annotation.versioning.ProviderType;
 
 import io.openems.common.channel.AccessMode;
+import io.openems.common.channel.Level;
 import io.openems.common.channel.Unit;
 import io.openems.common.types.OpenemsType;
 import io.openems.edge.common.channel.Doc;
 import io.openems.edge.common.channel.IntegerReadChannel;
+import io.openems.edge.common.channel.StateChannel;
 import io.openems.edge.common.channel.value.Value;
 import io.openems.edge.common.component.OpenemsComponent;
 import io.openems.edge.common.modbusslave.ModbusSlaveNatureTable;
@@ -113,8 +115,12 @@ 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}
 		 * </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)),
 
@@ -137,6 +143,8 @@ 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}
 		 * </ul>
 		 */
 		DISCHARGE_MAX_CURRENT(Doc.of(OpenemsType.INTEGER) //
@@ -189,7 +197,29 @@ public enum ChannelId implements io.openems.edge.common.channel.ChannelId {
 		 * </ul>
 		 */
 		MAX_CELL_VOLTAGE(Doc.of(OpenemsType.INTEGER) //
-				.unit(Unit.MILLIVOLT));
+				.unit(Unit.MILLIVOLT)),
+
+		/**
+		 * Force charge active.
+		 * 
+		 * <ul>
+		 * <li>Interface: Battery
+		 * <li>Indicates that battery is in force charge mode
+		 * </ul>
+		 */
+		FORCE_CHARGE_ACTIVE(Doc.of(Level.INFO).text("Force charge mode is active")), //
+
+		/**
+		 * Force discharge active.
+		 * 
+		 * <ul>
+		 * <li>Interface: Battery
+		 * <li>Indicates that battery is in force discharge mode
+		 * </ul>
+		 */
+		FORCE_DISCHARGE_ACTIVE(Doc.of(Level.INFO).text("Force discharge mode is active")), //
+
+		;
 
 		private final Doc doc;
 
@@ -710,4 +740,80 @@ public default void _setMaxCellVoltage(Integer value) {
 	public default void _setMaxCellVoltage(int value) {
 		this.getMaxCellVoltageChannel().setNextValue(value);
 	}
+
+	/**
+	 * Gets the Channel for {@link ChannelId#FORCE_CHARGE_ACTIVE}.
+	 *
+	 * @return the Channel
+	 */
+	public default StateChannel getForceChargeActiveChannel() {
+		return this.channel(ChannelId.FORCE_CHARGE_ACTIVE);
+	}
+
+	/**
+	 * Gets the State. See {@link ChannelId#FORCE_CHARGE_ACTIVE}.
+	 *
+	 * @return the Channel {@link Value}
+	 */
+	public default Value<Boolean> getForceChargeActive() {
+		return this.getForceChargeActiveChannel().value();
+	}
+
+	/**
+	 * Internal method to set the 'nextValue' on
+	 * {@link ChannelId#FORCE_CHARGE_ACTIVE} Channel.
+	 *
+	 * @param value the next value
+	 */
+	public default void _setForceChargeActive(Boolean value) {
+		this.getForceChargeActiveChannel().setNextValue(value);
+	}
+
+	/**
+	 * Internal method to set the 'nextValue' on
+	 * {@link ChannelId#FORCE_CHARGE_ACTIVE} Channel.
+	 *
+	 * @param value the next value
+	 */
+	public default void _setForceChargeActive(boolean value) {
+		this.getForceChargeActiveChannel().setNextValue(value);
+	}
+
+	/**
+	 * Gets the Channel for {@link ChannelId#FORCE_DISCHARGE_ACTIVE}.
+	 *
+	 * @return the Channel
+	 */
+	public default StateChannel getForceDischargeActiveChannel() {
+		return this.channel(ChannelId.FORCE_DISCHARGE_ACTIVE);
+	}
+
+	/**
+	 * Gets the State. See {@link ChannelId#FORCE_DISCHARGE_ACTIVE}.
+	 *
+	 * @return the Channel {@link Value}
+	 */
+	public default Value<Boolean> getForceDischargeActive() {
+		return this.getForceDischargeActiveChannel().value();
+	}
+
+	/**
+	 * Internal method to set the 'nextValue' on
+	 * {@link ChannelId#FORCE_DISCHARGE_ACTIVE} Channel.
+	 *
+	 * @param value the next value
+	 */
+	public default void _setForceDischargeActive(Boolean value) {
+		this.getForceDischargeActiveChannel().setNextValue(value);
+	}
+
+	/**
+	 * Internal method to set the 'nextValue' on
+	 * {@link ChannelId#FORCE_DISCHARGE_ACTIVE} Channel.
+	 *
+	 * @param value the next value
+	 */
+	public default void _setForceDischargeActive(boolean value) {
+		this.getForceDischargeActiveChannel().setNextValue(value);
+	}
 }

io.openems.edge.battery.api/src/io/openems/edge/battery/test/DummyBattery.java

@@ -31,4 +31,40 @@ public void setStartStop(StartStop value) throws OpenemsNamedException {
 		this._setStartStop(value);
 	}
 
+	public DummyBattery withCapacity(int value) {
+		this._setCapacity(value);
+		this.getCapacityChannel().nextProcessImage();
+		return this;
+	}
+
+	public DummyBattery withVoltage(int value) {
+		this._setVoltage(value);
+		this.getVoltageChannel().nextProcessImage();
+		return this;
+	}
+
+	public DummyBattery withDischargeMaxCurrent(int value) {
+		this._setDischargeMaxCurrent(value);
+		this.getDischargeMaxCurrentChannel().nextProcessImage();
+		return this;
+	}
+
+	public DummyBattery withChargeMaxCurrent(int value) {
+		this._setChargeMaxCurrent(value);
+		this.getChargeMaxCurrentChannel().nextProcessImage();
+		return this;
+	}
+
+	public DummyBattery withMinCellVoltage(int value) {
+		this._setMinCellVoltage(value);
+		this.getMinCellVoltageChannel().nextProcessImage();
+		return this;
+	}
+
+	public DummyBattery withMaxCellVoltage(int value) {
+		this._setMaxCellVoltage(value);
+		this.getMaxCellVoltageChannel().nextProcessImage();
+		return this;
+	}
+
 }

io.openems.edge.battery.bydcommercial/src/io/openems/edge/battery/bydcommercial/statemachine/Context.java

@@ -2,14 +2,14 @@
 
 import io.openems.edge.battery.bydcommercial.BatteryBoxC130;
 import io.openems.edge.battery.bydcommercial.Config;
+import io.openems.edge.common.statemachine.AbstractContext;
+
+public class Context extends AbstractContext<BatteryBoxC130> {
 
-public class Context {
-	protected final BatteryBoxC130 component;
 	protected final Config config;
 
-	public Context(BatteryBoxC130 component, Config config) {
-		super();
-		this.component = component;
+	public Context(BatteryBoxC130 parent, Config config) {
+		super(parent);
 		this.config = config;
 	}
 }

io.openems.edge.battery.bydcommercial/src/io/openems/edge/battery/bydcommercial/statemachine/ErrorHandler.java

@@ -4,6 +4,7 @@
 import java.time.Instant;
 
 import io.openems.common.exceptions.OpenemsError.OpenemsNamedException;
+import io.openems.edge.battery.bydcommercial.BatteryBoxC130;
 import io.openems.edge.battery.bydcommercial.enums.PowerCircuitControl;
 import io.openems.edge.battery.bydcommercial.statemachine.StateMachine.State;
 import io.openems.edge.common.statemachine.StateHandler;
@@ -17,18 +18,20 @@ protected void onEntry(Context context) throws OpenemsNamedException {
 		this.entryAt = Instant.now();
 
 		// Try to stop system
-		context.component._setPowerCircuitControl(PowerCircuitControl.SWITCH_OFF);
+		context.getParent()._setPowerCircuitControl(PowerCircuitControl.SWITCH_OFF);
 	}
 
 	@Override
 	protected void onExit(Context context) throws OpenemsNamedException {
-		context.component._setMaxStartAttempts(false);
-		context.component._setMaxStopAttempts(false);
+		BatteryBoxC130 battery = context.getParent();
+
+		battery._setMaxStartAttempts(false);
+		battery._setMaxStopAttempts(false);
 	}
 
 	@Override
 	public State runAndGetNextState(Context context) {
-		System.out.println("Stuck in ERROR_HANDLING: " + context.component.getStateChannel().listStates());
+		System.out.println("Stuck in ERROR_HANDLING: " + context.getParent().getStateChannel().listStates());
 
 		if (Duration.between(this.entryAt, Instant.now()).getSeconds() > 120) {
 			// Try again

io.openems.edge.battery.bydcommercial/src/io/openems/edge/battery/bydcommercial/statemachine/GoRunningHandler.java

@@ -4,6 +4,7 @@
 import java.time.Instant;
 
 import io.openems.common.exceptions.OpenemsError.OpenemsNamedException;
+import io.openems.edge.battery.bydcommercial.BatteryBoxC130;
 import io.openems.edge.battery.bydcommercial.enums.PowerCircuitControl;
 import io.openems.edge.battery.bydcommercial.statemachine.StateMachine.State;
 import io.openems.edge.battery.bydcommercial.utils.Constants;
@@ -18,12 +19,13 @@ public class GoRunningHandler extends StateHandler<State, Context> {
 	protected void onEntry(Context context) throws OpenemsNamedException {
 		this.lastAttempt = Instant.MIN;
 		this.attemptCounter = 0;
-		context.component._setMaxStartAttempts(false);
+		context.getParent()._setMaxStartAttempts(false);
 	}
 
 	@Override
 	public State runAndGetNextState(Context context) throws OpenemsNamedException {
-		PowerCircuitControl preChargeControl = context.component.getPowerCircuitControl();
+		BatteryBoxC130 battery = context.getParent();
+		PowerCircuitControl preChargeControl = battery.getPowerCircuitControl();
 
 		if (preChargeControl == PowerCircuitControl.SWITCH_ON) {
 			return State.RUNNING;
@@ -36,12 +38,12 @@ public State runAndGetNextState(Context context) throws OpenemsNamedException {
 
 			if (this.attemptCounter > Constants.RETRY_COMMAND_MAX_ATTEMPTS) {
 				// Too many tries
-				context.component._setMaxStartAttempts(true);
+				battery._setMaxStartAttempts(true);
 				return State.UNDEFINED;
 
 			} else {
 				// Trying to switch on
-				context.component.setPowerCircuitControl(PowerCircuitControl.PRE_CHARGING_1);
+				battery.setPowerCircuitControl(PowerCircuitControl.PRE_CHARGING_1);
 				this.lastAttempt = Instant.now();
 				this.attemptCounter++;
 				return State.GO_RUNNING;

io.openems.edge.battery.bydcommercial/src/io/openems/edge/battery/bydcommercial/statemachine/GoStoppedHandler.java

@@ -4,6 +4,7 @@
 import java.time.Instant;
 
 import io.openems.common.exceptions.OpenemsError.OpenemsNamedException;
+import io.openems.edge.battery.bydcommercial.BatteryBoxC130;
 import io.openems.edge.battery.bydcommercial.enums.PowerCircuitControl;
 import io.openems.edge.battery.bydcommercial.statemachine.StateMachine.State;
 import io.openems.edge.battery.bydcommercial.utils.Constants;
@@ -22,7 +23,8 @@ protected void onEntry(Context context) {
 
 	@Override
 	public State runAndGetNextState(Context context) throws OpenemsNamedException {
-		PowerCircuitControl powerCircuitControl = context.component.getPowerCircuitControl();
+		BatteryBoxC130 battery = context.getParent();
+		PowerCircuitControl powerCircuitControl = battery.getPowerCircuitControl();
 
 		if (powerCircuitControl == PowerCircuitControl.SWITCH_OFF) {
 			return State.STOPPED;
@@ -35,12 +37,12 @@ public State runAndGetNextState(Context context) throws OpenemsNamedException {
 
 			if (this.attemptCounter > Constants.RETRY_COMMAND_MAX_ATTEMPTS) {
 				// Too many tries
-				context.component._setMaxStopAttempts(true);
+				battery._setMaxStopAttempts(true);
 				return State.UNDEFINED;
 
 			} else {
 				// Trying to switch off
-				context.component.setPowerCircuitControl(PowerCircuitControl.SWITCH_OFF);
+				battery.setPowerCircuitControl(PowerCircuitControl.SWITCH_OFF);
 				this.lastAttempt = Instant.now();
 				this.attemptCounter++;
 				return State.GO_STOPPED;