Add AQI documentation for pmsx003 sensor, improve AQI documentation in general

content/components/ethernet.md

@@ -240,6 +240,20 @@ ethernet:
   power_pin: GPIO5
 ```
 
+**DFRobot Edge101** and **ESP32-DOWD-V3**:
+
+```yaml
+ethernet:
+  type: IP101
+  mdc_pin: GPIO4
+  mdio_pin: GPIO13
+  clk:
+    pin: GPIO0
+    mode: CLK_EXT_IN
+  power_pin: GPIO2
+  phy_addr: 1
+```
+
 **AiThinker ESP32-G Gateway**:
 
 ```yaml

content/components/sensor/hm3301.md

@@ -49,13 +49,39 @@ sensor:
   - **calculation_type** (**Required**): One of: `AQI` or `CAQI`.
   - All other options from [Sensor](/components/sensor).
 
-## Air Quality Sensor
+## Air Quality Index
 
-There is a sensor which calculates quality of air based on PM 2.5 and PM 10.0 values.
-There are two implementations:
+The AQI (Air Quality Index) sensor calculates an air quality index value based on the PM2.5 and PM10 particulate matter concentrations. This provides a single number that indicates overall air quality and associated health concerns.
 
-- AQI: USA air quality standard
-- CAQI: Europe air quality standard
+Two calculation standards are supported:
+
+- **AQI** (US EPA Air Quality Index): The standard used in the United States, Canada, and parts of Asia. Scale of 0-500+.
+- **CAQI** (Common Air Quality Index): The European standard. Scale of 0-400.
+
+Both calculation types take the PM2.5 and PM10 values and return the higher (more conservative) of the two calculated index values.
+
+### AQI Scale (US EPA)
+
+| Index | Level | Health Implications |
+|-------|-------|---------------------|
+| 0-50 | Good | Air quality is satisfactory |
+| 51-100 | Moderate | Acceptable; some pollutants may be a concern for sensitive individuals |
+| 101-150 | Unhealthy for Sensitive Groups | Members of sensitive groups may experience health effects |
+| 151-200 | Unhealthy | Everyone may begin to experience health effects |
+| 201-300 | Very Unhealthy | Health alert: everyone may experience more serious health effects |
+| 301-500 | Hazardous | Health warnings of emergency conditions |
+
+### CAQI Scale (European)
+
+| Index | Level | Health Implications |
+|-------|-------|---------------------|
+| 0-25 | Very Low | Air quality is excellent |
+| 26-50 | Low | Air quality is good |
+| 51-75 | Medium | Air quality is fair |
+| 76-100 | High | Air quality is poor |
+| 101-400 | Very High | Air quality is very poor |
+
+### Configuration Example
 
 ```yaml
 sensor:
@@ -65,8 +91,13 @@ sensor:
     pm_10_0:
       name: "PM10.0"
     aqi:
-      name: "AQI"
-      calculation_type: "CAQI"
+      name: "Air Quality Index"
+      calculation_type: "CAQI"  # or "AQI" for US EPA standard
+      # Optional: Apply filters for smoother values
+      filters:
+        - sliding_window_moving_average:
+            window_size: 10
+            send_every: 1
 ```
 
 ## See Also

content/components/sensor/pmsx003.md

@@ -41,6 +41,9 @@ sensor:
       name: "Particulate Matter <2.5µm Concentration"
     pm_10_0:
       name: "Particulate Matter <10.0µm Concentration"
+    aqi:
+      name: "Air Quality Index"
+      calculation_type: "AQI"
 ```
 
 ## Configuration variables
@@ -90,12 +93,69 @@ sensor:
 - **formaldehyde** (*Optional*): Use the formaldehyde (HCHO) concentration in µg per cubic meter for the `PMS5003S` and `PMS5003ST` type sensors.
   All options from [Sensor](/components/sensor).
 
+- **aqi** (*Optional*): Air Quality Index sensor. Requires both `pm_2_5` and `pm_10_0` sensors to be configured. See [Air Quality Index](#air-quality-index) below.
+
+  - **calculation_type** (**Required**): The AQI calculation standard to use. One of: `AQI` (US EPA) or `CAQI` (European).
+  - All other options from [Sensor](/components/sensor).
+
 - **update_interval** (*Optional*): Amount of time to wait between generating measurements. If this is longer than 30
   seconds, and if `tx_pin` is set in the UART configuration, the fan will be spun down between measurements. Default to `0s` (forward data as it's coming in from the sensor).
 
 - **uart_id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID of the [UART Component](/components/uart) if you want
   to use multiple UART buses.
 
+## Air Quality Index
+
+The AQI (Air Quality Index) sensor calculates an air quality index value based on the PM2.5 and PM10 particulate matter concentrations. This provides a single number that indicates overall air quality and associated health concerns.
+
+Two calculation standards are supported:
+
+- **AQI** (US EPA Air Quality Index): The standard used in the United States, Canada, and parts of Asia. Scale of 0-500+.
+- **CAQI** (Common Air Quality Index): The European standard. Scale of 0-400.
+
+Both calculation types take the PM2.5 and PM10 values and return the higher (more conservative) of the two calculated index values.
+
+### AQI Scale (US EPA)
+
+| Index | Level | Health Implications |
+|-------|-------|---------------------|
+| 0-50 | Good | Air quality is satisfactory |
+| 51-100 | Moderate | Acceptable; some pollutants may be a concern for sensitive individuals |
+| 101-150 | Unhealthy for Sensitive Groups | Members of sensitive groups may experience health effects |
+| 151-200 | Unhealthy | Everyone may begin to experience health effects |
+| 201-300 | Very Unhealthy | Health alert: everyone may experience more serious health effects |
+| 301-500 | Hazardous | Health warnings of emergency conditions |
+
+### CAQI Scale (European)
+
+| Index | Level | Health Implications |
+|-------|-------|---------------------|
+| 0-25 | Very Low | Air quality is excellent |
+| 26-50 | Low | Air quality is good |
+| 51-75 | Medium | Air quality is fair |
+| 76-100 | High | Air quality is poor |
+| 101-400 | Very High | Air quality is very poor |
+
+### Configuration Example
+
+```yaml
+sensor:
+  - platform: pmsx003
+    type: PMSX003
+    pm_2_5:
+      name: "PM2.5"
+    pm_10_0:
+      name: "PM10"
+    aqi:
+      name: "Air Quality Index"
+      calculation_type: "AQI"  # or "CAQI" for European standard
+      # Optional: Apply filters for smoother values
+      filters:
+        - sliding_window_moving_average:
+            window_size: 15
+            send_every: 1
+```
+
 ## See Also
 
 - {{< docref "/components/sensor/sds011" >}}

content/components/wifi.md

@@ -97,13 +97,19 @@ wifi:
   for ESP8266 is 20dB, 20.5dB might cause unexpected restarts.
 
 - **fast_connect** (*Optional*, boolean): If enabled, directly connects to WiFi network without doing a full scan
-  first. This is required for hidden networks and can significantly improve connection times (thus reducing power
-  consumption). Defaults to `off`.
+  first. This can significantly improve connection times (thus reducing power consumption). Defaults to `off`.
   The downside is that this option connects to the first network the ESP sees, even if that network is very far away and
   better ones are available. If multiple networks are configured, the last successfully connected one is tested first.
   In case it fails, all networks are then tested one after the other in their declared order, starting with the first
   one in the list.
 
+  > [!NOTE]
+  > While `fast_connect` skips the initial scan, if the connection attempt fails, ESPHome will still perform a scan
+  > to find available networks. For hidden networks, use `hidden: true` on the network configuration (see
+  > [Connecting to Multiple Networks](#wifi-networks)) to ensure the device always connects without scanning.
+  > Be aware that marking networks as hidden prevents ESPHome from finding the best access point to connect to,
+  > so the device may not connect to the AP with the best signal strength.
+
 - **min_auth_mode** (*Optional*, string): Only on `esp32` and `esp8266`. Sets the minimum WiFi authentication mode
   that the device will accept when connecting to access points. This controls the weakest encryption your device will
   allow. Possible values are:
@@ -300,11 +306,27 @@ wifi:
 - **hidden** (*Optional*, boolean): Whether this network is hidden. Defaults to false.
   If you add this option you also have to specify ssid.
 
+  > [!TIP]
+  > Set `hidden: true` if your network does not broadcast its SSID. This ensures the device attempts to connect
+  > using hidden network mode without first scanning for visible networks. Note that when connecting to a hidden
+  > network, ESPHome cannot determine which access point has the best signal strength, potentially resulting in
+  > connections to APs with weaker signals when multiple APs share the same SSID.
+
 - **priority** (*Optional*, int): The priority of this network (range: -128 to 127). The network with
   the highest priority is chosen. After each connection failure, the priority is decreased by one.
   If all tracked BSSIDs have identical priorities, they are automatically reset to 0 to start fresh.
   Defaults to `0`.
 
+### Example: Connecting to a Hidden Network
+
+```yaml
+wifi:
+  networks:
+  - ssid: MyHiddenNetwork
+    password: VerySafePassword
+    hidden: true
+```
+
 {{< anchor "eap" >}}
 
 ## Enterprise Authentication