Document HomeKit controller device automation triggers and improve debugging guide (#14476)

source/_integrations/homekit_controller.markdown

@@ -41,6 +41,13 @@ There is currently support for the following device types within Home Assistant:
 - Sensor (HomeKit humidity, temperature, co2 and light level sensors)
 - Fan
 - Air Quality
+- Automation Triggers (HomeKit 'stateless' accessories like buttons, remotes and doorbells)
+
+<div class='note'>
+
+  If your device is not on this list then you may still be able to pair it, and it will be visible in the Device Registry. But Home Assistant may not create entities for it.
+
+</div>
 
 HomeKit IP accessories for these device types may work with some caveats:
 
@@ -51,11 +58,33 @@ HomeKit controller will poll your devices, but it will also automatically enable
 
 Home Assistant does not currently support HomeKit BLE.
 
-<div class='note'>
+## 'Stateless' switches and sensors
 
-  HomeKit Controller might detect some HomeKit devices on your network that are not currently supported by this integration. One such example is HomeKit displays (such as Vizio TVs which have been updated with HomeKit support). These devices might pair with Home Assistant if you go through the pairing process, but no entity will be created, and you won't be able to control these devices with Home Assistant. However, pairing the device with Home Assistant *will* remove the persistent notification generated when Home Assistant finds new devices.
+Some HomeKit devices (like buttons, remotes and doorbells) don't have sensors that can be read like a normal HomeKit device - they only inform Home Assistant when something happens. This means Home Assistant can't show an entity for them, as they have no state. But they are available for use as [device automations](/integrations/device_automation/).
 
-</div>
+For example, to add a new automation that is triggered by one of these devices go to the device registry UI and find the device you want to use as a trigger. Click on it to reveal the device registry entry for it. You will be able to see the devices model, manufacturer and firmware version. You might see related entities - like a battery sensor.
+
+<p class='img'>
+<img src='/images/integrations/homekit_controller/device_automation_start.png' />
+</p>
+
+Click on the button to add an automation. A popup will show you a list of triggers that are available.
+
+<p class='img'>
+<img src='/images/integrations/homekit_controller/device_automation_triggers.png' />
+</p>
+
+Clicking on one will drop you in to the automation editor with a trigger pre-filled in. If your device supports it you will be able to choose between types of event - like a short press or a long press.
+
+<p class='img'>
+<img src='/images/integrations/homekit_controller/device_automation_new.png' />
+</p>
+
+When you have filled in the rest of the form to create your migration it will show up against that device in the device registry.
+
+<p class='img'>
+<img src='/images/integrations/homekit_controller/device_automation_finish.png' />
+</p>
 
 ## Troubleshooting
 
@@ -75,6 +104,36 @@ For IP accessories, Home Assistant can only find devices that are already on the
 
 Home Assistant can only find accessories that aren't already paired. Even if you reset your Home Assistant configuration, the accessory will still think it is paired and you won't be able to use it with Home Assistant. You should reset the accessory according to the manufacturer's instructions. Some devices have a "Reset HomeKit" option, and some may require a full reset.
 
+If your devices are on a different VLAN to Home Assistant you must have an mDNS reflector for discovery and pairing to work.
+
+Check that your device is visible with an mDNS tool. If you are comfortable with the command line you can run `netdisco` from your Home Assistant installation:
+
+```bash
+python3 -m netdisco
+Discovered devices:
+homekit:
+[ {'host': '192.168.17.5',
+  'hostname': 'Philips-hue.local.',
+  'name': 'Philips hue - xxxx',
+  'port': 8080,
+  'properties': {'c#': '21',
+                 'ci': '2',
+                 'ff': '1',
+                 'id': 'AA:BB:CC:DD:EE:FF',
+                 'md': 'BSB002',
+                 'pv': '1.1',
+                 's#': '1',
+                 'sf': '0'}},
+```
+
+`netdisco` is not used by Home Assistant to discover HomeKit devices, so if it can't see your device the problem is more likely to be environmental than with Home Assistant itself.
+
+Alternatively if you are less comfortable with the command line you could use Discovery for [Mac](https://apps.apple.com/us/app/discovery-dns-sd-browser/id1381004916?mt=12) or [iOS](https://apps.apple.com/us/app/discovery-dns-sd-browser/id305441017), Android [Service Browser](https://play.google.com/store/apps/details?id=com.druk.servicebrowser) or [All My Lan](https://www.microsoft.com/en-us/p/all-my-lan/9wzdncrdn19v). These are a less useful diagnostic as they aren't running from the same point on your network as Home Assistant. Even if it is visible in this tool it might still be a networking issue. They can give sometimes give clues.
+
+Where a discovery tool does give an IP, check it is what you expect (compare to DHCP leases in your router for example). Can you ping it? If not, you have a network problem.
+
+Some users have reported that their network configuration has interfered with using HomeKit devices with Home Assistant. The symptoms vary but include discovery not working at all or being unstable (sometimes working, sometimes not). This is very specific not only to the hardware in use but how it is configured and unfortunately we can't suggest appropriate settings. For example, we have seen IGMP Snooping be blamed as the cause of the problem and also suggested as the fix.
+
 ### HomeKit controller is finding devices on my network even though I don't have any Apple devices
 
 This is completely normal. Unlike many other commercial IoT offerings, the HomeKit protocol is a local and offline protocol that does not rely on the Apple ecosystem to function. You do not need an Apple online account to use a "Works with HomeKit" device. Some Wi-Fi devices may need an iOS device briefly to get them onto your WiFi, but other than that you do not need any Apple hardware on your network.
@@ -96,3 +155,7 @@ In these cases it's unlikely that HomeKit controller itself is directly responsi
 - There is a problem with the accessory itself which is causing intermittent network issues.
 
 In these cases, HomeKit Controller will skip polling to avoid a buildup of back pressure in your instance.
+
+### I can't see any events generated for "stateless" accessories
+
+This is expected. The only way to use stateless accessories like some doorbells, buttons or remotes with Home Assistant is through device automations. Home Assistant doesn't create duplicate events for device automation triggers, so for example you won't be able to watch them with the events developer tools.