You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Introduce ElectricityMeter as replacement for SymmetricMeter & AsymmetricMeter (OpenEMS#2144)
Distinguishing between `SymmetricMeter` and `AsymmetricMeter` and having `AsymmetricMeter extends SymmetricMeter` did never really make sense physically. In fact the _asymmetric_ meter (i.e. the three-phase meter) is the _most normal_ case. Special cases are:
- a _symmetric_ meter, i.e. one that has the same values on all phases; this can be handled entirely by deriving the individual phase values from the sum values, via dividing the power by three.
- a _single-phase_ meter, i.e. one that only has values on one phase. This requires active configuration and then allows setting the other phases to zero. The `SinglePhaseMeter` Nature is kept, because it allows a use-case when UI should really only show one value for these devices.
The special cases can be represented properly by this newly introduced `ElectricityMeter`, which combines most of the Channels and replaces SymmetricMeter and AsymmetricMeter entirely. It also clearly distinguishes _electricity meters_ from _heat meters_ that are slowly coming to OpenEMS.
This PR includes:
- Replace SymmetricMeter and AsymmetricMeter
- Breaking:
- Renamed Meter.Virtual.Asymmetric.Add -> Meter.Virtual.Add
- Dropped Meter.Virtual.Symmetric.Add
- Renamed Meter.Virtual.Symmetric.Subtract -> Meter.Virtual.Subtract
- Simulator Grid Meter Reacting: add Voltage and Current sum and per phase for better testing
- UI fixes
- show negative current per phase
- fix translation issues
It also tries to clarify the sometimes confusing representation of positive and negative values for Power and Current. See the Javadoc in ElectricityMeter and the discussion at https://community.openems.io/t/change-energy-channel-assignment-based-on-meter-type/1603/6.
As this PR touches a lot of files, it is kept as small, simple and non-breaking as possible. Follow-up PRs will add more features,
. Make the class implement the `SymmetricMeter` nature:
205
+
. Make the class implement the `ElectricityMeter` nature:
206
206
+
207
207
[source,java]
208
208
----
209
-
public class MeterSimulatedImpl extends AbstractOpenemsModbusComponent implements MeterSimulated, SymmetricMeter, OpenemsComponent, ModbusComponent {
209
+
public class MeterSimulatedImpl extends AbstractOpenemsModbusComponent implements MeterSimulated, ElectricityMeter, OpenemsComponent, ModbusComponent {
210
210
----
211
-
. Eclipse will underline `SymmetricMeter` and show you the error *SymmetricMeter cannot be resolved to a type*. Resolve it by importing adding an `import io.openems.edge.meter.api.SymmetricMeter;`.
211
+
. Eclipse will underline `ElectricityMeter` and show the error *ElectricityMeter cannot be resolved to a type*. Resolve it by adding the line `import io.openems.edge.meter.api.ElectricityMeter;` to the import section of the file.
212
212
+
213
-
NOTE: The easiest way to fix these kind of import errors is to to selecto btn:[Source] → btn:[Organize Imports] in the menu or simply press btn:[Ctrl] + btn:[Shift] + btn:[o]. Alternatively click the 'error light bulb' next to the line with the error and select btn:[Import 'SymmetricMeter' (io.openems.edge.meter.api)].
214
-
. Eclipse still complains and now underlines the class name `MeterSimulated` with the error *The type MeterSimulated must implement the inherited abstract method SymmetricMeter.getMeterType()*. Resolve it by adding an implementation of the `getMeterType()` method:
213
+
NOTE: The easiest way to fix these kind of import errors is to select btn:[Source] → btn:[Organize Imports] in the menu or simply press btn:[Ctrl] + btn:[Shift] + btn:[o]. Alternatively click the 'light bulb' next to the line with the error and select btn:[Import 'ElectricityMeter' (io.openems.edge.meter.api)].
214
+
. Eclipse still complains and now underlines the class name `MeterSimulated` with the error *The type MeterSimulated must implement the inherited abstract method ElectricityMeter.getMeterType()*. Resolve it by adding an implementation of the `getMeterType()` method:
215
215
+
216
216
[source,java]
217
217
----
@@ -220,14 +220,14 @@ public MeterType getMeterType() {
220
220
return this.config.type();
221
221
}
222
222
----
223
-
. Tell the OpenEMS framework that `MeterSimulated` provides the SymmetricMeter *Channels*, by adjusting the constructor:
223
+
. Tell the OpenEMS framework that `MeterSimulated` provides the ElectricityMeter *Channels*, by adjusting the constructor:
new FC3ReadRegistersTask(1000, Priority.HIGH, // <15>
344
-
m(SymmetricMeter.ChannelId.ACTIVE_POWER, new SignedWordElement(1000)))); // <16>
344
+
m(ElectricityMeter.ChannelId.ACTIVE_POWER, new SignedWordElement(1000)))); // <16>
345
345
}
346
346
347
347
@Override
@@ -364,7 +364,7 @@ public class MeterSimulatedImpl extends AbstractOpenemsModbusComponent // <6>
364
364
+
365
365
NOTE: If the device was using another protocol, it is advisable to use the *AbstractOpenemsComponent* class as a convenience layer instead of implementing everything required by the *OpenemsComponent* interface manually.
366
366
<7> The class implements *OpenemsComponent*. This makes it an xref:coreconcepts.adoc#_openems_component[OpenEMS Component].
367
-
The Device that we are is a *SymmetricMeter*. We already defined the required Channels in the _initializeChannels()_ method. Additionally the Component also needs to implement the Nature interface.
367
+
The Device that we are implementing is an *ElectricityMeter*. We already defined the required Channels in the _initializeChannels()_ method. Additionally the Component also needs to implement the Nature interface.
368
368
+
369
369
NOTE: In plain Java it is not required to add `implements OpenemsComponent` if we inherit from 'AbstractOpenemsComponent' or 'AbstractOpenemsModbusComponent'. Be aware that for OSGi dependency injection to function properly, it is still required to mention all implemented interfaces again, as it is not considering the complete inheritance tree.
370
370
+
@@ -374,7 +374,7 @@ NOTE: In plain Java it is not required to add `implements OpenemsComponent` if w
374
374
- This enum is empty, as we do not have custom Channels here.
375
375
- ChannelId enums require a Doc object that provides meta information about the Channel - e.g. the above ACTIVE_POWER Channel is defined as `ACTIVE_POWER(new Doc().type(OpenemsType.INTEGER).unit(Unit.WATT)`
376
376
====
377
-
<8> We call the constructor of the super class (`AbstractOpenemsModbusComponent`/`AbstractOpenemsComponent`) to initialize the Channels of the Component. It is important to list all ChannelId-Enums of all implemented Natures. The call takes the *ChannelId* declarations and creates a Channel instance for each of them; e.g. for the `SymmetricMeter.ACTIVE_POWER` ChannelId, an object instance of `IntegerReadChannel` is created that represents the Channel.
377
+
<8> We call the constructor of the super class (`AbstractOpenemsModbusComponent`/`AbstractOpenemsComponent`) to initialize the Channels of the Component. It is important to list all ChannelId-Enums of all implemented Natures. The call takes the *ChannelId* declarations and creates a Channel instance for each of them; e.g. for the `ElectricityMeter.ACTIVE_POWER` ChannelId, an object instance of `IntegerReadChannel` is created that represents the Channel.
378
378
<9> The `super.activate()` method requires an instance of *ConfigurationAdmin* as a parameter. Using the *@Reference* annotation the OSGi framework is going to provide the ConfigurationAdmin service via dependency injection.
379
379
<10> The Component utilizes an external Modbus Component (the _Modbus Bridge_) for the actual Modbus communication. We receive an instance of this service via dependency injection (like we did already for the _ConfigurationAdmin_ service). Most of the magic is handled by the _AbstractOpenemsModbusComponent_ implementation, but the way the OSGi framework works, we need to define the _@Reference_ explicitly here in the actual implementation of the component and call the parent `setModbus()` method.
380
380
<11> The *activate()* method (marked by the *@Activate* annotation) is called on activation of an object instance of this Component. It comes with a ComponentContext and an instance of a configuration in the form of a Config object. All logic for activating and deactivating the OpenEMS Component is hidden in the super classes and just needs to be called from here.
@@ -384,7 +384,7 @@ NOTE: In plain Java it is not required to add `implements OpenemsComponent` if w
384
384
<15> *FC3ReadRegistersTask* is an implementation of Modbus http://www.simplymodbus.ca/FC03.htm[function code 3 "Read Holding Registers" icon:external-link[]]. Its first parameter is the start address of the register block. The second parameter is a priority information that defines how often this register block needs to be queried. Following parameters are an arbitrary number of *ModbusElements*.
385
385
+
386
386
NOTE: Most Modbus function codes are available by their respective _FC*_ implementation classes.
387
-
<16> Here the internal *m()* method is used to make a simple 1-to-1 mapping between the Modbus element at address `1000` and the Channel _SymmetricMeter.ChannelId.ACTIVE_POWER_. The Modbus element is defined as a 16 bit word element with an signed integer value.
387
+
<16> Here the internal *m()* method is used to make a simple 1-to-1 mapping between the Modbus element at address `1000` and the Channel _ElectricityMeter.ChannelId.ACTIVE_POWER_. The Modbus element is defined as a 16 bit word element with an signed integer value.
388
388
+
389
389
[NOTE]
390
390
====
@@ -393,7 +393,7 @@ NOTE: Most Modbus function codes are available by their respective _FC*_ impleme
393
393
- For more advanced channel-to-element mapping functionalities the internal *cm()* method can be used - e.g. to map one Modbus element to multiple Channels.
394
394
+
395
395
Using this principle a complete Modbus table consisting of multiple register blocks that need to be read or written with different Modbus function codes can be defined. For details have a look at the existing implementation classes inside the Modbus Bridge source code.
396
-
<17> The SymmetricMeter Nature requires us to provide a *MeterType* via a `MeterType getMeterType()` method. The MeterType is provided by the Config.
396
+
<17> The ElectricityMeter Nature requires us to provide a *MeterType* via a `MeterType getMeterType()` method. The MeterType is provided by the Config.
397
397
<18> Finally it is always a good idea to define a *debugLog()* method. This method is called in each cycle by the *Controller.Debug.Log* and very helpful for continuous debugging.
Copy file name to clipboardexpand all lines: io.openems.edge.bosch.bpts5hybrid/src/io/openems/edge/bosch/bpts5hybrid/meter/BoschBpts5HybridMeterImpl.java
Copy file name to clipboardexpand all lines: io.openems.edge.controller.asymmetric.balancingcosphi/src/io/openems/edge/controller/asymmetric/balancingcosphi/ControllerAsymmetricBalancingCosPhiImpl.java
0 commit comments