Assist tutorial on setting up phone to control HA (#27121)

* Assist tutorial on setting up phone to control HA

- Add new folder projects/private-voice-assistant
- Add tutorial on setting up a classic analog phone to control Home Assistant
-- Instructions on setting up Grandstream
-- Instructions on setting up Voice over IP integration
-- Instructions on setting up voice assistant (basic setup using default settings, not including Alexa or Google)
-- Troubleshooting information
- Link to tutorial from front page
- Link to tutorial from documentation page, asides

* VoIP tutorial: add step to activate assistant

* Remove unused images

* Remove unused ESPHome images

* VoIP tutorial: fix grammar: set up vs setup

* Apply suggestions from code review

Co-authored-by: Paulus Schoutsen <balloob@gmail.com>
Co-authored-by: Franck Nijhof <git@frenck.dev>

* Apply suggestions from code review

Co-authored-by: Franck Nijhof <git@frenck.dev>

* Review feedback: update images

* Review feedback: fix sidebar

* Review feedback: rename file to index

* Review comments: remove info on how to view logs

* Implement review feedback

* Review feedback: update troubleshooting procedures

* Implement review comments: Remove section on setting up assistant

- There will be one setup by default.

* Move generic troubleshooting into separate section

- so that it can be a link target for other pages
- Pointing to the VoIP tutorial for troubleshooting is less ideal,
- as it is more than troubelshooting
- and includes VoIP specific troubleshooting

* Remove FAQ

- It contained a reference to the list of supported languages.
- It is no longer required to check if one's languages is supported,
	 as the UI only proposes supported languages.

* add link to custom sentences

-add name of phone model used in video by @TheFes

* Implement review feedback

* Implement review feedback. Missed that one

* Fix broken links

* Fix title

* Change troubleshooting file name

* Update screenshot

* Fix title in aside

* Add interview with Mario

* Fix typo

---------

Co-authored-by: Paulus Schoutsen <balloob@gmail.com>
Co-authored-by: Franck Nijhof <git@frenck.dev>

source/_includes/asides/docs_navigation.html

@@ -46,7 +46,9 @@
           <li>{% active_link /docs/assist/apple/ Assist for Apple devices %}</li>
           <li>{% active_link /docs/assist/builtin_sentences/ Built-in sentences %}</li>
           <li>{% active_link /docs/assist/custom_sentences/ Custom sentences %}</li>
+          <li>{% active_link /docs/assist/troubleshooting/ Troubleshooting Assist %}</li>
           <li>{% active_link /docs/assist/voice_remote_local_assistant/ Configuring a local assistant %}</li>
+          <li>{% active_link /projects/worlds-most-private-voice-assistant/ Tutorial: World's most private voice assistant %}</li>
           <li>{% active_link /projects/thirteen-usd-voice-remote/ Tutorial: $13 voice remote %}
           </li>
         </ul>

source/_integrations/voip.markdown

@@ -12,7 +12,7 @@ ha_domain: voip
 ha_integration_type: integration
 ---
 
-The VoIP integration enables users to talk to [Assist](/docs/assist) using an analog phone and a VoIP adapter such as the [Grandstream HT801](https://amzn.to/40k7mRa). See [the tutorial](/projects/private-voice-assistant/voice_remote_classic_phone/) for detailed instructions.
+The VoIP integration enables users to talk to [Assist](/docs/assist) using an analog phone and a VoIP adapter such as the [Grandstream HT801](https://amzn.to/40k7mRa). See [the tutorial](/projects/worlds-most-private-voice-assistant/voice_remote_classic_phone/) for detailed instructions.
 
 <p class='img'>
   <img src="/images/integrations/voip/voip_adapter.png" />

source/index.html

@@ -90,7 +90,7 @@ feedback: false
       </a>
     </div>
     <div class="grid__item two-thirds lap-two-thirds palm-one-whole">
-      <!-- State of the Open Home 2022 -->
+      <!-- Year of the voice chapter 2 -->
       <a
         href="https://www.youtube.com/watch?v=Tk-pnm7FY7c"
         target="_blank"
@@ -101,7 +101,18 @@ feedback: false
           padding-top: 45%;
         "
       ></a>
-
+      <!-- Tutorial: setup private voice assistant over phone -->
+      <a
+        href="/projects/worlds-most-private-voice-assistant/"
+        target="_blank"
+        class="material-card picture-promo"
+        style="
+          background-image: url(/images/frontpage/promo-private-voice-assistant.png);
+          background-size: cover;
+          padding-top: 45%;
+        "
+      ></a>
+      <!-- State of the Open Home 2022 -->
       <a
         href="https://www.youtube.com/watch?v=D936T1Ze8-4"
         target="_blank"

source/projects/troubleshooting.markdown

@@ -0,0 +1,30 @@
+---
+title: "Troubleshooting Assist"
+---
+
+This section lists a few steps that may help you troubleshoot issues with Assist. 
+
+## View debug information
+
+1. Go to **Settings** > **Voice assistants**.
+1. From the list of assistants, select your assistant.
+   ![Select your assistant](/images/assist/assistant-select.png)
+1. In the dialog, select **Debug**.
+![Open the debug dialog](/images/assist/assistant-debug-03.png)
+1. At the top of the screen, from the dropdown menu, select the run you are interested in.
+![Debug speech-to-text](/images/assist/assistant-debug-02.png)
+
+## Test if the phrase works without voice
+
+1. [Open the debug view](#view-debug-information).
+1. In the top right corner, select the icon.
+![Open the pipeline debug dialog](/images/assist/assistant-debug-04.png)
+1. Select **Run text pipeline**.
+![Open the pipeline debug dialog](/images/assist/assistant-debug-pipeline-01.png)
+1. Enter the phrase you want to test and select **Run**.
+![Open the pipeline debug dialog](/images/assist/assistant-debug-pipeline-02.png)
+1. Check if it worked.
+![Open the pipeline debug dialog](/images/assist/assistant-debug-pipeline-03.png)
+   * If the phrase does not work, try a variant. For example, if *Turn off the light* doesn't work, try: *Turn off the lights in the kitchen*.
+   * Check if your phrase is [supported](/docs/assist/builtin_sentences/).
+   * Make sure you are using the name of the area as it is defined in Home Assistant. If you have a room called *bathroom*, the phrase *Turning on the lights in the bath* won’t work.

source/projects/worlds-most-private-voice-assistant.markdown

@@ -0,0 +1,99 @@
+---
+title: "World's Most Private Voice Assistant"
+---
+
+This tutorial will guide you to turn your old landline phone into the
+world's most private voice assistant. Pick up the phone to talk to
+your smart home and issue commands and get responses.
+
+<lite-youtube videoid="0YJzLIMrnGk" videotitle="Using an analog phone to control Home Assistant"></lite-youtube>
+
+## Required material
+
+* Home Assistant 2023.5 or later
+* An [analog phone](#about-the-analog-phone) with an RJ11 socket
+* An analog telephone adapter 
+  [Grandstream HT801](https://amzn.to/40k7mRa)
+  * includes a 5&nbsp;V power adapter and an Ethernet cable
+* RJ11 phone cable to connect the phone to the Grandstream
+* [Home Assistant Cloud](https://www.nabucasa.com) or a manually configured [Assist Pipeline](/integrations/assist_pipeline)
+
+## Setting up Grandstream
+
+1. Connect the RJ11 cable from the phone to the green socket on the Grandstream.
+   ![Grandstream HT801 ports](/images/assist/grandstream-ht801-interfaces.png)
+1. Connect the Grandstream to your network: 
+   * Plug the Ethernet cable into the blue socket and connect it to your router.
+1. Start up the Grandstream.
+   * Connect the power supply.
+   * Once the Grandstream has booted, the two LEDs for power and Ethernet light up solid blue. The phone LED won't light up.
+1. Identify the IP address of the Grandstream.
+   * If your phone has a star * key, you can get your phone to tell you it's IP address:
+      *  Press *** (press the star key three times) and wait until you hear *Enter the menu option*.
+      *  Press 02 and the phone will tell you its IP address.
+   * If your phone does not have a star * key, log onto your router to find the IP address.
+1. Enter the IP address into a browser window and log onto the Grandstream *Device Configuration* software.
+   * The default credentials are:
+     * **Username**: `admin`
+     * **Password**: `admin`  
+   ![Login to Grandstream](/images/assist/grandstream_login.png)
+1. Open the **FXS Port** tab and in the **Offhook Auto-Dial** field, enter the Home Assistant IP address in the following format:
+   * \*47192\*168\*1\*100\*5060
+   ![Define IP for autodial](/images/assist/grandstream_autodial.png)
+   * Note: instead of 192\*168\*1\*100\*, enter the IP address of your Home Assistant instance.
+   * At the bottom of the page, select **Apply**. 
+   ![Define IP for autodial](/images/assist/grandstream_apply.png)
+   * *Offhook Auto-Dial* means that when you pick up the phone, it directly calls Home Assistant. No need to dial.
+
+## Setting up the phone in Home Assistant
+
+1. In Home Assistant, go to {% my config_flow_start domain="voip" title="**Settings** > **Devices & Services** > **Add integration**" %} and add the **Voice over IP** integration.
+    ![Voice over IP integration](/images/assist/voip_install.png)
+1. Once you see the integration, pick up the phone.
+   * You should now hear the message *This is your smart home speaking. Your phone is connected, but you must configure it within Home Assistant.*
+   * The integration should now include a device and entities.
+    ![Voice over IP integration with device and entities](/images/assist/voip_device_available.png)
+   * Don't hear the voice? Try these [troubleshooting steps](/projects/worlds-most-private-voice-assistant/#troubleshoot-grandstream).
+1. Allow calls.
+   * Calls from new devices are blocked by default since voice commands could be used to control sensitive devices, such as locks and garage doors.
+   * In the **Voice over IP** integration, select the **device** link.
+   * To allow this phone to control your smart home, under **Configuration**, enable **Allow calls**.   
+   ![Voice over IP integration - allow calls](/images/assist/voip_configuration.png) 
+1. Congratulations! You set up your analog phone to work with Home Assistant. Now pick up the phone and control your device. 
+   * Say a [supported voice command](/docs/assist/builtin_sentences/). For example, *Turn off the light in the kitchen*.
+   * You can also ask a question, such as
+     *  *Is the front door locked?*
+     *  *Which lights are on in the living room?*
+   * Make sure you're using the area name as you defined it in Home Assistant. If you have a room called *bathroom*, the phrase *Turn on the lights in the bath* won't work.
+   * Your command is not supported? [Add your own commands](/integrations/conversation/).
+
+## Give your voice assistant personality using the OpenAI integration
+
+<lite-youtube videoid="eLx8_NAqptk" videotitle="Give your voice assistant personality using the OpenAI integration"></lite-youtube>
+
+## Troubleshoot Grandstream
+
+If you’re unable to call Home Assistant, confirm the following settings in your Grandstream device’s web interface.
+
+1. On the **FXS Port** tab, check the **Preferred Vocoder** list. 
+   * Make sure that **OPUS** is selected for one of the choices:
+   ![Vocoder OPUS option](/images/assist/grandstream_vocoder.png) 
+1. Under **OPUS Payload type**, make sure the value is `123`. It's the default option.
+   ![Vocoder OPUS payload type](/images/assist/grandstream_opus_payload.png)
+1. At the bottom of the page, select **Apply**.
+1. Pick up the phone again and check if you hear the voice.
+
+## Other troubleshooting steps
+
+Are things still not working as expected? 
+
+* Checkout the [general troubleshooting section for Assist](/projects/troubleshooting).
+
+## About the analog phone
+
+You can use any analog landline phone with an RJ11 socket.
+
+The phone shown in the video by TheFes is a *Heemaf type 1955*, which was used by the Dutch telephone company PTT at the time.
+
+The phone used during creation of this tutorial is a 1953 [*Tischstation Mod.29 HF-TR* by Autophon AG](https://www.radiomuseum.org/r/autophon_tischstation_mod29_hf_tr.html).
+![Analog phone Tischstation Mod.29 by Autophon AG](/images/assist/autophon-mod-29.jpg)