homeassistant-alphaESS

Monitor your energy generation, storage, usage data and electric vehicle using the official Open API from Alpha ESS

AlphaESS OpenAPI

In November 2023, AlphaESS introduced a new web API for their own web client and developers were officially encouraged to migrate to using the AlphaESS Open API published at https://open.alphaess.com/. This component has been updated to use that Open API. Anyone wanting to use this component in Home Assistant will first need to register their own inverter with the AlphaESS Open API developer portal.

1. Navigate to https://open.alphaess.com/ and chose the option to register an account.
2. Once registered and logged in follow the instructions in your inverters manual to find your inverter SN and CheckCode, See example here
3. Add your inverter to the developer portal using your SN and CheckCode

Modifying existing installs to use the new OpenAPI

If you had previously been using this custom component in Home Assistant you will need to change to use the new authentication mechanism required by the AlphaESS OpenAPI.

1. First upgrade the HomeAssistant component to at least version 0.4.0 and then restart your HomeAssistant
2. In HomeAssistant navigate to Settings / Devices & Services / AlphaESS
3. Look for the pane labeled Integration entries and click on the "3 dots" menu to the right of your existing AlphaESS service.
4. Delete the existing AlphaESS service.
5. Click Add Entry to add a new AlphaESS service
6. Provide the AppID and AppSecret for your account on the Alpha ESS OpenAPI developer portal.
7. The new service will be created keeping the same entity/device names as before.

Installation using HACS

1. Use HACS, in `HACS > Integrations > Hamburger Menu > Custom Repositories add https://github.com/CharlesGillanders/homeassistant-alphaESS with category set to integration.
2. in HACS > Integrations > Explore & Add Repositories search for "alphaess".
3. Restart Home Assistant.
4. Enable Advanced Mode using Profile (click on your username at the bottom of the navigation column) -> Advanced Mode -> On
5. Log out of HomeAssistant and back in again
6. In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Alpha ESS".
7. You will be prompted for the AppID and AppSecret for your account on the Alpha ESS OpenAPI developer portal.

Manual Installation

1. Make a custom_components/alphaess folder in your Home Assistant file system.
2. Copy all the files and folders from this repository into the custom_components/alphaess folder
3. Restart Home Assistant
4. Enable Advanced Mode using Profile (click on your username at the bottom of the navigation column) -> Advanced Mode -> On
5. Log out of HomeAssistant and back in again
6. Setup this integration for your Alpha ESS energy storage system in Home Assistant via Configuration -> Integrations -> Add -> Alpha ESS
7. You will be prompted for the AppID and AppSecret for your account on the Alpha ESS OpenAPI developer portal.

Alpha ESS: GUI based Set Battery Charge/Discharge Times information

These settings will only use slot 1 for charging and discharging, while you are not able to modify slot 2 from this integration, you are able to view its current settings

Alpha has recently, and unannounced removed most of the restrictions around the POST API calls that can be made. The current restrictions are:

• Charging can only be set once every 30s
• Discharging can only be set once every 30s
• The reset button calls both set Charging and set Discharging

Some values are set by default, this includes

• updateChargeConfigInfo: gridcharge = 1
• updateDisChargeConfigInfo: ctrDis = 0

Setting the bathighcap and batusecap only save it to hass data (making it persistent across restarts)
and will only be applied when the respective button (or the reset button) is pressed

An error will be placed in the logs

The current charge config, discharge config and charging range will only update once the API is re-called (can be up to 1 min)

If you want to adjust the restrictions yourself, you are able to by modifying the ALPHA_POST_REQUEST_RESTRICTION varible in const.py to the amount of seconds allowed per call

Issues with registering systems to the AlphaESS OpenAPI

There has been a few issues regarding registering systems to the AlphaESS OpenAPI. The following are some of the issues that have been reported and how to resolve them.

Issue: Unable to register system to AlphaESS OpenAPI (not receiving verification code)

If you are unable to register your system to the AlphaESS OpenAPI because you are not receiving the verification code, you can try the following steps to resolve the issue:

1. Access the current postman collection library for the AlphaESS OpenAPI here (you will need to fork the collection)
2. Clicking on the root of the list of API calls (should be called AlphaESS Open API) and then click on the variables tab and fill in your AppID, AppSecret, systemSN and CheckCode into the initial and current value fields.
3. Click on the getVerificationCode GET API call followed by the send button to send the request. You should receive a verification code either in the response body or by email.

Services

This project allows you to use the following services in Home Assistant:

Alpha ESS: Set Battery Charge

This service call allows you to set the grid charge settings for your system.
Times are not validated and must be compatible with the Alpha values.
Data needed:
- serial = The serial of your system.
- enabled = True or False
- cp1start = Charging Period 1 Start Time
- cp1end = Charging Period 1 End Time
- cp2start = Charging Period 2 Start Time
- cp2end = Charging Period 2 End Time

example:

service: alphaess.setbatterycharge
data:
  serial: AA123456789
  enabled: True
  cp1start: "01:00"
  cp1end: "04:00"
  cp2start: "13:00"
  cp2end: "16:00"
  chargestopsoc: 100

Alpha ESS: Set Battery Discharge

This service call allows you to set the battery discharge settings for your system.
Times are not validated and must be compatible with the Alpha values.
Data needed:
- serial = The serial of your system.
- enabled = True or False
- dp1start = Discharging Period 1 Start Time
- dp1end = Discharging Period 1 End Time
- dp2start = Discharging Period 2 Start Time
- dp2end = Discharging Period 2 End Time

example:

service: alphaess.setbatterydischarge
data:
  serial: AA123456789
  enabled: True
  dp1start: "01:00"
  dp1end: "04:00"
  dp2start: "13:00"
  dp2end: "16:00"
  dischargecutoffsoc: 10