Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation update #8

Merged
merged 2 commits into from
Oct 17, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 129 additions & 50 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# bia
# FoxESS - Energy Management

[![GitHub Release][releases-shield]][releases]
[![GitHub Activity][commits-shield]][commits]
@@ -14,82 +14,161 @@
[![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

<details>
<summary><b>Solcast Setup</b></summary></p>

- **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)

</details>

<details>
<summary><b>FoxESS Cloud Setup</b></summary></p>

- **Username**: Username from FoxESS Cloud
- **Password**: Password from FoxESS Cloud

![FoxESS Setup](images/config-step-2.png)

</details>

<details>
<summary><b>Battery Parameters</b></summary></p>

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)

</details>

<details>
<summary><b>Home Assistant Sensors</b></summary></p>

- **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)

</details>

## Sensors and Switches

<details>
<summary><b>Sensors</b></summary></p>

Description of sensors:

| Sensor | Description | Attributes |
| ------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Capacity: Charge Needed | Charge needed for the next off-peak period | Dawn charge needed </br> Day charge needed </br> Charge start time </br> 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</br> Forecast last update</br> Average last update</br> |
| 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 | |

</details>

<details>
<summary><b>Switches</b></summary></p>

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. |

</details>

## Contributions are welcome!

If you want to contribute to this please read the [Contribution guidelines](CONTRIBUTING.md)

## 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
2 changes: 1 addition & 1 deletion custom_components/foxess_em/const.py
Original file line number Diff line number Diff line change
@@ -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"
Binary file added images/config-step-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/config-step-2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/config-step-3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/config-step-4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.