Enphase Envoy: Add manual AC Battery (ACB) control via sleep mode

[genestealer]

Integration name

Enphase Envoy

Link to integration documentation on our website

https://www.home-assistant.io/integrations/enphase_envoy

Describe the enhancement

The integration currently has no support for controlling the older Enphase AC Battery (ACB). There is no native charge/discharge control available anywhere - not in the Enlighten end user app, not in the Installer Toolkit, and not in any existing HA integration. The ACB is a distinct product from the IQ Battery and uses a different local API endpoint on the IQ Gateway.

The only known workaround is to manipulate the ACB's sleep mode via the IQ Gateway's local endpoint /admin/lib/acb_config.json. By setting sleep_min_soc: 0 and sleep_max_soc: 100, the battery is effectively prevented from discharging. Cancelling sleep mode via a DELETE request restores normal operation. This gives basic on/off discharge control even though it was not designed for that purpose.

This has been confirmed working on firmware D8.3.5167 with Bearer token auth. The endpoint is documented by the community here:
https://github.com/Matthew1471/Enphase-API/blob/main/Documentation/IQ%20Gateway%20API/Admin/Lib/ACB_Config.adoc

The enhancement request is to expose ACB sleep mode as a controllable switch or service within the integration, giving users at least basic manual control over charge and discharge.

Use cases

Users with Enphase AC Batteries on time-of-use tariffs have no way to prevent the battery discharging during off-peak morning hours. The Enphase tariff scheduler has no native hold state, so the battery discharges immediately after the overnight grid-charge window closes regardless of any peak window configured. The only current workaround is manually manipulating the ACB sleep mode via the local API, which is not practical without proper HA integration.

Anything else?

Community forum post with further context: https://community.home-assistant.io/t/controlling-enphase-ac-battery-acb/999707
API documentation: https://github.com/Matthew1471/Enphase-API/blob/main/Documentation/IQ%20Gateway%20API/Admin/Lib/ACB_Config.adoc

@bdraco @cgarwood @catsmanac

[github-actions[bot]]

🏷️ I've automatically added the integration: enphase_envoy label to help categorize this feature request.

[catsmanac]

Hi @genestealer, Richard, think adding this should be possible. Testing it may be a bit harder as I have no batteries.

What are your abilities to test along the process? First step will be to update the underlying library pyenphase with some functions that implement this. With that done, some python test program can be used on some computer to test if it all works. Next step would be to update HA and to add the buttons, switch or action to it in the Dev environment. In Dev it can be tested again with a real Envoy, provided a HA Dev environment is setup. Next test option is beta testing during a HA monthly release cycle by installing a HA beta version. Final last test is when all this is part of HA and is used in a production HA.

All these steps take time for development, testing and reviews. The earlier in the process we can test with a real envoy, the fewer time will be lost if we have to apply changes as result of testing.

IS there any testing you can do?