Tweaks to HomeKit documentation (#16875)

source/_integrations/homekit.markdown

@@ -12,19 +12,33 @@ ha_codeowners:
 ha_zeroconf: true
 ---
 
-The HomeKit integration allows you to make your Home Assistant entities available in Apple HomeKit, so they can be controlled from Apple's Home app and Siri. Please make sure that you have read the [considerations](#considerations) listed below to save you some trouble later. However if you do encounter issues, check out the [troubleshooting](#troubleshooting) section.
+The HomeKit integration allows you to make your Home Assistant entities available in Apple HomeKit,
+so they can be controlled from Apple's Home app and Siri.
+
+Please make sure that you have read the [considerations](#considerations) listed below to save you
+some trouble later. However if you do encounter issues, check out the
+[troubleshooting](#troubleshooting) section.
 
 <div class="note">
 
-  If you want to control `HomeKit` only devices with Home Assistant, check out the [HomeKit controller](/integrations/homekit_controller/) component.
+  If you want to control HomeKit only devices with Home Assistant,
+  check out the [HomeKit controller](/integrations/homekit_controller/) integration.
+  That one provides the possibility to pull HomeKit enabled devices into Home Assistant.
 
 </div>
 
 {% include integrations/config_flow.md %}
 
-If you need to use the `entity_config`, `ip_address`, or `advertise_ip` configuration options, HomeKit Bridge must be configured via your `configuration.yaml` file:
+## Manual configuration
 
-```yaml
+If you want make specific changes to the way entities are published to HomeKit, override the
+IP address the HomeKit integration uses to communicate with your network or change the
+IP address the HomeKit uses to advertise itself to the network, you'll need to configure the
+HomeKit integration using a manual YAML entry to your `configuration.yaml` file.
+
+This is an example entry of how that would look:
+
+```yaml test
 # Example configuration.yaml entry configuring HomeKit
 homekit:
   - filter:
@@ -43,7 +57,7 @@ homekit:
         linked_battery_sensor: sensor.living_room_motion_battery
         low_battery_threshold: 31
       light.kitchen_table:
-      name: Kitchen Table Light
+        name: "Kitchen Table Light"
       lock.front_door:
         code: 1234
       media_player.living_room:
@@ -55,8 +69,8 @@ homekit:
       switch.bedroom_outlet:
         type: outlet
       camera.back_porch:
-      support_audio: True
+        support_audio: true
-- name: HASS Bridge 2
+  - name: "HASS Bridge 2"
     port: 56332
     filter:
       include_domains:
@@ -521,10 +535,6 @@ Pairing works fine when the filter is set to only include `demo.demo`, but fails
 1. Make sure that you don't try to add more than 150 accessories, see [device limit](#device-limit). In rare cases, one of your entities doesn't work with the HomeKit component. Use the [filter](#configure-filter) to find out which one. Feel free to open a new issue in the `home-assistant` repository, so we can resolve it.
 2. Check logs, and search for `Starting accessory Home Assistant Bridge on address`. Make sure Home Assistant Bridge hook up to a correct interface. If it did not, explicitly set `homekit.ip_address` configuration variable.
 
-#### Duplicate AID found when attempting to add accessory
-
-Two of your entities share the same `entity_id`. Either resolve this or configure the [filter](#configure-filter) to exclude them.
-
 ### Issues during normal use
 
 #### Some of my devices don't show up - Z-Wave / Discovery
@@ -569,7 +579,6 @@ Media Player entities with `device_class: tv` will show up as Television accesso
 
 The [Universal Media Player](/integrations/universal/#harmony-remote-example) has an example of how it can be used to wrap existing entities to enable them to be used as a Television accessory in HomeKit.
 
-
 #### Can't control volume of your TV media player?
 
 The volume and play/pause controls will show up on the Remote app or Control Center. If your TV supports volume control through Home Assistant, you will be able to control the volume using the side volume buttons on the device while having the remote selected on screen.