diff --git a/README.md b/README.md index 8218943..1c320d0 100755 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# bia +# FoxESS - Energy Management [![GitHub Release][releases-shield]][releases] [![GitHub Activity][commits-shield]][commits] @@ -14,51 +14,130 @@ [![Discord][discord-shield]][discord] [![Community Forum][forum-shield]][forum] -**TO BE REMOVED: If you need help, as a developer, to use this custom component tempalte, -please look at the [User Guide in the Cookiecutter documentation](https://cookiecutter-homeassistant-custom-component.readthedocs.io/en/stable/quickstart.html)** +\*\* **This project is not endorsed by, directly affiliated with, maintained, authorized, or sponsored by FoxESS** \*\* -**This component will set up the following platforms.** +## Introduction -| Platform | Description | -| -------- | ----------------------------------- | -| `sensor` | Show info from bia API. | -| `switch` | Switch something `True` or `False`. | +A Home Assistant custom component designed to maximises solar, battery and grid usage and avoid peak rate tarriffs. -![example][exampleimg] +This integration will ensure that your home batteries are charged to the optimal level when the forecasted solar output drops below your daily average usage. The integration will also ensure that, given a day where the solar forecast is greater than your daily average usage, the battery has enough charge to last until dawn. + +To further ease managing the battery state, the integration includes a switch to boost (+1kW) the battery charge and a second switch to charge fully; this is useful for times when you expect a higher than average load. + +Example showing the integration: + +- Charging the battery off-peak (3:24am -> 4:30am) as the battery wouldn't have last until dawn (i.e. when the solar takes over) +- Forecasted solar charging the battery (9:21am -> 12:20pm) up to ~80% +- Base house load consuming battery (12:20pm -> 3:25am) to a minimum of 15% +- Repeat + +![Example](images/example.png) + +### Assumptions/Dependencies + +These may change as development progresses: + +- Only one Solcast site is supported (i.e. one solar array) +- Only one FoxESS inverter is supported ## Installation -1. Using the tool of choice open the directory (folder) for your HA configuration (where you find `configuration.yaml`). -2. If you do not have a `custom_components` directory (folder) there, you need to create it. -3. In the `custom_components` directory (folder) create a new folder called `bia`. -4. Download _all_ the files from the `custom_components/bia/` directory (folder) in this repository. -5. Place the files you downloaded in the new directory (folder) you created. -6. Restart Home Assistant -7. In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "bia" - -Using your HA configuration directory (folder) as a starting point you should now also have this: - -```text -custom_components/bia/translations/en.json -custom_components/bia/translations/fr.json -custom_components/bia/translations/nb.json -custom_components/bia/translations/sensor.en.json -custom_components/bia/translations/sensor.fr.json -custom_components/bia/translations/sensor.nb.json -custom_components/bia/translations/sensor.nb.json -custom_components/bia/__init__.py -custom_components/bia/api.py -custom_components/bia/binary_sensor.py -custom_components/bia/config_flow.py -custom_components/bia/const.py -custom_components/bia/manifest.json -custom_components/bia/sensor.py -custom_components/bia/switch.py -``` - -## Configuration is done in the UI - - +Recommend installation through [HACS][hacs] + +1. Navigate to HACS integrations +2. Hit the menu button (top right) and select 'Custom repositories' +3. Paste this GitHub [link][foxess_em] and select 'Integration' +4. Install as usual through HACS + - 'Explore & Download Repositories' + - Search for 'FoxESS...' + - Download + +## Configuration and Options + +
+ Solcast Setup

+ +- **Site ID**: Single site ID from Solcast Toolkit (i.e. aaaa-bbbb-cccc...) +- **API Key**: API Key from Solcast Toolkit + +![Solcast Setup](images/config-step-1.png) + +
+ +
+ FoxESS Cloud Setup

+ +- **Username**: Username from FoxESS Cloud +- **Password**: Password from FoxESS Cloud + +![FoxESS Setup](images/config-step-2.png) + +
+ +
+ Battery Parameters

+ +Enter your desired battery parameters: + +- **Eco Start Time**: Start time of your off-peak period (i.e. 00:30 on Octopus Go) +- **Eco End Time**: End time of your off-peak period (i.e. 4:30 on Octopus Go) +- **Dawn Buffer**: As forecasts and usage patterns can change, leave a buffer to ensure the battery doesn't get too close to empty +- **Day Buffer**: As above, but for the day +- **Battery Capacity**: Capacity of battery in kWh +- **Charge Rate**: Typical charge rate observed through a charging window (usually inverter output (i.e. 3.6kw minus standing hour load) +- **Minimum SoC**: Minimum State of Charge as set in the FoxESS App + +![Battery Params](images/config-step-3.png) + +
+ +
+ Home Assistant Sensors

+ +- **Battery SoC**: Battery State of Charge sensor - must be an integer % +- **House Power**: House load power - must be kW +- **Aux Power**: Aux sensors to remove from the house power, i.e. an Eddi, Zappi charger etc. which will skew the base house load calculations - must be W + +![HA Sensors](images/config-step-4.png) + +
+ +## Sensors and Switches + +
+ Sensors

+ +Description of sensors: + +| Sensor | Description | Attributes | +| ------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| Capacity: Charge Needed | Charge needed for the next off-peak period | Dawn charge needed
Day charge needed
Charge start time
Target % | +| Capacity: Dawn | Forecasted battery capacity at dawn | | +| Capacity: Eco End | Forecasted battery capacity at the end of the off-peak period | | +| Capacity: Eco Start | Forecasted battery capacity at the start of the off-peak period | | +| Capacity: Next Dawn Time | Forecasted next dawn time (i.e. solar output > house load) | | +| Forecast: API Count | Number of hits against the Solcast API | | +| Forecast: Today | Forecasted solar output for today | | +| Forecast: Today Remaining | Forecasted solar output remaining (resampled to 1Min for continual updates) | | +| Forecast: Tomorrow | Forecasted solar output for tomorrow | | +| Last Update | Last update time | Battery last update
Forecast last update
Average last update
| +| Load: Daily | Total load, averaged over the last 2 complete days | | +| Load: Last 15m | Average load for the last 15 minutes | | +| Load: Peak | Peak only load (i.e. outside of the Go period), averaged over the last 2 complete days | | + +
+ +
+ Switches

+ +Description of switches: + +| Switch | Description | +| ------------------- | -------------------------------------------------------------------------- | +| Boost Charge (+1kW) | Adds 1kW to the charge needed sensor. Resets after the charge period. | +| Full Charge | Fully charges the battery during off-peak. Resets after the charge period. | + +
## Contributions are welcome! @@ -66,30 +145,30 @@ If you want to contribute to this please read the [Contribution guidelines](CONT ## Credits -This project was generated from [@oncleben31](https://github.com/oncleben31)'s [Home Assistant Custom Component Cookiecutter](https://github.com/oncleben31/cookiecutter-homeassistant-custom-component) template. - -Code template was mainly taken from [@Ludeeus](https://github.com/ludeeus)'s [integration_blueprint][integration_blueprint] template +Thanks to the awesome work from [oziee][ha_solcast] and [StealthChesnut][ha_modbus] --- -[integration_blueprint]: https://github.com/custom-components/integration_blueprint [black]: https://github.com/psf/black [black-shield]: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge [buymecoffee]: https://www.buymeacoffee.com/nathanmarlor [buymecoffeebadge]: https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg?style=for-the-badge -[commits-shield]: https://img.shields.io/github/commit-activity/y/nathanmarlor/bia.svg?style=for-the-badge -[commits]: https://github.com/nathanmarlor/bia/commits/main +[commits-shield]: https://img.shields.io/github/commit-activity/y/nathanmarlor/foxess_em.svg?style=for-the-badge +[commits]: https://github.com/nathanmarlor/foxess_em/commits/main [hacs]: https://hacs.xyz [hacsbadge]: https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge [discord]: https://discord.gg/Qa5fW2R [discord-shield]: https://img.shields.io/discord/330944238910963714.svg?style=for-the-badge -[exampleimg]: example.png +[foxessimg]: https://github.com/home-assistant/brands/raw/master/custom_integrations/foxess/logo.png +[foxess_em]: https://github.com/nathanmarlor/foxess_em [forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg?style=for-the-badge [forum]: https://community.home-assistant.io/ -[license-shield]: https://img.shields.io/github/license/nathanmarlor/bia.svg?style=for-the-badge +[license-shield]: https://img.shields.io/github/license/nathanmarlor/foxess_em.svg?style=for-the-badge [maintenance-shield]: https://img.shields.io/badge/maintainer-%40nathanmarlor-blue.svg?style=for-the-badge [pre-commit]: https://github.com/pre-commit/pre-commit [pre-commit-shield]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?style=for-the-badge -[releases-shield]: https://img.shields.io/github/release/nathanmarlor/bia.svg?style=for-the-badge -[releases]: https://github.com/nathanmarlor/bia/releases +[releases-shield]: https://img.shields.io/github/release/nathanmarlor/foxess_em.svg?style=for-the-badge +[releases]: https://github.com/nathanmarlor/foxess_em/releases [user_profile]: https://github.com/nathanmarlor +[ha_modbus]: https://github.com/StealthChesnut/HA-FoxESS-Modbus +[ha_solcast]: https://github.com/oziee/ha-solcast-solar diff --git a/custom_components/foxess_em/const.py b/custom_components/foxess_em/const.py index 5a7df2e..474d17c 100755 --- a/custom_components/foxess_em/const.py +++ b/custom_components/foxess_em/const.py @@ -20,7 +20,7 @@ SOLCAST_API_SITE = "site" SOLCAST_API_KEY = "key" SOLCAST_SCAN_INTERVAL = "scan_interval" -# SOLCAST_URL = "https://8c85c8b3-56db-49c5-96c3-44f615be2779.mock.pstmn.io" +# SOLCAST_URL = "https://77ed64fa-6470-4e50-aa2c-d5ec88ada8a6.mock.pstmn.io" SOLCAST_URL = "https://api.solcast.com.au" FOX_USERNAME = "fox_username" FOX_PASSWORD = "fox_password" diff --git a/images/config-step-1.png b/images/config-step-1.png new file mode 100644 index 0000000..a220b28 Binary files /dev/null and b/images/config-step-1.png differ diff --git a/images/config-step-2.png b/images/config-step-2.png new file mode 100644 index 0000000..9075032 Binary files /dev/null and b/images/config-step-2.png differ diff --git a/images/config-step-3.png b/images/config-step-3.png new file mode 100644 index 0000000..3213ea1 Binary files /dev/null and b/images/config-step-3.png differ diff --git a/images/config-step-4.png b/images/config-step-4.png new file mode 100644 index 0000000..be57d25 Binary files /dev/null and b/images/config-step-4.png differ diff --git a/images/example.png b/images/example.png new file mode 100644 index 0000000..c3b8bd7 Binary files /dev/null and b/images/example.png differ