diff --git a/README.md b/README.md index b894046..e653264 100644 --- a/README.md +++ b/README.md @@ -5,22 +5,23 @@ Integrate FusionSolar into your Home Assistant. - [Home Assistant FusionSolar Integration](#home-assistant-fusionsolar-integration) - - [Installation](#installation) - - [Kiosk](#kiosk) - - [Northbound API / OpenAPI](#northbound-api--openapi) - - [Exposed Devices](#exposed-devices) - - [Realtime data](#realtime-data) - - [Integration with the Energy dashboard](#integration-with-the-energy-dashboard) - - [FAQ](#faq) - + - [Installation](#installation) + - [Kiosk](#kiosk) + - [Northbound API / OpenAPI](#northbound-api--openapi) + - [Exposed Devices](#exposed-devices) + - [Realtime data](#realtime-data) + - [Integration with the Energy dashboard](#integration-with-the-energy-dashboard) + - [FAQ](#faq) The integration is able to work with Kiosk mode, or with a Northbound API / OpenAPI account, see below for more details. ## Installation -This integration is part of the default HACS repositories, so can add it directly from HACS or add this repository as a custom repository in HACS. +This integration is part of the default HACS repositories, so can add it directly from HACS or add this repository as a +custom repository in HACS. -When the integration is installed in HACS, you need to add it in Home Assistant: Settings → Devices & Services → Add Integration → Search for FusionSolar. +When the integration is installed in HACS, you need to add it in Home Assistant: Settings → Devices & Services → Add +Integration → Search for FusionSolar. The configuration happens in the configuration flow when you add the integration. @@ -56,7 +57,8 @@ They will need to grant the following permissions: #### Device Data -For each of the Device Data permissions, there is a choice of the following device types. Ensure your installer gives you access to each device type, and all data under each device type, based on your installation: +For each of the Device Data permissions, there is a choice of the following device types. Ensure your installer gives +you access to each device type, and all data under each device type, based on your installation: * String Inverter * Residential Inverter @@ -68,7 +70,9 @@ For each of the Device Data permissions, there is a choice of the following devi ### If you know your current installer, but would like to manage the devices on your own -There is a plant transfer process, which keeps all data. This can be found under ***Plants → Plant Migration*** in the installer interface. You will need your own installer account, and you will need to supply the losing installer with your company name and code. +There is a plant transfer process, which keeps all data. This can be found under ***Plants → Plant Migration*** in the +installer interface. You will need your own installer account, and you will need to supply the losing installer with +your company name and code. This can be found here: ***System → System → Company Management → Company Info*** @@ -85,15 +89,20 @@ There is a process to create your own installer account, but there are caveats: [How to login to the API](https://support.huawei.com/enterprise/en/doc/EDOC1100261860/9e1a18d2/login-interface) -An example of the API url is: ```https://intl.fusionsolar.huawei.com/thirdData/``` where ```intl``` is the prefix on your own FusionSolar login page. +An example of the API url is: ```https://intl.fusionsolar.huawei.com/thirdData/``` where ```intl``` is the prefix on +your own FusionSolar login page. -The Northbound API has very strict rate limits on endpoints, as well as a single login session limit. If you wish to do your own testing or development alongside running this integration, it is recommended to get your installer to create 2 identical accounts. +The Northbound API has very strict rate limits on endpoints, as well as a single login session limit. If you wish to do +your own testing or development alongside running this integration, it is recommended to get your installer to create 2 +identical accounts. -If you try to use the same account in Postman and the integration, you will experience issues such as constant directions to log back in using Postman, returned data not being complete etc. +If you try to use the same account in Postman and the integration, you will experience issues such as constant +directions to log back in using Postman, returned data not being complete etc. ### Exposed Devices -The integration will expose the different devices (Residential inverter, String inverter, Battery, Dongle, ...) in your plant/station. +The integration will expose the different devices (Residential inverter, String inverter, Battery, Dongle, ...) in your +plant/station. ### Realtime data @@ -107,7 +116,9 @@ The devices that support realtime information (`getDevRealKpi` api call): * Power Sensor * C&I and Utility ESS -The exposed entities can be different per device. [These are documented here](https://support.huawei.com/enterprise/en/doc/EDOC1100261860/3557ba96/real-time-device-data-interface). But the names are pretty self-explanatory. +The exposed entities can be different per +device. [These are documented here](https://support.huawei.com/enterprise/en/doc/EDOC1100261860/3557ba96/real-time-device-data-interface). +But the names are pretty self-explanatory. The realtime data is updated every minute per device group. As the API only allows 1 call per minute to each endpoint and the same endpoint is needed for each device group. The more different devices you have the slower the @@ -118,8 +129,10 @@ updates will be. See [Disabling devices](#disabling-devices) The integration updates the total yields (current day, current month, current year, lifetime) every 10 minutes. ## Integration with the Energy dashboard - -If you have not set up the Energy dashboard in HomeAssistant, you can select it from the sidebar and step through the wizard. If you have configured it previously and want to change the settings you can access from the sidebar by clicking on [Settings → Dashboards](https://my.home-assistant.io/redirect/lovelace_dashboards/). + +If you have not set up the Energy dashboard in HomeAssistant, you can select it from the sidebar and step through the +wizard. If you have configured it previously and want to change the settings you can access from the sidebar by clicking +on [Settings → Dashboards](https://my.home-assistant.io/redirect/lovelace_dashboards/). As the name suggests, the dashboard requires sensors with units of energy as input (i.e. kWh), not power. @@ -150,37 +163,107 @@ If you don't see the kiosk button, you are probably logged in with an installer ### I am using the kiosk mode, but the data is not updating -First check that the Kiosk url is still working. The url is valid for 1 year. So you will need to update the kiosk url every year. +First check that the Kiosk url is still working. The url is valid for 1 year. So you will need to update the kiosk url +every year. ### Energy Dashboard: Active Power not showing in the list of available entities -Active Power is the current power production in Watt (W) or kilo Watt (kW). The Energy dashboard expects a value in **kWh**. +Active Power is the current power production in Watt (W) or kilo Watt (kW). The Energy dashboard expects a value in * +*kWh**. -Your plant, inverter(s), batteries, ... expose a lot of entities, you can see them all: Settings → Devices & Integrations → Click on the "x devices" on the Fusion Solar Integration. Click on the device you want to see the entities for. +Your plant, inverter(s), batteries, ... expose a lot of entities, you can see them all: Settings → Devices & +Integrations → Click on the "x devices" on the Fusion Solar Integration. Click on the device you want to see the +entities for. ### What do all entities mean? -As I don't own an installation with all possible devices this integration is mostly based on the [Northbound Interface Reference](https://support.huawei.com/enterprise/en/doc/EDOC1100261860/d4ee355a/v6-interface-reference). +As I don't own an installation with all possible devices this integration is mostly based on +the [Northbound Interface Reference](https://support.huawei.com/enterprise/en/doc/EDOC1100261860/d4ee355a/v6-interface-reference). The entity names are based on the names in the interface reference. ### Disabling devices / plants / stations -If you have a lot of devices / plants / stations wherefore you don't want to use the data. You can disable them through the interface: +If you have a lot of devices / plants / stations wherefore you don't want to use the data. You can disable them through +the interface: -Settings → Devices & Integrations → Click on the "x devices" on the Fusion Solar Integration. Click on the device / plant / station you want to disable. Click on the pencil icon in the upper right corner. Switch off "Enable device". +Settings → Devices & Integrations → Click on the "x devices" on the Fusion Solar Integration. Click on the device / +plant / station you want to disable. Click on the pencil icon in the upper right corner. Switch off "Enable device". -This can speed up the updating of the other devices. Keep in mind that a call is made per device type. So if you have multiple devices from the same time you need to disable them all to have effect. +This can speed up the updating of the other devices. Keep in mind that a call is made per device type. So if you have +multiple devices from the same time you need to disable them all to have effect. You will also need to restart Home Assistant. ### Can I work with the API myself? Yes. There is a [Postman] Collection available. You can import it in Postman and start working with it. -The collection is available under [docs/postman_collection](https://github.com/tijsverkoyen/HomeAssistant-FusionSolar/tree/master/docs/postman_collection.json). +The collection is available +under [docs/postman_collection](https://github.com/tijsverkoyen/HomeAssistant-FusionSolar/tree/master/docs/postman_collection.json). You will need to create an environment in Postman with the following variables: * `USERNAME`, your Northbound API / OpenAPI username * `SYSTEMCODE`, your Northbound API / OpenAPI password * `URL`, the url you will query + +### I need to change the Kiosk URL + +The Kiosk URL is valid for 1 year. After that you will need to update the URL. At this point there is no way to update +the URL without re-adding the integration. This can result in data los. + +You can work around this, **but this is not recommended and is at your own risk**: + +Open the file `.storage/core.config_entries` in the Home Assistant directory. + +There will be an entry like below" + +```json + { + "entry_id": "8cd2320a2969e84XXX", + "version": 1, + "domain": "fusion_solar", + "title": "Fusion Solar", + "data": { + "kiosks": [ + { + "name": "Foo", + "url": "https://eu5.fusionsolar.huawei.com/pvmswebsite/nologin/assets/build/index.html#/kiosk?kk=XXX" + } + ], + "credentials": {} + }, + ... +} +``` + +Update the `url`. And restart Home Assistant. + +### How can I verify my Northbound API / OpenAPI credentials? + +You can verify your credentials by doing a `curl` call. + +``` +curl --location 'https://eu5.fusionsolar.huawei.com/thirdData/login' \ +--header 'Content-Type: application/json' \ +--data '{ + "userName": "XXX", + "systemCode": "YYY" +}' + +``` + +Check if you need to alter the base hostname https://eu5.fusionsolar.huawei.com. And replace XXX with your username and +YYY with your password. + +The response should look like: + +```json +{ + "data": null, + "success": true, + "failCode": 0, + "params": {}, + "message": null +} +```