Implementing a device

1. Step-by-step guide

This chapter explains the steps required to implement an electric meter in OpenEMS Edge that is connected via Modbus/TCP. The meter itself is simulated using a small Modbus slave application, so no external hardware is required for this guide.

The tutorial is based on the Getting Started guide.

1.1. Create a new OSGi Bundle

For more information see OSGi Bundle.

  1. In the menu choose FileNewOther

    Creating a new project in Eclipse IDE
    Figure 1. Creating a new project in Eclipse IDE
  2. Select BndtoolsBnd OSGi Project and press Next >

    Creating a Bnd OSGi Project in Eclipse IDE
    Figure 2. Creating a Bnd OSGi Project in Eclipse IDE
  3. Select OpenEMS TemplatesOpenEMS Modbus Devices and press Next >

    Creating an OpenEMS Modbus Devices Bundle in Eclipse IDE
    Figure 3. Creating an OpenEMS Modbus Devices Bundle in Eclipse IDE
  4. Choose a project name and press Next >

    The project name is used as the folder name in OpenEMS source directory. The naming is up to you, but it is good practice to keep the name lower case and use something like io.openems.[edge/backend].[purpose/nature].[implementation]. For the simulated meter io.openems.edge.meter.simulated is a good choice.
    Naming an OpenEMS Modbus Devices Bundle in Eclipse IDE
    Figure 4. Naming an OpenEMS Modbus Devices Bundle in Eclipse IDE
  5. Accept defaults for the final screen and press Finish

    Java settings for an OpenEMS Modbus Devices Bundle in Eclipse IDE
    Figure 5. Java settings for an OpenEMS Modbus Devices Bundle in Eclipse IDE
  6. The assistant closes and you can see your new bundle.

1.2. Define Bundle dependencies

OSGi Bundles can be dependent on certain other Bundles. This information needs to be set in a bnd.bnd file.

  1. Select the component directory srcio.openems.edge.meter.simulated

    New simulated meter OpenEMS Modbus Devices Bundle in Eclipse IDE
    Figure 6. New simulated meter OpenEMS Modbus Devices Bundle in Eclipse IDE
  2. Open the bnd.bnd file by double clicking on it.

  3. Open the Build tab

    You can see, that the Bundle is by default dependent on some core bundles

    ${buildpath}

    applies some defaults defined in /cnf/build.bnd

    io.openems.common

    OpenEMS commons

    io.openems.edge.bridge.modbus

    the Modbus Bridge provides the Bridge services for Modbus/RTU and Modbus/TCP protocols

    io.openems.edge.common

    OpenEMS Edge commons

    slf4j.api

    to be able to use the logger

    Bndtools Build configuration
    Figure 7. Bndtools Build configuration
  4. Click the + symbol next to Build Path.

    Bndtools Project Build Path configuration
    Figure 8. Bndtools Project Build Path configuration
  5. Use the Project Build Path assistant to add the following Bundle as dependency:

    io.openems.edge.meter.api

    The Meter API Bundle provides the interfaces for OpenEMS Edge Meter Nature.

  6. It is also a good moment to configure the Bundle meta information. Still inside the bnd.bnd file open the Source tab. Adjust the meta information - it will help the users of your component:

    Bundle-Name: OpenEMS Edge Meter Simulated
    Bundle-Vendor: OpenEMS Association e.V.
    Bundle-License: https://opensource.org/licenses/EPL-2.0
    Bundle-Version: 1.0.0.${tstamp}
    
    -buildpath: \
    	${buildpath},\
    	io.openems.common,\
    	io.openems.edge.bridge.modbus,\
    	io.openems.edge.common,\
    	io.openems.edge.meter.api,\
    	slf4j.api,\
    
    -testpath: \
    	${testpath}
The ;version=latest declaration is not required and can be removed. Also it is best practice to sort the buildpath bundles alphabetically.

1.3. Define configuration parameters

OpenEMS Components can have several configuration parameters. They are defined as Java annotations and specific OSGi annotations are used to generate meta information that is used e.g. by Apache Felix Web Console to generate a user interface form (see Getting Started).

  1. Open the Config.java file inside src/io.openems.edge.meter.simulated by double clicking on it.

  2. Adjust the following lines in the template:

    1. In the @ObjectClassDefinition set the name to "Meter Simulated" and the description to "Implements the simulated meter.".

    2. Set the default value of the String id() attribute to "meter0".

    3. After the boolean enabled() attribute add a Meter-Type attribute:

      @AttributeDefinition(name = "Meter-Type", description = "Grid, Production (=default), Consumption")
      MeterType type() default MeterType.PRODUCTION;
    4. Set the String webconsole_configurationFactory_nameHint() default value to "Meter Simulated [{id}]"

  3. The content should now match the following code:

    package io.openems.edge.meter.simulated;
    
    import org.osgi.service.metatype.annotations.AttributeDefinition;
    import org.osgi.service.metatype.annotations.ObjectClassDefinition;
    
    import io.openems.edge.meter.api.MeterType;
    
    @ObjectClassDefinition((1)
    		name = "Meter Simulated", //
    		description = "Implements the simulated meter.")
    @interface Config {
    
    	@AttributeDefinition(name = "Component-ID", description = "Unique ID of this Component")
    	String id() default "meter0"; (2)
    
    	@AttributeDefinition(name = "Alias", description = "Human-readable name of this Component; defaults to Component-ID")
    	String alias() default ""; (3)
    
    	@AttributeDefinition(name = "Is enabled?", description = "Is this Component enabled?")
    	boolean enabled() default true; (4)
    
    	@AttributeDefinition(name = "Meter-Type", description = "Grid, Production (=default), Consumption") (5)
    	MeterType type() default MeterType.PRODUCTION; (6)
    
    	@AttributeDefinition(name = "Modbus-ID", description = "ID of Modbus brige.")
    	String modbus_id() default "modbus0"; (7)
    
    	@AttributeDefinition(name = "Modbus Unit-ID", description = "The Unit-ID of the Modbus device.")
    	int modbusUnitId() default 1; (8)
    
    	@AttributeDefinition(name = "Modbus target filter", description = "This is auto-generated by 'Modbus-ID'.")
    	String Modbus_target() default ""; (9)
    
    	String webconsole_configurationFactory_nameHint() default "Meter Simulated [{id}]"; (10)
    
    }
    1 The @ObjectClassDefinition annotation defines this file as a Meta Type Resource for OSGi configuration admin. Use it to set a name and description for this OpenEMS Component.
    2 The id configuration parameter sets the OpenEMS Component-ID (see Channel Adress). Note: A default ID 'meter0' is defined. It is good practice to define such an ID here, as it simplifies configuration in the UI.
    3 The alias configuration parameter sets the human-readable name of this OpenEMS Component. If no alias is configured, the Component-ID is used instead.
    4 The enabled parameter provides a soft way of deactivating an OpenEMS Component programmatically.
    5 The @AttributeDefinition annotation provides meta information about a configuration parameter like name and description.
    6 The 'Meter' nature requires definition of a MeterType that defines the purpose of the Meter. We will let the user define this type by a configuration parameter.
    7 The 'Modbus-ID' parameter creates the link to a Modbus-Service via its OpenEMS Component-ID. At runtime the user will typically set this configuration parameter to something like 'modbus0'.
    8 The Modbus service implementation requires us to provide the Modbus Unit-ID (also commonly called Device-ID or Slave-ID) of the Modbus slave device. This is the ID that is configured at the simulated meter.
    9 The Modbus_target will be automatically set by OpenEMS framework and does usually not need to be configured by the user. Note: Linking other OpenEMS Components is implemented using OSGi References. The OpenEMS Edge framework therefor sets the 'target' property of a reference to filter the matched services.
    10 The webconsole_configurationFactory_nameHint parameter sets a custom name for Apache Felix Web Console, helping the user to find the correct bundle.

1.4. Implement the OpenEMS Component

The Bndtools assistant created a MyModbusDevice.java file. First step is to set a proper name for this file. To rename the file, select it by clicking on it and choose RefactorRename…​ in the menu. Write MeterSimulated as 'New name' and press Finish.

Renaming a Java class in Eclipse IDE
Figure 9. Renaming a Java class in Eclipse IDE

Afterwards adjust the following content in the template:

  1. In the @Component annotation set the name to "Meter.Simulated":

    @Component(//
    		name = "Meter.Simulated", //
    		immediate = true, //
    		configurationPolicy = ConfigurationPolicy.REQUIRE //
    )
  2. Make the class implement the SymmetricMeter nature:

    public class MeterSimulated extends AbstractOpenemsModbusComponent implements SymmetricMeter, OpenemsComponent {
  3. 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;.

    The easiest way to fix these kind of import errors is to to selecto SourceOrganize Imports in the menu or simply press Ctrl + Shift + o. Alternatively click the 'error light bulb' next to the line with the error and select Import 'SymmetricMeter' (io.openems.edge.meter.api).
  4. 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:

    @Override
    public MeterType getMeterType() {
    	return this.config.type();
    }
  5. Tell the OpenEMS framework that MeterSimulated provides the SymmetricMeter Channels, by adjusting the constructor:

    public MeterSimulated() {
    	super(//
    			OpenemsComponent.ChannelId.values(), //
    			SymmetricMeter.ChannelId.values(), //
    			ChannelId.values() //
    	);
    }
  6. Finally we need to delare the modbus protocol of the simulated meter inside the defineModbusProtocol method. Replace the existing method

    @Override
    protected ModbusProtocol defineModbusProtocol() {
    	// TODO implement ModbusProtocol
    	return new ModbusProtocol(this);
    }

    with

    @Override
    protected ModbusProtocol defineModbusProtocol() {
    	return new ModbusProtocol(this, //
    			new FC3ReadRegistersTask(1000, Priority.HIGH,
    					m(SymmetricMeter.ChannelId.ACTIVE_POWER, new SignedWordElement(1000))));
    }

    and solve the import errors again as described above.

  7. Additionally it is advisable to implement a debugLog() method. This method provides information for the continuous log output of OpenEMS, provided by the DebugLogController. Adjust the method to return the ActivePower value of the meter:

    @Override
    public String debugLog() {
    	return "L:" + this.getActivePower().value().asString();
    }

The content of MeterSimulated.java should now match the following code:

package io.openems.edge.meter.simulated;

import org.osgi.service.cm.ConfigurationAdmin;
import org.osgi.service.component.ComponentContext;
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.ConfigurationPolicy;
import org.osgi.service.component.annotations.Deactivate;
import org.osgi.service.component.annotations.Reference;
import org.osgi.service.component.annotations.ReferenceCardinality;
import org.osgi.service.component.annotations.ReferencePolicy;
import org.osgi.service.component.annotations.ReferencePolicyOption;
import org.osgi.service.metatype.annotations.Designate;

import io.openems.edge.bridge.modbus.api.AbstractOpenemsModbusComponent;
import io.openems.edge.bridge.modbus.api.BridgeModbus;
import io.openems.edge.bridge.modbus.api.ModbusProtocol;
import io.openems.edge.bridge.modbus.api.element.SignedWordElement;
import io.openems.edge.bridge.modbus.api.task.FC3ReadRegistersTask;
import io.openems.edge.common.channel.Doc;
import io.openems.edge.common.component.OpenemsComponent;
import io.openems.edge.common.taskmanager.Priority;
import io.openems.edge.meter.api.MeterType;
import io.openems.edge.meter.api.SymmetricMeter;

@Designate(ocd = Config.class, factory = true) (1)
@Component((2)
		name = "Meter.Simulated", (3)
		immediate = true, (4)
		configurationPolicy = ConfigurationPolicy.REQUIRE (5)
)
public class MeterSimulated extends AbstractOpenemsModbusComponent (6)
	implements SymmetricMeter, OpenemsComponent { (7)

	private Config config = null;

	public enum ChannelId implements io.openems.edge.common.channel.ChannelId { (8)
		;

		private final Doc doc;

		private ChannelId(Doc doc) {
			this.doc = doc;
		}

		@Override
		public Doc doc() {
			return this.doc;
		}
	}

	public MeterSimulated() {
		super((9)
				OpenemsComponent.ChannelId.values(), //
				SymmetricMeter.ChannelId.values(), //
				ChannelId.values() //
		);
	}

	@Reference
	protected ConfigurationAdmin cm; (10)

	@Reference(policy = ReferencePolicy.STATIC, policyOption = ReferencePolicyOption.GREEDY, cardinality = ReferenceCardinality.MANDATORY)
	protected void setModbus(BridgeModbus modbus) {
		super.setModbus(modbus); (11)
	}

	@Activate
	void activate(ComponentContext context, Config config) { (12)
		super.activate(context, config.id(), config.alias(), config.enabled(), config.modbusUnitId(), this.cm, "Modbus",
				config.modbus_id());
		this.config = config;
	}

	@Deactivate
	protected void deactivate() { (13)
		super.deactivate();
	}

	@Override
	protected ModbusProtocol defineModbusProtocol() { (14)
		return new ModbusProtocol(this, (15)
				new FC3ReadRegistersTask(1000, Priority.HIGH, (16)
						m(SymmetricMeter.ChannelId.ACTIVE_POWER, new SignedWordElement(1000)))); (17)
	}

	@Override
	public MeterType getMeterType() { (18)
		return this.config.type();
	}

	@Override
	public String debugLog() { (19)
		return "L:" + this.getActivePower().value().asString();
	}
}
1 The @Designate annotation is used for OSGi to create a connection to the Config annotation class. It also defines this Component as a factory, i.e. it can produce multiple instances with different configurations.
2 The @Component annotation marks this class as an OSGi component.
3 The name property sets the unique name of this component. It is used to store configuration in the filesystem, to identify the component inside Apache Felix Web Console, and so on. Configure a human-readable name in the form [nature].[vendor].[product].
4 The immediate property defines whether the component should be started immediately. Configure the Component to be started immediately after configuration, i.e. it is not waiting till its service is required by another Component.
5 The configurationPolicy define that the configuration of the Component is required before it gets activated.
6 To ease the implementation of a Modbus device we can extend the AbstractOpenemsModbusComponent class.
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.
7 The class implements OpenemsComponent. This makes it an OpenEMS Component. 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.
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.
8 The simulated implementation is only going to provide Channels defined by OpenemsComponent and SymmetricMeter natures. It is still good practice to add a skeleton for custom Channels to the Component implementation. We therefor add the Channel Declaration block inside the class.
  • Channel declarations are enum types implementing the ChannelId interface.

  • This enum is empty, as we do not have custom Channels here.

  • 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)

9 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.
10 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.
11 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.
12 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.
13 The deactivate() method (marked by the @Deactivate annotation) is called on deactivation of the Component instance.
14 AbstractOpenemsModbusComponent requires to implement a defineModbusProtocol() method that returns an instance of ModbusProtocol. The ModbusProtocol class maps Modbus addresses to OpenEMS Channels and provides some conversion utilities. Instantiation of a ModbusProtocol object uses the Builder pattern
15 Creates a new ModbusProtocol instance. A reference to the component itself is the first parameter, followed by an arbitrary number of 'Tasks' (implemented as a Java varags array).
16 FC3ReadRegistersTask is an implementation of Modbus function code 3 "Read Holding Registers" . 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.
Most Modbus function codes are available by their respective FC* implementation classes.
17 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.
  • The m() method also takes an instance of ElementToChannelConverter as an additional parameter. It can be used to add implicit unit conversions between Modbus element and OpenEMS Channel - like adding a scale factor that converts a read value of '95' to a channel value of '950'.

  • For Modbus registers that are empty or should be ignored, the DummyRegisterElement can be used.

  • 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.

    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. <18> The SymmetricMeter Nature requires us to provide a MeterType via a MeterType getMeterType() method. The MeterType is provided by the Config. <19> 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.

1.5. Start the device simulator

To start the device simulator, open the io.openems.edge.bridge.modbus project and navigate to the testio.openems.edge.brige.modbus folder. There you find the ModbusSlaveSimulator.java file. Right-click that file and select Run AsJava Application.

This ModbusSlaveSimulator runs a small Modbus-TCP Slave-Server, that provides some constant values:

Address

Constant value

1000

500

1001

100

2000

123

In the end of this guide, you will see a production of '500 W' - where '500' comes from register address 1000.

1.6. Enable the Component

To enable the Component for running, open the io.openems.edge.application project and open the EdgeApp.bndrun file.

Eclipse IDE EdgeApp.bndrun
Figure 10. Eclipse IDE EdgeApp.bndrun

Select the io.openems.edge.meter.simulated bundle in the left Repositories list and drag & drop it to the Run Requirements list.

Click on Resolve to update the list of bundles that are required to run OpenEMS Edge. After a few seconds the Resolution Results window should appear; acknowledge by pressing Finish.

Eclipse IDE Resolve EdgeApp.bndrun
Figure 11. Eclipse IDE Resolve EdgeApp.bndrun

These steps changed the content of the 'EdgeApp.bndrun' file. You can observe the changes inside the Source tab:

  • The drag & drop caused a new line to be added under -runrequires: \:

    bnd.identity;id='io.openems.edge.meter.simulated'

  • Resolving updated the -runbundles: \ list by adding the line:

    io.openems.edge.meter.simulated;version='[1.0.0,1.0.1)'

The \ at the end of each line is required to announce bndtools that the definition still continues on the next line.

Also you may have found, that the existing entries are sorted alphabetically.

Now switch back to Run view.

1.7. Run the implementation

Press Run OSGi to run OpenEMS Edge.

From then you can configure your component as shown in Getting Started guide. Add the following configurations inside Apache Felix Web Console:

Controller Debug Log
  • ID: ctrlDebugLog0

  • Enabled: checked

Scheduler All Alphabetically
  • ID: scheduler0

  • Enabled: checked

  • Cycle time: 1000

Bridge Modbus/TCP
  • ID: modbus0

  • IP-Address: localhost

  • Enabled: checked

Meter Simulated
  • ID: meter0

  • Enabled: checked

  • Meter-Type: PRODUCTION

  • Modbus-ID: modbus0

  • Modbus Unit-ID: 1

In the Eclipse IDE console log you should see an output like this:

2020-01-20 13:32:12,095 [re.Cycle] INFO  [e.controller.debuglog.DebugLog] [ctrlDebugLog0] _sum[State:Ok Production:500 W Consumption:500 W] meter0[L:500 W]

It shows a Production of 500 W which is what is provided by the simulated meter device. Congrats!

1.8. Debug the implementation

If you experience any errors you can always run OpenEMS Edge using the Debug OSGi button in EdgeApp.bndrun. This allows you to stop code execution at any time using Breakpoints.