APsystems EZ1 Local API Binding

deibich · May 11, 2024, 8:38pm

This binding utilizes the local API of EZ-1 inverters from APsystems.

To make the binding work, the inverter must be put into local mode. With the known IP address of the inverter, a Thing can be created. The API endpoints are mapped to channels for current power, energy production, status, and error messages.

The Readme for this binding is available here.

Changelog

Version 0.5

Change default polling interval to 20 seconds
endpoint for on/off status responds with status not state
Check if response from inverter was successful
Log trace raw response from inverter

Version 0.4 - Breaking change

Rename dto variable and Thing channel from state to status.

The thing definition changed. You have to recreate the inverter Thing and link your items against the new Thing.

Version 0.3

Rename thing config variable for refresh interval
Increase request timeout

Version 0.2

Fixed Offgrid Error channel mapping

Version 0.1

initial release

Resources

org.openhab.binding.apsystemsez1-4.2.0-SNAPSHOT.jar

Source

Releases

Mario75 · May 22, 2024, 9:41am

Hi,
I just installed your binding and I like it a lot.
So far I have manual created Items and a rule that was using HttpGetRequest to parse the result to the Items.
Problem:
I noticed that chaning the “Refresh Interval” has not effect, like 60 seconds.
The polling seems to be every 10 seconds as can be seen in the log.

My system:

runtimeInfo:
version: 4.1.2
buildString: Release Build
locale: de-DE
systemInfo:
javaVersion: 17.0.10
javaVendor: Raspbian
osName: Linux
osVersion: 6.1.21-v8+
osArchitecture: arm

I did some code inspection in the source and I found some naming differences:

in the “thing-types.xml” file the Refresh Interval is named “refreshInterval”
same naming in “apsystemsez1.properties”
BUT in “APsystemsEZ1Configuration.java” it is named “refreshIntervalSeconds”
this “refreshIntervalSeconds” is also used in " APsystemsEZ1Handler.java"

I have no clue how to make the changes to the files and get a running version, sorry for that.

Thanks a lot.
Mario

LukaNoah · May 22, 2024, 5:13pm

Great, thank you very much for the binding. I’m testing it.
The time interval is not changed for me either. Polling takes place every 10s, I set it to 20s.
Every 1 to 2 minutes my thing times out for a query cycle.

deibich · May 22, 2024, 7:03pm

Thank you for testing the binding!

Forgot to rename the config files. Thank you for the hint. v0.3 should fix this.

A timeout should only occur if there is an issue with the network. At least, that’s what I think. It hasn’t happened for me so far. Nevertheless, I have increased the timeout for all requests to 2 seconds. Please let me know whether it works or not.

LukaNoah · May 23, 2024, 12:22pm

Hi, the timeout no longer occurred for me. Now the refresh also works at the set interval.
However, the Output Power State always remains OFF.

deibich · May 23, 2024, 7:59pm

Thank you for the hint. A wrong key was set when parsing the response. I renamed state to status to better reflect the API responses. Should work now.
You need to unlink the item and link against the renamed channel “device#status”.

LukaNoah · May 23, 2024, 8:58pm

Thanks for the update.
The previous status channel has disappeared, but the new one does not appear.
Wouldn’t it make sense to set the thing status to offline when the device status is off? Comm error is a bit confusing.

deibich · May 23, 2024, 9:39pm

I think, because I changed the thing definition, you have to recreate the Thing to make the channel appear. Watch out to link your items after recreating the Thing. Sorry.

The Thing is offline with “communication error” as status detail because I can’t deduce the reason why the inverter is not reachable.

Problem: The inverter (EZ1-M in my case) is not powered from the grid but from the solar panels and shuts down if there is not enough power. → No Bluetooth and no Wifi on rainy days or after sunset.

If the inverter is not available in the network we get a communication error. But the binding does not know why the inverter is not available. Could be different things like wrong IP/Hostname, wrong port, your openHAB instance can’t access the network, inverter offline and so on. For the request executed it‘s a communication error in any of those cases.

I see that the renamed channel “device#status” can be a bit misleading. The channel does not reflect the availability of the inverter but if the inverter is allowed to output power to the grid.

LukaNoah · May 24, 2024, 9:46am

You’re right.
So far I have gotten the data from the inverter via Rule. I could see that before the inverter switches off, the status changes to OFF. Now you could use the thing status from the inverter status “OFF” and the occurring timeout for OFFLINE. If only the timeout comes and the status is ON, then it is a communication problem. If there is no timeout and the status is OFF, then the thing is ONLINE. What do you make of it?
Attached are the last 3 days of the inverter status from me (read out by rule). You can see ON and OFF, which could confirm my thesis. I didn’t send any commands to the status, which is something you could do.

deibich · May 24, 2024, 10:29am

I wasn’t aware that the inverter sets its status to OFF on its own. This isn’t mentioned in the API description. As long as the behavior is not clearly described, I don’t think it’s a good idea to use the status for other purposes.

So your suggestion is that if the inverter sets its status to OFF and shortly after becomes unreachable, we set the Thing’s status to OFFLINE (without COMMUNICATION_ERROR)? And in all other cases set the status of the THING to OFFLINE (with COMMUNICATION_ERROR)?

LukaNoah · May 24, 2024, 11:58am

Exactly.
Status OFF & TimeOut → Thing OFFLINE
Status ON & TimeOut → Thing communication error
Status ON & no TimeOut → Thing ONLINE
Status OFF & no TimeOut → Thing ONLINE

deibich · May 25, 2024, 9:49am

The inverter is not in the network and therefore not reachable. This leads to a communication error. I see no benefit in hiding this error from the user, especially when it depends on an undocumented and user-changeable state.

LukaNoah · May 25, 2024, 11:17am

OK. That’s your view of things, which I can also understand. I see it a little differently, also due to work reasons. A malfunction that is caused by the operating status and in this case should not be viewed as an error should not be represented in this way.
But let’s leave it alone. It’s great that the binding exists. Thank you for that

DARqz · January 14, 2025, 9:04pm

As @deibeich mentioned: with no sun, the inverter is reliable without power and therefore unreachable.

Just an idea (I don’t now whether this is easy or feasible):

if the thing “astro:sun:local” is present and configured:
when the event sunset end is triggered → set the APSystemsEZ1 thing to offline
when the event sunrise start is triggered → set the APSystemsEZ1 thing to online (and show communication errors)

Perhaps make this behaviour configurable?

kolli · July 25, 2025, 3:00pm

I’m having a bit of an issue with this binding in 5.0.0.
After upgrading to 5.0.0, I get the following error message at startup:

2025-07-25 16:45:20.627 [WARN ] [mmon.WrappedScheduledExecutorService] - Scheduled runnable ended with an exception: 
java.lang.IllegalArgumentException: UID segment 'dc1:power' contains invalid characters. The last segment of the channel UID must match the pattern '[\w-]*(?:#[\w-]*)?'.
	at org.openhab.core.thing.ChannelUID.validateSegment(ChannelUID.java:137) ~[?:?]
	at org.openhab.core.common.AbstractUID.<init>(AbstractUID.java:76) ~[?:?]
	at org.openhab.core.thing.UID.<init>(UID.java:66) ~[?:?]
	at org.openhab.core.thing.ChannelUID.<init>(ChannelUID.java:60) ~[?:?]
	at org.openhab.core.thing.binding.BaseThingHandler.isLinked(BaseThingHandler.java:647) ~[?:?]
	at org.openhab.binding.apsystemsez1.internal.APsystemsEZ1Handler.anyChannelLinkedForEndpointData(APsystemsEZ1Handler.java:364) ~[?:?]
	at org.openhab.binding.apsystemsez1.internal.APsystemsEZ1Handler.pollDevice(APsystemsEZ1Handler.java:181) ~[?:?]
	at java.util.concurrent.Executors$RunnableAdapter.call(Unknown Source) ~[?:?]
	at java.util.concurrent.FutureTask.runAndReset(Unknown Source) ~[?:?]
	at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(Unknown Source) ~[?:?]
	at java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source) ~[?:?]
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source) ~[?:?]
	at java.lang.Thread.run(Unknown Source) [?:?]

This causes the THING" not to pull any changes going forward.
I recompiled the sources under 5.0.0 setup. Same issue.
Rolled back to 4.3.5. all working fine

kolli · August 1, 2025, 12:19pm

Seems to be, I found the reason. I think, it is related to this change:
Bugfix 455434: added default constructor, Dennis Nobel - Added channel group id, Kai Kreuzer - Changed creation of channels to not require a thing type, Christoph Weitkamp - Changed pattern for validating last segment to contain either a single # or none.

I replaced all “:” to “#”. Working now for me. Will do more testing, but looking promising…

    public static final Map<Class<? extends EZ1ResponseData>, List<String>> RESPONSE_DATA_CHANNEL_UID_LIST_MAP = Map
            .ofEntries(Map.entry(EZ1DeviceInfoResponseData.class, List.of()), Map.entry(EZ1OutputDataResponseData.class,
                    List.of(CHANNEL_GROUP_DC1 + "#" + CHANNEL_POWER, CHANNEL_GROUP_DC1 + "#" + CHANNEL_ENERGY_START,
                            CHANNEL_GROUP_DC1 + "#" + CHANNEL_ENERGY_LIFETIME, CHANNEL_GROUP_DC2 + "#" + CHANNEL_POWER,
                            CHANNEL_GROUP_DC2 + "#" + CHANNEL_ENERGY_START,
                            CHANNEL_GROUP_DC2 + "#" + CHANNEL_ENERGY_LIFETIME,
                            CHANNEL_GROUP_DEVICE + "#" + CHANNEL_POWER,
                            CHANNEL_GROUP_DEVICE + "#" + CHANNEL_ENERGY_START,
                            CHANNEL_GROUP_DEVICE + "#" + CHANNEL_ENERGY_LIFETIME)),
                    Map.entry(EZ1MaxPowerResponseData.class, List.of(CHANNEL_GROUP_DEVICE + "#" + CHANNEL_MAX_PWR)),
                    Map.entry(EZ1AlarmResponseData.class, List.of(CHANNEL_GROUP_DEVICE + "#" + CHANNEL_ALARM_OE,
                            CHANNEL_GROUP_DEVICE + "#" + CHANNEL_ALARM_OG, CHANNEL_GROUP_DC1 + "#" + CHANNEL_ALARM_ISCE,
                            CHANNEL_GROUP_DC2 + "#" + CHANNEL_ALARM_ISCE)),
                    Map.entry(EZ1OnOffResponseData.class, List.of(CHANNEL_GROUP_DEVICE + "#" + CHANNEL_STATUS)));

kaenguruhs · February 9, 2026, 8:22pm

Hi everyone, has anyone managed to develop a working version of this binding for openHAB 5 based on kolli’s notes and would be willing to share the JAR file?

Fleck · February 9, 2026, 8:39pm

Sort of. After applying Kolli’s changes the binding would randomly hang after either a few hours or two days at most. Gemini AI gave a very clear error description and proposed a fix, which appears to work for me (tested for 6 days by now).

Download link on github: https://github.com/JensHeilig/openhab-addons/releases/download/v0.5-interim-openHABv5/org.openhab.binding.apsystemsez1-5.2.0-SNAPSHOT.jar

Note: You will probably need to re-create the APSystemsEZ1 Thing. At least I had to, due to the modified channel names.

Fleck · February 9, 2026, 10:04pm

Using the patched jar file for openHAB 5.1 from above, I observe a strange issue which I had not noticed using the “original” binding in openHAB 4.3:

There are significant discrepancies between “Energy Lifetime” and “Energy since startup”: Every day, “Energy Lifetime” reports significantly less energy for the day than “Energy since startup”.

Additionally, “Energy Lifetime” has non-monotonic growth. For example today’s measurements:

vs. “Energy since startup”:

Total energy today, according to “Energy Lifetime”: 24 Wh

Total energy today, according to “Energy since startup”: 740 Wh

I have not observed this in openHAB4, using the JAR file from the Marketplace. Can anybody confirm this behavior or does it work correctly for you?