Voice: add separate troubleshooting section (#30280)

source/_includes/asides/voice_navigation.html

@@ -22,7 +22,6 @@
       <li>{% active_link /voice_control/custom_sentences/ Custom sentences %}</li>
       <li>{% active_link /voice_control/using_tts_in_automation/ Using Piper TTS in automations %}</li>
       <li>{% active_link /voice_control/assist_create_open_ai_personality/ Creating a personality with OpenAI %}</li>
-      <li>{% active_link /voice_control/troubleshooting/ Troubleshooting Assist %}</li>
     </ul>
   </div>
 
@@ -36,4 +35,11 @@
       <li>{% active_link /voice_control/assist_daily_summary/ Tutorial: Your daily summary by Assist %}</li>
     </ul>
   </div>
+  <div class="section">
+    <h1 class="title delta">Troubleshooting</h1>
+    <ul class="divided sidebar-menu">
+      <li>{% active_link /voice_control/troubleshooting/ Troubleshooting Assist %}</li>
+      <li>{% active_link /voice_control/troubleshooting_the_s3_box/ Troubleshooting the ESP32-S3-BOX %}</li>
+    </ul>
+  </div>
 </section>

source/_redirects

@@ -252,6 +252,9 @@ layout: null
 /docs/assist/using_voice_assistants_overview/ /voice_control/
 /docs/assist/voice_remote_expose_devices/ /voice_control/voice_remote_expose_devices/
 /docs/assist/voice_remote_local_assistant/ /voice_control/voice_remote_local_assistant/
+# Redirect for the QR Codes on the S3 Box
+/s3-box-no-wifi /voice_control/troubleshooting_the_s3_box/#error-unable-to-connect-to-wi-fi
+/s3-box-no-ha /voice_control/troubleshooting_the_s3_box/#error-no-home-assistant
 /docs/assist/troubleshooting/ /voice_control/troubleshooting/
 /docs/assist/worlds-most-private-voice-assistant/ /voice_control/worlds-most-private-voice-assistant/
 /projects/worlds-most-private-voice-assistant/ /voice_control/worlds-most-private-voice-assistant/

source/voice_control/troubleshooting_the_s3_box.markdown

@@ -0,0 +1,72 @@
+---
+title: "Troubleshooting the ESP32-S3-BOX-3"
+---
+
+This section provides troubleshooting steps for the ESP32-S3-BOX-3 by Espressif.
+
+## Error: Unable to connect to Wi-Fi
+
+### Symptom
+
+The ESP32-S3-BOX-3 shows a message that it is unable to connect to Wi-Fi.
+
+### Remedy
+
+1. First, check if your network is ready in general.
+   1. Make sure your router is on and within reach.
+   2. Make sure you have chosen a Wi-Fi network that supports 2.4 GHz. The ESP32-S3-BOX-3 won't show up on a 5 GHz network.
+
+2. The next step is to make sure you entered the correct Wi-Fi password. Follow the steps either under **Option 1** or **Option 2**, depending on whether or not you have the ESPHome add-on installed.
+   - **Option 1**: You do not have the ESPHome add-on installed or you have the add-on but did **not** adopt the ESP32-S3-BOX-3. If the device is shown in green, it is not adopted. 
+      ![ESP32-S3-BOX-3 not adopted](/images/assist/esp32-not-adopted.png)
+     1. Make sure the USB cable is plugged into the ESP32-S3-BOX-3.
+     2. Go to the [ESPHome projects website](https://esphome.io/projects/index.html), select the **Connect** button, then **Change Wi-Fi**.
+   - **Option 2**: You already have the ESPHome add-on installed and adopted the ESP32-S3-BOX-3 on your ESPHome dashboard.
+     1. Make sure the USB cable is plugged into the ESP32-S3-BOX-3.
+     2. In Home Assistant, go to [**Settings** > **Add-ons** > **ESPHome**](https://my.home-assistant.io/redirect/supervisor_addon/?addon=5c53de3b_esphome), and **Open Web UI**.
+     3. On the **ESP32-S3-BOX-3** add-on, select edit.
+       ![ESP32-S3-BOX-3 open config file](/images/assist/esps32-s3-edit-config.png)
+        - **Result**: An editor opens, showing the configuration file.
+       ![ESP32-S3-BOX-3 edit config file](/images/assist/esp32-edit-wifi-credentials.png)
+     4. In the **wifi** section, check if it refers to the `secrets` file (contains `!secret`).
+        If it does not contain a **wifi** section, enter the section below:
+
+        ```yaml
+        wifi:
+          ssid: !secret wifi_ssid
+          password: !secret wifi_password
+        ```
+
+     5. Close the editor and in the overview, select **Secrets**.
+        ![ESP32-S3-BOX-3 open config file](/images/assist/esp32-open-secrets.png)
+     6. Enter your Wi-Fi credentials.
+        ![ESP32-S3-BOX-3 open config file](/images/assist/esp32-edit-secrets.png)
+
+## Error: No Home Assistant
+
+### Symptom
+
+The ESP32-S3-BOX-3 shows a message that there is no Home Assistant.
+
+### Description
+
+This message indicates that the device could connect to the Wi-Fi, but is unable to communicate with Home Assistant.
+
+### Remedy
+
+1. If you see this message during a restart or while an update is running, wait until the restart or update is finished.
+   - In this case, there is nothing you need to do. It is expected that the device temporarily stops communicating.
+2. Make sure your device is on the same network as Home Assistant.
+   - If you have a complex network setup with VLAN, make sure it is in the same VLAN.
+3. Go to {% my integrations title="**Settings** > **Devices & Services**" %}.
+   - If the device is shown as **Discovered**, select **Configure**.
+     ![ESP32-S3-BOX-3 open config file](/images/assist/esp32-discovered.png)
+   - If it was not discovered, select [**Add integration** > **ESPHome**](https://my.home-assistant.io/redirect/config_flow_start/?domain=esphome).
+4. If you see the screen below, but the ESP32-S3-BOX-3 is not listed, select **Setup another instance of ESPHome**.
+
+   ![ESP32-S3-BOX-3 open config file](/images/assist/esp32-s3-box-not-discovered.png)
+   - Go to your router, find the IP address or hostname of your device, and enter it.
+
+## Related topics
+
+- [Assist Pipeline](/voice_control/voice_remote_local_assistant)