Expand AirGradient documentation (#39464)

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

source/_integrations/airgradient.markdown

@@ -27,6 +27,18 @@ ha_zeroconf: true
 The AirGradient integration will fetch data from your [AirGradient devices](https://www.airgradient.com/).
 AirGradient creates indoor and outdoor air quality monitors that enable you know if the air quality is healthy or not. They measure metrics such as PM2.5, CO2, TVOCs, and NOx. Both the software and hardware are open-source, allowing you to customize or extend the device functionality. 
 
+## Use cases
+
+- Monitor indoor and outdoor air quality.
+- Warn to open windows when CO2 levels are too high.
+- Control ventilation systems based on air quality.
+
+## Supported devices
+
+- AirGradient DIY Air Quality Monitor
+- AirGradient Indoor Air Quality Monitor
+- AirGradient Outdoor Air Quality Monitor
+
 {% important %}
 In order for the device to be set up or discovered by Home Assistant, the [firmware](https://www.airgradient.com/documentation/firmwares) version should be at least 3.1.1.
 {% endimportant %}
@@ -38,7 +50,11 @@ Host:
   description: "The IP address or hostname for your AirGradient device."
 {% endconfiguration_basic %}
 
-## Available sensors
+## Supported functionality
+
+Below is a complete overview of the entities this integration provides.
+
+### Available sensors
 
 The integration will fetch data from each device. The following sensors are supported:
 
@@ -65,7 +81,7 @@ A number of configuration entities are available as sensors to automate with if
 - Display temperature unit
 - Display brightness
 
-## Available configuration entities
+### Available configuration entities
 
 The integration provides a few configuration entities to customize the device experience.
 The settings are only available when the configuration source is set to local.
@@ -84,6 +100,67 @@ The following entities are supported:
 - NOx learning offset
 - Total volatile organic compounds learning offset
 
+### Updates
+
+The AirGradient integration provides an update entity that checks for firmware updates for your AirGradient device.
+To install the update, the device needs to be rebooted.
+
+## Data updates
+
+This integration uses local {% term polling %}, meaning it checks for changes to all entities by regularly communicating with the AirGradient device.
+
+The integration will retrieve data from the device every minute.
+
+The updates for the device are checked once every hour.
+
+## Actions
+
+This integration does not provide additional actions. All actions available
+for this integration are provided by their respective entities.
+
+## Examples
+
+The following examples show how to use the AirGradient integration in Home
+Assistant automations. These examples are just a starting point, and you can
+use them as inspiration to create your own automations.
+
+### Notify when the CO2 level is too high
+
+The following example sends a notification to your mobile device when the CO2 level exceeds 1000 ppm.
+
+{% raw %}
+
+```yaml
+automation:
+  - alias: "Notify when CO2 level is too high"
+    triggers:
+      - trigger: numeric_state
+        entity_id: sensor.airgradient_carbon_dioxide
+        above: 1000
+
+    actions:
+      - action: notify.mobile_app_your_device
+        data:
+          title: "High CO2 Level Alert"
+          message: >
+            The CO2 level is too high at {{ states('sensor.airgradient_carbon_dioxide') }} ppm.
+            Please consider ventilating the room.
+```
+
+{% endraw %}
+
+## Known limitations
+
+The AirGradient integration currently has the following limitations:
+- The update entity is not able to install updates automatically. You will need to reboot the device manually after installing the update.
+
+## Troubleshooting
+
+If you're experiencing issues with your AirGradient integration, try these general troubleshooting steps:
+
+1. Make sure your AirGradient is powered on and properly connected to your home network.
+2. If the integration shows as unavailable, try restarting both your AirGradient and Home Assistant.
+
 ## Removing the integration
 
 This integration follows standard integration removal, no extra steps are required.