Add HEOS configuration options documentation

source/_integrations/heos.markdown

@@ -46,6 +46,22 @@ Host:
     description: "The host name or IP address (e.g., \"192.168.1.2\") of your HEOS-capable product. If you have more than one device, select, or enter a host, that is connected to the LAN via wire or has the strongest wireless signal."
 {% endconfiguration_basic %}
 
+## Configuration options
+
+The integration provides the following configuration options. By entering your HEOS Account login information, the integration will be able to access streaming services, playlists, favorites, and other features. The integration will validate and sign in to your HEOS Account when credentials are entered or updated, and will ensure the HEOS System remains logged in while the credentials remain valid. Clearing the credentials will sign the HEOS System out of your account.
+
+1. Go to **{% my integrations icon title="Settings > Devices & Services" %}**.
+2. Select **Denon HEOS**. Click **CONFIGURE**.
+3. Enter or clear your HEOS Account credentials.
+4. Click Submit to save the options.
+
+{% configuration_basic %}
+Username:
+  description: "The username or e-mail address of your HEOS Account."
+Password:
+  description: "The password to your HEOS Account."
+{% endconfiguration_basic %}
+
 ## Reconfiguration
 
 Once setup, the host name or IP address used to access the HEOS System can be changed by reconfiguring the integration.
@@ -191,6 +207,10 @@ The HEOS integration makes various custom {% term actions %} available in additi
 Use the sign-in action to sign the connected device into a HEOS account so that it can retrieve and play HEOS favorites and playlists. An error message is logged if sign-in is unsuccessful.
 
 {% note %}
+The [configuration options](/integrations/heos#configuration-options) is the preferred method for managing your HEOS Account credentials. This service action will be deprecated in the future.
+
+ 
+
 The device the integration connects to authenticates independently of other devices and the HEOS mobile app. When you first set up the integration, or after a device firmware update, the device will most likely not be logged in.
 {% endnote %}
 
@@ -214,6 +234,10 @@ data:
 
 Use the sign-out action to sign the connected device out of a HEOS account. An error message is logged if sign-out is unsuccessful. There are no parameters to this action Example action data payload:
 
+{% note %}
+The [configuration options](/integrations/heos#configuration-options) is the preferred method for managing your HEOS Account credentials. This service action will be deprecated in the future.
+{% endnote %}
+
 ```yaml
 action: heos.sign_out
 data: {% raw %}{}{% endraw %}
@@ -244,15 +268,37 @@ HEOS pushes data to Home Assistant via the local network when data and entity st
 
 ### Missing favorites
 
-#### Symptom: "IP_ADDRESS is not logged in to a HEOS account and will be unable to retrieve HEOS favorites..."
+#### Symptom: "The HEOS System is not logged in: Enter credentials in the integration options to access favorites and streaming services"
+
+The message above is logged during integration startup and the `source_list` attribute of the integration's media_player entities are empty. Attempting call the `media_player.play_media` action
+for `favorite` and `playlist` will fail. Other functionality of the integration is unaffected.
+
+##### Description
+
+To access features, such as favorites, playlists, and streaming services, the HEOS System must be logged in to your HEOS Account. This occurs when credentials are not entered in the configuration options and the HEOS System is in a logged out state.
+
+##### Resolution
+
+Enter the credentials to your HEOS Account in the [configuration options](/integrations/heos#configuration-options) if you want to access playlists, favorites, and streaming services; otherwise the logged warning can be ignored. If credentials are entered, the integration will ensure that the HEOS System remains logged in while the credentials remain valid.
+
+### Error attempting to submit configuration options
+
+#### Symptom: "Invalid authentication"
+
+##### Description
+
+The integration was unable to log the HEOS System in using the credentials provided. An informational log message contains the specific reason, such as: `User not found (10)` or `Invalid credentials (6)`.
+
+##### Resolution
+
+Validate your credentials by logging in to the HEOS Mobile App and then re-enter your credentials in the configuration options and try submitting again.
 
-The message above is logged and the `source_list` attribute of the integration's media_player entities are empty. Attempting call the `media_player.play_media` action
-for `favorite` and `playlist` will fail.
+#### Symptom: "Unexpected error"
 
 ##### Description
 
-The HEOS system is not logged in to a HEOS account. This occurs when the integration is first added, the HEOS account has changed (e.g. password reset), and sometimes after a firmware update.
+An unexpected error occurred signing in or logging out of your HEOS Account. An error-level log message contains the error information.
 
 ##### Resolution
 
-Use the [heos.sign_in action](/integrations/heos#action-heossign_in) to sign the HEOS system into a HEOS account. This only needs to be performed once, as the system will remain signed in while the account credentials are valid.
+Power-cycle the host that the integration is connected to and try again. If the problem persists, open an issue and include the error information.