ioBroker.apsystems-ecu alpha-version

Integration of APSystems inverters via ECU-R

This adapter integrates APSystems inverters via APSystems ECU-R/ECU-B communication unit to collect data from solar modules. The adapter queries the local ECU using the proprietary APSytems ECU to EMAapp protocol. It collects realtime information and history data from the ECU about the configured inverters. The ECU supports several connections and protocols on its LAN and WLAN interface. This implementation is focused on the services available via WLAN TCP port 8899 and the so called command group 11 of the ECU.

Many Thanks ...

This project was only possible because of the great protocol analysis work of @checking12, @HAEdwin and other people on the home assistant forum.
There exists already a Python implementation for home assistant ksheumaker/homeassistant-apsystems_ecur which was used to get a better understanding of the ECU behavior. See also the discussion in APsystems APS ECU R local inverters data pull for more details.
apsystems-ecu is a new development in JavaScript for iobroker.

How it works

The ECU has to run in its 'normal mode' and has to be connected to the local network and the internet. A connection to the EMA cloud seems to be needed or the Ecu will not offer the used services (but this was not deeper investigated). In my system only the WLAN interface of the Ecu is used. The usage of the LAN interface was not investigated.
The Ecu uses zigbee to communicate with the configured inverters. The poll time of the Ecu to inverter communication in smaller systems is normally 300sec. It's reported that the cycle time will increase in bigger systems but I could not investigated.
The adapter connects cyclic to the Ecu via TCP port 8899 (default) (port and IP address can be configured) and collects data. The adapter poll time can be configured. Received data used to update the iobroker database. Objects and states are automatically created if new devices (inverters) are online.

Remark:

• The setup of the Ecu, the inverters and the connection to the EMA cloud is not part of this project.
• The adapter was developed and tested with a small system with one QS1 inverter only.
• Tests with YC600, YC1000, DS3, ECU-B are done with support of some users.
  
  

Suported devices and services

Communication units:

• ECU-R - OK
• ECU-C - may work but not tested
• ECU-B - OK (may depent on firmware version)

Inverters:

• QS1 - OK
• YC600 - OK
• YC1000 - OK
• DS3 - OK

Interface and protocol

Only the following interface and protocol is supported

• WLAN
• TCP port 8899
• Command group 11 and 12 (only GetEnergyOfWeekMonthYear)
  
  

Functions overview

• Implementation of all (known) command group 11 services

  • GetSystemInfo, GetRealTimeData, GetInverterDataSERVICE_COUNT_ID, GetPowerOfDay
  • GetEnergyOfWeekMonthYear - no more supported by ECU with firmware version > 2.x
  • Decoding and storing of all data offered by these services
  • New! Support of command group 12 GetEnergyOfWeekMonthYear service
    
    

• Cyclic request of realtime services GetSystemInfo, GetRealTimeData and GetInverterSignalLevel

  • Start/Stop of cyclic service execution by user
  • cmd_start_stop=true/false
  • Cyclic requests are automatically disabled between sunset and sunrise
  • Longitude and latitude from system configuration used
    
    

• Calling GetPowerOfDay service by command

  • Selectable day power_of_day_date for power data
  • Once requested at adapter start
  • Request by user command
  • cmd_power_of_day=true
  • power_of_day_date changed
    
    

• Calling GetEnergyOfWeekMonthYear service by command

  • Support depents on ECU firmware version
  • disable/enable with config parameter extendedService
  • Once requested at adapter start
  • Request by user command
  • cmd_energy_of_week=true
  • cmd_energy_of_month=true
  • cmd_energy_of_year=true
    
    

• The adapter computes sunrise and sunset based on the iobroker system settings at midnight.

  • ECU polling is stopped at sunset and started at sunrise

Appendix

Links

There are several projects about APsystems Inverters available using different interfaces.
Just an incomplete list of links ...

• Collect inverter data via zigbee using Fake ECU

• ksheumaker/homeassistant-apsystems_ecur

• bgbraga/homeassistant-apsystems

• Extracting data from APsystems inverters via EMA cloud
  
  
  

ECU-R behaviour

• The typical ECU-R response time in my configuration is <50ms (see debug log)
• I got regular a socket error (remote close) after communication pause > 15sec between service requests
  • Enabling keep-alive did't improve this behavior
  • So TCP connection is opened and closed for each communication service to avoid remote close
    
    
    

APSystems ECU Protocol - Command Group 11

GetSystemInfo

Request: "APS1100160001END\n"

GetRealTimeData

Request: "APS110028000221600xxxxxxxEND\n" where 21600xxxxxx=ECUId

Inverter Id's | Type | Id-Prefix | YC600 | "40xxxxxxxxxxx" | YC1000 | "50xxxxxxxxxxx" | DS2 | "70xxxxxxxxxxx" | QS1 | "80xxxxxxxxxxx"

GetPowerOfDay

Request: "APS110039000321600xxxxxxxENDddddddddEND\n" where 21600xxxxxxx=ECUId dddddddd=Date (BCD e.c. 20220209)

GetEnergyOfWeekMonthYear (suport depents on ECU type and firmware version)

Request: "APS110039000421600xxxxxxxENDppEND\n" where 21600xxxxxxx=ECUId, pp=Period ("00"/"01"/"02" - week/month/year)

GetInverterSignalLevel

Request: "APS110028000421600xxxxxxxEND\n" where 21600xxxxxxx=ECUId

Changelog

0.2.10 (npeter) (23-10-10)

1. README.md GetEnergyOfWeekMonthYear CommandCode corrected (0040->0004); Some improvements
2. issue#16: Support of GetEnergyOfWeekMonthYear response with CommandGroup 12
3. issue#12: New state rssi in inverter object. rssi is inverter signal_level in dBm it will replace signal_level in future versions
4. issue#13, issue15 README.md some typos and errors corrected
5. Admin/index_n.html description for extended_service improved

0.2.9 (npeter) (in work 22-04-14)

• Service response status check about "no data" added/improved
• Response length check improved
• New config parameter extended_service to disable/enable GetEnergyOfWeekMonthYear service processing
  • avoid warnings if firmware support for GetEnergyOfWeekMonthYear service is missed
  • checked: GetEnergyOfWeekMonthYear states created and services executed
  • not checked (default): GetEnergyOfWeekMonthYear services are skiped and states not created
• Config parameter pollAlways removed
• README.md Request for GetPowerOfDay and GetEnergyOfWeekMonthYear corrected
• \r replaced by \n in "const req = REQ_POWER_OF_DAY + this.ecuId + REQ_END + day + REQ_END + '\n';"

0.2.8 (npeter) (in work 22-03-27-B)

• Testversion for #8
  • DS3 states Power1/2, and Voltage1/2 added - correction of 0.2.7

0.2.7 (npeter) (in work 22-03-27)

• Testversion for #8
  • DS3 states Power1/2, and Voltage1/2 added

0.2.6 (npeter) (in work 22-03-26)

• Testversion for #8
  • YC600 and DS3 identfication corrected

0.2.5 (npeter) (in work 22-03-25)

• Testversion for #8
  • ECU connect/disconect for each service
  • "ECU intervall" is used as delay between service calls instead of delay between ECU polling
    • SystemInfo - delay - GetRealTimeData - delay - GetInverterSignalLevel - delay - [GetPowerOfDay - delay -] [...]
  • Service error is ignored (no repeat)
• Support of DS3
  • Device with "ds3" prefix created
• Correct processing of "only registered" inverters
  • No devices and states created
• GetRealTimeData protocoll doc improved (DS3 and only registered inverters)
• ECU Version added to SystemInfo debug log

0.2.4 (npeter) (in work 22-03-09)

• new configuration.poll_always added (test)
  • poll_always will disable stopping of ECU polling at sunset

0.2.3 (npeter) (in work 22-03-09)

• new state ecu.total_energy_yesterday (issue #5)
  • ecu.current_day_energy stored in ecu.total_energy_yesterday at midnight
  • Remark: ecu.current_day_energy is reset by ECU
• info.service_count set to 0 at midnight
• new state ecu.dc_peak_power_yesterday
  • update with ecu.dc_peak_power_today at midnight
• new state ecu.dc_peak_power_today (drag indicator) (issue #4)
  • peak of dc_power of all inverters (GetRealTimeData)
  • reset at midnight

0.2.2 (npeter)

• issues #2, #3 solved and closed
• YC600 and YC1000 states dc_voltage(n) changed to ac_voltage(n)
• README.md
  • protocol description adapted
  • some improvements and corrections

0.2.1 (npeter)

• README.md improved
• Inverter state values wrong if multiple inverters connected #1 solved

  0.2.0

• (npeter) First alpha version

0.1.0

• (npeter) initial commit on githup as public project

0.0.1

• (npeter) initial prototype
  
  

License

MIT License - Copyright (c) 2021-2022 npeter peter_n@gmx.de

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.