[evcc] Add channels for grid currents, grid energy and charging currents.

[marcelGoerentz]

Enhancement for evcc binding:

• Add channels for grid currents and energy
• Add channels for charging currents
• Add some enhancements

[marcelGoerentz]

@lsiepel Can you check the unit tests I've added? If they are fine I will add tests for the handlers

[lsiepel]

Thanks. Especially for attempting to write tests. They look good. When you write more and more you probably refactor and perform some code de-duplication. As that is what i'm experiencing over and over again. :-)

[marcelGoerentz]

I will add more tests as soon as possible

[lsiepel]

Marked this as draft, please change ready to review when you are done.

[marvkis]

Hi Marcel,

thank you for your work on this!

I'm quite new to evcc (but using OH for quite some time ;)) and thought: hey, use this new version of the plugin ;)
(Background: I get a new smart meter gateway due to a new heat pump and I want to use evcc for eebus communication and power dimming).

During my migration I stumbled over an issue with the value in limitEnergy on a loadPoint vanishing / not reflecting the value shown in evcc.

So I started digging into it, and compiled it myself for debugging.

After installing my self-compiled own addon, I got this exception:

2025-10-12 11:59:10.349 [WARN ] [c.internal.handler.EvccBridgeHandler] - Listener evcc:loadpoint:kis:go-e-garage-1 couldn't parse evcc state
java.lang.UnsupportedOperationException: null
        at java.util.ImmutableCollections.uoe(ImmutableCollections.java:142) ~[?:?]
        at java.util.ImmutableCollections$AbstractImmutableCollection.add(ImmutableCollections.java:147) ~[?:?]
        at org.openhab.binding.evcc.internal.handler.EvccBaseThingHandler.updateStatesFromApiResponse(EvccBaseThingHandler.java:288) ~[?:?]
        at org.openhab.binding.evcc.internal.handler.EvccLoadpointHandler.prepareApiResponseForChannelStateUpdate(EvccLoadpointHandler.java:120) ~[?:?]
        at org.openhab.binding.evcc.internal.handler.EvccBridgeHandler.notifyListeners(EvccBridgeHandler.java:153) ~[?:?]
        at org.openhab.binding.evcc.internal.handler.EvccBridgeHandler.lambda$3(EvccBridgeHandler.java:120) ~[?:?]
        at java.util.Optional.ifPresent(Optional.java:178) ~[?:?]
        at org.openhab.binding.evcc.internal.handler.EvccBridgeHandler.lambda$2(EvccBridgeHandler.java:118) ~[?:?]
        at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:572) ~[?:?]
        at java.util.concurrent.FutureTask.runAndReset(FutureTask.java:358) ~[?:?]
        at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:305) ~[?:?]
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1144) ~[?:?]
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:642) ~[?:?]
        at java.lang.Thread.run(Thread.java:1583) [?:?]

Okay, you try to modify the list returned in EvccBaseThingHandler.java#L282 - which is immutable by nature ;)
I changed this locally to have clone of the original list: List<Channel> channels = new ArrayList<>(getThing().getChannels());

Now the addon was able to start and things worked again ;)

Next I added some debugging output to see what happens with the value. This is what was shown:

2025-10-12 13:24:35.142 [TRACE] [nternal.handler.EvccBaseThingHandler] - State for Channel 'evcc:loadpoint:kis:go-e-garage-1:loadpoint-limit-energy' type `ItemTypeUnit@0x23cfa8d8{unit: Wh; unitHint: kWh; itemType: Number:Energy}`: json: 5, finalValue: 5.0

The value is here - but the unit's are not matching. And yes, looking on the item value - the 2.5 Wh are here, but we need kWh ;)

I have seen there is already some handling for unit mismatches in EvccBaseThingHandler.java#L223 and so I added

@@ -221,9 +222,13 @@ public abstract class EvccBaseThingHandler extends BaseThingHandler implements E
             case NUMBER_LENGTH:
             case NUMBER_POWER:
                 Double finalValue = "%".equals(itemTypeUnit.unitHint) ? value.getAsDouble() / 100 : value.getAsDouble();
-                if (channelUID.getId().contains("capacity") || "km".equals(itemTypeUnit.unitHint)) {
+                if (channelUID.getId().contains("capacity") || "km".equals(itemTypeUnit.unitHint)
+                        || ("kWh".equals(itemTypeUnit.unitHint) && Units.WATT_HOUR.equals(itemTypeUnit.unit))) {
                     updateState(channelUID, new QuantityType<>(finalValue, itemTypeUnit.unit.multiply(1000)));
                 } else if ("Wh".equals(itemTypeUnit.unitHint)) {

And now it works for me (tm) ;-)

I havent tracked down why unit and unitHint differs. But maybe it would be worth to align it or to maintain unit's matching the UnitHint?

Thanks & Bye,
Chris

[marvkis]

Hi Marcel,

now I stumbled over a Channel/Item where it is the other way:

2025-10-12 13:59:55.591 [TRACE] [nternal.handler.EvccBaseThingHandler] - State for Channel 'evcc:loadpoint:kis:go-e-garage-1:loadpoint-session-energy' type `ItemTypeUnit@0x424a6971{unit: Wh; unitHint: kWh; itemType: Number:Energy}`: json: 52.767, finalValue: 52.767

It seems this value is really ment as Wh by evcc. Do you have a list which unit is used for each value provided by evcc?

bye,
Chris

[marcelGoerentz]

@marvkis Thanks for the input.
Can you send me the payload you get from the evcc api/state?

[marcelGoerentz]

Hi Marcel,

now I stumbled over a Channel/Item where it is the other way:

2025-10-12 13:59:55.591 [TRACE] [nternal.handler.EvccBaseThingHandler] - State for Channel 'evcc:loadpoint:kis:go-e-garage-1:loadpoint-session-energy' type `ItemTypeUnit@0x424a6971{unit: Wh; unitHint: kWh; itemType: Number:Energy}`: json: 52.767, finalValue: 52.767

It seems this value is really ment as Wh by evcc. Do you have a list which unit is used for each value provided by evcc?

bye, Chris

In the latest version everything is running fine. The session energy was at 270Wh and in openHAB it was displayed as 0.27kWh.
Can you please verify that there is an issue with the latest code?
That would be very helpful :)

[marvkis]

Hi Marcel,

Sorry for the late reply – I had Covid.

@marvkis Thanks for the input.
Can you send me the payload you get from the evcc api/state?

Here is my state.json file with the relevant values: state-loadlimit.json

Here a fragment with the values from loadpoints[1]:

...
            "limitEnergy": 5,
            "limitSoc": 0,
...            
            "sessionCo2PerKWh": 72.848,
            "sessionEnergy": 2033.189,
...

Let's start with loadpoints[1].limitEnergy - which shows a 5 here. This 5 should be read as 5 kWh, but it will show up as 5 Wh on the OH-channel/item.

This is why I mode the change in EvccBaseThingHandler.java#L223, as mentioned in my previous post.

After making this change I noted that sessionEnergy was displaying the incorrect 'power' value (in mathematical sense) as this value should be interpreted in Wh and not kWh.

I think the unitHint for point-session-energy in loadpoint.xml#L622 should be changed from kWh to Wh.

Having briefly viewed the JSON and the loadpoint.xml it also seems that the unit for loadpoint-charged-energy should be changed.

I believe that the adjusting the kWh calculation could reveal several more such (kilo-) mismatches.

I hope you can understand where my original problem lay and why I am suggesting this change.

thanks & bye,
chris

[marcelGoerentz]

Oh I hope you feel we'll again.

I see what you mean. I will take a deeper look into it. Probably you are right that there will be less calculation to do when I'm matching the values unit and the unit hints. I think I wanted the values to be congruent.

I will see what I can do. Unfortunately there is no documentation from evcc which unit each data point has.

[lsiepel]

Just for the record. The unitHint is only there for the presentation in the openHAB domain. It does not have any effect in the read value from the evcc api. UoM is in between. When reading the value from the API and updating the channel one should know the value /precision

[marvkis]

Hi @lsiepel , thanks for pointing this out - I wasn't aware of that. Using it as a hint for API precision doesn't seem like a good idea anymore. Is there any way to specify a 'custom' channel attribute that can be used as the 'unit used by the API'?

[marcelGoerentz]

Since the channels are getting created dynamically, what would be a smart way to get the correct UoM for the values? Right now I'm using the unit hints as a hint to the UoM.

[lsiepel]

Well it depends about every API provides this. Usually three ways they do this:

1. documentation about the unit/precision for every data item
2. Enclosed in the data item itself (e.g. 1,312 kWh)
3. By some additional metadata item provided by the api.

You can also use a mapping file and provide it yourself, but I don’t think you want that here.

Does that provide enough information to continue?

[marcelGoerentz]

Hmm, unfortunately there is no documentation about the units and they are also not enclosed.

I guess I have to define a file myself.
Any recommendations on file the file type? YAML or JSON or any other?

[lsiepel]

Left two comments to look at.

I would prefer to have some test confirmations due to the extend of this PR. Maybe provide a jar to the community or otherwise. Ping me when both tests and comments are addressed.

[marcelGoerentz]

Done

[lsiepel]

Done

Only after Spotless ;-)

[marcelGoerentz]

Done

Only after Spotless ;-)

Nooooooooo, sorry for that. Now I'm done 😄

[lsiepel]

Thanks for providing this PR. LGTM

I'll merge when you let me know this has been tested enough.

[marcelGoerentz]

On my site it is running well just waiting for some responses of the community.
@marvkis looking forward to your report

[marvkis]

Hi @marcelGoerentz ,

Thanks for all your work! I've tested the latest version, and limitEnergy looks good now!

But it seems the precision for chargeTotalImport is wrong now. For my charger it seems to deliver full kWh, but in OH the value is imported as Wh (Compared with the readings from the Charger itself - I currently cannot find where this value is shown in evcc).
Can you double check? As I'm not able to find a visualization within evcc, it might also be that the API between evcc and my charger is broken...
(I've recently updated evcc from 0.209.1 -> 0.209.6 - not sure if they changed the precision of chargeTotalImport or I just didn't notice before)

/Chris

[marvkis]

Hi @marcelGoerentz,

I've found where it's shown in evcc: It's hidden in the config view for the charger. And here it is also visualized as kWh - so it seems chargeTotalImport should be interpreted as kWh

/chris

[marcelGoerentz]

Hi @marvkis ,
Thanks again for your input.
You are right, imported energy needs to be in kWh also. I will fix this with the next commit. This is a no brainer, since I only need to adapt the StateResolver again.

[marvkis]

Hi @marcelGoerentz ,

thanks for the update. When I try to install the addon I get this excpetion:

2025-11-02 09:50:55.541 [WARN ] [re.xml.osgi.XmlDocumentBundleTracker] - The XML document '/OH-INF/thing/site.xml' in module 'org.openhab.binding.evcc' could not be parsed:
---- Debugging information ----
cause-exception     : java.lang.IllegalArgumentException
cause-message       : A unit hint must not be set if the item type is not a number with dimension!
class               : org.openhab.core.thing.xml.internal.ChannelTypeXmlResult
required-type       : org.openhab.core.thing.xml.internal.ChannelTypeXmlResult
converter-type      : org.openhab.core.thing.xml.internal.ChannelTypeConverter
path                : /thing-descriptions/channel-type[30]
line number         : 322
class[1]            : java.util.ArrayList
required-type[1]    : java.util.ArrayList
converter-type[1]   : com.thoughtworks.xstream.converters.collections.CollectionConverter
class[2]            : org.openhab.core.thing.xml.internal.ThingDescriptionList
required-type[2]    : org.openhab.core.thing.xml.internal.ThingDescriptionList
converter-type[2]   : org.openhab.core.thing.xml.internal.ThingDescriptionConverter
version             : 1.4.21
-------------------------------
com.thoughtworks.xstream.converters.ConversionException:
---- Debugging information ----
cause-exception     : java.lang.IllegalArgumentException                                                                                                                                 [36/1847]
cause-message       : A unit hint must not be set if the item type is not a number with dimension!
class               : org.openhab.core.thing.xml.internal.ChannelTypeXmlResult
required-type       : org.openhab.core.thing.xml.internal.ChannelTypeXmlResult
converter-type      : org.openhab.core.thing.xml.internal.ChannelTypeConverter
path                : /thing-descriptions/channel-type[30]
line number         : 322
class[1]            : java.util.ArrayList
required-type[1]    : java.util.ArrayList
converter-type[1]   : com.thoughtworks.xstream.converters.collections.CollectionConverter
class[2]            : org.openhab.core.thing.xml.internal.ThingDescriptionList
required-type[2]    : org.openhab.core.thing.xml.internal.ThingDescriptionList
converter-type[2]   : org.openhab.core.thing.xml.internal.ThingDescriptionConverter
version             : 1.4.21
-------------------------------
        at com.thoughtworks.xstream.core.TreeUnmarshaller.convert(TreeUnmarshaller.java:81) ~[?:?]
        at com.thoughtworks.xstream.core.AbstractReferenceUnmarshaller.convert(AbstractReferenceUnmarshaller.java:72) ~[?:?]
        at com.thoughtworks.xstream.core.TreeUnmarshaller.convertAnother(TreeUnmarshaller.java:68) ~[?:?]
        at com.thoughtworks.xstream.core.TreeUnmarshaller.convertAnother(TreeUnmarshaller.java:52) ~[?:?]
        at com.thoughtworks.xstream.converters.collections.AbstractCollectionConverter.readBareItem(AbstractCollectionConverter.java:132) ~[?:?]
        at com.thoughtworks.xstream.converters.collections.AbstractCollectionConverter.readItem(AbstractCollectionConverter.java:117) ~[?:?]
        at com.thoughtworks.xstream.converters.collections.CollectionConverter.addCurrentElementToCollection(CollectionConverter.java:99) ~[?:?]
        at com.thoughtworks.xstream.converters.collections.CollectionConverter.populateCollection(CollectionConverter.java:92) ~[?:?]
        at com.thoughtworks.xstream.converters.collections.CollectionConverter.populateCollection(CollectionConverter.java:86) ~[?:?]
        at com.thoughtworks.xstream.converters.collections.CollectionConverter.unmarshal(CollectionConverter.java:81) ~[?:?]                                                             [19/1854]
        at com.thoughtworks.xstream.core.TreeUnmarshaller.convert(TreeUnmarshaller.java:74) ~[?:?]
        at com.thoughtworks.xstream.core.AbstractReferenceUnmarshaller.convert(AbstractReferenceUnmarshaller.java:72) ~[?:?]
        at com.thoughtworks.xstream.core.TreeUnmarshaller.convertAnother(TreeUnmarshaller.java:68) ~[?:?]
        at com.thoughtworks.xstream.core.TreeUnmarshaller.convertAnother(TreeUnmarshaller.java:52) ~[?:?]
        at org.openhab.core.thing.xml.internal.ThingDescriptionConverter.unmarshal(ThingDescriptionConverter.java:56) ~[?:?]
        at com.thoughtworks.xstream.core.TreeUnmarshaller.convert(TreeUnmarshaller.java:74) ~[?:?]
        at com.thoughtworks.xstream.core.AbstractReferenceUnmarshaller.convert(AbstractReferenceUnmarshaller.java:72) ~[?:?]
        at com.thoughtworks.xstream.core.TreeUnmarshaller.convertAnother(TreeUnmarshaller.java:68) ~[?:?]
        at com.thoughtworks.xstream.core.TreeUnmarshaller.convertAnother(TreeUnmarshaller.java:52) ~[?:?]
        at com.thoughtworks.xstream.core.TreeUnmarshaller.start(TreeUnmarshaller.java:136) ~[?:?]
        at com.thoughtworks.xstream.core.AbstractTreeMarshallingStrategy.unmarshal(AbstractTreeMarshallingStrategy.java:32) ~[?:?]
        at com.thoughtworks.xstream.XStream.unmarshal(XStream.java:1468) ~[?:?]
        at com.thoughtworks.xstream.XStream.unmarshal(XStream.java:1445) ~[?:?]
        at com.thoughtworks.xstream.XStream.fromXML(XStream.java:1393) ~[?:?]
        at com.thoughtworks.xstream.XStream.fromXML(XStream.java:1345) ~[?:?]
        at org.openhab.core.config.core.xml.util.XmlDocumentReader.readFromXML(XmlDocumentReader.java:106) ~[?:?]
        at org.openhab.core.config.core.xml.osgi.XmlDocumentBundleTracker.parseDocuments(XmlDocumentBundleTracker.java:394) ~[?:?]
        at org.openhab.core.config.core.xml.osgi.XmlDocumentBundleTracker.processBundle(XmlDocumentBundleTracker.java:380) ~[?:?]
        at org.openhab.core.config.core.xml.osgi.XmlDocumentBundleTracker$2.run(XmlDocumentBundleTracker.java:345) ~[?:?]
        at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:572) ~[?:?]
        at java.util.concurrent.FutureTask.run(FutureTask.java:317) ~[?:?]
        at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:304) ~[?:?]
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1144) ~[?:?]
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:642) ~[?:?]
        at java.lang.Thread.run(Thread.java:1583) [?:?]
Caused by: java.lang.IllegalArgumentException: A unit hint must not be set if the item type is not a number with dimension!
        at org.openhab.core.thing.type.ChannelType.<init>(ChannelType.java:88) ~[?:?]
        at org.openhab.core.thing.internal.type.StateChannelTypeBuilderImpl$StateChannelTypeImpl.<init>(StateChannelTypeBuilderImpl.java:46) ~[?:?]
        at org.openhab.core.thing.internal.type.StateChannelTypeBuilderImpl.build(StateChannelTypeBuilderImpl.java:93) ~[?:?]
        at org.openhab.core.thing.xml.internal.ChannelTypeConverter.unmarshalType(ChannelTypeConverter.java:240) ~[?:?]
        at org.openhab.core.thing.xml.internal.ChannelTypeConverter.unmarshalType(ChannelTypeConverter.java:1) ~[?:?]
        at org.openhab.core.thing.xml.internal.AbstractDescriptionTypeConverter.unmarshal(AbstractDescriptionTypeConverter.java:193) ~[?:?]
        at com.thoughtworks.xstream.core.TreeUnmarshaller.convert(TreeUnmarshaller.java:74) ~[?:?]
        ... 34 more

I think it is related to this change: 701b164#diff-33f058b22b270592f6020bb2ab248034e02ae4816d0cc9240c8180a4dc58492b

shouldn't it be Number:Time there?

I've fixed it locally. Now it loads again, but the chargeTotalImport still shows the wrong precision.
I digged into it and found: in my state json it shows: "chargeTotalImport":9720 - it seems there is no fraction.
When i'm right || lowerKey.contains("import") has to be added to StateResolver.java:25.

Last but not least a new one from the openhab log i've noticed:

2025-11-02 10:01:17.107 [WARN ] [ui.internal.items.ItemUIRegistryImpl] - Exception while formatting value 'OFF' of item EVCC_C1_Charging_State with format '%f %unit%': Conversion = 'u'

When i'm right removing the pattern="%f %unit%" part in loadpoint.xml:197 should solve this.

Thanks for all!

/chris

[marcelGoerentz]

You are completely right in everything you mentioned. I added your suggestions. Thanks again. The one with the Loadpoint is an old one, I don't know why it didn't come up to me earlier...

[marvkis]

@marcelGoerentz It looks good now from my side!
@lsiepel we are ready to merge ;)

Thanks @marcelGoerentz for all your work!

/chris

[marcelGoerentz]

For those who want to test the latest version:
https://github.com/marcelGoerentz/openhab-addons/releases/tag/evcc_binding_release_1.3

[marvkis]

Hi @marcelGoerentz ,

i've updated to your .jar and it seems the limitEnergy broke again - still investigating...

/chris

[marvkis]

I added a comment where i think limitEnergy broke: marcelGoerentz@701b164#r169449282

[marcelGoerentz]

Ah yeah, that happens when I do something different than before, I missed that special case.

[marcelGoerentz]

I've updated the jar files in the link. Energy limit is now fixed.

[marvkis]

Hi,

I just tested the latest jar - LGTM now ;)

/chris

[lsiepel]

Thanks, LGTM