Merge branch 'release/2023.4.0'

.github/workflows/build.yml

@@ -6,11 +6,11 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - name: Setup Java 11
+      - name: Setup Java 17
         uses: actions/setup-java@v3
         with:
           distribution: 'temurin'
-          java-version: '11'
+          java-version: '17'
           java-package: jdk
 
       - name: Setup Cache for Java/Gradle

.github/workflows/docs.yml

@@ -10,6 +10,13 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
+      - name: Setup Java 17
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+          java-package: jdk
+
       - name: Setup Cache for Java/Gradle
         uses: actions/cache@v3
         with:

.gitpod.Dockerfile

@@ -1,7 +1,7 @@
 FROM gitpod/workspace-postgres
 
 RUN bash -c ". /home/gitpod/.sdkman/bin/sdkman-init.sh \
-             && sdk install java 11.0.13-tem"
+             && sdk install java 17.0.6-tem"
 
 # disable angular analytics
 ENV NG_CLI_ANALYTICS=false

.gradle-wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.0.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.0.2-bin.zip
 networkTimeout=10000
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

cnf/build.bnd

@@ -74,5 +74,5 @@ testpath: \
 	Edge_Timedata;member=${filter;${p};io\.openems\.edge\.timedata\..*},\
 	Edge_TimeOfUseTariff;member=${filter;${p};io\.openems\.edge\.timeofusetariff\..*},\
 
-javac.source: 11
-javac.target: 11
+javac.source: 17
+javac.target: 17

cnf/pom.xml

@@ -1,12 +1,9 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 	<modelVersion>4.0.0</modelVersion>
-
 	<groupId>local</groupId>
 	<artifactId>central</artifactId>
 	<version>0.0.0</version>
-
 	<packaging>pom</packaging>
-
 	<dependencies>
 		<!-- biz -->
 		<dependency>
@@ -190,32 +187,40 @@
 			<artifactId>org.apache.felix.eventadmin</artifactId>
 			<version>1.6.4</version>
 		</dependency>
+		<dependency>
+			<!-- Apache Felix File Install -->
+			<!-- Changelog: https://github.com/apache/felix-dev/blob/master/fileinstall/doc/changelog.txt -->
+			<groupId>org.apache.felix</groupId>
+			<artifactId>org.apache.felix.fileinstall</artifactId>
+			<version>3.7.4</version>
+		</dependency>
 		<dependency>
 			<!-- Apache Felix Framework -->
 			<!-- Changelog: https://github.com/apache/felix-dev/blob/master/framework/doc/changelog.txt -->
 			<groupId>org.apache.felix</groupId>
 			<artifactId>org.apache.felix.framework</artifactId>
 			<version>7.0.5</version>
 		</dependency>
-		<dependency>
-			<!-- Apache Felix Inventory -->
-			<!-- Changelog: https://github.com/apache/felix-dev/blob/master/inventory/changelog.txt -->
-			<groupId>org.apache.felix</groupId>
-			<artifactId>org.apache.felix.inventory</artifactId>
-			<version>1.1.0</version>
-		</dependency>
 		<dependency>
 			<!-- Apache Felix HTTP Service -->
 			<!-- Changelog: https://github.com/apache/felix-dev/commits/master/http -->
 			<groupId>org.apache.felix</groupId>
 			<artifactId>org.apache.felix.http.jetty</artifactId>
-			<version>4.2.2</version>
+			<version>5.0.4</version>
 		</dependency>
 		<dependency>
+			<!-- Apache Felix Servlet API -->
 			<groupId>org.apache.felix</groupId>
 			<artifactId>org.apache.felix.http.servlet-api</artifactId>
 			<version>2.1.0</version>
 		</dependency>
+		<dependency>
+			<!-- Apache Felix Inventory -->
+			<!-- Changelog: https://github.com/apache/felix-dev/blob/master/inventory/changelog.txt -->
+			<groupId>org.apache.felix</groupId>
+			<artifactId>org.apache.felix.inventory</artifactId>
+			<version>1.1.0</version>
+		</dependency>
 		<dependency>
 			<!-- Apache Felix Metatype Service -->
 			<!-- Changelog: https://github.com/apache/felix-dev/blob/master/metatype/changelog.txt -->
@@ -254,12 +259,12 @@
 			<!-- Changelog: https://github.com/typetools/checker-framework/blob/master/docs/CHANGELOG.md -->
 			<groupId>org.checkerframework</groupId>
 			<artifactId>checker-qual</artifactId>
-			<version>3.31.0</version>
+			<version>3.32.0</version>
 		</dependency>
 		<dependency>
 			<groupId>org.dhatim</groupId>
 			<artifactId>fastexcel</artifactId>
-			<version>0.14.18</version>
+			<version>0.15.2</version>
 		</dependency>
 		<dependency>
 			<!-- Eclipse Paho MQTTv5 Client -->
@@ -270,22 +275,22 @@
 		<dependency>
 			<groupId>com.influxdb</groupId>
 			<artifactId>influxdb-client-java</artifactId>
-			<version>6.7.0</version>
+			<version>6.8.0</version>
 		</dependency>
 		<dependency>
 			<groupId>com.influxdb</groupId>
 			<artifactId>influxdb-client-core</artifactId>
-			<version>6.7.0</version>
+			<version>6.8.0</version>
 		</dependency>
 		<dependency>
 			<groupId>com.influxdb</groupId>
 			<artifactId>influxdb-client-utils</artifactId>
-			<version>6.7.0</version>
+			<version>6.8.0</version>
 		</dependency>
 		<dependency>
 			<groupId>com.influxdb</groupId>
 			<artifactId>flux-dsl</artifactId>
-			<version>6.7.0</version>
+			<version>6.8.0</version>
 		</dependency>
 		<dependency>
 			<groupId>org.java-websocket</groupId>
@@ -295,7 +300,7 @@
 		<dependency>
 			<groupId>org.jetbrains.kotlin</groupId>
 			<artifactId>kotlin-osgi-bundle</artifactId>
-			<version>1.8.10</version>
+			<version>1.8.20</version>
 		</dependency>
 		<dependency>
 			<groupId>org.jetbrains.kotlinx</groupId>
@@ -387,7 +392,7 @@
 			<!-- Used by io.openems.backend.metadata.odoo -->
 			<groupId>org.postgresql</groupId>
 			<artifactId>postgresql</artifactId>
-			<version>42.5.4</version>
+			<version>42.6.0</version>
 		</dependency>
 		<dependency>
 			<!-- Used by com.influxdb: influxdb -->

doc/modules/ROOT/pages/backend/build.adoc

@@ -9,7 +9,7 @@
 :icons: font
 :imagesdir: ../../assets/images
 
-This chapter explains, how OpenEMS Edge can be compiled to a JAR file that can be executed outside of an IDE.
+This chapter explains, how the OpenEMS Backend can be compiled to a JAR file that can be executed outside of an IDE.
 
 == Build using Eclipse IDE
 
@@ -31,4 +31,8 @@ link:https://gradle.org/[Gradle] is a build tool that is used in the OpenEMS pro
 
 . Open a console and change to your repository directory.
 
-. Execute `gradlew buildBackend`
+. Execute `gradlew buildBackend`
+
+=== Building only a specific project
+
+If developing a component for the backend, it might make sense to only build the component in isolation instead of the entire backend (same applies to the Edge). This can be achieved by executing `gradlew :io.openems.backend.metadata.mymetadata:build`, which produces a JAR file.

doc/modules/ROOT/pages/contribute/coding-guidelines.adoc

@@ -26,7 +26,7 @@
 * Use precise naming for methods/functions
 * Use narrow scopes for variables; avoid class variables
 * Split code in Interface, Implementation(..Impl) and Config files
-* Use modern Java 11 syntax (e.g. 'var' keyword, streams, etc.)
+* Use modern Java 17 syntax (e.g. 'var' keyword, streams, etc.)
 * Add readme.adoc to a new bundle
 * Review data in bnd.bnd file
 * Format all files via Eclipse Autoformat, organize Imports, apply Checkstyle suggestions (see below)

doc/modules/ROOT/pages/edge/implement.adoc

@@ -67,7 +67,7 @@ image::eclipse-new-simulatedmeter-bundle.png[New simulated meter OpenEMS Modbus
 ====
 You can see, that the Bundle is by default dependent on some core bundles
 
-$\{buildpath\}:: 
+$\{buildpath\}::
   applies some defaults defined in `/cnf/build.bnd`
 io.openems.common::
   OpenEMS commons
@@ -114,7 +114,7 @@ NOTE: The `;version=latest` declaration is not required and can be removed. Also
 
 === 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 xref:gettingstarted.adoc[Getting Started]).  
+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 xref:gettingstarted.adoc[Getting Started]).
 
 . Open the btn:[Config.java] file inside `src/io.openems.edge.meter.simulated` by double clicking on it.
 
@@ -154,7 +154,7 @@ import io.openems.edge.meter.api.MeterType;
 
 	@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>
 
@@ -374,13 +374,13 @@ NOTE: In plain Java it is not required to add `implements OpenemsComponent` if w
 - 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)`
 ====
-<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. 
+<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.
 <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.
 <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.
 <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.
 <12> The *deactivate()* method (marked by the *@Deactivate* annotation) is called on deactivation of the Component instance.
-<13> _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 https://en.wikipedia.org/wiki/Builder_pattern#Java[Builder pattern icon:external-link[]] 
-<14> 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).  
+<13> _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 https://en.wikipedia.org/wiki/Builder_pattern#Java[Builder pattern icon:external-link[]]
+<14> 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).
 <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*.
 +
 NOTE: Most Modbus function codes are available by their respective _FC*_ implementation classes.
@@ -389,7 +389,7 @@ NOTE: Most Modbus function codes are available by their respective _FC*_ impleme
 [NOTE]
 ====
 - 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 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.
@@ -433,7 +433,7 @@ image::eclipse-edgeapp-bndrun.png[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.
 
-Press btn:[Ctrl] + btn:[s] to save the `EdgeApp.bndrun` file. 
+Press btn:[Ctrl] + btn:[s] to save the `EdgeApp.bndrun` file.
 
 Click on btn:[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 btn:[Finish].
 
@@ -453,14 +453,14 @@ These steps changed the content of the 'EdgeApp.bndrun' file. You can observe th
 
 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. 
+Also you may have found, that the existing entries are sorted alphabetically.
 
 Now switch back to btn:[Run] view.
 ====
 
 === Run the implementation
 
-Press btn:[Run OSGi] to run OpenEMS Edge. 
+Press btn:[Run OSGi] to run OpenEMS Edge.
 
 From then you can configure your component as shown in xref:gettingstarted.adoc[Getting Started] guide. Add the following configurations inside Apache Felix Web Console:
 
@@ -493,4 +493,16 @@ It shows a Production of `500 W` which is what is provided by the simulated mete
 
 === Debug the implementation
 
-If you experience any errors you can always run OpenEMS Edge using the btn:[Debug OSGi] button in EdgeApp.bndrun. This allows you to stop code execution at any time using https://help.eclipse.org/2019-12/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Ftasks%2Ftask-add_line_breakpoints.htm[Breakpoints].
+If you experience any errors you can always run OpenEMS Edge using the btn:[Debug OSGi] button in EdgeApp.bndrun. This allows you to stop code execution at any time using https://help.eclipse.org/2019-12/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Ftasks%2Ftask-add_line_breakpoints.htm[Breakpoints].
+
+=== Alternative Device Development Flow
+
+Instead of adding the device to the btn:[EdgeApp.bndrun] file (as described in xref:implement.adoc#_enable_the_component[Enable the Component]), the device can be loaded dynamically by using [Apache Felix File Install]. Copying the device's built jar file into a `load` folder, relative to the project's root directory. Apache Felix File Install watches this folder and handles the device automatically.
+
+The folder is configurable by supplying the `felix.fileinstall.dir` option when starting the edge app. More configuration options can be found in the https://felix.apache.org/documentation/subprojects/apache-felix-file-install.html[Apache Felix File Install documentation].
+
+[NOTE]
+This functionality can also be used in production environments albeit dynamic code loading without additional safety measures is not recommended.
+
+[NOTE]
+Same applies to the OpenEMS Backend for dynamically loading devices.

doc/modules/ROOT/pages/gettingstarted.adoc

@@ -42,7 +42,7 @@ NOTE: OpenEMS uses the **git** version control system via the popular GitHub pla
 NOTE: Eclipse IDE is the recommended development environment for newcomers to OpenEMS. If you are more familiar with IntelliJ IDEA, feel free to use it. Follow xref:intellij.adoc[this guide].
 
 . Prepare Eclipse IDE
-.. Download Java Development Kit (JDK) 11 and install it. We recommend the https://adoptium.net/?variant=openjdk11&jvmVariant=hotspot[OpenJDK Temurin builds by the Adoptium project]
+.. Download Java Development Kit (JDK) 17 and install it. We recommend the https://adoptium.net/de/temurin/releases/?version=17[OpenJDK Temurin builds by the Adoptium project]
 .. Download https://www.eclipse.org[Eclipse for Java icon:external-link[]], install and start it
 .. On first start you will get asked to create a workspace.
 Select your source code directory (`C:\Users\your.user\git\openems` in our example) and press btn:[Launch].
@@ -54,15 +54,15 @@ image::eclipse-workspace.png[Creating a workspace in Eclipse IDE]
 +
 Menu: btn:[Help] → btn:[Eclipse Marketplace...] → btn:[Find:] → enter btn:[Bndtools] → press btn:[Install]
 
-.. Configure Eclipse IDE to use JDK 11.
+.. Configure Eclipse IDE to use JDK 17.
 +
 - In the Menu select btn:[Windows] → btn:[Preferences]
 - Select btn:[Java] - btn:[Installed JREs] in the navigation tree
 - Press the btn:[Add...] button
 - Keep btn:[Standard VM] selected and press btn:[Next >]
-- Press the btn:[Directory...] button and select the folder of the installed JDK (e.g. `C:\Program Files\Eclipse Adoptium\jdk-11.0.13.8-hotspot`)
+- Press the btn:[Directory...] button and select the folder of the installed JDK (e.g. `C:\Program Files\Eclipse Adoptium\jdk-17.0.6.10-hotspot`)
 - Press the btn:[Finish] button
-- Back in the Preferences window, tick the newly added JDK 11 and press btn:[Apply and Close]
+- Back in the Preferences window, tick the newly added JDK 17 and press btn:[Apply and Close]
 +
 .Creating a workspace in Eclipse IDE
 image::eclipse-select-jdk.png[Set the Java Development Kit in Eclipse IDE]

doc/modules/ROOT/pages/intellij.adoc

@@ -49,6 +49,34 @@ image::intellij-new-module.png[]
 Rightclick on an existing module: New -> Module
 +
 Amdatu-> Project Template Project (Stringtemplate)
++
+.. add Support for Eclipse Code Formatting
++
+Search for 'Adapter for Eclipse Code Formatter' in the Plugin store
++
+.download Adapter for Eclipse Code Formatter
+image::intellij-code-formatter.png[]
++
+After restarting the IDE go to Settings -> Other Settings -> Adapter for Eclipse Code Formatter
++
+.Adapter Settings
+image::intellij-code-formatter-settings.png[]
++
+Check the radiobutton for "Use Eclipse's Code Formatter"
++
+.Enable Adapter
+image::intellij-code-formatter-enable.png[]
++
+Type in your Eclipse installation folder
++
+.Set Eclipse Path
+image::intellij-code-formatter-path.png[]
++
+Choose 'Eclipse [built-in]' as a formatter config
++
+.Choose Format
+image::intellij-code-formatter-format.png[]
+Now Reformat Code will use the Eclipse format (e.g. Use TAB instead of Whitespaces)
 
 == Hints - intellij problems
 .. If you have some problems - for example java version is not found: look in File -> Project Structure -> Project