Energy Docs (#18328)

Co-authored-by: Klaas Schoute <klaas_schoute@hotmail.com>
Co-authored-by: Franck Nijhof <git@frenck.dev>

source/_docs/energy.markdown

@@ -0,0 +1,16 @@
+---
+title: "Understanding Home Energy Management"
+description: "How to get started using home energy management in Home Assistant."
+---
+
+Home Assistant allows you to get on top of your energy use with its home energy management feature. Gain new insights, optimize your solar panel production, plan energy usage and save money.
+
+Home Assistant works with three different types of information sources. You can start using it even if you just have one source connected to Home Assistant. Every source you add will complement the other sources, giving you even more insight into energy in your home.
+
+Home Assistant is an open platform and so home energy management is not restricted to specific hardware. Any energy monitoring hardware that integrates with Home Assistant can be used as a data source. Check out the following sections for in-depth explanations and hardware recommendations.
+
+- [Integrate your energy use from the electricity grid](/docs/energy/electricity-grid/)
+- [Integrate your solar panels](/docs/energy/solar-panels/)
+- [Integrate individual devices](/docs/energy/individual-devices/)
+
+<img src='/images/docs/energy/energy-overview.png' alt='Visual representation of how all different energy forms relate.' style='border: 0;box-shadow: none;'>

source/_docs/energy/electricity-grid.markdown

@@ -0,0 +1,56 @@
+---
+title: "Integrating your electricity grid"
+description: "Learn how to add information about your electricity grid to Home Assistant home energy management."
+---
+
+Energy management is all about knowing how much energy you’re consuming, where it’s coming from and where it’s going.
+
+Almost all houses are connected to the electricity grid which provides the energy your home will need. The energy usage is being tracked by your energy meter and is billed to you by your energy provider. Energy prices can differ based on a schedule or change according to market price.
+
+<img src='/images/docs/energy/grid.png' alt='Graphic showing energy flowing from the grid to Home Assistant.' style='border: 0;box-shadow: none;'>
+
+## Tariffs
+
+It has become popular for energy utilities to split the price of energy based on time of the day; this is done in order to incentivise consumers to shift their power needs towards times where the grid has lower loads. These periods of time are commonly referred to as Peak and Off Peak, exactly because they match periods of time where everyone is consuming energy (Peak) and periods of time where the energy is abundant but no one is using it (Off Peak). Therefore Peak energy is more expensive then Off Peak energy.
+
+If you are using a 3rd party device (e.g. not reading directly from your utility meter device or from the utility provider cloud service) you need HA to split your energy measurements into 2 (or more) tariffs, in order to track these energy consumptions separately. To accomplish such, you might use [the utility_meter integration](/integrations/utility_meter/). With the utility_meter integration you define as many tariffs as required (in accordance to your utility provider contract) and HA will be able to differentiate energy consumptions in each of the tariffs. Please note that each utility provider has their own time schedules for peak and off peak and you are required to create an automation that switches the utility_meter entity from one tariff to the other.
+
+## Hardware
+
+Home Assistant will need to know the amount of energy flowing through your meter. This can be done in various ways.
+
+### Using a CT clamp sensor
+
+CT clamp sensors measure the instantaneous current passing through an electrical wire. To translate this into electrical power (Wh) you also need a voltage measurement, because Power = Current x Voltage.
+
+In Home Assistant we have support for off-the-shelf CT clamp sensors and you can build your own with ESPHome's [CT Clamp Current sensor](https://esphome.io/components/sensor/ct_clamp.html).
+
+The off-the-shelf solution that we advice is the [Shelly EM](https://shop.shelly.cloud/shelly-em-120a-clamp-wifi-smart-home-automation#143). The device has a local API, updates are pushed to Home Assistant and it has a high quality integration.
+
+Devices like Shelly EM/3EM, Iotawatt, Openenergymonitor (EmonPi) measure both current and voltage.
+
+In case of three-phase electrical systems, attention should be drawn to the fact that the current measurement of a given phase is matched to the voltage of the same phase, otherwise the power measurements will be incorrect.
+
+_Attention! Installing CT clamp sensor devices requires opening your electrical cabinet. This work should be done by someone familiar with electrical wiring. Your qualified installer will know how to do this._
+
+### Connect to your meter
+
+The best way to get this data is directly from your electricity meter that sits between your house and the grid. In certain countries these meters contain standardized ways of reading out the information locally.
+
+### Connect using a P1 port
+
+The P1 port is a standardized port in the Netherlands, Belgium and Luxembourg. A P1 reader can connect to this port and receive real-time information.
+
+We have worked with creator Marcel Zuidwijk to develop [Slimme Lezer](https://www.slimmelezer.nl). It's a P1 reader powered by ESPHome that will seamlessly integrate this information in Home Assistant. It is being sold on his website.
+
+### Reading the meter via a pulse counter
+
+Many meters, including older ones, have an LED that will flash whenever energy passes through it. For example, each flash is a 1/1000th kWh. By monitoring the time between flashes it’s possible to determine the energy consumption.
+
+We have developed [Home Assistant Glow](https://github.com/klaasnicolaas/home-assistant-glow), an open source solution powered by ESPHome's [pulse meter sensor](https://esphome.io/components/sensor/pulse_meter.html).
+
+### Data provided by your energy provider
+
+Some energy providers will provide you real-time information about your usage and have this data integrated into Home Assistant.
+
+_Disclaimer: Some links on this page are affiliate links._

source/_docs/energy/faq.markdown

@@ -0,0 +1,14 @@
+---
+title: "Frequently Asked Questions about home energy management"
+description: "Home Energy Management is a vast topic and not everything might be clear. This page tries to clarify a couple of things."
+---
+
+## Energy vs Power
+
+Energy is a quantitative measurement of what it takes to produce work (e.g. heat water) while Power measures the speed at which energy is transferred.
+
+Electrical Power is usually measured in Watts (W) and Electrical Energy is usually measured in Watt-Hour (Wh) (not to be confused with Watt/Hour).
+
+This difference is very important as you need to use the proper entities and/or convert between the two. Energy (Watt-Hour) is not an average of the Power you are consuming over a given period of time, but the sum of the power function: Power is the derivative of Energy over time.
+
+Think of this in a parallel to speed and distance: Power is the speed you are going and Energy is the distance driven.

source/_docs/energy/individual-devices.markdown

@@ -0,0 +1,12 @@
+---
+title: "Integrating individual device energy usage"
+description: "Learn how to add information about individual device energy usage to Home Assistant home energy management."
+---
+
+Home Assistant can integrate the energy usage of individual devices into Home Assistant. This usage is generally measured by a smart plug sitting between the device and the outlet.
+
+Depending on what protocols you use at home, you can use Zigbee, Z-Wave or Wi-Fi based plugs.
+
+<img src='/images/docs/energy/devices.png' alt='Graphic showing energy flowing from the home to individual devices.' style='border: 0;box-shadow: none;'>
+
+_Disclaimer: Some links on this page are affiliate links._

source/_docs/energy/solar-panels.markdown

@@ -0,0 +1,28 @@
+---
+title: "Integrating your solar panels"
+description: "Learn how to add information about your solar panels to Home Assistant home energy management."
+---
+
+Gain insight into your energy production by integrating your solar panels into Home Assistant.
+
+If you also set up [the Solar Forecast integration](/integrations/forecast_solar), you will be able to see expected solar production and automate based on planned production.
+
+<img src='/images/docs/energy/solar.png' alt='Graphic showing energy flowing from the solar panels to Home Assistant and back to the grid.' style='border: 0;box-shadow: none;'>
+
+## Hardware
+
+Home Assistant will need to know the amount of energy that is being produced. This can be done in various ways.
+
+### Using a CT clamp sensor
+
+CT clamp sensors measure the instantaneous current passing through an electrical wire. To translate this into electrical power (Wh) you also need a voltage measurement, because Power = Current x Voltage.
+
+In Home Assistant we have support for off-the-shelf CT clamp sensors and you can build your own with ESPHome's [CT Clamp Current sensor](https://esphome.io/components/sensor/ct_clamp.html).
+
+The off-the-shelf solution that we advice is the [Shelly EM](https://shop.shelly.cloud/shelly-em-120a-clamp-wifi-smart-home-automation#143). The device has a local API, updates are pushed to Home Assistant and it has a high quality integration.
+
+Devices like Shelly EM/3EM, Iotawatt, Openenergymonitor (EmonPi) measure both current and voltage.
+
+In case of three-phase electrical systems, attention should be drawn to the fact that the current measurement of a given phase is matched to the voltage of the same phase, otherwise the power measurements will be incorrect.
+
+_Attention! Installing CT clamp sensor devices requires opening your electrical cabinet. This work should be done by someone familiar with electrical wiring. Your qualified installer will know how to do this._

source/_includes/asides/docs_navigation.html

@@ -42,6 +42,15 @@
           </li>
         </ul>
       </li>
+      <li>
+        <b>Home Energy Management</b>
+        <ul>
+          <li>{% active_link /docs/energy/ Introduction %}</li>
+          <li>{% active_link /docs/energy/electricity-grid/ Electricity Grid %}</li>
+          <li>{% active_link /docs/energy/solar-panels/ Solar Panels %}</li>
+          <li>{% active_link /docs/energy/individual-devices/ Individual Devices %}</li>
+        </ul>
+      </li>
       <li>
         <b>Advanced Configuration</b>
         <ul>