Update Electricity Maps documentation with use cases, configuration options, and tips (#40098)

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>

source/_integrations/co2signal.markdown

@@ -18,14 +18,190 @@ ha_codeowners:
   - '@VIKTORVAV99'
 ---
 
-The `Electricity Maps` sensor platform (formerly known as CO2Signal) queries the [Electricity Maps](https://www.electricitymaps.com/) API for the CO2 intensity of a specific region. Data can be collected for your home by using the latitude/longitude or a country code. This API uses the same data as <https://app.electricitymaps.com>. Not all countries/regions in the world are supported, so please consult the app to check local availability.
+The **Electricity Maps** {% term integration %} (formerly known as CO2Signal) queries the [Electricity Maps](https://www.electricitymaps.com/) API for the CO2 intensity of a specific region. 
+Data can be collected for your home by using the home location, latitude/longitude, or a country code.
+
+This API uses the same data as shown on the [Electricity Maps app](https://app.electricitymaps.com). 
+Not all countries/regions in the world are supported, so please check the app to verify local availability before setting up the integration.
+
+## Use case
+
+The Electricity Maps integration helps you understand the carbon intensity of your electricity grid in real-time. This information can be valuable for:
+
+- Timing energy-intensive tasks (like charging electric vehicles or running appliances) during periods of lower carbon intensity.
+- Creating automations that respond to changing grid conditions.
+- Visualizing your region's progress towards cleaner energy.
+- Understanding how weather conditions affect renewable energy availability in your area.
+- Tracking the carbon impact of your home's energy usage in the {% my energy title="**Energy Dashboard**" %}.
 
 ## Prerequisites
 
 To configure and use this integration, you need to obtain a free API key from Electricity Maps by signing up to the Free Tier product on the [Electricity Maps API Portal](https://electricitymaps.com/free-tier).
+Please be aware that the Free Tier API is limited to one location (called a zone). You need to specify the zone for your home location when creating your account.
 
 {% include integrations/config_flow.md %}
 
-## Sensor types
+The integration provides the following configuration options when setting it up:
 
-When configured, the platform will create two sensors for each configured location: the carbon intensity expressed in `gCO2eq/kWh` and a percentage of how much the grid relies on fossil fuels for production.
+{% configuration_basic %}
+Location:
+  description: Choose between using your Home Assistant's configured home location, a specific country code, or custom latitude/longitude coordinates.
+API key:
+  description: The API key obtained from the Electricity Maps API Portal.
+{% endconfiguration_basic %}
+
+When configuring the location based on latitude/longitude, you will be prompted to enter the following:
+
+{% configuration_basic %}
+Latitude:
+  description: The latitude of your home location.
+Longitude:
+  description: The longitude of your home location.
+{% endconfiguration_basic %}
+
+When configuring the location based on a country code, you will be prompted to enter the following:
+
+{% configuration_basic %}
+Country code:
+  description: The two-letter ISO 3166-1 alpha-2 country code for your home location (e.g., "US" for the United States, "DE" for Germany).
+{% endconfiguration_basic %}
+
+## Supported functionality
+
+### Sensors
+
+The integration creates two sensors for each configured location:
+
+- **Carbon intensity**: Shows the carbon intensity of electricity production in your area, measured in gCO2eq/kWh (grams of CO2 equivalent per kilowatt-hour).
+- **Fossil fuel percentage**: Shows what percentage of the electricity grid currently relies on fossil fuels for production.
+
+## Examples
+
+### Creating a dashboard card
+
+You can create a gauge card to visualize the carbon intensity of your electricity:
+
+{% raw %}
+```yaml
+type: gauge
+entity: sensor.electricity_maps_carbon_intensity
+name: Carbon Intensity
+min: 0
+max: 500
+severity:
+  green: 0
+  yellow: 150
+  red: 300
+```
+{% endraw %}
+
+### Automation example: Run appliances when carbon intensity is low
+
+This automation starts your dishwasher when the carbon intensity drops below a specific threshold:
+
+{% raw %}
+```yaml
+alias: "Run Dishwasher at Low Carbon Intensity"
+description: "Starts the dishwasher when carbon intensity is low"
+trigger:
+  - platform: numeric_state
+    entity_id: sensor.electricity_maps_carbon_intensity
+    below: 100
+    for:
+      minutes: 10
+condition:
+  - condition: time
+    after: "22:00:00"
+    before: "06:00:00"
+  - condition: state
+    entity_id: binary_sensor.dishwasher_ready
+    state: "on"
+action:
+  - service: switch.turn_on
+    target:
+      entity_id: switch.dishwasher
+  - service: notify.mobile_app
+    data:
+      message: "Dishwasher started during low carbon intensity period ({{ states('sensor.electricity_maps_carbon_intensity') }} gCO2eq/kWh)"
+```
+{% endraw %}
+
+### Creating a history graph to track changes
+
+Add this to your dashboard to track how carbon intensity changes throughout the day:
+
+{% raw %}
+```yaml
+type: history-graph
+entities:
+  - entity: sensor.electricity_maps_carbon_intensity
+    name: Carbon Intensity
+hours_to_show: 24
+refresh_interval: 60
+```
+{% endraw %}
+
+### Energy Dashboard integration
+
+The Electricity Maps integration is automatically used on the Energy Dashboard when set up. The carbon intensity data appears in the Energy Dashboard as a real-time gauge showing the carbon footprint of your household electricity usage.
+
+You don't need to manually configure anything - the integration is automatically detected and used by the Energy Dashboard to calculate and display your home's carbon emissions based on your energy consumption and the current grid carbon intensity.
+
+To view this information:
+1. Navigate to the {% my energy title="**Energy Dashboard**" %}.
+2. Look for the carbon intensity gauge in the dashboard.
+
+If you don't see the carbon information in your Energy Dashboard:
+1. Make sure the Electricity Maps integration is properly set up and working.
+2. Verify that you have energy monitoring configured in Home Assistant.
+
+## Data updates
+
+The integration {% term polling polls %} data from the Electricity Maps API every 15 minutes by default. The actual update frequency may be limited by your API tier's rate limits.
+
+## Known limitations
+
+- The Free Tier API is limited to one location. You need to specify the country when creating your account.
+- The Free Tier API has a limit of 50 requests per hour, but the integration is designed to poll at a rate that won't exceed this limit.
+- Not all geographic regions are supported by Electricity Maps. Check their app to see if your region has coverage.
+
+## Troubleshooting
+
+### Integration fails to set up
+
+#### Symptom: "The given token is invalid" during setup
+
+If you see an invalid token error during setup, your API key may be invalid or expired.
+
+##### Resolution
+
+1. Verify that you've correctly copied the API key from the Electricity Maps API portal.
+2. Check if your API key is still active in the Electricity Maps API portal.
+3. Try generating a new API key if the issue persists.
+
+#### Symptom: "No data available for selected location" during setup
+
+If you receive a "No data available for selected location" error, the coordinates or country code you provided might not be supported by Electricity Maps.
+
+##### Resolution
+
+1. Check the [Electricity Maps app](https://app.electricitymaps.com) to verify coverage for your location.
+2. Try using a country code instead of coordinates, or vice versa.
+3. If your exact location isn't supported, try using the nearest supported location.
+
+### Sensors show "unavailable"
+
+If your sensors show as "unavailable" after successful setup, there might be issues with the API connection.
+
+#### Resolution
+
+1. Check your internet connection.
+2. Verify that your API key still has available quota for the day.
+3. Check if the Electricity Maps service is experiencing downtime.
+4. Restart Home Assistant if the issue persists.
+
+## Removing the integration
+
+This integration follows standard integration removal. No extra steps are required.
+
+{% include integrations/remove_device_service.md %}