Merge branch 'release/2021.4.0'

.github/workflows/build.yml

@@ -0,0 +1,59 @@
+name: Build OpenEMS
+on: [push]
+jobs:
+  build-code:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup Java 8
+        uses: actions/setup-java@v1
+        with:
+          java-version: '8'
+
+      - name: Setup Cache for Java/Gradle
+        uses: actions/cache@v2
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: ${{ runner.os }}-gradle-
+
+      - name: Setup Cache for Java/Maven
+        uses: actions/cache@v2
+        with:
+          path: ~/.m2/repository
+          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+          restore-keys: |
+            ${{ runner.os }}-maven-
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: '14'
+
+      - name: Setup Cache for Node.js
+        uses: actions/cache@v2
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: ${{ runner.os }}-node-
+
+      - name: Build all Java packages
+        run: ./gradlew build
+
+      - name: Resolve OpenEMS Backend bundles
+        run: ./gradlew resolve.BackendApp
+
+      - name: Validate BackendApp.bndrun
+        run: git diff --exit-code io.openems.backend.application/BackendApp.bndrun
+
+      - name: Resolve OpenEMS Edge bundles
+        run: ./gradlew resolve.EdgeApp
+
+      - name: Validate EdgeApp.bndrun
+        run: git diff --exit-code io.openems.edge.application/EdgeApp.bndrun
+
+      - name: Build OpenEMS UI
+        run: ./gradlew buildUiForEdge --continue

.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Build Docs
+on:
+  push:
+    branches:
+      - develop
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Build Javadocs
+        run: ./gradlew buildAggregatedJavadocs --continue
+
+      - name: Build Antora-docs for openems.io
+        run: ./gradlew buildAntoraDocs --continue
+
+      - name: Deploy to GitHub pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          personal_token: ${{ secrets.DOCS }}
+          external_repository: OpenEMS/openems.io
+          publish_branch: master
+          publish_dir: build/www

.gitpod.Dockerfile

@@ -6,4 +6,7 @@ RUN bash -c ". /home/gitpod/.sdkman/bin/sdkman-init.sh \
 # disable angular analytics
 ENV NG_CLI_ANALYTICS=false
 
+# Docker build does not rebuild an image when a base image is changed, increase this counter to trigger it.
+ENV TRIGGER_REBUILD 3
+
 RUN npm install -g @angular/cli 

.gradle-wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-6.8-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-6.8.3-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

README.md

@@ -1,4 +1,4 @@
-[![Build Status](https://www.travis-ci.com/OpenEMS/openems.svg?branch=develop)](https://www.travis-ci.com/OpenEMS/openems)
+[![Build Status](https://github.com/OpenEMS/openems/actions/workflows/build.yml/badge.svg)](https://github.com/OpenEMS/openems/actions/workflows/build.yml)
 [![Gitpod live-demo](https://img.shields.io/badge/Gitpod-live--demo-blue?logo=gitpod)](https://gitpod.io/#https://github.com/OpenEMS/openems/tree/master)
 [![Cite via Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.4440884.svg)](https://doi.org/10.5281/zenodo.4440883)
 

build.gradle

@@ -69,6 +69,7 @@ task buildAggregatedJavadocs(type: Javadoc, description: 'Generate javadocs from
     title = "OpenEMS Javadoc"
     subprojects.each { proj ->
         proj.tasks.withType(Javadoc).each { javadocTask ->
+            options.addStringOption('Xdoclint:none', '-quiet')
             source += javadocTask.source
             classpath += javadocTask.classpath
             excludes += javadocTask.excludes

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">

cnf/pom.xml

@@ -81,7 +81,7 @@
 			<!-- HikariCP A solid, high-performance, JDBC connection pool at last. -->
 			<groupId>com.zaxxer</groupId>
 			<artifactId>HikariCP</artifactId>
-			<version>4.0.1</version>
+			<version>4.0.2</version>
 		</dependency>
 		<!-- commons -->
 		<dependency>
@@ -106,7 +106,7 @@
 			<!-- Used by SDNotify -->
 			<groupId>net.java.dev.jna</groupId>
 			<artifactId>jna</artifactId>
-			<version>5.6.0</version>
+			<version>5.7.0</version>
 		</dependency>
 		<!-- org -->
 		<dependency>
@@ -211,12 +211,12 @@
 		<dependency>
 			<groupId>org.ops4j.pax.logging</groupId>
 			<artifactId>pax-logging-api</artifactId>
-			<version>2.0.6</version>
+			<version>2.0.8</version>
 		</dependency>
 		<dependency>
 			<groupId>org.ops4j.pax.logging</groupId>
 			<artifactId>pax-logging-log4j1</artifactId>
-			<version>2.0.6</version>
+			<version>2.0.8</version>
 		</dependency>
 		<dependency>
 			<groupId>org.osgi</groupId>
@@ -237,7 +237,7 @@
 			<!-- Used by io.openems.backend.metadata.odoo -->
 			<groupId>org.postgresql</groupId>
 			<artifactId>postgresql</artifactId>
-			<version>42.2.18</version>
+			<version>42.2.19</version>
 		</dependency>
 		<dependency>
 			<!-- Used by io.openems.edge.timedata.rrd4j -->

doc/modules/ROOT/nav.adoc

@@ -13,10 +13,10 @@
 ** xref:edge/build.adoc[Build OpenEMS Edge]
 ** xref:edge/deploy.adoc[Deploy OpenEMS Edge]
 * OpenEMS UI
+** xref:ui/architecture.adoc[Architecture]
 ** xref:ui/build.adoc[Build OpenEMS UI]
 * OpenEMS Backend
 ** xref:backend/architecture.adoc[Architecture]
-** xref:backend/configuration.adoc[Configuration]
 ** xref:backend/backend-to-backend.adoc[Backend-to-Backend]
 ** xref:backend/build.adoc[Build OpenEMS Backend]
 ** xref:backend/deploy.adoc[Deploy OpenEMS Backend]

doc/modules/ROOT/pages/component-communication/index.adoc

@@ -9,22 +9,163 @@
 :imagesdir: ../../assets/images
 
 
-This page describes the internal communication protocol between OpenEMS Edge, OpenEMS Backend and OpenEMS UI. The components keep an open https://de.wikipedia.org/wiki/WebSocket[Websocket] connection which is used for bi-directional communication. The protocol is based on https://www.jsonrpc.org/specification[JSON-RPC]. For details about JSON-RPC please refer to the specification. As a rough summary, the protocol is divided into
+This page describes the internal communication protocol between OpenEMS Edge, OpenEMS Backend and OpenEMS UI. The components keep an open https://de.wikipedia.org/wiki/WebSocket[Websocket] connection which is used for bi-directional communication. 
 
-JSON-RPC Request::
-  Identified by a unique ID and method name with specific params. Expects a Response.
+== JSON-RPC introduction
 
-JSON-RPC Success Response::
-  Referring to the ID of the Request, providing a result which can be empty or hold specific data.
+The protocol is based on https://www.jsonrpc.org/specification[JSON-RPC]. For details about JSON-RPC please refer to the specification. As a rough summary, the protocol is divided into
 
-JSON-RPC Error Response::
-  Referring to the ID of the Request, providing error code, message and optionally data.
+=== JSON-RPC Request
 
-JSON-RPC Notification::
-  Identified by a unique method name with specific params. Does not expect a Response.
+Identified by a unique ID and method name with specific params. Expects a Response.
+
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "id": UUID,
+  "method": "method",
+  "params": {}
+}
+----
+
+=== JSON-RPC Success Response
+
+Referring to the ID of the Request, providing a result which can be empty or hold specific data.
+
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "id": UUID,
+  "result": {}
+}
+----
+
+=== JSON-RPC Error Response
+
+Referring to the ID of the Request, providing error code, message and optionally data.
+
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "id": UUID,
+  "result": {
+    "code": number,
+    "message": string,
+    "data"?: {}
+  }
+}
+----
+
+=== JSON-RPC Notification
+
+Identified by a unique method name with specific params. Does not expect a Response.
+
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "method": "method",
+  "params": {}
+}
+----
+
+== Example communication messages
 
 The information on this page is useful to understand the internal communication structure and can help if your plan is to replace one component by a custom implementation, e.g. implementing your own frontend application, or if you plan to extend the provided feature-set.
 
+== Subscribe Channels
+
+Real-time channel data may change at a high rate. Instead of requiring the consumer to constantly pull the data, the OpenEMS API provides a publish-subscribe schema that notifies the consumer about updated values. It is initiated via a JSON-RPC request:
+
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "id": UUID,
+  "method": "subscribeChannels",
+  "params": {
+    "count": number,
+    "channels": string[]
+  }
+}
+----
+
+The parameters for subscribing to channel data are:
+
+- `count`: a request count value that needs to be increased on each request to avoid concurrency problems
+- `channels`: a list of channel addresses as strings, e.g. "ess0/Soc", "ess0/ActivePower"
+
+From then on, the API constantly keeps sending `currentData` JSON-RPC notifications, containing the data for all subscribed channels:
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "method": "currentData",
+  "params": {
+    [channelAddress]: string | number
+  }
+}
+----
+
+To unsubscribe from channels, a new `subscribeChannels` request has to be sent with an empty list of channels.
+
+
+== Edge-RPC
+
+When using the API via OpenEMS Backend, it is possible to transparently target a specific OpenEMS Edge, that is connected to the Backend by wrapping the JSON-RPC request into an `Edge-RPC` request:
+
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "id": UUID,
+  "method": "edgeRpc",
+  "params": {
+    "edgeId": string,
+    "payload": JSON-RPC-Request
+  }
+}
+----
+
+The parameters for an “edgeRpc” request are:
+
+- `edgeId`: the unique ID of the Edge at the Backend
+- `payload`: the JSON-RPC Request that should be forwarded to the Edge, e.g. `getEdgeConfig` or `updateComponentConfig`.
+
+The JSON-RPC response then also wraps the original result as a payload:
+
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "id": UUID,
+  "result": {
+    "payload": JSON-RPC-Response
+  }
+}
+----
+
+==	JsonApi Component
+
+To directly send a JSON-RPC request to one specific OpenEMS Component, that component has to implement the `JsonApi` interface.
+Then the `componentJsonApi` request can be used to wrap a JSON-RPC request as payload:
+
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "id": "UUID",
+  "method": "componentJsonApi",
+  "params": {
+    "componentId": string,
+    "payload": JSON-RPC-Request
+  }
+}
+----
+
 == Authenticate UI to Edge/Backend using token
 
 NOTE: On opening of the websocket connection to Edge/Backend, the UI is authenticated using an existing token.