Package: apsystems-ez1
APsystems EZ1 -  Python LibraryOverviewThe APsystems EZ1 Python library can be used to interact with APsystems EZ1 Microinverters. It provides a convenient way to communicate with the microinverter over yourlocal network, allowing you to read and set various device parameters like power status, alarm information, device information, and power limits.About Sonnenladen GmbHThis library is published, maintained, and developed by Sonnenladen GmbH. Our collaboration with the APsystems R&D Team has been instrumental in making this API a reality. At Sonnenladen GmbH, we are committed to providing top-notch solar energy solutions and are excited to offer this library to enhance the experience of using APsystems inverters.Purchase APsystems InvertersFor those interested in purchasing APsystems inverters, please visit our German online shop atSonnenladen. We offer a range of APsystems products, backed by our expertise in solar energy solutions.FeaturesGet detailed device informationRetrieve alarm status informationFetch output data(power output, energy readings)Set and get maximum power limits(30 W up to 800 W)Manage device power status(sleep_mode/on/off)Calculate combined power output and total energy generatedand much more...See our Home Assistant Integration based on this library:https://github.com/SonnenladenGmbH/APsystems-EZ1-API-HomeAssistantDevice CompatibilityThis table includes all micro-inverters we tested and can confirm 100 % compatbility with this library.DeviceNameSupport / CompatibilityAvailable to purchase at:APsystems EZ1-M(Firmware: EZ1 1.6.0)Sonnenladen GmbH - Online ShopIN STOCK | AUF LAGERSetup your InverterThe local API access needs to be activated once in the settings of the EZ1. Please follow our Step-By-Step Guide to do so:Step 1: Connect to the inverter using the "Direct Connection" method.Step 2: Establish a connection with your inverter.Step 3: Select the Settings menu.Step 4: Switch to the "Local Mode" section.Step 5: Activate local mode and select "Continuous"Step 6: Done! Make a note of the IP address for future reference.(To ensure a successful connection to your Wi-Fi network, it's essential to first set up your device using the standard procedure outlined in the APsystems Quickstart Guide. This initial setup is a crucial step before proceeding with any further configurations or usage.)InstallationTo use the APsystemsEZ1 library, you need to have Python >=3.8 installed on your system.See the following guide to install the latest Python release:https://www.python.org/downloadsYou can easily install theapsystems-ez1library via pip. The package is hosted on PyPI, making it straightforward to install and update. To install, run the following command:pipinstallapsystems-ez1NOTE: You need to have pip installed on your system. See the following guide to do so:https://pip.pypa.io/en/stable/installation/Python CompatibilityWe tested our library on multiple platforms and python versions and can confirm functionality:Language-Version-OSPlattformSupport / CompatibilityPython:Python 3.11+MacOSLinuxWindowsetc.PCs and LaptopsHome ServersVirtual MachinesSingle Board Computers (Raspberry Pi)MicroPython:N/AMicroPython as a FirmwareRaspbery Pi PicoESP8266 and ESP32STM32 MicrocontrollersTeensy, Pyboardand many more..We're working on it...DocumentationFor a complete understanding of the APsystems EZ1 Python Library, refer to our online documentation. It includes detailed descriptions of the library's functionality, usage examples, and regular updates on new features and improvements.Access the Documentation:APsystems EZ1M Python Library Documentation 📖This resource is designed to support both new and experienced users in implementing and optimizing the library in their projects.UsageHere's a quick example of how to use the APsystemsEZ1 library:fromAPsystemsEZ1importAPsystemsEZ1M# import the APsystemsEZ1 libraryimportasyncio# Initialize the inverter with the specified IP address and port number.inverter=APsystemsEZ1M("192.168.1.100",8050)asyncdefmain():try:# Get device informationdevice_info=awaitinverter.get_device_info()print("Device Information:",device_info)# Get alarm informationalarm_info=awaitinverter.get_alarm_info()print("Alarm Information:",alarm_info)# Get output dataoutput_data=awaitinverter.get_output_data()print("Output Data:",output_data)# Set maximum power limit (ensure the value is within valid range)set_power_response=awaitinverter.set_max_power(500)print("Set Power Response:",set_power_response)# Set power status (ensure "ON" or other value is valid)set_power_status_response=awaitinverter.set_device_power_status("ON")print("Set Power Status Response:",set_power_status_response)# Get current power statuspower_status=awaitinverter.get_device_power_status()print("Power Status:",power_status)exceptExceptionase:print(f"An error occurred:{e}")# Run the main coroutineasyncio.run(main())Examples - Retrieve Basic DataFetch and display data from the inverter.This function performs the following tasks:Fetches output data from the inverter.Extracts relevant information from the fetched data.Prints the power input from two PV inputs and the total generation for the day.fromAPsystemsEZ1importAPsystemsEZ1Mimportasyncio# Initialize the inverter with the specified IP address and port number.inverter=APsystemsEZ1M("192.168.178.168",8050)asyncdefmain():try:# Fetch output data from the inverter.response=awaitinverter.get_output_data()# Display power input from PV-Input 1 and 2.print("Power PV-Input 1: "+str(response.p1)+" W")print("Power PV-Input 2: "+str(response.p2)+" W")# Display total energy generation for the current day.print("Generation today "+str(round(response.e1+response.e2,3))+" kWh")exceptExceptionase:# Handle any exceptions that occur during the data fetch and print the error.print(f"An error occurred:{e}")# Run the main coroutine.# This is the entry point of the script and it runs the main function in an asynchronous manner.asyncio.run(main())Example Output:Power PV-Input 1: 126 WPower PV-Input 2: 161 WGeneration today: 3.167 kWhExamples - Set a maximum power output limitSet the maximum power output limit of the inverter and display the response.This script performs the following tasks:Sets the maximum output power of the inverter to a specified value (e.g., 60 Watts).Awaits the response from the inverter after setting the power limit.Prints the response from the inverter to confirm the change or indicate any errors.fromAPsystemsEZ1importAPsystemsEZ1Mimportasyncio# Initialize the inverter with the specified IP address and port number.inverter=APsystemsEZ1M("192.168.178.168",8050)asyncdefmain():try:# Fetch output data from the inverter.response=awaitinverter.get_output_data()# Display power input from PV-Input 1 and 2.print("Power PV-Input 1: "+str(response.p1)+" W")print("Power PV-Input 2: "+str(response.p2)+" W")# Display total energy generation for the current day.print("Generation today "+str(round(response.e1+response.e2,3))+" kWh")exceptExceptionase:# Handle any exceptions that occur during the data fetch and print the error.print(f"An error occurred:{e}")# Run the main coroutine.# This is the entry point of the script and it runs the main function in an asynchronous manner.asyncio.run(main())More examples can be found in our Wiki.MethodsThe library includes several methods to interact with the microinverter. You can find all of them with comprehensive docs ion our GitHub Pages.get_device_info(): Retrieves detailed information about the device.get_alarm_info(): Fetches the alarm status information for various components of the device.get_output_data(): Retrieves the output data from the device.get_total_energy_today(): Retrieves the total energy generated today by inverter inputs.get_total_energy_lifetime(): Retrieves the total lifetime energy generated by inverter inputs.get_max_power(): Retrieves the set maximum power setting of the device.set_max_power(power_limit): Sets the maximum power limit of the device.get_device_power_status(): Retrieves the current power status of the device.set_device_power_status(power_status): Sets the power status of the device.for a more detailed documentation see our GitHub Pages.RecommendationsWe highly recommend to set astatic IPfor the inverter you want to interact with. This can be achieved be accessing your local router, searching for the inverters IP and setting it to "static ip" or similar. A quick Google search will tell you how to do it exactly for your specific router model.Contribute to this projectEveryone is invited to commit changes to this library. This is considered a community project to realise countless projects that may need very specific new functionality. We're happy to see your ideas ;)You're also welcome to request new features to be built natively into the inverters API. We're in close contact with APsystems and happy to add new features in the future.APsystems API documentationYou can find the latest API documentation of APsystems inside the following directory:assets/apsystems-documentation/*https://github.com/SonnenladenGmbH/APsystems-EZ1-API/blob/main/assets/apsystems-documentation/LicenseThis library is released under the MIT License.