APsystems EZ1 Local API Binding

Add-on Marketplace Bundles
, ,
1

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

3 Likes
2

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

3

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.

image
image733×179 4.5 KB

4

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.

5

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.

image
image727×234 11.4 KB

6

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”.

7

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.

8

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.

9

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.

image
image1301×453 8.56 KB

10

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)?

11

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

12

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.

13

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 :wink: