Integrating Kostal Inverter using httpbinding and json

Bernd_Ritter · July 31, 2019, 3:36am

Kostal Inverters with older firmware can be integrated into OpenHab with the Kostal Inverter Binding:

At some point, Kostal have changed the firmware and the “old” binding does not work with the latest firmwares/models.
There is a new binding in development:

But you can also integrate your Kostal inverter without the special kostal binding. You just need the “HTTP Binding” and “JSONPath Transformation”.

Let’s have a look on how this can be done:
With the new firmware, you can get the values from your Kostal inverter via json.
You just have to call like this:

http://<IP_Of_Kostal_Inverter>/api/dxs.json?dxsEntries=33556736

The last part called “dxsEntries” is the interesting part. This specifies which value we want to get from the Kostal inverter.

If you want to get more than one value, you can combine “dxsEntries” like this:

http://<IP_Of_Kostal_Inverter>/api/dxs.json?dxsEntries=33556736&dxsEntries=67109120&dxsEntries=83888128&dxsEntries=33556229

So how do we find out which dxEntries values are available?
I opened the webinterface of my Kostal Inverter using Mozilla Firefox and then used the “network analysis view” to see which “dxsEntries” are used in the json calls.
So I figured out all values used for my Kostal PIKO 6.0 BA with 2 strings:

Home
|
|-Power Values
  -Total DC input [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33556736
  -Output power [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67109120
  -Self-consumption [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=83888128
|
|-Battery
  -Charging status [%][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33556229
|
|-Status
  -Operating status [integer] --> http://192.168.178.21/api/dxs.json?dxsEntries=16780032


Current values
|
|-PV Generator
  |-DC input 1
    -Voltage [V][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33555202
    -Current [A][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33555201
    -Power [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33555203
  |-DC input 2
    -Voltage [V][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33555458
    -Current [A][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33555457
    -Power [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33555459
|
|-Battery
  -Voltage [V][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33556226
  -Charging status [%][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33556229
  -Charging [A][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33556238
  Note: Charge/discharge status is 0=charge,1=discharge [integer] --> http://192.168.178.21/api/dxs.json?dxsEntries=33556230
  -Charge cycles [integer] --> http://192.168.178.21/api/dxs.json?dxsEntries=33556228
  -Temperature [degree celcius][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=33556227
|
|-House
  |-Home consumption covered by
    -Solar generator [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=83886336
    -Battery [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=83886592
    -Grid [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=83886848
  |-Phase selective home consumption
    -Phase 1 [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=83887106
    -Phase 2 [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=83887362
    -Phase 3 [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=83887618
|
|-Grid
  |-Grid parameters
    -Output power [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67109120
    -Grid frequency [Hz][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67110400
    -Cos φ [double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67110656
    -Limitation on [%][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67110144
  |-Phase 1
    -Voltage [V][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67109378
    -Current [A][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67109377
    -Power [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67109379
  |-Phase 2
    -Voltage [V][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67109634
    -Current [A][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67109633
    -Power [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67109635
  |-Phase 3
    -Voltage [V][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67109890
    -Current [A][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67109889
    -Power [W][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=67109891
|
|-Analog inputs
  -Analoginput 1 [V][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=167772417
  -Analoginput 2 [V][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=167772673
  -Analoginput 3 [V][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=167772929
  -Analoginput 4 [V][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=167773185
|
|-S0 input
  -Number of energy pulses (S0-in) [no unit/s][integer/integer] --> http://192.168.178.21/api/dxs.json?dxsEntries=184549632&dxsEntries=150995968


Statistics
|
|-Day
  -Yield [Wh][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=251658754
  -Home-consumption [Wh][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=251659010
  -Self-consumption [Wh][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=251659266
  -Self-consumption rate [%][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=251659278
  -Degree of self-sufficiency [%][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=251659279
|
|-Total
  -Yield [kWh][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=251658753
  -Home-consumption [kWh][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=251659009
  -Self-consumption [kWh][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=251659265
  -Self-consumption rate [%][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=251659280
  -Degree of self-sufficiency [%][double] --> http://192.168.178.21/api/dxs.json?dxsEntries=251659281
  -Operation time [h][integer] --> http://192.168.178.21/api/dxs.json?dxsEntries=251658496

Now that we know all the values we want to get, how do we integrate that into Openhab?
This can be done using the “http binding” and “JSONPath Transformation”.
So you go to PaperUI of your Openhab installation, go to “Add-Ons”, click on “bindings”, search for “HTTP Binding” and install it.
Then you click on “transformations”, search for “json” and install the “JSONPath Transformation”.

Now we can create a http.cfg file. You can find an empty http.cfg file on your Openhab installtion. E.g. on my Raspberry Pi, it is in the folder:
\openhabianpi\openhab-conf\services

For every cache item, we can specify an URL and an update interval:

# configuration of the first cache item  
#<id1>.url=
#<id1>.updateInterval=

So for our Kostal inverter, we add values like this:

kostalCache.url=http://192.168.178.21/api/dxs.json?dxsEntries=33556736&dxsEntries=67109120&dxsEntries=83888128&dxsEntries=33556229&dxsEntries=16780032&dxsEntries=33555202&dxsEntries=33555201&dxsEntries=33555203&dxsEntries=33555458&dxsEntries=33555457&dxsEntries=33555459&dxsEntries=33556226&dxsEntries=33556238&dxsEntries=33556230&dxsEntries=33556228&dxsEntries=33556227&dxsEntries=83886336&dxsEntries=83886592&dxsEntries=83886848&dxsEntries=83887106&dxsEntries=83887362&dxsEntries=83887618&dxsEntries=67110400&dxsEntries=67110656&dxsEntries=67110144
kostalCache.updateInterval=60000

Unfortunately, there seems to be a limitation on how many values you can get with one cache item. It worked only with 25 items for me, so I had to make several cache items in the http.cfg to get all the values from my kostal:

# configuration of the first cache item
kostalCache.url=http://192.168.178.21/api/dxs.json?dxsEntries=33556736&dxsEntries=67109120&dxsEntries=83888128&dxsEntries=33556229&dxsEntries=16780032&dxsEntries=33555202&dxsEntries=33555201&dxsEntries=33555203&dxsEntries=33555458&dxsEntries=33555457&dxsEntries=33555459&dxsEntries=33556226&dxsEntries=33556238&dxsEntries=33556230&dxsEntries=33556228&dxsEntries=33556227&dxsEntries=83886336&dxsEntries=83886592&dxsEntries=83886848&dxsEntries=83887106&dxsEntries=83887362&dxsEntries=83887618&dxsEntries=67110400&dxsEntries=67110656&dxsEntries=67110144
kostalCache.updateInterval=60000

# configuration of the second cache item 
kostalCache2.url=http://192.168.178.21/api/dxs.json?dxsEntries=67109378&dxsEntries=67109377&dxsEntries=67109379&dxsEntries=67109634&dxsEntries=67109633&dxsEntries=67109635&dxsEntries=67109890&dxsEntries=67109889&dxsEntries=67109891
kostalCache2.updateInterval=60000

# configuration of the third cache item  (These are the statistics. We set a longer updateInterval for this.)
kostalCache3.url=http://192.168.178.21/api/dxs.json?dxsEntries=251658754&dxsEntries=251659010&dxsEntries=251659266&dxsEntries=251659278&dxsEntries=251659279&dxsEntries=251658753&dxsEntries=251659009&dxsEntries=251659265&dxsEntries=251659280&dxsEntries=251659281&dxsEntries=251658496
kostalCache3.updateInterval=3600000

Now we can create an items file, using the items from the http cache, e.g.:

Number Kostal_TotalDcInput "DC-Eingang Gesamt [%.1f W]" { http="<[kostalCache:60000:JSONPATH($.dxsEntries[0].value)]"}
Number Kostal_OutputPower "Ausgangsleistung [%.1f W]" { http="<[kostalCache:60000:JSONPATH($.dxsEntries[1].value)]" }
Number Kostal_SelfConsumption "Eigenverbrauch [%.1f W]" { http="<[kostalCache:60000:JSONPATH($.dxsEntries[2].value)]" }
Number Kostal_BatteryStatus "Ladezustand [%.1f %%]" { http="<[kostalCache:60000:JSONPATH($.dxsEntries[3].value)]" }
Number Kostal_OperatingStatus "Betriebsstatus [%d]" { http="<[kostalCache:60000:JSONPATH($.dxsEntries[4].value)]" }

Please find my http.cfg, items file and sitemap file attached.
I had to rename the files to .txt, to be able to upload them.
So you have to rename them back to “http.cfg”, “kostal.items” and “kostal.sitemap”.

Place the “http.cfg” in the folder “\openhabianpi\openhab-conf\services”.
Place the “kostal.items” in the folder “\openhabianpi\openhab-conf\items”.
Place the “kostal.sitemap” in the folder “\openhabianpi\openhab-conf\sitemaps”.

Now you can see all the values available via the webinterface of your Kostal inverter in openHab in the basic UI

Best Regards
Bernd
http_cfg.txt (1.7 KB) kostal_items.txt (5.3 KB) kostal_sitemap.txt (2.7 KB)

geraldus · October 5, 2019, 1:30pm

Hi,
I think, the api has changed again. I have a plenticore 8.5 from kostal and the url with the api call to dxs.json not longer works.
I can see the new api if I called http:///api/v1/

Bernd_Ritter · October 5, 2019, 7:18pm

So is it just the url that is different? All the other stuff is still valid?

Regards
Bernd

geraldus · October 6, 2019, 10:19am

No, I think the whole api has changed. I get no response (404) with the old URL.
But I’m not shure, if the new api is public, because I could not find any documentation about it.
If you call the new url you get a swagger description about the possible calls
Especially the authenticalion is not self explained.

GuidoDirkes · January 1, 2021, 4:26pm

Thanks for your hints concerning the option to bind the Kostal Inverter using http binding and json.
It tool me some time to transfer the information to OH3 therefore I will take the liberty to add it here:

In the Thing configuration the “Base url” field gets “http://192.168.178.21/api/dxs.json?dxsEntries=67109378&dxsEntries=67109634” with all the chosen ids as described in the original post.
In the Channel configuration the “State Transformation” gets “JSONPATH:$.dxsEntries[0].value” expression.
Finally you link your items, where you might use e.g. the map transformation to map the operation mode (“Betriebsstatus” in German) 0 --> off, …

hafniumzinc · January 1, 2021, 5:45pm

Another option, if you prefer, is to perform the transformation at the Channel itself - you can chain transformations in the new OH3 HTTP Binding! Here’s what one of my transformations looks like - from an unrelated project - which first extracts the value from JSON, and then sends it through to the MAP transform.

JSONPATH:$.SiteRep.DV.Location.Period[0].Rep[0].W∩MAP:weathertype.map