From 7264031099e0f0d6b73eceb4020edae38e9a1a87 Mon Sep 17 00:00:00 2001
From: Jochen Zink <jochen.zink@jnk-consulting.de>
Date: Sun, 18 Feb 2024 14:01:03 +0100
Subject: [PATCH] Deployed b30bee5 with MkDocs version: 1.5.2

---
 about/release-notes/index.html |  22 ++++++++++++++++++++++
 search/search_index.json       |   2 +-
 sitemap.xml.gz                 | Bin 365 -> 365 bytes
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/about/release-notes/index.html b/about/release-notes/index.html
index fbcb94d1..6023024d 100644
--- a/about/release-notes/index.html
+++ b/about/release-notes/index.html
@@ -772,6 +772,13 @@
     </label>
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
+        <li class="md-nav__item">
+  <a href="#version-230-2024-02-18" class="md-nav__link">
+    Version 2.3.0 (2024-02-18)
+  </a>
+  
+</li>
+      
         <li class="md-nav__item">
   <a href="#version-222-2024-02-07" class="md-nav__link">
     Version 2.2.2 (2024-02-07)
@@ -849,6 +856,13 @@
     </label>
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
+        <li class="md-nav__item">
+  <a href="#version-230-2024-02-18" class="md-nav__link">
+    Version 2.3.0 (2024-02-18)
+  </a>
+  
+</li>
+      
         <li class="md-nav__item">
   <a href="#version-222-2024-02-07" class="md-nav__link">
     Version 2.2.2 (2024-02-07)
@@ -903,6 +917,14 @@
 
 
 <h1 id="release-notes">Release Notes<a class="headerlink" href="#release-notes" title="Permanent link">&para;</a></h1>
+<h2 id="version-230-2024-02-18">Version 2.3.0 (2024-02-18)<a class="headerlink" href="#version-230-2024-02-18" title="Permanent link">&para;</a></h2>
+<ul>
+<li><a href="https://github.com/jnk-cons/easy-rscp/issues/32">#32</a>) Add missing WallBox Tags</li>
+<li>Added a bunch of Tags to WB and EMS Namespace</li>
+<li><a href="https://github.com/jnk-cons/easy-rscp/issues/34">#34</a>) Extend services with wallbox live data</li>
+<li>DefaultLiveDataService returns the complete wallbox consumption and the solar share</li>
+<li>New DefaultWallboxService to query the connected wallboxes and read the live data for each</li>
+</ul>
 <h2 id="version-222-2024-02-07">Version 2.2.2 (2024-02-07)<a class="headerlink" href="#version-222-2024-02-07" title="Permanent link">&para;</a></h2>
 <ul>
 <li><a href="https://github.com/jnk-cons/easy-rscp/issues/30">#30</a>) Battery status contains the incorrect volt and temperature values per cell</li>
diff --git a/search/search_index.json b/search/search_index.json
index d61870f9..6e377057 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"easy-rscp","text":"<p>easy-rscp is an INOFFICIAL library written in Kotlin (fully Java compatible) for accessing E3DC home power plants.</p> <p>E3DC is a brand of HagerEnergy Gmbh (website). I have nothing to do with the company, except that I own a home power plant from E3DC and wanted to include it in my SmartHome. This \"desire\" gave birth to easy-rscp. </p>"},{"location":"#what-is-easy-rscp","title":"What is easy-rscp?","text":"<p>E3DC's home power plants offer a TCP/IP interface for read and write access. The protocol used for the content is proprietary and is called RSCP. The RSCP structure is well documented by E3DC, but in terms of content there is almost no documentation at all. In addition, the documentation is incomplete, partly incorrect and not publicly available. The E3DC service portal, to which every customer has access, contains the RSCP documentation. easy-rscp and this documentation have the goal to make RSCP more easily accessible for the open source world.</p>"},{"location":"#what-do-i-get","title":"What do I get?","text":""},{"location":"#as-a-kotlin-developer","title":"As a Kotlin developer","text":"<p>A library written entirely in Kotlin to access home power plants from E3DC. Easy to use, well documented -&gt; Have fun.</p>"},{"location":"#as-a-java-developer","title":"As a Java developer","text":"<p>Basically the same as a Kotlin developer. The bytecode is Java compatible and in the examples you can choose between Kotlin and Java. </p> <p>Small disadvantage for you (besides the Java syntax, but you should be used to that), as a dependency smaller Kotlin libraries will be necessary.</p>"},{"location":"#as-ja-typescript-or-javascript-developer","title":"As ja TypeScript or JavaScript developer","text":"<p>You will find what you are looking for in the sister project easy-rscp-js. The core functionality is identical. The documentation of both projects is summarized here.</p>"},{"location":"#as-xyz-developer","title":"As XYZ Developer","text":"<p>Ok, you can't use the library directly. But in the course of the project this documentation was created. Especially the chapter RSCP should be interesting for you. Here you find a description of the RSCP protocol and all tags and meanings known to me. Maybe this will help you.</p>"},{"location":"#where-do-i-start","title":"Where do I start?","text":"<p>Best in the Getting started section.</p>"},{"location":"#can-i-participate","title":"Can I participate","text":"<p>Absolutely!</p>"},{"location":"#i-have-found-a-bug","title":"I have found a bug","text":"<p>Too bad, but that can happen. Create a new Bug and we'll take a look.</p> <p>You already know the solution? Very cool! Post a PR and we'll bring it to the main branch.</p>"},{"location":"#i-have-cool-extensions-improvements-fixes","title":"I have cool extensions, improvements fixes","text":"<p>The best thing to do is to create a PR.</p> <p>You can also participate in the project as a maintainer. Create a ticket here and we will see how you can support best.</p>"},{"location":"#i-have-further-knowledge-about-the-rscp-protocol","title":"I have further knowledge about the RSCP protocol","text":"<p>Every drop helps to decode this protocol completely. You can create a PR for the doc, or create a ticket. </p> <p>If you want to describe a specific RSCP tag, it is best to go to the API description and the corresponding tag class. At each entry you will find a link to create a ticket for exactly this tag.</p>"},{"location":"#special-thanks","title":"Special thanks","text":"<p>The RSCP protocol is virtually undocumented and there is no help available from E3DC. This library would not have been possible without numerous other projects. I would like to highlight two projects and two people in particular.</p> <p>First of all, a big \"thank you\" to Stefan. The developer of the incredible iOS my4E. Although he himself had no benefit from answering my questions about the RSCP protocol, he did it anyway and was a great help! Not a matter of course.</p> <p>A lot of inspiration and also help in understanding the RSCP protocol came from Uli. The developer of the E3DC plugin for ioBroker. Many thanks for the support.</p>"},{"location":"#license","title":"License","text":"<p>The library is licensed under the MIT License. License</p>"},{"location":"about/license/","title":"License","text":""},{"location":"about/license/#_1","title":"License","text":"<pre><code>MIT License\n\nCopyright (c) 2023 Jochen Zink\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n</code></pre>"},{"location":"about/license/#included-projects","title":"Included projects","text":""},{"location":"about/license/#this-documentation","title":"This documentation","text":"<p>This documentation was created using the great MkDocs tool and the wonderful Material for MkDocs theme:</p> <ul> <li>MkDocs - Project - View license</li> <li>Material for MkDocs - Project - View license</li> </ul>"},{"location":"about/license/#the-easy-rscp-library","title":"The easy rscp library","text":"<p>Without all the work of many, many OpenSource developers, this library would not have been possible. Many thanks to the authors of these fantastic projects:</p> <pre><code>Lists of 30 third-party dependencies.\n     (The Apache Software License, Version 2.0) kotlin-logging (io.github.microutils:kotlin-logging-jvm:3.0.5 - https://github.com/oshai/kotlin-logging)\n     (Apache License, Version 2.0) MockK Agent API (io.mockk:mockk-agent-api-jvm:1.13.9 - https://mockk.io)\n     (Apache License, Version 2.0) MockK (io.mockk:mockk-agent-jvm:1.13.9 - https://mockk.io)\n     (Apache License, Version 2.0) MockK Core (io.mockk:mockk-core-jvm:1.13.9 - https://mockk.io)\n     (Apache License, Version 2.0) MockK DSL (io.mockk:mockk-dsl-jvm:1.13.9 - https://mockk.io)\n     (Apache License, Version 2.0) MockK (io.mockk:mockk-jvm:1.13.9 - https://mockk.io)\n     (Eclipse Public License 1.0) JUnit (junit:junit:4.13.2 - http://junit.org)\n     (Apache License, Version 2.0) Byte Buddy (without dependencies) (net.bytebuddy:byte-buddy:1.14.6 - https://bytebuddy.net/byte-buddy)\n     (Apache License, Version 2.0) Byte Buddy agent (net.bytebuddy:byte-buddy-agent:1.14.6 - https://bytebuddy.net/byte-buddy-agent)\n     (The Apache License, Version 2.0) org.apiguardian:apiguardian-api (org.apiguardian:apiguardian-api:1.1.2 - https://github.com/apiguardian-team/apiguardian)\n     (Bouncy Castle Licence) Bouncy Castle Provider (org.bouncycastle:bcprov-jdk18on:1.77 - https://www.bouncycastle.org/java.html)\n     (New BSD License) Hamcrest Core (org.hamcrest:hamcrest-core:1.3 - https://github.com/hamcrest/JavaHamcrest/hamcrest-core)\n     (The Apache Software License, Version 2.0) IntelliJ IDEA Annotations (org.jetbrains:annotations:13.0 - http://www.jetbrains.org)\n     (The Apache License, Version 2.0) Kotlin Reflect (org.jetbrains.kotlin:kotlin-reflect:1.9.10 - https://kotlinlang.org/)\n     (The Apache License, Version 2.0) Kotlin Stdlib (org.jetbrains.kotlin:kotlin-stdlib:1.9.10 - https://kotlinlang.org/)\n     (The Apache License, Version 2.0) Kotlin Stdlib Common (org.jetbrains.kotlin:kotlin-stdlib-common:1.9.10 - https://kotlinlang.org/)\n     (The Apache License, Version 2.0) Kotlin Stdlib Jdk7 (org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.9.10 - https://kotlinlang.org/)\n     (The Apache License, Version 2.0) Kotlin Stdlib Jdk8 (org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.9.10 - https://kotlinlang.org/)\n     (The Apache Software License, Version 2.0) kotlinx-coroutines-core (org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4 - https://github.com/Kotlin/kotlinx.coroutines)\n     (The Apache Software License, Version 2.0) kotlinx-coroutines-core (org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.6.4 - https://github.com/Kotlin/kotlinx.coroutines)\n     (Eclipse Public License v2.0) JUnit Jupiter (Aggregator) (org.junit.jupiter:junit-jupiter:5.10.1 - https://junit.org/junit5/)\n     (Eclipse Public License v2.0) JUnit Jupiter API (org.junit.jupiter:junit-jupiter-api:5.10.1 - https://junit.org/junit5/)\n     (Eclipse Public License v2.0) JUnit Jupiter Engine (org.junit.jupiter:junit-jupiter-engine:5.10.1 - https://junit.org/junit5/)\n     (Eclipse Public License v2.0) JUnit Jupiter Params (org.junit.jupiter:junit-jupiter-params:5.10.1 - https://junit.org/junit5/)\n     (Eclipse Public License v2.0) JUnit Platform Commons (org.junit.platform:junit-platform-commons:1.10.1 - https://junit.org/junit5/)\n     (Eclipse Public License v2.0) JUnit Platform Engine API (org.junit.platform:junit-platform-engine:1.10.1 - https://junit.org/junit5/)\n     (Apache License, Version 2.0) Objenesis (org.objenesis:objenesis:3.3 - http://objenesis.org/objenesis)\n     (The Apache License, Version 2.0) org.opentest4j:opentest4j (org.opentest4j:opentest4j:1.3.0 - https://github.com/ota4j-team/opentest4j)\n     (MIT License) SLF4J API Module (org.slf4j:slf4j-api:2.0.11 - http://www.slf4j.org)\n     (MIT License) SLF4J Simple Provider (org.slf4j:slf4j-simple:2.0.11 - http://www.slf4j.org)\n</code></pre>"},{"location":"about/release-notes/","title":"Release Notes","text":""},{"location":"about/release-notes/#version-222-2024-02-07","title":"Version 2.2.2 (2024-02-07)","text":"<ul> <li>#30) Battery status contains the incorrect volt and temperature values per cell</li> </ul>"},{"location":"about/release-notes/#version-221-2024-02-06","title":"Version 2.2.1 (2024-02-06)","text":"<ul> <li>#23) ASOC/SOH interchange</li> </ul>"},{"location":"about/release-notes/#version-220-2024-02-01","title":"Version 2.2.0 (2024-02-01)","text":"<ul> <li>Fixed wrong return code if a data block is in error</li> <li>#21) Service to control the manual charging system</li> <li>The ChargingService has been expanded to include the following functions<ul> <li>readManualChargeState() -&gt; Reading out the current status of a manual storage tank charge</li> <li>setManualCharge(amountWh) -&gt; Starting a manual storage tank charge</li> <li>stopManualCharge() -&gt; Stopping a manual storage tank charge</li> </ul> </li> <li>BatTag and EMSTag enums have been expanded to include a number of tags relating to the battery system </li> <li>#23) Fixed Training Mode</li> <li>The status of the battery training mode was interpreted as a Boolean in version 2.1.0. However, it is actually an enum. This has been fixed</li> <li>The boolean value trainingModeActive is now deprecated and scheduled for removal in 2.4.0</li> <li>#22) Add emergency power related Tags and a new service for controlling the emergency power system</li> <li>BatTag and EMSTag enums have been expanded to include a number of tags relating to emergency power system</li> <li>A new service EmergencyPowerService has been created<ul> <li>readState() -&gt; Reads out the status of the emergency power function</li> <li>setReserveWH(reserve) -&gt; Configuring the emergency power reserve in watt hours</li> <li>setReservePercentage(reserve) -&gt; Configuring the emergency power reserve as a percentage relative to the battery capacity</li> <li>removeReserve() -&gt; Removes a configured emergency power reserve</li> </ul> </li> </ul>"},{"location":"about/release-notes/#version-210-2024-01-22","title":"Version 2.1.0 (2024-01-22)","text":"<ul> <li>#2) DataBuilder().none() is optional, now</li> <li>It To create a data block of data type <code>NONE</code>, the function <code>none()</code> must no longer be called explicitly. This behavior is now default.</li> <li>The examples in the documentation have been adjusted.</li> <li>#13) BatteryService and more BatteryTags</li> <li>A whole host of new tags for the BAT namespace have now been added</li> <li>A new service for reading out battery information is available</li> <li>#14) Dependency updates</li> <li>slf4j: from 2.0.9 to 2.0.11</li> <li>BouncyCastle: from 1.76 to 1.77</li> <li>JUnit: from 5.10.0 to 5.10.1</li> <li>Mockk: from 1.13.7 to 1.13.9</li> <li>#15) TypeScript added to the documentation</li> <li>To avoid duplication, this documentation also contains the TypeScript examples for the sister project easy-rscp-js</li> <li>New API functions:</li> <li>Class Frame<ul> <li>isDataBlockInError()</li> <li>errorCodeByTag()</li> </ul> </li> <li>Class Data<ul> <li>valueAsErrorCode</li> </ul> </li> <li>New enum ErrorCode</li> </ul>"},{"location":"about/release-notes/#version-200-2023-09-22","title":"Version 2.0.0 (2023-09-22)","text":"<ul> <li>Initial Public release</li> </ul>"},{"location":"getting-started/hello-world/","title":"Hello RSCP","text":"<p>In this example we will establish a connection to the home power plant and read out some system information.</p>"},{"location":"getting-started/hello-world/#provide-connection-data","title":"Provide connection data","text":"<p>For connection building it is easiest to use the <code>ConnectionBuilder()</code> class. For TypeScript you can use the factory classes. Here is an example with the minimum necessary configuration:</p> KotlinJavaTypeScript <pre><code>val connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n</code></pre> <pre><code>ConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\n</code></pre> <pre><code>const connectionData: E3dcConnectionData = {\naddress: host,\nport: 5033,\nportalUser: portalUser,\nportalPassword: portalPassword,\nrscpPassword: rscpPassword\n}\nconst factory = new DefaultHomePowerPlantConnectionFactory(connectionData)\nconst connection = await factory.openConnection()\n</code></pre> Parameter Description address IP address or DNS name of the home power plant portalUser Username. Corresponds to the username from the E3DC portal portalPassword Password. Corresponds to the password on the E3DC portal rscpPassword Encryption password. This value is configured directly at the home power plant and must be identical here"},{"location":"getting-started/hello-world/#create-service-builder","title":"Create Service Builder","text":"<p>The access itself is done via one of the services. Here in the example we use the <code>InfoService</code>. The easiest way to create it is to use the <code>InfoServiceBuilder()</code> class. In TypeScript you can easily create a service if you have created an RSCP connection:</p> KotlinJavaTypeScript <pre><code>val serviceBuilder = InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\n</code></pre> <pre><code>InfoServiceBuilder infoServiceBuilder = new InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder);\n</code></pre> <pre><code>const service = new DefaultInfoService(connection)\n</code></pre>"},{"location":"getting-started/hello-world/#create-and-use-service","title":"Create and use service","text":"<p>And now ... have fun:</p> KotlinJavaTypeScript <pre><code>val service = serviceBuilder.buildService()\nval systemInfos = service.readSystemInfo()\nprintln(systemInfos)\n</code></pre> <pre><code>InfoService service = infoServiceBuilder.buildService();\nSystemInfo infos = service.readSystemInfo();\nSystem.out.println(infos);\n</code></pre> <pre><code>const service = new DefaultInfoService(connection)\nservice.readSystemInfo()\n.then(systemInfos =&gt; console.log(systemInfos)\n</code></pre>"},{"location":"getting-started/hello-world/#all-together","title":"All together","text":"KotlinJavaTypeScript <pre><code>import de.jnkconsulting.e3dc.easyrscp.connection.ConnectionBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder\nval host = \"192.168.1.2\" // IP address of your home power plant\nval portalUser = \"my_e3dc_username\" // The username you use to log in to the E3DC portal\nval portalPassword = \"my_e3dc_password\" // The password to your E3DC portal access\nval rscpPassword = \"my_rscp_password\" // The password you set on your home power plant \nfun main() {\nval connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\nval serviceBuilder = InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\nval service = serviceBuilder.buildService()\nval systemInfos = service.readSystemInfo()\nprintln(systemInfos)\n}\n</code></pre> <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.service.InfoService;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.SystemInfo;\nimport de.jnkconsulting.e3dc.easyrscp.connection.ConnectionBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder;\npublic class ReadSystemInfos {\nprivate static String host = \"192.168.1.2\"; // IP address of your home power plant\nprivate static String portalUser = \"my_e3dc_username\"; // The username you use to log in to the E3DC portal\nprivate static String portalPassword = \"my_e3dc_password\"; // The password to your E3DC portal access\nprivate static String rscpPassword = \"my_rscp_password\"; // The password you set on your home power plant\npublic static void main(String[] args) {\nConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\nInfoServiceBuilder infoServiceBuilder = new InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder);\nInfoService service = infoServiceBuilder.buildService();\nSystemInfo infos = service.readSystemInfo();\nSystem.out.println(infos);\n}\n}\n</code></pre> <pre><code>import {E3dcConnectionData, DefaultHomePowerPlantConnectionFactory, DefaultInfoService} from 'easy-rscp';\nconst connectionData: E3dcConnectionData = {\naddress: host,\nport: 5033,\nportalUser: portalUser,\nportalPassword: portalPassword,\nrscpPassword: rscpPassword\n}\nconst factory = new DefaultHomePowerPlantConnectionFactory(connectionData)\nconst connection = await factory.openConnection()\nconst service = new DefaultInfoService(connection)\nservice.readSystemInfo()\n.then(systemInfos =&gt; console.log(systemInfos)\n</code></pre> <p>If everything worked, you should see something like the following result (The serialNumber is hidden here): <pre><code>SystemInfo(serialNumber=***, softwareVersion=H20_2023_024, productionDate=ProductionDate(rscpValue='KW27 2022', calendarWeek=27, year=2022, localDate=2022-07-04))\n</code></pre></p> <p>That's it. Your first RSCP request to the home power plant is done!</p>"},{"location":"getting-started/hello-world/#whats-next","title":"What's next?","text":"<p>Either you read the documentation of the Service API or, if you want to code more, you look at the integration tests in the service module. These are normal unit tests that are only executed when certain environment variables are set. There is one test for each service function. You can find the tests in the service module under <code>src/test/kotlin/de/jnkconsulting/e3dc/easyrscp/service</code>. The variables are visible in the code and correspond to the connection data to the home power plant.</p>"},{"location":"getting-started/setup/","title":"Setting up the RSCP interface at the home power plant","text":"<p>By default, the RSCP interface is disabled on the home power plant. Therefore you have to go to the home power plant once and activate the RSCP interface. Details can be found in the manual of your home power plant.</p> <p>As an example I show the setup on my S10X (On other models it should be similar). The pictures are in german (sorry for that), but it should be easy to adapt.</p>"},{"location":"getting-started/setup/#setup-on-the-s10x-home-power-plant","title":"Setup on the S10X home power plant","text":"Switch from the main page to the main menu Select \"Personalize\" in the main menu Select \"Profile\" here Go to the next page Set password and confirm -&gt; The small lamp must now light up green"},{"location":"getting-started/setup/#using-the-library","title":"Using the library","text":"Warning of damage to your home power plant <p>This library is provided absolutely without any warranty. You can use it for write access to E3DC home power plants. The library does not validate in any way whether the requests make sense. The usage is completely in the responsibility of the user!</p> <p>The library is divided into three sections</p> artifact-id Description jnk-easy-rscp-api Mainly contains interfaces and descriptions of the library. The other modules implement the interfaces. jnk-easy-rscp-lowlevel RSCP interface at the bottom. Here you can compile an RSCP request down to the byte, send it and interpret the response. jnk-easy-rscp-service Higher level that hides RSCP subtleties behind services. Most users should use this module. The scope will be extended in future version. Maven central <p>The artifacts are available in the maven central repository and for easy-rscp-js on npm</p> MavenGradle (groovy)Gradle (kotlin)npm <pre><code>&lt;dependency&gt;\n&lt;groupId&gt;de.jnk-consulting.e3dc.easyrscp&lt;/groupId&gt;\n&lt;artifactId&gt;jnk-easy-rscp-service&lt;/artifactId&gt;\n&lt;version&gt;2.0.0&lt;/version&gt;\n&lt;/dependency&gt;\n</code></pre> <pre><code>implementation 'de.jnk-consulting.e3dc.easyrscp:jnk-easy-rscp-service:2.0.0'\n</code></pre> <pre><code>implementation(\"de.jnk-consulting.e3dc.easyrscp:jnk-easy-rscp-service:2.0.0\")\n</code></pre> <pre><code>npm i easy-rscp\n</code></pre>"},{"location":"lowlevel/connection/","title":"Connection setup","text":"<p>The <code>connection</code> package contains all classes that are needed to establish a connection to the home power plant. The class <code>DefaultHomePowerPlantConnection</code> serves as connection point. Here frames are sent to the home power plant and the answers are parsed.</p> <p>To create a connection the class <code>DefaultHomePowerPlantConectionFactory</code> is available.</p> <p>As <code>ConnectionPool</code> the implementation <code>SingleInstanceConnectionPool</code> is available, which keeps Thread Save open a connection to the home power plant.</p> <p>To simplify the creation and dependencies, there is the <code>ConnectionBuilder</code> which can create the instances with little configuration effort.</p> Differences in TypeScript <p>In the TypeScript version there is no ConnectionPool and no ConnectionBuilder. The connection ensures that all requests are sent serialized</p>"},{"location":"lowlevel/connection/#connectionbuilder-usage","title":"ConnectionBuilder usage","text":"<p>In the following example we create a ConnectionBuilder instance, get a ConnectionPool and request the current live production data. To be able to read the answer we use the <code>StringFrameConverter</code> to output the answer frame:</p> KotlinJavaTypeScript <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.tags.EMSTag\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder\nimport de.jnkconsulting.e3dc.easyrscp.connection.ConnectionBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.StringFrameConverter\nval host = \"192.168.1.2\" // IP address of your home power plant\nval portalUser = \"my_e3dc_username\" // The username you use to log in to the E3DC portal\nval portalPassword = \"my_e3dc_password\" // The password to your E3DC portal access\nval rscpPassword = \"my_rscp_password\" // The password you set on your home power plant\nfun main() {\nval connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\nval connectionPool = connectionBuilder.buildConnectionPool()\nval answer = connectionPool.executeAndRelease {\nit.send(FrameBuilder()\n.addData(\nDataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nDataBuilder().tag(EMSTag.REQ_BAT_SOC).build(),\n).build()\n)\n}\nprintln(StringFrameConverter().invoke(answer))\n}\n</code></pre> <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.connection.ConnectionPool;\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.Frame;\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.tags.EMSTag;\nimport de.jnkconsulting.e3dc.easyrscp.connection.ConnectionBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.StringFrameConverter;\npublic class ConnectionBuilderExample {\nprivate static String host = \"192.168.1.2\"; // IP address of your home power plant\nprivate static String portalUser = \"my_e3dc_username\"; // The username you use to log in to the E3DC portal\nprivate static String portalPassword = \"my_e3dc_password\"; // The password to your E3DC portal access\nprivate static String rscpPassword = \"my_rscp_password\"; // The password you set on your home power plant\npublic static void main(String[] args) {\nConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\nConnectionPool connectionPool = connectionBuilder.buildConnectionPool();\nFrame answer = connectionPool.executeAndRelease(connection -&gt; {\nFrame requestFrame = new FrameBuilder()\n.addData(\nnew DataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nnew DataBuilder().tag(EMSTag.REQ_BAT_SOC).build()\n).build();\nreturn connection.send(requestFrame);\n});\nSystem.out.println(new StringFrameConverter().invoke(answer));\n}\n}\n</code></pre> <pre><code>import {\nE3dcConnectionData, DefaultHomePowerPlantConnectionFactory, FrameBuilder,\nDataBuilder,\nStringFrameConverter} from 'easy-rscp';\nconst connectionData: E3dcConnectionData = {\naddress: host,\nport: 5033,\nportalUser: portalUser,\nportalPassword: portalPassword,\nrscpPassword: rscpPassword\n}\nconst factory = new DefaultHomePowerPlantConnectionFactory(connectionData)\nconst connection = await factory.openConnection()\nconst request = new FrameBuilder()\n.addData(\nnew DataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nnew DataBuilder().tag(EMSTag.REQ_BAT_SOC).build()\n).build()\nconnection.send(request)\n.then(response =&gt; {\nconsole.log(new StringFrameConverter().convert(response))\n})\n</code></pre> <p>The output should look something like this: <pre><code>Timestamp:  2023-09-19T19:08:44.664348Z\nWithChecksum:   true\n    Tag:    EMS.POWER_PV - 01800001\n    Type:   INT32 - 06\n    Value:  0 - 00000000\n    Tag:    EMS.POWER_BAT - 01800002\n    Type:   INT32 - 06\n    Value:  -639 - 81fdffff\n    Tag:    EMS.POWER_GRID - 01800004\n    Type:   INT32 - 06\n    Value:  23 - 17000000\n    Tag:    EMS.POWER_HOME - 01800003\n    Type:   INT32 - 06\n    Value:  662 - 96020000\n    Tag:    EMS.BAT_SOC - 01800008\n    Type:   UCHAR8 - 03\n    Value:  86 - 56\n</code></pre></p>"},{"location":"lowlevel/crypt/","title":"Encryption","text":"<p>The <code>crypt</code> package contains the AES implementations. Each request and response frame must be AES encrypted. Here E3DC has made some specifications which are mapped in the class <code>BouncyCastleAESCipher</code>.</p> Uses the class only and exclusively to communicate with the home power plant <p>E3DC requires some peculiarities that make the AES algrithm used here insecure. </p> <ol> <li>A password is not well suited as an AES key. Actually, a password derivation algorithm should be used. This is not the case here. Simply the bytes from the string are used and converted into a 32Byte long key. If the password is too short, the key is padded, if the passowrt is too long, it is truncated.</li> <li>The IV for the first request is always empty.</li> </ol> <p>None of this can be changed, the home power plant requires exactly this algorithm. Therefore use this class only here and otherwise please not!</p>"},{"location":"lowlevel/crypt/#usage","title":"Usage","text":"TypeScript <p>If you want to intervene in the encryption, you can implement your own AesCipherFactory and make this known to the DefaultHomePowerPlantConnectionFactory in the structure.</p> <p>The classes are not used directly, but created automatically by the <code>ConnectionBuilder</code>. Only if you want to exchange the supplied implementation, you can set your factory at the builder:</p> KotlinJavaTypeScript <pre><code>val connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n.withCipherFactory(myCustomCipherFactory)\n</code></pre> <pre><code>ConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n.withCipherFactory(myCustomCipherFactory);\n</code></pre> <pre><code>const factory = new DefaultHomePowerPlantConnectionFactory(\nconnectionData,\nmyCustomAESImplementation);\n</code></pre>"},{"location":"lowlevel/frame/","title":"Frames and Data","text":"<p>Frames are used to send requests to the home power plant. The home power plant also responds in frames.  Each frame consists of a series (at least one) of data blocks. The type of a block is determined by so-called tags.</p>"},{"location":"lowlevel/frame/#tags","title":"Tags","text":"<p>Tags describe the type of a data block. They tell whether the contained value is a number or a text, and whether it is, for example, the current PV prodction or a load limit.</p> <p>The tags I know are located as enum classes in the package <code>de.jnkconsulting.e3dc.easyrscp.api.frame.tags</code>.  For each namespace defined by E3DC there is a separate enum class.</p> <p>What exactly the namespaces mean is described in the RSCP section.</p> <p>If a tag is needed, either as a request or as a response, which are not defined here in enum classes, an instance of <code>UnknownTag</code> can be used.  The original byte value remains here and can be used accordingly.</p>"},{"location":"lowlevel/frame/#building-frames","title":"Building frames","text":"<p>The easiest way to create frames is to use the <code>FrameBuilder</code> and the <code>DataBuilder</code> classes.</p> Know what you do <p>You must know what you are doing. Neither the <code>FrameBuilder</code> nor the <code>DataBuilder</code> check if the combination makes any sense!</p> <p>Here is an example of how to put together a query frame that asks for some live data:</p> KotlinJavaTypeScript <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.tags.EMSTag\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.StringFrameConverter\nfun main() {\nval requestFrame = FrameBuilder()\n.addData(\nDataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nDataBuilder().tag(EMSTag.REQ_BAT_SOC).build(),\n).build()\nprintln(StringFrameConverter().invoke(requestFrame))\n}\n</code></pre> <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.Frame;\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.tags.EMSTag;\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.StringFrameConverter;\npublic class FrameExamples {\npublic static void main(String[] args) {\nFrame requestFrame =  new FrameBuilder()\n.addData(\nnew DataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nnew DataBuilder().tag(EMSTag.REQ_BAT_SOC).build()\n).build();\nSystem.out.println(new StringFrameConverter().invoke(requestFrame));\n}\n}\n</code></pre> <pre><code>import {FrameBuilder, DataBuilder, StringFrameConverter, EMSTag} from 'easy-rscp';\nconst request = new FrameBuilder()\n.addData(\nnew DataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nnew DataBuilder().tag(EMSTag.REQ_BAT_SOC).build()\n).build();\nconsole.log(new StringFrameConverter().convert(requestFrame));\n</code></pre> <p>The output should look something like this:</p> <pre><code>Timestamp:  2023-09-19T20:32:43.305569Z\nWithChecksum:   true\n    Tag:    EMS.REQ_POWER_PV - 01000001\n    Type:   NONE - 00\n    Value:  [NONE] - \n    Tag:    EMS.REQ_POWER_BAT - 01000002\n    Type:   NONE - 00\n    Value:  [NONE] - \n    Tag:    EMS.REQ_POWER_GRID - 01000004\n    Type:   NONE - 00\n    Value:  [NONE] - \n    Tag:    EMS.REQ_POWER_HOME - 01000003\n    Type:   NONE - 00\n    Value:  [NONE] - \n    Tag:    EMS.REQ_BAT_SOC - 01000008\n    Type:   NONE - 00\n    Value:  [NONE] - \n</code></pre>"},{"location":"lowlevel/frame/#reading-frames","title":"Reading frames","text":"<p>Reading data from a frame can be complex. Theoretically, a frame can contain data blocks of type <code>container</code>. So, blocks that contain other blocks. To make it as comfortable as possible to access the individual values, the frame class provides various functions to access the contents in any depth. For this purpose different <code>xxxByTag</code> functions are available. The functions search for a specific data block with the given tag. There is an additional vararg parameter, which maps the path through possibly existing containers.</p> <p>Here is an example to read the house consumption of a certain day. For this, a request was made to the home power plant database. In response, a frame with a nested structure is provided. The searched value is in the following structure:</p> <p><pre><code>DBTag.HISTORY_DATA_DAY -&gt; DBTag.SUM_CONTAINER -&gt; DBTag.CONSUMPTION\n</code></pre> <code>DBTag.HISTORY_DATA_DAY</code> and <code>DBTag.SUM_CONTAINER</code> are data blocks of type <code>container</code>. <code>DBTag.CONSUMPTION</code> contains a float value indicating the total house consumption of the day.</p> <p>This value can be accessed as follows:</p> KotlinJavaTypeScript <pre><code>val answerFrame: Frame = ...\nval consumption = answerFrame.floatByTag(\nDBTag.CONSUMPTION, DBTag.HISTORY_DATA_DAY, DBTag.SUM_CONTAINER)\n</code></pre> <pre><code>Frame answerFrame = ...;\nfloat consumption = amswerFrame.floatByTag(\nDBTag.CONSUMPTION, DBTag.HISTORY_DATA_DAY, DBTag.SUM_CONTAINER);\n</code></pre> <pre><code>import {Frame, DBTag} from 'easy-rscp';\nconst answerFrame: Frame = ...\nconst consumption = answerFrame.floatByTag(\nDBTag.CONSUMPTION, DBTag.HISTORY_DATA_DAY, DBTag.SUM_CONTAINER)\n</code></pre> <p>The various <code>xxxByTag</code> usually always return a value. If the corresponding tag is not found, a default value is returned (For numeric values 0, for string \"\" etc.).</p> <p>The <code>xxxByTag</code> methods have their limit when a container contains several data blocks of the same type. This happens quite rarely (in database queries for example). But if it does, then you have to access manually according to the content.</p>"},{"location":"lowlevel/general-concepts/","title":"General concept","text":"RSCP Knowledge <p>If you want to work with the lowlevel API, you must be familiar with the RSCP protocol, at least in its basic features. I therefore recommend to also read the RSCP section.</p> <p>The API of easy-rscp consists of three areas, which are separated by the packages <code>connection</code>, <code>crypt</code> and <code>frame</code>.</p>"},{"location":"lowlevel/general-concepts/#connection","title":"connection","text":"<p>Here are all the classes that are needed to establish a connection to the home power plant.</p> <p>To create and correctly connect the different objects, a <code>ConnectionBuilder</code> is available. More info in the Connection setup section.</p>"},{"location":"lowlevel/general-concepts/#crypt","title":"crypt","text":"<p>Here are the implementations of <code>AESCipher</code> and <code>AESCipherFactory</code>. easy-rscp uses the Java Crypto Framework BouncyCastle for the implementations.</p> <p>If you want to work without BouncyCastle dependency, you can implement the two interfaces yourself and set them accordingly in the <code>ConnectionBuilder</code>.</p>"},{"location":"lowlevel/general-concepts/#frame","title":"frame","text":"<p>Everything that has to do with frames and data blocks, parsing etc. is located here.</p>"},{"location":"rscp/authentication/","title":"Authentication","text":"<p>After a TCP/IP connection to the home power plant has been established, an authentication frame must first be sent.</p> <p>This consists of a data block <code>RSCP.REQ_AUTHENTICATION</code> of type <code>container</code>. This contains two data blocks. Once <code>RSCP.AUTHENTICATION_USER</code> and <code>RSCP.AUTHENTICATION_PASSWORD</code>. Each of the type string. The access data to the E3DC portal are set as values.</p>"},{"location":"rscp/authentication/#example-authentication-frame","title":"Example authentication frame","text":"<p>In the example, the username <code>TEST</code> and the password <code>123</code> were used:</p> Human readableAs hex code <pre><code>Timestamp:  2023-09-20T14:22:25.542694Z\nWithChecksum:   true\n    Tag:    RSCP.REQ_AUTHENTICATION - 00000001\n    Type:   CONTAINER - 0e\n        Tag:    RSCP.AUTHENTICATION_USER - 00000002\n        Type:   STRING - 0d\n        Value:  TEST - 54455354\n\n        Tag:    RSCP.AUTHENTICATION_PASSWORD - 00000003\n        Type:   STRING - 0d\n        Value:  123 - 313233\n</code></pre> <pre><code>e3dc001121000b650000000070da58201c00010000000e1500020000000d040054455354030000000d030031323378babe16\n</code></pre>"},{"location":"rscp/authentication/#response-frame-on-successful-authentication","title":"Response frame on successful authentication","text":"Human readableAs hex code <pre><code>Timestamp:  2023-09-20T14:26:14.787390Z\nWithChecksum:   true\n    Tag:    RSCP.AUTHENTICATION - 00800001\n    Type:   UCHAR8 - 03\n    Value:  10 - 0a\n</code></pre> <pre><code>e3dc001106010b6500000000309eee2e0800010080000301000ad4e6f5cf\n</code></pre> <p>The response frame contains the value <code>10</code>. This specifies some kind of authorization. The following values are known (Even though we usually always have to make do with the USER level):</p> Wert E3DC Name 0 NO_AUTH 10 USER 20 INSTALLER 30 PARTNER 40 E3DC 50 E3DC_ADMIN 60 E3DC_ROOT"},{"location":"rscp/authentication/#response-frame-if-authentication-is-not-successful","title":"Response frame if authentication is NOT successful","text":"Human readableAs hex code <pre><code>Timestamp:  2023-09-20T14:27:42.534655Z\nWithChecksum:   true\n    Tag:    RSCP.AUTHENTICATION - 00800001\n    Type:   INT32 - 06\n    Value:  0 - 00000000\n</code></pre> <pre><code>e3dc00115e010b65000000001830de1f0b00010080000604000000000003120cf6\n</code></pre>"},{"location":"rscp/basic-rscp/","title":"Basic stuff","text":"<p>E3DC's home power plants offer a TCP/IP interface for read and write access. The protocol used for the content is proprietary and is called RSCP. </p> <p>The RSCP structure is well documented by E3DC, but in terms of content there is almost no documentation at all. In addition, the documentation is incomplete, partly incorrect and not publicly available. The E3DC service portal, to which every customer has access, contains the RSCP documentation. </p> <p>This section aims to explain the subtleties of the protocol in as much detail as possible. For example, if you want to create your own framework in another language, you can use the documentation as a basis.</p> Help is welcome <p>Much of the knowledge about RSCP that has been written down here has been determined by trial and error. There are still large gaps in our knowledge and certainly there will be errors. If you can contribute something to the documentation, you are welcome. Just report in a ticket.</p>"},{"location":"rscp/basic-rscp/#base-information","title":"Base information","text":"<p>The home power plant listens on a specific port (usually 5033) and waits for RSCP requests. An RSCP request is a byte block called a frame. A frame contains different metadata and 1-n data blocks. On this page I only want to give a short overview, the whole frame structure is described byte by byte in the section Frames in Detail.</p>"},{"location":"rscp/basic-rscp/#communication-principle","title":"Communication principle","text":"<p>RSCP works according to the send/response principle. This means that you send a request frame to the home power plant and you get the appropriate response frame back in reply. A special authentication frame must be sent beforehand. All further requests must be handled in the same connection. Otherwise another authentication is necessary. How the authentication works is described in the section Authentication.</p> <p>The home power plant does not provide transport encryption. But each frame must be AES256 encrypted. Details about the algorithm can be found in the Encryption section.</p> <p>Sending and receiving a frame:</p> <pre><code>    sequenceDiagram\n        Client-&gt;&gt;Client: buildAuthenticationFrame()\n        Client-&gt;&gt;Client: encryptAuthenticationFrame(authenticationFrame)\n        Client-&gt;&gt;home power plant: send(encryptedAuthenticationFrame)\n        home power plant--&gt;&gt;Client: respond(encryptedAuthenticationAnswerFrame)\n        Client-&gt;&gt;Client: buildRequestFrame()\n        Client-&gt;&gt;Client: encryptRequestFrame(requestFrame)\n        Client-&gt;&gt;home power plant: send(encryptedRequestFrame)\n        home power plant--&gt;Client: respond(encryptedAnswerFrame)\n        Client-&gt;&gt;Client: decrypt(encryptedAnswerFrame)\n        Client-&gt;&gt;Client: useAndBeHappy(answerFrame)</code></pre>"},{"location":"rscp/encryption/","title":"Encryption","text":"<p>This section describes how to encrypt (or decrypt) a frame. It is assumed that some terms are already known. AES, IV, etc. are not described in detail because they are part of the standard AES algorithm.</p>"},{"location":"rscp/encryption/#the-basics","title":"The basics","text":"<p>Each frame must be AES-256 encrypted. The response frames must be decrypted accordingly. The RSCP password configured on the home power plant is used as the key (see Setup).</p> <p>Note the handling of the IV. Initially, an IV completely filled with the values 0xFF is used. Afterwards the last encrypted block is always used as IV for the next one (AES standard). This also applies across frames. So when you send the authentication frame, you have to remember the last block, because it is needed as IV for the next frame.</p> <p>On the decryption side it is the same. The initial IV is filled with 0xFF. When decrypting you have to remember the last block again, because it is needed for the next response frame.</p> Do not use this algorithm anywhere else! <p>The algorithm given by E3DC is not completely secure. Therefore, do not use the algorithm or the encryption implementation in any other project. Three problems make the algorithm insecure:</p> <ol> <li>Empty IV: Actually, a random (or at least secret) value should be used. Since a symmetrical procedure is used here, it is not possible to transmit such a secret securely. The value was therefore chosen empty by E3DC. The first block of the encryption is therefore less strongly encrypted than the others.</li> <li>No <code>password derivation function</code>: AES is byte based. Here AES-256 -&gt; A 32Byte long key consisting of binary data is used. Now it is quite inconvenient for humans to remember binary data, so E3DC decided to use a text as key. This can be done, but then you should use a <code>password derivation function</code> (PBKDF2, Argon2, etc). Otherwise the key space is limited to the printable characters, and thus the security is reduced considerably. E3DC does not do this!</li> <li>Pseudo security by key generation: E3DC pretends that the 32byte long key is generated directly from the bytes of the text password. If the password is too short, the key is padded with 0xFF values. If the password is too long, the key is truncated.</li> </ol> The transferred data is not secure <p>In addition to pointing out that please do not use the algorithm anywhere else, it is also worth mentioning that the data transmitted in the frames cannot be considered completely safe either. Be aware of this. Among other things, your E3DC Portal username and E3DC Portal password will be transmitted! </p> <p>Usually the transmission is done in your private network, but I don't want to leave it unmentioned. When you log in to the E3DC portal with your data, these are SSL encrypted and therefore not readable in your private network. When communicating with the home power plant you have to rely on the poorly implemented AES algorithm.</p> Good AES vs Bad AES <p>Just to clarify: AES itself is not considered insecure as of today (end of 2023) and is a very good symmetric algorithm. However, if you choose the parameters incorrectly, the security is unfortunately gone.</p>"},{"location":"rscp/encryption/#aes-parameter","title":"AES Parameter","text":"<p>To use your AES algorithm correctly, you need to consider the following parameters:</p> <ol> <li>Key length 32Byte (AES-256)</li> <li>CBC Mode (Cipher Block Chaining)</li> <li>ZeroBytePadding</li> </ol>"},{"location":"rscp/frame-details/","title":"Frames in Detail","text":""},{"location":"rscp/frame-details/#the-big-picture","title":"The big picture","text":"Please Zoom <p>To visualize the frame structure I used Gantt charts here. They are actually meant for something else, but they serve their purpose and can be easily generated with mermaid.js. Unfortunately the diagrams don't offer a zoom function, so use the browser zoom!</p> <p>The following diagrams show the structure of a frame. And this byte by byte. Please note that the bytes are transmitted in little endian order.</p>"},{"location":"rscp/frame-details/#frame","title":"Frame","text":"<pre><code>gantt\n    title Structure of a frame\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Frame\n        Whole frame          : frame, 2014-01-01, 30d         \n    section Header        \n        Magic bytes          : mb, 2014-01-01, 2d\n        CTRL                 : ctrl, after mb, 2d\n        Timestamp            : ts, after ctrl, 12d\n        length               : dlength, after ts, 2d\n    section Data        \n        Data                 : crit, data, after dlength, 8d\n    section Checksum\n        CRC32                : active, crc, after data, 4d</code></pre> <p>In the diagram above the structure of a frame is shown. Please note that the length of the data block is variable and is only shown here as an example of 8 bytes. In reality a data block is significantly longer.</p>"},{"location":"rscp/frame-details/#magic-bytes","title":"Magic Bytes","text":"<p>Each frame starts with a 2 byte MagicByte block. This always contains the values E3DC (Hexcode ...)</p> <pre><code>gantt\n    title Magic Bytes\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Magic Bytes\n        0xE3                : e3, 2014-01-01, 1d\n        0xDC                : dc, after e3, 1d</code></pre>"},{"location":"rscp/frame-details/#control-bytes","title":"Control Bytes","text":"<p>The control bytes currently contain 2 pieces of information.</p> <ol> <li>Does the frame contain a checksum at the end (the checksum is optional)?</li> <li>Which protocol version is used? To my knowledge this is always 0x01 so far</li> </ol> <p>Both information are placed in the first byte. The second byte is intended for future use is currently always 0.</p> <pre><code>gantt\n    title Control Bytes\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section CRC true\n        0x00                : b1, 2014-01-01, 1d\n        0x11                : b2, after b1, 1d\n    section CRC false\n        0x00                : b1, 2014-01-01, 1d\n        0x01                : b2, after b1, 1d</code></pre>"},{"location":"rscp/frame-details/#timestamp","title":"Timestamp","text":"<p>The timestamp area indicates the creation time of the frame. In seconds and nanoseconds since 01/01/1970 00:00. As I understand it in UTC.</p> <p>The first 8 bytes indicate the seconds value and the next 4 bytes the nanoseconds.</p> <p>The following timestamp block, represents the timestamp 2023-09-20T07:57:05.362489Z.</p> <p>Since the 01.01.1970 00:00 o'clock up to this Timestamp 1,695,196,625 seconds and 362,489,000 nanoseconds have passed.</p> <pre><code>gantt\n    title Timestamp\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Timestamp\n        0xd1a50a6500000000  : seconds, 2014-01-01, 8d\n        0xa8249b15          : nanos, after seconds, 4d</code></pre>"},{"location":"rscp/frame-details/#length","title":"Length","text":"<p>In the length field the length of the following data block is indicated in bytes. Since a frame can consist of several data blocks, the sum of all data block lengths is specified here.</p> <p>In the example 28bytes (0x1c00 in hexcode Little Endian)</p> <pre><code>gantt\n    title Length\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Timestamp\n        0x1c00  : length, 2014-01-01, 2d</code></pre>"},{"location":"rscp/frame-details/#data-block","title":"Data block","text":"<p>One or more data blocks follow. The length is determined by the previous length field. The structure is described in detail in the data block area.</p>"},{"location":"rscp/frame-details/#checksum","title":"Checksum","text":"<p>If the frame uses a checksum, it is specified here, with a length of 4 bytes. The standard algorithm CRC32 is used.</p> <pre><code>gantt\n    title CRC32\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Timestamp\n        0xe2a60c5d  : crc, 2014-01-01, 4d</code></pre>"},{"location":"rscp/frame-details/#datenblock","title":"Datenblock","text":"<p>A data block represents a concrete value in a frame. Exception: A data block is of the type 'container'. Then it contains further data blocks</p> <pre><code>gantt\n    title Structure of a Data Block\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Data\n        Whole Block          : block, 2014-01-01, 15d         \n    section Header        \n        Tag                  : tag, 2014-01-01, 4d\n        Type                 : type, after tag, 1d\n        Length               : length, after type, 2d        \n    section Value        \n        Value                : crit, value, after length, 8d</code></pre>"},{"location":"rscp/frame-details/#tag","title":"Tag","text":"<p>The tag gives a meaning to the content. It describes which area of the home power plant it is (namespace), whether it is a request or response block, and which field from the respective namespace is meant.</p> <p>For example the tag <code>MAC_ADDRESS</code> from the namespace <code>INFO</code>. This has the value <code>0a80000a</code>.</p> <pre><code>gantt\n    title The Tag INFO.MAC_ADDRESS\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Namespace\n        0x0a                : ns, 2014-01-01, 1d         \n    section Tag        \n        0x00800a            : tag, after ns, 3d</code></pre> Info <p>Whether it is a request or response block can be seen by the first bit(!) of the tag area. 0=request, 1=response</p>"},{"location":"rscp/frame-details/#type","title":"Type","text":"<p>In the next byte the data type is specified. That is, how the value area in the block is to be interpreted (number, string, etc.).</p> <pre><code>gantt\n    title Datatype String\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section String\n        0x0d                : type, 2014-01-01, 1d</code></pre>"},{"location":"rscp/frame-details/#length_1","title":"Length","text":"<p>This area is 2 bytes long and specifies the length in bytes of the following value area.</p> <pre><code>gantt\n    title Lengthj\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section String\n        0x1100               : length, 2014-01-01, 2d</code></pre>"},{"location":"rscp/frame-details/#value","title":"Value","text":"<p>Here hides the actual value, which can be interpreted depending on length and type. Here is an example for the software release number <code>H20_2023_024</code> (tag <code>INFO.SW_RELEASE</code>)</p> <pre><code>gantt\n    title Example String\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section String\n        0x4832305f323032335f303234               : value, 2014-01-01, 2d</code></pre> Blocks as values <p>If the data type is <code>container</code>, the value area contains a complete further data block(s)!</p>"},{"location":"rscp/frame-details/#example","title":"Example","text":"<p>To make things a little clearer, let's take a look at a request frame and its corresponding response frame.</p> <p>We want to query the live data of the current PV production and the battery. For this purpose, we first assemble the query frame.</p> <p>In human readable form: <pre><code>Timestamp:  2023-09-20T08:42:32.818989Z\nWithChecksum:   true\n    Tag:    EMS.REQ_POWER_PV - 01000001\n    Type:   NONE - 00\n    Value:  [NONE] - \n    Tag:    EMS.REQ_POWER_BAT - 01000002\n    Type:   NONE - 00\n    Value:  [NONE] - \n</code></pre></p> <p>In home power plant readable form: <pre><code>e3dc001178b00a6500000000c8c7d0300e0001000001000000020000010000004c769f09\n</code></pre></p> <p>And once disassembled:</p> Bytes Value Description 1 - 2 e3dc Magic Bytes 3 - 4 0011 Controlbytes -&gt; protocol version 1 and checksum is enabled 5 - 12 78b00a6500000000 Timestamp, seconds since 01.01.1970 00:00 UTC -&gt; 1,695,199,352 13 - 16 c8c7d030 Timestamp, Nanoseconds -&gt; 818,989,000 17 - 18 0e00 Length of the data block area in bytes -&gt; 14 bytes 18 - 21 01000001 Namespace + Tag -&gt; EMS.REQ_POWER_PV 22 00 Data type -&gt; None 23 - 24 0000 Length of the data block -&gt; Data type is <code>none</code>, therefore 0 25 - 28 02000001 Namespace + Tag -&gt; EMS.REQ_POWER_BAT 29 00 Data type -&gt; None 31-32 0000 Length of the data block -&gt; data type is <code>none</code>, therefore 0 33-36 4c769f09 CRC32 checksum <p>As a response we get the following frame:</p> <p>In human readable form: <pre><code>Timestamp:  2023-09-20T08:42:35.019685Z\nWithChecksum:   true\n    Tag:    EMS.POWER_PV - 01800001\n    Type:   INT32 - 06\n    Value:  4687 - 4f120000\n    Tag:    EMS.POWER_BAT - 01800002\n    Type:   INT32 - 06\n    Value:  2139 - 5b080000\n</code></pre></p> <p>In home power plant readable form: <pre><code>e3dc00117bb00a6500000000885e2c011600010080010604004f120000020080010604005b08000058156e18\n</code></pre></p> <p>And once disassembled:</p> Bytes Value Description 1 - 2 e3dc Magic Bytes 3 - 4 0011 Kontrolbytes -&gt; Protocol version 1 and checksum is activated 5 - 12 7bb00a6500000000 Timestamp, seconds since 01.01.1970 00:00 UTC -&gt; 1,695,199,355 13 - 16 885e2c01 Timestamp, Nanoseconds -&gt; 19,685,000 17 - 18 1600 Length of the data block area in bytes -&gt; 22 bytes 18 - 21 01008001 Namespace + Tag -&gt; EMS.POWER_PV 22 06 Data type -&gt; INT32 23 - 24 0400 Length of the data block -&gt; data type is <code>INT32</code>, therefore 4 bytes 25 - 28 4f120000 Actual value -&gt; data type is <code>INT32</code>, therefore 4,687 29 - 32 02008001 Namespace + Tag -&gt; EMS.POWER_BAT 33 06 Data type -&gt; INT32 34 - 35 0400 Length of the data block -&gt; data type is <code>INT32</code>, therefore 4 bytes 36 - 39 5b080000 Actual value -&gt; data type is <code>INT32</code>, therefore 2,139 40 - 43 58156e18 CRC32 checksume"},{"location":"rscp/frame-details/#namespaces","title":"Namespaces","text":"<p>E3DC has split all tags into different namespaces to create some overview. All namespaces known to me are documented in kdoc in the enum class <code>de.jnkconsulting.e3dc.easyrscp.api.frame.Namespace</code>.</p>"},{"location":"rscp/frame-details/#tags","title":"Tags","text":"<p>The multitude of tags is also documented in kdoc. Each namespace has its own enum class to ensure at least some overview.</p> <p>If I know anything about the structure and meaning of the tag, it is stored in kdoc. Partly E3DC has documented a little bit. If available, I have included the original E3DC documentation in kdoc and marked it with <code>Original E3DC Documentation:</code>. Once translated in English and once in German, as supplied by E3DC. </p> <p>Here you can find the tags TAG API.</p>"},{"location":"rscp/frame-details/#data-types","title":"Data types","text":"<p>The protocol defines a set of data types. These are documented in the enum class <code>de.jnkconsulting.e3dc.easyrscp.api.frame.DataType</code>.</p>"},{"location":"service/extension-points/","title":"Extension points","text":"<p>There are currently three ways to interfere with the operation of the service or lowlevel API.</p> <p>Listener \u2192 Are called at specific points in the request/response lifecycle</p> <p>FrameConverter \u2192 Read data from a response frame from the home power plant and convert the data into an object</p> <p>FrameCreator \u2192 Generates request frames to the home power plant</p>"},{"location":"service/extension-points/#listener","title":"Listener","text":"<p>For instances of type <code>ConnectionBuilder</code> any number of <code>RSCPRequestResponseListener</code> can be registered. These listeners are called at different points in the request-response cycle.</p> TypeScript <p>In TypeScript you can pass the listeners to the ConnectionFactory</p> KotlinJavaTypeScript <pre><code>val connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n.addRequestResponseListener(listener1, listener2)\n</code></pre> <pre><code>ConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n.addRequestResponseListener(listener1, listener2);\n</code></pre> <pre><code>const factory = new DefaultHomePowerPlantConnectionFactory(\nconnectionData,\naesFactory,\nsocketFactory,\nframeParser,\nlistenerArray\n)\n</code></pre> Please note <p>The listeners are only used if NO own instance of type <code>HomePowerPlantConnectionFactory</code> or <code>ConnectionPool</code> is configured at the Builder!</p>"},{"location":"service/extension-points/#request-response-lifecycle","title":"Request-/Response Lifecycle","text":"<pre><code>sequenceDiagram\n  autonumber\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onBeforeRequestFrameEncryption(event)\n  DefaultHomePowerPlantConnection-&gt;&gt;AESCipher: encrypt(frameBytes)\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onBeforeRequestSend(event)\n  DefaultHomePowerPlantConnection-&gt;&gt;HomePowerPlant: send(encryptedFrameBytes)\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onAfterRequestSend(event)\n  HomePowerPlant-&gt;&gt;DefaultHomePowerPlantConnection: sendAnswer(encryptedAnswerFrameBytes)\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onAnswerReceived(event)\n  DefaultHomePowerPlantConnection-&gt;&gt;AESCipher: decrypt(encryptedAnswerFrameBytes)\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onAnswerDecrypted(event)\n  DefaultHomePowerPlantConnection-&gt;&gt;FrameParser: parseRSCPFrame(decryptedAnswerBytes)\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onAnswerParsed(event)</code></pre>"},{"location":"service/extension-points/#frameconverter","title":"FrameConverter","text":"<p>Each service offers the possibility to set its own <code>FrameConverter</code> instances. The builders offer corresponding functions here.</p> <p>A <code>FrameConverter</code> reads a response frame from the home power plant and converts it into a corresponding logical object. The service API already provides corresponding converters. Normally you don't need to do anything here. But if you want to influence the conversion process, you can create your own converter and set it as constructor parameter or via one of the builders.</p> <p>Here is an example how to set your own converter at the <code>InfoService</code>:</p> KotlinJavaTypeScript <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.Frame\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.tags.InfoTag\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.ProductionDate\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.SystemInfo\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.ConnectionBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.FrameConverter\nclass CustomConverter: FrameConverter&lt;SystemInfo&gt; {\noverride fun invoke(frame: Frame) =\nSystemInfo(\nserialNumber = frame.stringByTag(InfoTag.SERIAL_NUMBER),\nsoftwareVersion = frame.stringByTag(InfoTag.SW_RELEASE),\nproductionDate = ProductionDate(frame.stringByTag(InfoTag.PRODUCTION_DATE)),\n)\n}\nfun main() {\nval connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\nval builder = InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\n.withSystemInfoFrameConverter(CustomConverter())\n}\n</code></pre> <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.Frame;\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.tags.InfoTag;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.InfoService;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.ProductionDate;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.SystemInfo;\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.ConnectionBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.FrameConverter;\npublic class CustomConverter implements FrameConverter&lt;SystemInfo&gt; {\n@Override\npublic SystemInfo invoke(Frame frame) {\nString serialNumber = frame.stringByTag(InfoTag.SERIAL_NUMBER);\nString softwareVersion = frame.stringByTag(InfoTag.SW_RELEASE);\nProductionDate productionDate = new ProductionDate(frame.stringByTag(InfoTag.PRODUCTION_DATE));\nreturn new SystemInfo(serialNumber, softwareVersion, productionDate);\n}\nprivate static String host = ...;\nprivate static String portalUser = ...;\nprivate static String portalPassword = ...;\nprivate static String rscpPassword = ...;\npublic static void main(String[] args) {\nConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\nInfoServiceBuilder infoServiceBuilder = new InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\n.withSystemInfoFrameConverter(new CustomConverter());    }\n}    </code></pre> <pre><code>import {FrameConverter, Frame} from 'easy-rscp';\nclass CustomConverter implements FrameConverter&lt;SystemInfo&gt; {\nconvert(frame: Frame): SystemInfo {\nconst serialNumber = frame.stringByTag(InfoTag.SERIAL_NUMBER);\nconst softwareVersion = frame.stringByTag(InfoTag.SW_RELEASE);\nconst productionDate = ... // parse production date\nreturn {\nserialNumber: serialNumber,\nsoftwareVersion: softwareVersion,\nproductionDate: productionDate,\n}\n}\n}    const service = new DefaultInfoService(\nconnection,\nnew RequestSystemInfosCreator(),\nnew CustomConverter()\n)\n</code></pre>"},{"location":"service/extension-points/#framecreator","title":"FrameCreator","text":"<p>Each service offers the possibility to set its own <code>FrameCreator</code> instances. The builders offer corresponding functions here.</p> <p>A <code>FrameCreator</code> creates request frames that are sent to the home power plant. The service API already provides corresponding creators. Normally you don't need to do anything here. But if you want to influence the creation process, you can create your own creator and set it as constructor parameter or via one of the builders.</p> <p>Here is an example of how to set your own creator on the <code>InfoService</code>:</p> KotlinJavaTypeScript <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.tags.InfoTag\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.ConnectionBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.creator.FrameCreator\nclass CustomCreator: FrameCreator&lt;Nothing?&gt; {\noverride fun invoke(param: Nothing?) =\nFrameBuilder()\n.addData(\nDataBuilder().tag(InfoTag.REQ_MAC_ADDRESS).build(),\nDataBuilder().tag(InfoTag.REQ_PRODUCTION_DATE).build(),\nDataBuilder().tag(InfoTag.REQ_SERIAL_NUMBER).build(),\nDataBuilder().tag(InfoTag.REQ_SW_RELEASE).build()\n)\n.build()\n}\nfun main() {\nval connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\nval builder = InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\n.withRequestReadSystemInfoCreator(CustomCreator())\n}\n</code></pre> <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.Frame;\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.tags.InfoTag;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.InfoService;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.SystemInfo;\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.ConnectionBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.creator.FrameCreator;\npublic class CustomCreator implements FrameCreator&lt;Void&gt; {\n@Override\npublic Frame invoke(Void unused) {\nreturn new FrameBuilder()\n.addData(\nnew DataBuilder().tag(InfoTag.REQ_MAC_ADDRESS).build(),\nnew DataBuilder().tag(InfoTag.REQ_PRODUCTION_DATE).build(),\nnew DataBuilder().tag(InfoTag.REQ_SERIAL_NUMBER).build(),\nnew DataBuilder().tag(InfoTag.REQ_SW_RELEASE).build()\n)\n.build();\n}\nprivate static String host = ...;\nprivate static String portalUser = ...;\nprivate static String portalPassword = ...;\nprivate static String rscpPassword = ...;\npublic static void main(String[] args) {\nConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\nInfoServiceBuilder infoServiceBuilder = new InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\n.withRequestReadSystemInfoCreator(new CustomCreator());\n}\n}    </code></pre> <pre><code>import {FrameCreator, Frame, FrameBuilder, DataBuilder} from 'easy-rscp';\nclass CustomCreator implements FrameCreator&lt;undefined&gt; {\ncreate(input: undefined): Frame {\nreturn new FrameBuilder()\n.addData(\nnew DataBuilder().tag(InfoTag.REQ_MAC_ADDRESS).build(),\nnew DataBuilder().tag(InfoTag.REQ_PRODUCTION_DATE).build(),\nnew DataBuilder().tag(InfoTag.REQ_SERIAL_NUMBER).build(),\nnew DataBuilder().tag(InfoTag.REQ_SW_RELEASE).build()\n)\n.build();\n}\n}    const service = new DefaultInfoService(\nconnection,\nnew CustomCreator()\n)\n</code></pre>"},{"location":"service/general-concepts/","title":"General concept","text":"<p>The service API is based on the lowlevel API. Its goal is to hide all details of the RSCP interface behind service facades and to make working with the home power plant more logical.</p> You want more? <p>It should be noted that the RSCP interface is incredibly complex and only a very small part is currently used here. The expansion of the service API is planned and will be developed further. If you want to contribute here, have developed your own useful services, etc.: just create a PR or create a ticket with the title 'Maintainer'!</p> <p>Until then, the low-level API can be used. Here all RSCP possibilities are open to you.</p>"},{"location":"service/general-concepts/#service-creation","title":"Service creation","text":"<p>Generally, each service can be created simply with the constructor. Each service has exactly one mandatory parameter: The ConnectionPool. All other parameters are optional and have default values. Especially for the Java developers among you, the default parameters will not work because they are a Kotlin construct. Therefore, the use of the Builder API is recommended.</p> <p>For each service there is an own builder, which can create the service and if necessary allows to set the optional extension points. Each builder has a mandatory parameter. Namely an instance of the type <code>ConnectionBuilder</code> is needed. This creates the instances for encryption, connection setup etc. Don't worry, with the ConnectionBuilder it is sufficient to specify only the connection data. Everything else is optional. Here is an example:</p> TypeScript <p>The TypeScript versiond does not have the ServiceBuilder concept. You can create connections directly using the ConnectionFactory</p> KotlinJavaTypeScript <pre><code>val connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n</code></pre> <pre><code>ConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\n</code></pre> <pre><code>const connectionData: E3dcConnectionData = {\naddress: host,\nport: 5033,\nportalUser: portalUser,\nportalPassword: portalPassword,\nrscpPassword: rscpPassword\n}\nconst factory = new DefaultHomePowerPlantConnectionFactory(connectionData)\nconst connection = await factory.openConnection()\n</code></pre> Parameter Description address IP address or DNS name of the home power plant portalUser Username. Corresponds to the username from the E3DC portal portalPassword Password. Corresponds to the password on the E3DC portal rscpPassword Encryption password. This value is configured directly at the home power plant and must be identical here <p>With this instance you can configure all other ServiceBuilders. This is the only mandatory information that is required.</p> KotlinJavaTypeScript <pre><code>val serviceBuilder = InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\nval service = serviceBuilder.buildService()\nval systemInfos = service.readSystemInfo()\nprintln(systemInfos)\n</code></pre> <pre><code>InfoServiceBuilder infoServiceBuilder = new InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder);\nInfoService service = infoServiceBuilder.buildService();\nSystemInfo infos = service.readSystemInfo();\nSystem.out.println(infos);\n</code></pre> <pre><code>const service = new DefaultInfoService(connection)\nservice.readSystemInfo()\n.then(systemInfos =&gt; console.log(systemInfos)\n</code></pre>"},{"location":"service/general-concepts/#extension-points","title":"Extension points","text":"<p>The service API provides several points where you can intervene in the way it works. The details are described in the section Extension points.</p>"},{"location":"service/general-concepts/#logging-kotlinjava-only","title":"Logging (Kotlin/Java only)","text":"<p>easy-rscp uses internally SLF4J as logging framework. You may have already noticed that you get the following warning when running the examples:</p> <pre><code>SLF4J: No SLF4J providers were found.\nSLF4J: Defaulting to no-operation (NOP) logger implementation\nSLF4J: See https://www.slf4j.org/codes.html#noProviders for further details.\n</code></pre> <p>This is because easy-rscp does not provide a logging provider. Depending on which logging framework you use (Log4j, java logging, or whatever), you have to declare the corresponding provider implementation as a dependency. SLF4J provides instructions on what to do at the link https://www.slf4j.org/codes.html#noProviders.</p> Why another dependency? <p>Normally you will not need the log messages from easy-rscp. But it can be helpful for debugging. easy-rscp logs only on debug,  trace or error level to avoid too much noise. We don't want to impose a logging framework on you, so we use SLF4J to abstract the framework. You have the choice!</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"easy-rscp","text":"<p>easy-rscp is an INOFFICIAL library written in Kotlin (fully Java compatible) for accessing E3DC home power plants.</p> <p>E3DC is a brand of HagerEnergy Gmbh (website). I have nothing to do with the company, except that I own a home power plant from E3DC and wanted to include it in my SmartHome. This \"desire\" gave birth to easy-rscp. </p>"},{"location":"#what-is-easy-rscp","title":"What is easy-rscp?","text":"<p>E3DC's home power plants offer a TCP/IP interface for read and write access. The protocol used for the content is proprietary and is called RSCP. The RSCP structure is well documented by E3DC, but in terms of content there is almost no documentation at all. In addition, the documentation is incomplete, partly incorrect and not publicly available. The E3DC service portal, to which every customer has access, contains the RSCP documentation. easy-rscp and this documentation have the goal to make RSCP more easily accessible for the open source world.</p>"},{"location":"#what-do-i-get","title":"What do I get?","text":""},{"location":"#as-a-kotlin-developer","title":"As a Kotlin developer","text":"<p>A library written entirely in Kotlin to access home power plants from E3DC. Easy to use, well documented -&gt; Have fun.</p>"},{"location":"#as-a-java-developer","title":"As a Java developer","text":"<p>Basically the same as a Kotlin developer. The bytecode is Java compatible and in the examples you can choose between Kotlin and Java. </p> <p>Small disadvantage for you (besides the Java syntax, but you should be used to that), as a dependency smaller Kotlin libraries will be necessary.</p>"},{"location":"#as-ja-typescript-or-javascript-developer","title":"As ja TypeScript or JavaScript developer","text":"<p>You will find what you are looking for in the sister project easy-rscp-js. The core functionality is identical. The documentation of both projects is summarized here.</p>"},{"location":"#as-xyz-developer","title":"As XYZ Developer","text":"<p>Ok, you can't use the library directly. But in the course of the project this documentation was created. Especially the chapter RSCP should be interesting for you. Here you find a description of the RSCP protocol and all tags and meanings known to me. Maybe this will help you.</p>"},{"location":"#where-do-i-start","title":"Where do I start?","text":"<p>Best in the Getting started section.</p>"},{"location":"#can-i-participate","title":"Can I participate","text":"<p>Absolutely!</p>"},{"location":"#i-have-found-a-bug","title":"I have found a bug","text":"<p>Too bad, but that can happen. Create a new Bug and we'll take a look.</p> <p>You already know the solution? Very cool! Post a PR and we'll bring it to the main branch.</p>"},{"location":"#i-have-cool-extensions-improvements-fixes","title":"I have cool extensions, improvements fixes","text":"<p>The best thing to do is to create a PR.</p> <p>You can also participate in the project as a maintainer. Create a ticket here and we will see how you can support best.</p>"},{"location":"#i-have-further-knowledge-about-the-rscp-protocol","title":"I have further knowledge about the RSCP protocol","text":"<p>Every drop helps to decode this protocol completely. You can create a PR for the doc, or create a ticket. </p> <p>If you want to describe a specific RSCP tag, it is best to go to the API description and the corresponding tag class. At each entry you will find a link to create a ticket for exactly this tag.</p>"},{"location":"#special-thanks","title":"Special thanks","text":"<p>The RSCP protocol is virtually undocumented and there is no help available from E3DC. This library would not have been possible without numerous other projects. I would like to highlight two projects and two people in particular.</p> <p>First of all, a big \"thank you\" to Stefan. The developer of the incredible iOS my4E. Although he himself had no benefit from answering my questions about the RSCP protocol, he did it anyway and was a great help! Not a matter of course.</p> <p>A lot of inspiration and also help in understanding the RSCP protocol came from Uli. The developer of the E3DC plugin for ioBroker. Many thanks for the support.</p>"},{"location":"#license","title":"License","text":"<p>The library is licensed under the MIT License. License</p>"},{"location":"about/license/","title":"License","text":""},{"location":"about/license/#_1","title":"License","text":"<pre><code>MIT License\n\nCopyright (c) 2023 Jochen Zink\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n</code></pre>"},{"location":"about/license/#included-projects","title":"Included projects","text":""},{"location":"about/license/#this-documentation","title":"This documentation","text":"<p>This documentation was created using the great MkDocs tool and the wonderful Material for MkDocs theme:</p> <ul> <li>MkDocs - Project - View license</li> <li>Material for MkDocs - Project - View license</li> </ul>"},{"location":"about/license/#the-easy-rscp-library","title":"The easy rscp library","text":"<p>Without all the work of many, many OpenSource developers, this library would not have been possible. Many thanks to the authors of these fantastic projects:</p> <pre><code>Lists of 30 third-party dependencies.\n     (The Apache Software License, Version 2.0) kotlin-logging (io.github.microutils:kotlin-logging-jvm:3.0.5 - https://github.com/oshai/kotlin-logging)\n     (Apache License, Version 2.0) MockK Agent API (io.mockk:mockk-agent-api-jvm:1.13.9 - https://mockk.io)\n     (Apache License, Version 2.0) MockK (io.mockk:mockk-agent-jvm:1.13.9 - https://mockk.io)\n     (Apache License, Version 2.0) MockK Core (io.mockk:mockk-core-jvm:1.13.9 - https://mockk.io)\n     (Apache License, Version 2.0) MockK DSL (io.mockk:mockk-dsl-jvm:1.13.9 - https://mockk.io)\n     (Apache License, Version 2.0) MockK (io.mockk:mockk-jvm:1.13.9 - https://mockk.io)\n     (Eclipse Public License 1.0) JUnit (junit:junit:4.13.2 - http://junit.org)\n     (Apache License, Version 2.0) Byte Buddy (without dependencies) (net.bytebuddy:byte-buddy:1.14.6 - https://bytebuddy.net/byte-buddy)\n     (Apache License, Version 2.0) Byte Buddy agent (net.bytebuddy:byte-buddy-agent:1.14.6 - https://bytebuddy.net/byte-buddy-agent)\n     (The Apache License, Version 2.0) org.apiguardian:apiguardian-api (org.apiguardian:apiguardian-api:1.1.2 - https://github.com/apiguardian-team/apiguardian)\n     (Bouncy Castle Licence) Bouncy Castle Provider (org.bouncycastle:bcprov-jdk18on:1.77 - https://www.bouncycastle.org/java.html)\n     (New BSD License) Hamcrest Core (org.hamcrest:hamcrest-core:1.3 - https://github.com/hamcrest/JavaHamcrest/hamcrest-core)\n     (The Apache Software License, Version 2.0) IntelliJ IDEA Annotations (org.jetbrains:annotations:13.0 - http://www.jetbrains.org)\n     (The Apache License, Version 2.0) Kotlin Reflect (org.jetbrains.kotlin:kotlin-reflect:1.9.10 - https://kotlinlang.org/)\n     (The Apache License, Version 2.0) Kotlin Stdlib (org.jetbrains.kotlin:kotlin-stdlib:1.9.10 - https://kotlinlang.org/)\n     (The Apache License, Version 2.0) Kotlin Stdlib Common (org.jetbrains.kotlin:kotlin-stdlib-common:1.9.10 - https://kotlinlang.org/)\n     (The Apache License, Version 2.0) Kotlin Stdlib Jdk7 (org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.9.10 - https://kotlinlang.org/)\n     (The Apache License, Version 2.0) Kotlin Stdlib Jdk8 (org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.9.10 - https://kotlinlang.org/)\n     (The Apache Software License, Version 2.0) kotlinx-coroutines-core (org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4 - https://github.com/Kotlin/kotlinx.coroutines)\n     (The Apache Software License, Version 2.0) kotlinx-coroutines-core (org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.6.4 - https://github.com/Kotlin/kotlinx.coroutines)\n     (Eclipse Public License v2.0) JUnit Jupiter (Aggregator) (org.junit.jupiter:junit-jupiter:5.10.1 - https://junit.org/junit5/)\n     (Eclipse Public License v2.0) JUnit Jupiter API (org.junit.jupiter:junit-jupiter-api:5.10.1 - https://junit.org/junit5/)\n     (Eclipse Public License v2.0) JUnit Jupiter Engine (org.junit.jupiter:junit-jupiter-engine:5.10.1 - https://junit.org/junit5/)\n     (Eclipse Public License v2.0) JUnit Jupiter Params (org.junit.jupiter:junit-jupiter-params:5.10.1 - https://junit.org/junit5/)\n     (Eclipse Public License v2.0) JUnit Platform Commons (org.junit.platform:junit-platform-commons:1.10.1 - https://junit.org/junit5/)\n     (Eclipse Public License v2.0) JUnit Platform Engine API (org.junit.platform:junit-platform-engine:1.10.1 - https://junit.org/junit5/)\n     (Apache License, Version 2.0) Objenesis (org.objenesis:objenesis:3.3 - http://objenesis.org/objenesis)\n     (The Apache License, Version 2.0) org.opentest4j:opentest4j (org.opentest4j:opentest4j:1.3.0 - https://github.com/ota4j-team/opentest4j)\n     (MIT License) SLF4J API Module (org.slf4j:slf4j-api:2.0.11 - http://www.slf4j.org)\n     (MIT License) SLF4J Simple Provider (org.slf4j:slf4j-simple:2.0.11 - http://www.slf4j.org)\n</code></pre>"},{"location":"about/release-notes/","title":"Release Notes","text":""},{"location":"about/release-notes/#version-230-2024-02-18","title":"Version 2.3.0 (2024-02-18)","text":"<ul> <li>#32) Add missing WallBox Tags</li> <li>Added a bunch of Tags to WB and EMS Namespace</li> <li>#34) Extend services with wallbox live data</li> <li>DefaultLiveDataService returns the complete wallbox consumption and the solar share</li> <li>New DefaultWallboxService to query the connected wallboxes and read the live data for each</li> </ul>"},{"location":"about/release-notes/#version-222-2024-02-07","title":"Version 2.2.2 (2024-02-07)","text":"<ul> <li>#30) Battery status contains the incorrect volt and temperature values per cell</li> </ul>"},{"location":"about/release-notes/#version-221-2024-02-06","title":"Version 2.2.1 (2024-02-06)","text":"<ul> <li>#23) ASOC/SOH interchange</li> </ul>"},{"location":"about/release-notes/#version-220-2024-02-01","title":"Version 2.2.0 (2024-02-01)","text":"<ul> <li>Fixed wrong return code if a data block is in error</li> <li>#21) Service to control the manual charging system</li> <li>The ChargingService has been expanded to include the following functions<ul> <li>readManualChargeState() -&gt; Reading out the current status of a manual storage tank charge</li> <li>setManualCharge(amountWh) -&gt; Starting a manual storage tank charge</li> <li>stopManualCharge() -&gt; Stopping a manual storage tank charge</li> </ul> </li> <li>BatTag and EMSTag enums have been expanded to include a number of tags relating to the battery system </li> <li>#23) Fixed Training Mode</li> <li>The status of the battery training mode was interpreted as a Boolean in version 2.1.0. However, it is actually an enum. This has been fixed</li> <li>The boolean value trainingModeActive is now deprecated and scheduled for removal in 2.4.0</li> <li>#22) Add emergency power related Tags and a new service for controlling the emergency power system</li> <li>BatTag and EMSTag enums have been expanded to include a number of tags relating to emergency power system</li> <li>A new service EmergencyPowerService has been created<ul> <li>readState() -&gt; Reads out the status of the emergency power function</li> <li>setReserveWH(reserve) -&gt; Configuring the emergency power reserve in watt hours</li> <li>setReservePercentage(reserve) -&gt; Configuring the emergency power reserve as a percentage relative to the battery capacity</li> <li>removeReserve() -&gt; Removes a configured emergency power reserve</li> </ul> </li> </ul>"},{"location":"about/release-notes/#version-210-2024-01-22","title":"Version 2.1.0 (2024-01-22)","text":"<ul> <li>#2) DataBuilder().none() is optional, now</li> <li>It To create a data block of data type <code>NONE</code>, the function <code>none()</code> must no longer be called explicitly. This behavior is now default.</li> <li>The examples in the documentation have been adjusted.</li> <li>#13) BatteryService and more BatteryTags</li> <li>A whole host of new tags for the BAT namespace have now been added</li> <li>A new service for reading out battery information is available</li> <li>#14) Dependency updates</li> <li>slf4j: from 2.0.9 to 2.0.11</li> <li>BouncyCastle: from 1.76 to 1.77</li> <li>JUnit: from 5.10.0 to 5.10.1</li> <li>Mockk: from 1.13.7 to 1.13.9</li> <li>#15) TypeScript added to the documentation</li> <li>To avoid duplication, this documentation also contains the TypeScript examples for the sister project easy-rscp-js</li> <li>New API functions:</li> <li>Class Frame<ul> <li>isDataBlockInError()</li> <li>errorCodeByTag()</li> </ul> </li> <li>Class Data<ul> <li>valueAsErrorCode</li> </ul> </li> <li>New enum ErrorCode</li> </ul>"},{"location":"about/release-notes/#version-200-2023-09-22","title":"Version 2.0.0 (2023-09-22)","text":"<ul> <li>Initial Public release</li> </ul>"},{"location":"getting-started/hello-world/","title":"Hello RSCP","text":"<p>In this example we will establish a connection to the home power plant and read out some system information.</p>"},{"location":"getting-started/hello-world/#provide-connection-data","title":"Provide connection data","text":"<p>For connection building it is easiest to use the <code>ConnectionBuilder()</code> class. For TypeScript you can use the factory classes. Here is an example with the minimum necessary configuration:</p> KotlinJavaTypeScript <pre><code>val connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n</code></pre> <pre><code>ConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\n</code></pre> <pre><code>const connectionData: E3dcConnectionData = {\naddress: host,\nport: 5033,\nportalUser: portalUser,\nportalPassword: portalPassword,\nrscpPassword: rscpPassword\n}\nconst factory = new DefaultHomePowerPlantConnectionFactory(connectionData)\nconst connection = await factory.openConnection()\n</code></pre> Parameter Description address IP address or DNS name of the home power plant portalUser Username. Corresponds to the username from the E3DC portal portalPassword Password. Corresponds to the password on the E3DC portal rscpPassword Encryption password. This value is configured directly at the home power plant and must be identical here"},{"location":"getting-started/hello-world/#create-service-builder","title":"Create Service Builder","text":"<p>The access itself is done via one of the services. Here in the example we use the <code>InfoService</code>. The easiest way to create it is to use the <code>InfoServiceBuilder()</code> class. In TypeScript you can easily create a service if you have created an RSCP connection:</p> KotlinJavaTypeScript <pre><code>val serviceBuilder = InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\n</code></pre> <pre><code>InfoServiceBuilder infoServiceBuilder = new InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder);\n</code></pre> <pre><code>const service = new DefaultInfoService(connection)\n</code></pre>"},{"location":"getting-started/hello-world/#create-and-use-service","title":"Create and use service","text":"<p>And now ... have fun:</p> KotlinJavaTypeScript <pre><code>val service = serviceBuilder.buildService()\nval systemInfos = service.readSystemInfo()\nprintln(systemInfos)\n</code></pre> <pre><code>InfoService service = infoServiceBuilder.buildService();\nSystemInfo infos = service.readSystemInfo();\nSystem.out.println(infos);\n</code></pre> <pre><code>const service = new DefaultInfoService(connection)\nservice.readSystemInfo()\n.then(systemInfos =&gt; console.log(systemInfos)\n</code></pre>"},{"location":"getting-started/hello-world/#all-together","title":"All together","text":"KotlinJavaTypeScript <pre><code>import de.jnkconsulting.e3dc.easyrscp.connection.ConnectionBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder\nval host = \"192.168.1.2\" // IP address of your home power plant\nval portalUser = \"my_e3dc_username\" // The username you use to log in to the E3DC portal\nval portalPassword = \"my_e3dc_password\" // The password to your E3DC portal access\nval rscpPassword = \"my_rscp_password\" // The password you set on your home power plant \nfun main() {\nval connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\nval serviceBuilder = InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\nval service = serviceBuilder.buildService()\nval systemInfos = service.readSystemInfo()\nprintln(systemInfos)\n}\n</code></pre> <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.service.InfoService;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.SystemInfo;\nimport de.jnkconsulting.e3dc.easyrscp.connection.ConnectionBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder;\npublic class ReadSystemInfos {\nprivate static String host = \"192.168.1.2\"; // IP address of your home power plant\nprivate static String portalUser = \"my_e3dc_username\"; // The username you use to log in to the E3DC portal\nprivate static String portalPassword = \"my_e3dc_password\"; // The password to your E3DC portal access\nprivate static String rscpPassword = \"my_rscp_password\"; // The password you set on your home power plant\npublic static void main(String[] args) {\nConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\nInfoServiceBuilder infoServiceBuilder = new InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder);\nInfoService service = infoServiceBuilder.buildService();\nSystemInfo infos = service.readSystemInfo();\nSystem.out.println(infos);\n}\n}\n</code></pre> <pre><code>import {E3dcConnectionData, DefaultHomePowerPlantConnectionFactory, DefaultInfoService} from 'easy-rscp';\nconst connectionData: E3dcConnectionData = {\naddress: host,\nport: 5033,\nportalUser: portalUser,\nportalPassword: portalPassword,\nrscpPassword: rscpPassword\n}\nconst factory = new DefaultHomePowerPlantConnectionFactory(connectionData)\nconst connection = await factory.openConnection()\nconst service = new DefaultInfoService(connection)\nservice.readSystemInfo()\n.then(systemInfos =&gt; console.log(systemInfos)\n</code></pre> <p>If everything worked, you should see something like the following result (The serialNumber is hidden here): <pre><code>SystemInfo(serialNumber=***, softwareVersion=H20_2023_024, productionDate=ProductionDate(rscpValue='KW27 2022', calendarWeek=27, year=2022, localDate=2022-07-04))\n</code></pre></p> <p>That's it. Your first RSCP request to the home power plant is done!</p>"},{"location":"getting-started/hello-world/#whats-next","title":"What's next?","text":"<p>Either you read the documentation of the Service API or, if you want to code more, you look at the integration tests in the service module. These are normal unit tests that are only executed when certain environment variables are set. There is one test for each service function. You can find the tests in the service module under <code>src/test/kotlin/de/jnkconsulting/e3dc/easyrscp/service</code>. The variables are visible in the code and correspond to the connection data to the home power plant.</p>"},{"location":"getting-started/setup/","title":"Setting up the RSCP interface at the home power plant","text":"<p>By default, the RSCP interface is disabled on the home power plant. Therefore you have to go to the home power plant once and activate the RSCP interface. Details can be found in the manual of your home power plant.</p> <p>As an example I show the setup on my S10X (On other models it should be similar). The pictures are in german (sorry for that), but it should be easy to adapt.</p>"},{"location":"getting-started/setup/#setup-on-the-s10x-home-power-plant","title":"Setup on the S10X home power plant","text":"Switch from the main page to the main menu Select \"Personalize\" in the main menu Select \"Profile\" here Go to the next page Set password and confirm -&gt; The small lamp must now light up green"},{"location":"getting-started/setup/#using-the-library","title":"Using the library","text":"Warning of damage to your home power plant <p>This library is provided absolutely without any warranty. You can use it for write access to E3DC home power plants. The library does not validate in any way whether the requests make sense. The usage is completely in the responsibility of the user!</p> <p>The library is divided into three sections</p> artifact-id Description jnk-easy-rscp-api Mainly contains interfaces and descriptions of the library. The other modules implement the interfaces. jnk-easy-rscp-lowlevel RSCP interface at the bottom. Here you can compile an RSCP request down to the byte, send it and interpret the response. jnk-easy-rscp-service Higher level that hides RSCP subtleties behind services. Most users should use this module. The scope will be extended in future version. Maven central <p>The artifacts are available in the maven central repository and for easy-rscp-js on npm</p> MavenGradle (groovy)Gradle (kotlin)npm <pre><code>&lt;dependency&gt;\n&lt;groupId&gt;de.jnk-consulting.e3dc.easyrscp&lt;/groupId&gt;\n&lt;artifactId&gt;jnk-easy-rscp-service&lt;/artifactId&gt;\n&lt;version&gt;2.0.0&lt;/version&gt;\n&lt;/dependency&gt;\n</code></pre> <pre><code>implementation 'de.jnk-consulting.e3dc.easyrscp:jnk-easy-rscp-service:2.0.0'\n</code></pre> <pre><code>implementation(\"de.jnk-consulting.e3dc.easyrscp:jnk-easy-rscp-service:2.0.0\")\n</code></pre> <pre><code>npm i easy-rscp\n</code></pre>"},{"location":"lowlevel/connection/","title":"Connection setup","text":"<p>The <code>connection</code> package contains all classes that are needed to establish a connection to the home power plant. The class <code>DefaultHomePowerPlantConnection</code> serves as connection point. Here frames are sent to the home power plant and the answers are parsed.</p> <p>To create a connection the class <code>DefaultHomePowerPlantConectionFactory</code> is available.</p> <p>As <code>ConnectionPool</code> the implementation <code>SingleInstanceConnectionPool</code> is available, which keeps Thread Save open a connection to the home power plant.</p> <p>To simplify the creation and dependencies, there is the <code>ConnectionBuilder</code> which can create the instances with little configuration effort.</p> Differences in TypeScript <p>In the TypeScript version there is no ConnectionPool and no ConnectionBuilder. The connection ensures that all requests are sent serialized</p>"},{"location":"lowlevel/connection/#connectionbuilder-usage","title":"ConnectionBuilder usage","text":"<p>In the following example we create a ConnectionBuilder instance, get a ConnectionPool and request the current live production data. To be able to read the answer we use the <code>StringFrameConverter</code> to output the answer frame:</p> KotlinJavaTypeScript <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.tags.EMSTag\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder\nimport de.jnkconsulting.e3dc.easyrscp.connection.ConnectionBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.StringFrameConverter\nval host = \"192.168.1.2\" // IP address of your home power plant\nval portalUser = \"my_e3dc_username\" // The username you use to log in to the E3DC portal\nval portalPassword = \"my_e3dc_password\" // The password to your E3DC portal access\nval rscpPassword = \"my_rscp_password\" // The password you set on your home power plant\nfun main() {\nval connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\nval connectionPool = connectionBuilder.buildConnectionPool()\nval answer = connectionPool.executeAndRelease {\nit.send(FrameBuilder()\n.addData(\nDataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nDataBuilder().tag(EMSTag.REQ_BAT_SOC).build(),\n).build()\n)\n}\nprintln(StringFrameConverter().invoke(answer))\n}\n</code></pre> <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.connection.ConnectionPool;\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.Frame;\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.tags.EMSTag;\nimport de.jnkconsulting.e3dc.easyrscp.connection.ConnectionBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.StringFrameConverter;\npublic class ConnectionBuilderExample {\nprivate static String host = \"192.168.1.2\"; // IP address of your home power plant\nprivate static String portalUser = \"my_e3dc_username\"; // The username you use to log in to the E3DC portal\nprivate static String portalPassword = \"my_e3dc_password\"; // The password to your E3DC portal access\nprivate static String rscpPassword = \"my_rscp_password\"; // The password you set on your home power plant\npublic static void main(String[] args) {\nConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\nConnectionPool connectionPool = connectionBuilder.buildConnectionPool();\nFrame answer = connectionPool.executeAndRelease(connection -&gt; {\nFrame requestFrame = new FrameBuilder()\n.addData(\nnew DataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nnew DataBuilder().tag(EMSTag.REQ_BAT_SOC).build()\n).build();\nreturn connection.send(requestFrame);\n});\nSystem.out.println(new StringFrameConverter().invoke(answer));\n}\n}\n</code></pre> <pre><code>import {\nE3dcConnectionData, DefaultHomePowerPlantConnectionFactory, FrameBuilder,\nDataBuilder,\nStringFrameConverter} from 'easy-rscp';\nconst connectionData: E3dcConnectionData = {\naddress: host,\nport: 5033,\nportalUser: portalUser,\nportalPassword: portalPassword,\nrscpPassword: rscpPassword\n}\nconst factory = new DefaultHomePowerPlantConnectionFactory(connectionData)\nconst connection = await factory.openConnection()\nconst request = new FrameBuilder()\n.addData(\nnew DataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nnew DataBuilder().tag(EMSTag.REQ_BAT_SOC).build()\n).build()\nconnection.send(request)\n.then(response =&gt; {\nconsole.log(new StringFrameConverter().convert(response))\n})\n</code></pre> <p>The output should look something like this: <pre><code>Timestamp:  2023-09-19T19:08:44.664348Z\nWithChecksum:   true\n    Tag:    EMS.POWER_PV - 01800001\n    Type:   INT32 - 06\n    Value:  0 - 00000000\n    Tag:    EMS.POWER_BAT - 01800002\n    Type:   INT32 - 06\n    Value:  -639 - 81fdffff\n    Tag:    EMS.POWER_GRID - 01800004\n    Type:   INT32 - 06\n    Value:  23 - 17000000\n    Tag:    EMS.POWER_HOME - 01800003\n    Type:   INT32 - 06\n    Value:  662 - 96020000\n    Tag:    EMS.BAT_SOC - 01800008\n    Type:   UCHAR8 - 03\n    Value:  86 - 56\n</code></pre></p>"},{"location":"lowlevel/crypt/","title":"Encryption","text":"<p>The <code>crypt</code> package contains the AES implementations. Each request and response frame must be AES encrypted. Here E3DC has made some specifications which are mapped in the class <code>BouncyCastleAESCipher</code>.</p> Uses the class only and exclusively to communicate with the home power plant <p>E3DC requires some peculiarities that make the AES algrithm used here insecure. </p> <ol> <li>A password is not well suited as an AES key. Actually, a password derivation algorithm should be used. This is not the case here. Simply the bytes from the string are used and converted into a 32Byte long key. If the password is too short, the key is padded, if the passowrt is too long, it is truncated.</li> <li>The IV for the first request is always empty.</li> </ol> <p>None of this can be changed, the home power plant requires exactly this algorithm. Therefore use this class only here and otherwise please not!</p>"},{"location":"lowlevel/crypt/#usage","title":"Usage","text":"TypeScript <p>If you want to intervene in the encryption, you can implement your own AesCipherFactory and make this known to the DefaultHomePowerPlantConnectionFactory in the structure.</p> <p>The classes are not used directly, but created automatically by the <code>ConnectionBuilder</code>. Only if you want to exchange the supplied implementation, you can set your factory at the builder:</p> KotlinJavaTypeScript <pre><code>val connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n.withCipherFactory(myCustomCipherFactory)\n</code></pre> <pre><code>ConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n.withCipherFactory(myCustomCipherFactory);\n</code></pre> <pre><code>const factory = new DefaultHomePowerPlantConnectionFactory(\nconnectionData,\nmyCustomAESImplementation);\n</code></pre>"},{"location":"lowlevel/frame/","title":"Frames and Data","text":"<p>Frames are used to send requests to the home power plant. The home power plant also responds in frames.  Each frame consists of a series (at least one) of data blocks. The type of a block is determined by so-called tags.</p>"},{"location":"lowlevel/frame/#tags","title":"Tags","text":"<p>Tags describe the type of a data block. They tell whether the contained value is a number or a text, and whether it is, for example, the current PV prodction or a load limit.</p> <p>The tags I know are located as enum classes in the package <code>de.jnkconsulting.e3dc.easyrscp.api.frame.tags</code>.  For each namespace defined by E3DC there is a separate enum class.</p> <p>What exactly the namespaces mean is described in the RSCP section.</p> <p>If a tag is needed, either as a request or as a response, which are not defined here in enum classes, an instance of <code>UnknownTag</code> can be used.  The original byte value remains here and can be used accordingly.</p>"},{"location":"lowlevel/frame/#building-frames","title":"Building frames","text":"<p>The easiest way to create frames is to use the <code>FrameBuilder</code> and the <code>DataBuilder</code> classes.</p> Know what you do <p>You must know what you are doing. Neither the <code>FrameBuilder</code> nor the <code>DataBuilder</code> check if the combination makes any sense!</p> <p>Here is an example of how to put together a query frame that asks for some live data:</p> KotlinJavaTypeScript <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.tags.EMSTag\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.StringFrameConverter\nfun main() {\nval requestFrame = FrameBuilder()\n.addData(\nDataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nDataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nDataBuilder().tag(EMSTag.REQ_BAT_SOC).build(),\n).build()\nprintln(StringFrameConverter().invoke(requestFrame))\n}\n</code></pre> <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.Frame;\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.tags.EMSTag;\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.StringFrameConverter;\npublic class FrameExamples {\npublic static void main(String[] args) {\nFrame requestFrame =  new FrameBuilder()\n.addData(\nnew DataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nnew DataBuilder().tag(EMSTag.REQ_BAT_SOC).build()\n).build();\nSystem.out.println(new StringFrameConverter().invoke(requestFrame));\n}\n}\n</code></pre> <pre><code>import {FrameBuilder, DataBuilder, StringFrameConverter, EMSTag} from 'easy-rscp';\nconst request = new FrameBuilder()\n.addData(\nnew DataBuilder().tag(EMSTag.REQ_POWER_PV).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_BAT).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_GRID).build(),\nnew DataBuilder().tag(EMSTag.REQ_POWER_HOME).build(),\nnew DataBuilder().tag(EMSTag.REQ_BAT_SOC).build()\n).build();\nconsole.log(new StringFrameConverter().convert(requestFrame));\n</code></pre> <p>The output should look something like this:</p> <pre><code>Timestamp:  2023-09-19T20:32:43.305569Z\nWithChecksum:   true\n    Tag:    EMS.REQ_POWER_PV - 01000001\n    Type:   NONE - 00\n    Value:  [NONE] - \n    Tag:    EMS.REQ_POWER_BAT - 01000002\n    Type:   NONE - 00\n    Value:  [NONE] - \n    Tag:    EMS.REQ_POWER_GRID - 01000004\n    Type:   NONE - 00\n    Value:  [NONE] - \n    Tag:    EMS.REQ_POWER_HOME - 01000003\n    Type:   NONE - 00\n    Value:  [NONE] - \n    Tag:    EMS.REQ_BAT_SOC - 01000008\n    Type:   NONE - 00\n    Value:  [NONE] - \n</code></pre>"},{"location":"lowlevel/frame/#reading-frames","title":"Reading frames","text":"<p>Reading data from a frame can be complex. Theoretically, a frame can contain data blocks of type <code>container</code>. So, blocks that contain other blocks. To make it as comfortable as possible to access the individual values, the frame class provides various functions to access the contents in any depth. For this purpose different <code>xxxByTag</code> functions are available. The functions search for a specific data block with the given tag. There is an additional vararg parameter, which maps the path through possibly existing containers.</p> <p>Here is an example to read the house consumption of a certain day. For this, a request was made to the home power plant database. In response, a frame with a nested structure is provided. The searched value is in the following structure:</p> <p><pre><code>DBTag.HISTORY_DATA_DAY -&gt; DBTag.SUM_CONTAINER -&gt; DBTag.CONSUMPTION\n</code></pre> <code>DBTag.HISTORY_DATA_DAY</code> and <code>DBTag.SUM_CONTAINER</code> are data blocks of type <code>container</code>. <code>DBTag.CONSUMPTION</code> contains a float value indicating the total house consumption of the day.</p> <p>This value can be accessed as follows:</p> KotlinJavaTypeScript <pre><code>val answerFrame: Frame = ...\nval consumption = answerFrame.floatByTag(\nDBTag.CONSUMPTION, DBTag.HISTORY_DATA_DAY, DBTag.SUM_CONTAINER)\n</code></pre> <pre><code>Frame answerFrame = ...;\nfloat consumption = amswerFrame.floatByTag(\nDBTag.CONSUMPTION, DBTag.HISTORY_DATA_DAY, DBTag.SUM_CONTAINER);\n</code></pre> <pre><code>import {Frame, DBTag} from 'easy-rscp';\nconst answerFrame: Frame = ...\nconst consumption = answerFrame.floatByTag(\nDBTag.CONSUMPTION, DBTag.HISTORY_DATA_DAY, DBTag.SUM_CONTAINER)\n</code></pre> <p>The various <code>xxxByTag</code> usually always return a value. If the corresponding tag is not found, a default value is returned (For numeric values 0, for string \"\" etc.).</p> <p>The <code>xxxByTag</code> methods have their limit when a container contains several data blocks of the same type. This happens quite rarely (in database queries for example). But if it does, then you have to access manually according to the content.</p>"},{"location":"lowlevel/general-concepts/","title":"General concept","text":"RSCP Knowledge <p>If you want to work with the lowlevel API, you must be familiar with the RSCP protocol, at least in its basic features. I therefore recommend to also read the RSCP section.</p> <p>The API of easy-rscp consists of three areas, which are separated by the packages <code>connection</code>, <code>crypt</code> and <code>frame</code>.</p>"},{"location":"lowlevel/general-concepts/#connection","title":"connection","text":"<p>Here are all the classes that are needed to establish a connection to the home power plant.</p> <p>To create and correctly connect the different objects, a <code>ConnectionBuilder</code> is available. More info in the Connection setup section.</p>"},{"location":"lowlevel/general-concepts/#crypt","title":"crypt","text":"<p>Here are the implementations of <code>AESCipher</code> and <code>AESCipherFactory</code>. easy-rscp uses the Java Crypto Framework BouncyCastle for the implementations.</p> <p>If you want to work without BouncyCastle dependency, you can implement the two interfaces yourself and set them accordingly in the <code>ConnectionBuilder</code>.</p>"},{"location":"lowlevel/general-concepts/#frame","title":"frame","text":"<p>Everything that has to do with frames and data blocks, parsing etc. is located here.</p>"},{"location":"rscp/authentication/","title":"Authentication","text":"<p>After a TCP/IP connection to the home power plant has been established, an authentication frame must first be sent.</p> <p>This consists of a data block <code>RSCP.REQ_AUTHENTICATION</code> of type <code>container</code>. This contains two data blocks. Once <code>RSCP.AUTHENTICATION_USER</code> and <code>RSCP.AUTHENTICATION_PASSWORD</code>. Each of the type string. The access data to the E3DC portal are set as values.</p>"},{"location":"rscp/authentication/#example-authentication-frame","title":"Example authentication frame","text":"<p>In the example, the username <code>TEST</code> and the password <code>123</code> were used:</p> Human readableAs hex code <pre><code>Timestamp:  2023-09-20T14:22:25.542694Z\nWithChecksum:   true\n    Tag:    RSCP.REQ_AUTHENTICATION - 00000001\n    Type:   CONTAINER - 0e\n        Tag:    RSCP.AUTHENTICATION_USER - 00000002\n        Type:   STRING - 0d\n        Value:  TEST - 54455354\n\n        Tag:    RSCP.AUTHENTICATION_PASSWORD - 00000003\n        Type:   STRING - 0d\n        Value:  123 - 313233\n</code></pre> <pre><code>e3dc001121000b650000000070da58201c00010000000e1500020000000d040054455354030000000d030031323378babe16\n</code></pre>"},{"location":"rscp/authentication/#response-frame-on-successful-authentication","title":"Response frame on successful authentication","text":"Human readableAs hex code <pre><code>Timestamp:  2023-09-20T14:26:14.787390Z\nWithChecksum:   true\n    Tag:    RSCP.AUTHENTICATION - 00800001\n    Type:   UCHAR8 - 03\n    Value:  10 - 0a\n</code></pre> <pre><code>e3dc001106010b6500000000309eee2e0800010080000301000ad4e6f5cf\n</code></pre> <p>The response frame contains the value <code>10</code>. This specifies some kind of authorization. The following values are known (Even though we usually always have to make do with the USER level):</p> Wert E3DC Name 0 NO_AUTH 10 USER 20 INSTALLER 30 PARTNER 40 E3DC 50 E3DC_ADMIN 60 E3DC_ROOT"},{"location":"rscp/authentication/#response-frame-if-authentication-is-not-successful","title":"Response frame if authentication is NOT successful","text":"Human readableAs hex code <pre><code>Timestamp:  2023-09-20T14:27:42.534655Z\nWithChecksum:   true\n    Tag:    RSCP.AUTHENTICATION - 00800001\n    Type:   INT32 - 06\n    Value:  0 - 00000000\n</code></pre> <pre><code>e3dc00115e010b65000000001830de1f0b00010080000604000000000003120cf6\n</code></pre>"},{"location":"rscp/basic-rscp/","title":"Basic stuff","text":"<p>E3DC's home power plants offer a TCP/IP interface for read and write access. The protocol used for the content is proprietary and is called RSCP. </p> <p>The RSCP structure is well documented by E3DC, but in terms of content there is almost no documentation at all. In addition, the documentation is incomplete, partly incorrect and not publicly available. The E3DC service portal, to which every customer has access, contains the RSCP documentation. </p> <p>This section aims to explain the subtleties of the protocol in as much detail as possible. For example, if you want to create your own framework in another language, you can use the documentation as a basis.</p> Help is welcome <p>Much of the knowledge about RSCP that has been written down here has been determined by trial and error. There are still large gaps in our knowledge and certainly there will be errors. If you can contribute something to the documentation, you are welcome. Just report in a ticket.</p>"},{"location":"rscp/basic-rscp/#base-information","title":"Base information","text":"<p>The home power plant listens on a specific port (usually 5033) and waits for RSCP requests. An RSCP request is a byte block called a frame. A frame contains different metadata and 1-n data blocks. On this page I only want to give a short overview, the whole frame structure is described byte by byte in the section Frames in Detail.</p>"},{"location":"rscp/basic-rscp/#communication-principle","title":"Communication principle","text":"<p>RSCP works according to the send/response principle. This means that you send a request frame to the home power plant and you get the appropriate response frame back in reply. A special authentication frame must be sent beforehand. All further requests must be handled in the same connection. Otherwise another authentication is necessary. How the authentication works is described in the section Authentication.</p> <p>The home power plant does not provide transport encryption. But each frame must be AES256 encrypted. Details about the algorithm can be found in the Encryption section.</p> <p>Sending and receiving a frame:</p> <pre><code>    sequenceDiagram\n        Client-&gt;&gt;Client: buildAuthenticationFrame()\n        Client-&gt;&gt;Client: encryptAuthenticationFrame(authenticationFrame)\n        Client-&gt;&gt;home power plant: send(encryptedAuthenticationFrame)\n        home power plant--&gt;&gt;Client: respond(encryptedAuthenticationAnswerFrame)\n        Client-&gt;&gt;Client: buildRequestFrame()\n        Client-&gt;&gt;Client: encryptRequestFrame(requestFrame)\n        Client-&gt;&gt;home power plant: send(encryptedRequestFrame)\n        home power plant--&gt;Client: respond(encryptedAnswerFrame)\n        Client-&gt;&gt;Client: decrypt(encryptedAnswerFrame)\n        Client-&gt;&gt;Client: useAndBeHappy(answerFrame)</code></pre>"},{"location":"rscp/encryption/","title":"Encryption","text":"<p>This section describes how to encrypt (or decrypt) a frame. It is assumed that some terms are already known. AES, IV, etc. are not described in detail because they are part of the standard AES algorithm.</p>"},{"location":"rscp/encryption/#the-basics","title":"The basics","text":"<p>Each frame must be AES-256 encrypted. The response frames must be decrypted accordingly. The RSCP password configured on the home power plant is used as the key (see Setup).</p> <p>Note the handling of the IV. Initially, an IV completely filled with the values 0xFF is used. Afterwards the last encrypted block is always used as IV for the next one (AES standard). This also applies across frames. So when you send the authentication frame, you have to remember the last block, because it is needed as IV for the next frame.</p> <p>On the decryption side it is the same. The initial IV is filled with 0xFF. When decrypting you have to remember the last block again, because it is needed for the next response frame.</p> Do not use this algorithm anywhere else! <p>The algorithm given by E3DC is not completely secure. Therefore, do not use the algorithm or the encryption implementation in any other project. Three problems make the algorithm insecure:</p> <ol> <li>Empty IV: Actually, a random (or at least secret) value should be used. Since a symmetrical procedure is used here, it is not possible to transmit such a secret securely. The value was therefore chosen empty by E3DC. The first block of the encryption is therefore less strongly encrypted than the others.</li> <li>No <code>password derivation function</code>: AES is byte based. Here AES-256 -&gt; A 32Byte long key consisting of binary data is used. Now it is quite inconvenient for humans to remember binary data, so E3DC decided to use a text as key. This can be done, but then you should use a <code>password derivation function</code> (PBKDF2, Argon2, etc). Otherwise the key space is limited to the printable characters, and thus the security is reduced considerably. E3DC does not do this!</li> <li>Pseudo security by key generation: E3DC pretends that the 32byte long key is generated directly from the bytes of the text password. If the password is too short, the key is padded with 0xFF values. If the password is too long, the key is truncated.</li> </ol> The transferred data is not secure <p>In addition to pointing out that please do not use the algorithm anywhere else, it is also worth mentioning that the data transmitted in the frames cannot be considered completely safe either. Be aware of this. Among other things, your E3DC Portal username and E3DC Portal password will be transmitted! </p> <p>Usually the transmission is done in your private network, but I don't want to leave it unmentioned. When you log in to the E3DC portal with your data, these are SSL encrypted and therefore not readable in your private network. When communicating with the home power plant you have to rely on the poorly implemented AES algorithm.</p> Good AES vs Bad AES <p>Just to clarify: AES itself is not considered insecure as of today (end of 2023) and is a very good symmetric algorithm. However, if you choose the parameters incorrectly, the security is unfortunately gone.</p>"},{"location":"rscp/encryption/#aes-parameter","title":"AES Parameter","text":"<p>To use your AES algorithm correctly, you need to consider the following parameters:</p> <ol> <li>Key length 32Byte (AES-256)</li> <li>CBC Mode (Cipher Block Chaining)</li> <li>ZeroBytePadding</li> </ol>"},{"location":"rscp/frame-details/","title":"Frames in Detail","text":""},{"location":"rscp/frame-details/#the-big-picture","title":"The big picture","text":"Please Zoom <p>To visualize the frame structure I used Gantt charts here. They are actually meant for something else, but they serve their purpose and can be easily generated with mermaid.js. Unfortunately the diagrams don't offer a zoom function, so use the browser zoom!</p> <p>The following diagrams show the structure of a frame. And this byte by byte. Please note that the bytes are transmitted in little endian order.</p>"},{"location":"rscp/frame-details/#frame","title":"Frame","text":"<pre><code>gantt\n    title Structure of a frame\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Frame\n        Whole frame          : frame, 2014-01-01, 30d         \n    section Header        \n        Magic bytes          : mb, 2014-01-01, 2d\n        CTRL                 : ctrl, after mb, 2d\n        Timestamp            : ts, after ctrl, 12d\n        length               : dlength, after ts, 2d\n    section Data        \n        Data                 : crit, data, after dlength, 8d\n    section Checksum\n        CRC32                : active, crc, after data, 4d</code></pre> <p>In the diagram above the structure of a frame is shown. Please note that the length of the data block is variable and is only shown here as an example of 8 bytes. In reality a data block is significantly longer.</p>"},{"location":"rscp/frame-details/#magic-bytes","title":"Magic Bytes","text":"<p>Each frame starts with a 2 byte MagicByte block. This always contains the values E3DC (Hexcode ...)</p> <pre><code>gantt\n    title Magic Bytes\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Magic Bytes\n        0xE3                : e3, 2014-01-01, 1d\n        0xDC                : dc, after e3, 1d</code></pre>"},{"location":"rscp/frame-details/#control-bytes","title":"Control Bytes","text":"<p>The control bytes currently contain 2 pieces of information.</p> <ol> <li>Does the frame contain a checksum at the end (the checksum is optional)?</li> <li>Which protocol version is used? To my knowledge this is always 0x01 so far</li> </ol> <p>Both information are placed in the first byte. The second byte is intended for future use is currently always 0.</p> <pre><code>gantt\n    title Control Bytes\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section CRC true\n        0x00                : b1, 2014-01-01, 1d\n        0x11                : b2, after b1, 1d\n    section CRC false\n        0x00                : b1, 2014-01-01, 1d\n        0x01                : b2, after b1, 1d</code></pre>"},{"location":"rscp/frame-details/#timestamp","title":"Timestamp","text":"<p>The timestamp area indicates the creation time of the frame. In seconds and nanoseconds since 01/01/1970 00:00. As I understand it in UTC.</p> <p>The first 8 bytes indicate the seconds value and the next 4 bytes the nanoseconds.</p> <p>The following timestamp block, represents the timestamp 2023-09-20T07:57:05.362489Z.</p> <p>Since the 01.01.1970 00:00 o'clock up to this Timestamp 1,695,196,625 seconds and 362,489,000 nanoseconds have passed.</p> <pre><code>gantt\n    title Timestamp\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Timestamp\n        0xd1a50a6500000000  : seconds, 2014-01-01, 8d\n        0xa8249b15          : nanos, after seconds, 4d</code></pre>"},{"location":"rscp/frame-details/#length","title":"Length","text":"<p>In the length field the length of the following data block is indicated in bytes. Since a frame can consist of several data blocks, the sum of all data block lengths is specified here.</p> <p>In the example 28bytes (0x1c00 in hexcode Little Endian)</p> <pre><code>gantt\n    title Length\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Timestamp\n        0x1c00  : length, 2014-01-01, 2d</code></pre>"},{"location":"rscp/frame-details/#data-block","title":"Data block","text":"<p>One or more data blocks follow. The length is determined by the previous length field. The structure is described in detail in the data block area.</p>"},{"location":"rscp/frame-details/#checksum","title":"Checksum","text":"<p>If the frame uses a checksum, it is specified here, with a length of 4 bytes. The standard algorithm CRC32 is used.</p> <pre><code>gantt\n    title CRC32\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Timestamp\n        0xe2a60c5d  : crc, 2014-01-01, 4d</code></pre>"},{"location":"rscp/frame-details/#datenblock","title":"Datenblock","text":"<p>A data block represents a concrete value in a frame. Exception: A data block is of the type 'container'. Then it contains further data blocks</p> <pre><code>gantt\n    title Structure of a Data Block\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Data\n        Whole Block          : block, 2014-01-01, 15d         \n    section Header        \n        Tag                  : tag, 2014-01-01, 4d\n        Type                 : type, after tag, 1d\n        Length               : length, after type, 2d        \n    section Value        \n        Value                : crit, value, after length, 8d</code></pre>"},{"location":"rscp/frame-details/#tag","title":"Tag","text":"<p>The tag gives a meaning to the content. It describes which area of the home power plant it is (namespace), whether it is a request or response block, and which field from the respective namespace is meant.</p> <p>For example the tag <code>MAC_ADDRESS</code> from the namespace <code>INFO</code>. This has the value <code>0a80000a</code>.</p> <pre><code>gantt\n    title The Tag INFO.MAC_ADDRESS\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section Namespace\n        0x0a                : ns, 2014-01-01, 1d         \n    section Tag        \n        0x00800a            : tag, after ns, 3d</code></pre> Info <p>Whether it is a request or response block can be seen by the first bit(!) of the tag area. 0=request, 1=response</p>"},{"location":"rscp/frame-details/#type","title":"Type","text":"<p>In the next byte the data type is specified. That is, how the value area in the block is to be interpreted (number, string, etc.).</p> <pre><code>gantt\n    title Datatype String\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section String\n        0x0d                : type, 2014-01-01, 1d</code></pre>"},{"location":"rscp/frame-details/#length_1","title":"Length","text":"<p>This area is 2 bytes long and specifies the length in bytes of the following value area.</p> <pre><code>gantt\n    title Lengthj\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section String\n        0x1100               : length, 2014-01-01, 2d</code></pre>"},{"location":"rscp/frame-details/#value","title":"Value","text":"<p>Here hides the actual value, which can be interpreted depending on length and type. Here is an example for the software release number <code>H20_2023_024</code> (tag <code>INFO.SW_RELEASE</code>)</p> <pre><code>gantt\n    title Example String\n    dateFormat YYYY-MM-DD\n    axisFormat %d\n    tickInterval 1day\n    section String\n        0x4832305f323032335f303234               : value, 2014-01-01, 2d</code></pre> Blocks as values <p>If the data type is <code>container</code>, the value area contains a complete further data block(s)!</p>"},{"location":"rscp/frame-details/#example","title":"Example","text":"<p>To make things a little clearer, let's take a look at a request frame and its corresponding response frame.</p> <p>We want to query the live data of the current PV production and the battery. For this purpose, we first assemble the query frame.</p> <p>In human readable form: <pre><code>Timestamp:  2023-09-20T08:42:32.818989Z\nWithChecksum:   true\n    Tag:    EMS.REQ_POWER_PV - 01000001\n    Type:   NONE - 00\n    Value:  [NONE] - \n    Tag:    EMS.REQ_POWER_BAT - 01000002\n    Type:   NONE - 00\n    Value:  [NONE] - \n</code></pre></p> <p>In home power plant readable form: <pre><code>e3dc001178b00a6500000000c8c7d0300e0001000001000000020000010000004c769f09\n</code></pre></p> <p>And once disassembled:</p> Bytes Value Description 1 - 2 e3dc Magic Bytes 3 - 4 0011 Controlbytes -&gt; protocol version 1 and checksum is enabled 5 - 12 78b00a6500000000 Timestamp, seconds since 01.01.1970 00:00 UTC -&gt; 1,695,199,352 13 - 16 c8c7d030 Timestamp, Nanoseconds -&gt; 818,989,000 17 - 18 0e00 Length of the data block area in bytes -&gt; 14 bytes 18 - 21 01000001 Namespace + Tag -&gt; EMS.REQ_POWER_PV 22 00 Data type -&gt; None 23 - 24 0000 Length of the data block -&gt; Data type is <code>none</code>, therefore 0 25 - 28 02000001 Namespace + Tag -&gt; EMS.REQ_POWER_BAT 29 00 Data type -&gt; None 31-32 0000 Length of the data block -&gt; data type is <code>none</code>, therefore 0 33-36 4c769f09 CRC32 checksum <p>As a response we get the following frame:</p> <p>In human readable form: <pre><code>Timestamp:  2023-09-20T08:42:35.019685Z\nWithChecksum:   true\n    Tag:    EMS.POWER_PV - 01800001\n    Type:   INT32 - 06\n    Value:  4687 - 4f120000\n    Tag:    EMS.POWER_BAT - 01800002\n    Type:   INT32 - 06\n    Value:  2139 - 5b080000\n</code></pre></p> <p>In home power plant readable form: <pre><code>e3dc00117bb00a6500000000885e2c011600010080010604004f120000020080010604005b08000058156e18\n</code></pre></p> <p>And once disassembled:</p> Bytes Value Description 1 - 2 e3dc Magic Bytes 3 - 4 0011 Kontrolbytes -&gt; Protocol version 1 and checksum is activated 5 - 12 7bb00a6500000000 Timestamp, seconds since 01.01.1970 00:00 UTC -&gt; 1,695,199,355 13 - 16 885e2c01 Timestamp, Nanoseconds -&gt; 19,685,000 17 - 18 1600 Length of the data block area in bytes -&gt; 22 bytes 18 - 21 01008001 Namespace + Tag -&gt; EMS.POWER_PV 22 06 Data type -&gt; INT32 23 - 24 0400 Length of the data block -&gt; data type is <code>INT32</code>, therefore 4 bytes 25 - 28 4f120000 Actual value -&gt; data type is <code>INT32</code>, therefore 4,687 29 - 32 02008001 Namespace + Tag -&gt; EMS.POWER_BAT 33 06 Data type -&gt; INT32 34 - 35 0400 Length of the data block -&gt; data type is <code>INT32</code>, therefore 4 bytes 36 - 39 5b080000 Actual value -&gt; data type is <code>INT32</code>, therefore 2,139 40 - 43 58156e18 CRC32 checksume"},{"location":"rscp/frame-details/#namespaces","title":"Namespaces","text":"<p>E3DC has split all tags into different namespaces to create some overview. All namespaces known to me are documented in kdoc in the enum class <code>de.jnkconsulting.e3dc.easyrscp.api.frame.Namespace</code>.</p>"},{"location":"rscp/frame-details/#tags","title":"Tags","text":"<p>The multitude of tags is also documented in kdoc. Each namespace has its own enum class to ensure at least some overview.</p> <p>If I know anything about the structure and meaning of the tag, it is stored in kdoc. Partly E3DC has documented a little bit. If available, I have included the original E3DC documentation in kdoc and marked it with <code>Original E3DC Documentation:</code>. Once translated in English and once in German, as supplied by E3DC. </p> <p>Here you can find the tags TAG API.</p>"},{"location":"rscp/frame-details/#data-types","title":"Data types","text":"<p>The protocol defines a set of data types. These are documented in the enum class <code>de.jnkconsulting.e3dc.easyrscp.api.frame.DataType</code>.</p>"},{"location":"service/extension-points/","title":"Extension points","text":"<p>There are currently three ways to interfere with the operation of the service or lowlevel API.</p> <p>Listener \u2192 Are called at specific points in the request/response lifecycle</p> <p>FrameConverter \u2192 Read data from a response frame from the home power plant and convert the data into an object</p> <p>FrameCreator \u2192 Generates request frames to the home power plant</p>"},{"location":"service/extension-points/#listener","title":"Listener","text":"<p>For instances of type <code>ConnectionBuilder</code> any number of <code>RSCPRequestResponseListener</code> can be registered. These listeners are called at different points in the request-response cycle.</p> TypeScript <p>In TypeScript you can pass the listeners to the ConnectionFactory</p> KotlinJavaTypeScript <pre><code>val connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n.addRequestResponseListener(listener1, listener2)\n</code></pre> <pre><code>ConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n.addRequestResponseListener(listener1, listener2);\n</code></pre> <pre><code>const factory = new DefaultHomePowerPlantConnectionFactory(\nconnectionData,\naesFactory,\nsocketFactory,\nframeParser,\nlistenerArray\n)\n</code></pre> Please note <p>The listeners are only used if NO own instance of type <code>HomePowerPlantConnectionFactory</code> or <code>ConnectionPool</code> is configured at the Builder!</p>"},{"location":"service/extension-points/#request-response-lifecycle","title":"Request-/Response Lifecycle","text":"<pre><code>sequenceDiagram\n  autonumber\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onBeforeRequestFrameEncryption(event)\n  DefaultHomePowerPlantConnection-&gt;&gt;AESCipher: encrypt(frameBytes)\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onBeforeRequestSend(event)\n  DefaultHomePowerPlantConnection-&gt;&gt;HomePowerPlant: send(encryptedFrameBytes)\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onAfterRequestSend(event)\n  HomePowerPlant-&gt;&gt;DefaultHomePowerPlantConnection: sendAnswer(encryptedAnswerFrameBytes)\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onAnswerReceived(event)\n  DefaultHomePowerPlantConnection-&gt;&gt;AESCipher: decrypt(encryptedAnswerFrameBytes)\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onAnswerDecrypted(event)\n  DefaultHomePowerPlantConnection-&gt;&gt;FrameParser: parseRSCPFrame(decryptedAnswerBytes)\n  DefaultHomePowerPlantConnection-&gt;&gt;Listener: onAnswerParsed(event)</code></pre>"},{"location":"service/extension-points/#frameconverter","title":"FrameConverter","text":"<p>Each service offers the possibility to set its own <code>FrameConverter</code> instances. The builders offer corresponding functions here.</p> <p>A <code>FrameConverter</code> reads a response frame from the home power plant and converts it into a corresponding logical object. The service API already provides corresponding converters. Normally you don't need to do anything here. But if you want to influence the conversion process, you can create your own converter and set it as constructor parameter or via one of the builders.</p> <p>Here is an example how to set your own converter at the <code>InfoService</code>:</p> KotlinJavaTypeScript <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.Frame\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.tags.InfoTag\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.ProductionDate\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.SystemInfo\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.ConnectionBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.FrameConverter\nclass CustomConverter: FrameConverter&lt;SystemInfo&gt; {\noverride fun invoke(frame: Frame) =\nSystemInfo(\nserialNumber = frame.stringByTag(InfoTag.SERIAL_NUMBER),\nsoftwareVersion = frame.stringByTag(InfoTag.SW_RELEASE),\nproductionDate = ProductionDate(frame.stringByTag(InfoTag.PRODUCTION_DATE)),\n)\n}\nfun main() {\nval connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\nval builder = InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\n.withSystemInfoFrameConverter(CustomConverter())\n}\n</code></pre> <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.Frame;\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.tags.InfoTag;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.InfoService;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.ProductionDate;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.SystemInfo;\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.ConnectionBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.converter.FrameConverter;\npublic class CustomConverter implements FrameConverter&lt;SystemInfo&gt; {\n@Override\npublic SystemInfo invoke(Frame frame) {\nString serialNumber = frame.stringByTag(InfoTag.SERIAL_NUMBER);\nString softwareVersion = frame.stringByTag(InfoTag.SW_RELEASE);\nProductionDate productionDate = new ProductionDate(frame.stringByTag(InfoTag.PRODUCTION_DATE));\nreturn new SystemInfo(serialNumber, softwareVersion, productionDate);\n}\nprivate static String host = ...;\nprivate static String portalUser = ...;\nprivate static String portalPassword = ...;\nprivate static String rscpPassword = ...;\npublic static void main(String[] args) {\nConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\nInfoServiceBuilder infoServiceBuilder = new InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\n.withSystemInfoFrameConverter(new CustomConverter());    }\n}    </code></pre> <pre><code>import {FrameConverter, Frame} from 'easy-rscp';\nclass CustomConverter implements FrameConverter&lt;SystemInfo&gt; {\nconvert(frame: Frame): SystemInfo {\nconst serialNumber = frame.stringByTag(InfoTag.SERIAL_NUMBER);\nconst softwareVersion = frame.stringByTag(InfoTag.SW_RELEASE);\nconst productionDate = ... // parse production date\nreturn {\nserialNumber: serialNumber,\nsoftwareVersion: softwareVersion,\nproductionDate: productionDate,\n}\n}\n}    const service = new DefaultInfoService(\nconnection,\nnew RequestSystemInfosCreator(),\nnew CustomConverter()\n)\n</code></pre>"},{"location":"service/extension-points/#framecreator","title":"FrameCreator","text":"<p>Each service offers the possibility to set its own <code>FrameCreator</code> instances. The builders offer corresponding functions here.</p> <p>A <code>FrameCreator</code> creates request frames that are sent to the home power plant. The service API already provides corresponding creators. Normally you don't need to do anything here. But if you want to influence the creation process, you can create your own creator and set it as constructor parameter or via one of the builders.</p> <p>Here is an example of how to set your own creator on the <code>InfoService</code>:</p> KotlinJavaTypeScript <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.tags.InfoTag\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.ConnectionBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder\nimport de.jnkconsulting.e3dc.easyrscp.service.creator.FrameCreator\nclass CustomCreator: FrameCreator&lt;Nothing?&gt; {\noverride fun invoke(param: Nothing?) =\nFrameBuilder()\n.addData(\nDataBuilder().tag(InfoTag.REQ_MAC_ADDRESS).build(),\nDataBuilder().tag(InfoTag.REQ_PRODUCTION_DATE).build(),\nDataBuilder().tag(InfoTag.REQ_SERIAL_NUMBER).build(),\nDataBuilder().tag(InfoTag.REQ_SW_RELEASE).build()\n)\n.build()\n}\nfun main() {\nval connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\nval builder = InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\n.withRequestReadSystemInfoCreator(CustomCreator())\n}\n</code></pre> <pre><code>import de.jnkconsulting.e3dc.easyrscp.api.frame.Frame;\nimport de.jnkconsulting.e3dc.easyrscp.api.frame.tags.InfoTag;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.InfoService;\nimport de.jnkconsulting.e3dc.easyrscp.api.service.model.SystemInfo;\nimport de.jnkconsulting.e3dc.easyrscp.frame.DataBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.frame.FrameBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.ConnectionBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.builder.InfoServiceBuilder;\nimport de.jnkconsulting.e3dc.easyrscp.service.creator.FrameCreator;\npublic class CustomCreator implements FrameCreator&lt;Void&gt; {\n@Override\npublic Frame invoke(Void unused) {\nreturn new FrameBuilder()\n.addData(\nnew DataBuilder().tag(InfoTag.REQ_MAC_ADDRESS).build(),\nnew DataBuilder().tag(InfoTag.REQ_PRODUCTION_DATE).build(),\nnew DataBuilder().tag(InfoTag.REQ_SERIAL_NUMBER).build(),\nnew DataBuilder().tag(InfoTag.REQ_SW_RELEASE).build()\n)\n.build();\n}\nprivate static String host = ...;\nprivate static String portalUser = ...;\nprivate static String portalPassword = ...;\nprivate static String rscpPassword = ...;\npublic static void main(String[] args) {\nConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\nInfoServiceBuilder infoServiceBuilder = new InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\n.withRequestReadSystemInfoCreator(new CustomCreator());\n}\n}    </code></pre> <pre><code>import {FrameCreator, Frame, FrameBuilder, DataBuilder} from 'easy-rscp';\nclass CustomCreator implements FrameCreator&lt;undefined&gt; {\ncreate(input: undefined): Frame {\nreturn new FrameBuilder()\n.addData(\nnew DataBuilder().tag(InfoTag.REQ_MAC_ADDRESS).build(),\nnew DataBuilder().tag(InfoTag.REQ_PRODUCTION_DATE).build(),\nnew DataBuilder().tag(InfoTag.REQ_SERIAL_NUMBER).build(),\nnew DataBuilder().tag(InfoTag.REQ_SW_RELEASE).build()\n)\n.build();\n}\n}    const service = new DefaultInfoService(\nconnection,\nnew CustomCreator()\n)\n</code></pre>"},{"location":"service/general-concepts/","title":"General concept","text":"<p>The service API is based on the lowlevel API. Its goal is to hide all details of the RSCP interface behind service facades and to make working with the home power plant more logical.</p> You want more? <p>It should be noted that the RSCP interface is incredibly complex and only a very small part is currently used here. The expansion of the service API is planned and will be developed further. If you want to contribute here, have developed your own useful services, etc.: just create a PR or create a ticket with the title 'Maintainer'!</p> <p>Until then, the low-level API can be used. Here all RSCP possibilities are open to you.</p>"},{"location":"service/general-concepts/#service-creation","title":"Service creation","text":"<p>Generally, each service can be created simply with the constructor. Each service has exactly one mandatory parameter: The ConnectionPool. All other parameters are optional and have default values. Especially for the Java developers among you, the default parameters will not work because they are a Kotlin construct. Therefore, the use of the Builder API is recommended.</p> <p>For each service there is an own builder, which can create the service and if necessary allows to set the optional extension points. Each builder has a mandatory parameter. Namely an instance of the type <code>ConnectionBuilder</code> is needed. This creates the instances for encryption, connection setup etc. Don't worry, with the ConnectionBuilder it is sufficient to specify only the connection data. Everything else is optional. Here is an example:</p> TypeScript <p>The TypeScript versiond does not have the ServiceBuilder concept. You can create connections directly using the ConnectionFactory</p> KotlinJavaTypeScript <pre><code>val connectionBuilder = ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword)\n</code></pre> <pre><code>ConnectionBuilder connectionBuilder = new ConnectionBuilder()\n.withAddress(host)\n.withPortalUser(portalUser)\n.withPortalPassword(portalPassword)\n.withRSCPPassword(rscpPassword);\n</code></pre> <pre><code>const connectionData: E3dcConnectionData = {\naddress: host,\nport: 5033,\nportalUser: portalUser,\nportalPassword: portalPassword,\nrscpPassword: rscpPassword\n}\nconst factory = new DefaultHomePowerPlantConnectionFactory(connectionData)\nconst connection = await factory.openConnection()\n</code></pre> Parameter Description address IP address or DNS name of the home power plant portalUser Username. Corresponds to the username from the E3DC portal portalPassword Password. Corresponds to the password on the E3DC portal rscpPassword Encryption password. This value is configured directly at the home power plant and must be identical here <p>With this instance you can configure all other ServiceBuilders. This is the only mandatory information that is required.</p> KotlinJavaTypeScript <pre><code>val serviceBuilder = InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder)\nval service = serviceBuilder.buildService()\nval systemInfos = service.readSystemInfo()\nprintln(systemInfos)\n</code></pre> <pre><code>InfoServiceBuilder infoServiceBuilder = new InfoServiceBuilder()\n.withConnectionBuilder(connectionBuilder);\nInfoService service = infoServiceBuilder.buildService();\nSystemInfo infos = service.readSystemInfo();\nSystem.out.println(infos);\n</code></pre> <pre><code>const service = new DefaultInfoService(connection)\nservice.readSystemInfo()\n.then(systemInfos =&gt; console.log(systemInfos)\n</code></pre>"},{"location":"service/general-concepts/#extension-points","title":"Extension points","text":"<p>The service API provides several points where you can intervene in the way it works. The details are described in the section Extension points.</p>"},{"location":"service/general-concepts/#logging-kotlinjava-only","title":"Logging (Kotlin/Java only)","text":"<p>easy-rscp uses internally SLF4J as logging framework. You may have already noticed that you get the following warning when running the examples:</p> <pre><code>SLF4J: No SLF4J providers were found.\nSLF4J: Defaulting to no-operation (NOP) logger implementation\nSLF4J: See https://www.slf4j.org/codes.html#noProviders for further details.\n</code></pre> <p>This is because easy-rscp does not provide a logging provider. Depending on which logging framework you use (Log4j, java logging, or whatever), you have to declare the corresponding provider implementation as a dependency. SLF4J provides instructions on what to do at the link https://www.slf4j.org/codes.html#noProviders.</p> Why another dependency? <p>Normally you will not need the log messages from easy-rscp. But it can be helpful for debugging. easy-rscp logs only on debug,  trace or error level to avoid too much noise. We don't want to impose a logging framework on you, so we use SLF4J to abstract the framework. You have the choice!</p>"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 5bfd01afd213d98de9bacaf6aecfc072375e95c5..a273ca45ade9f68429a4514773d7c3ab85900d46 100644
GIT binary patch
delta 15
WcmaFM^p=TDzMF%i|Nlm|bVdLy`~^$^

delta 15
WcmaFM^p=TDzMF&N(w~iN>5Kp_e+7&H