docs 📝: Update README.md for improved interface detection and troubleshooting guidance

Updated the README.md file to include detailed instructions on how to improve interface detection, add Ansible facts-based validation, and enhance troubleshooting guidance.

README.md

@@ -1,13 +1,13 @@
 # ansible_proxmox_WOL
 
-A robust, idempotent Ansible role for enabling persistent Wake-on-LAN (WOL) on Proxmox VE servers. This role automatically detects physical network interfaces backing bridge interfaces (including bonded interfaces) and persistently enables WOL via udev rules.
+A robust, idempotent Ansible role for enabling persistent Wake-on-LAN (WOL) on Proxmox VE servers. This role automatically detects physical network interfaces with WOL capability using Ansible facts and persistently enables WOL via udev rules.
 
 ## Features
 
 ✅ **Fully Idempotent**: Checks current WOL status and only applies changes when needed  
 ✅ **Multiple Bridge Support**: Configure WOL on multiple bridges simultaneously  
 ✅ **Bond0 Detection**: Automatically detects and configures bonded interfaces  
-✅ **Auto-Detection**: Intelligently detects physical NICs backing Proxmox bridges  
+✅ **Ansible Facts-Based**: Uses Ansible facts to detect and validate WOL-capable interfaces  
 ✅ **Safe & Persistent**: Uses udev rules for persistence across reboots  
 ✅ **Comprehensive Validation**: Verifies WOL capability before configuration  
 ✅ **Detailed Reporting**: Shows configuration status and MAC addresses for WOL senders  
@@ -24,14 +24,15 @@ A robust, idempotent Ansible role for enabling persistent Wake-on-LAN (WOL) on P
 ## How It Works
 
 1. **Package Installation**: Ensures `ethtool` is installed for WOL management
-2. **Bridge Discovery**: Reads bridge configuration and maps to physical NICs
-3. **Bond0 Detection**: Detects if interfaces are bonded and extracts slave information
-4. **Validation**: Verifies all detected NICs support Wake-on-LAN
-5. **Idempotency Check**: Reads current WOL status to avoid redundant changes
-6. **Enable WOL**: Applies WOL settings only to interfaces that need it
-7. **Persist Settings**: Creates/updates udev rules for persistence across reboots
-8. **Reload Udev**: Reloads udev rules and triggers network interface refresh
-9. **Verification & Reporting**: Displays WOL configuration status and MAC addresses
+2. **Interface Discovery**: Uses Ansible facts to identify all physical Ethernet interfaces
+3. **WOL Validation**: Tests each interface for Wake-on-LAN capability using ethtool
+4. **Bridge Mapping**: Maps configured bridges to their backing WOL-capable physical NICs
+5. **Bond0 Detection**: Detects if interfaces are bonded and extracts slave information
+6. **Idempotency Check**: Reads current WOL status to avoid redundant changes
+7. **Enable WOL**: Applies WOL settings only to interfaces that need it
+8. **Persist Settings**: Creates/updates udev rules for persistence across reboots
+9. **Reload Udev**: Reloads udev rules and triggers network interface refresh
+10. **Verification & Reporting**: Displays WOL configuration status and MAC addresses
 
 ## Usage Examples
 
@@ -165,32 +166,42 @@ ACTION=="add", SUBSYSTEM=="net", KERNEL=="eno1", RUN+="/sbin/ethtool -s eno1 wol
 ```
 
 ### Detection Logic
-1. Reads `bridge link show` output
-2. Filters out virtual interfaces (veth, tap, fw*)
-3. Selects first physical NIC per bridge
-4. For bond0: extracts slave interfaces from `/proc/net/bonding/bond0`
+1. **Interface Discovery**: Uses Ansible facts to enumerate all network interfaces
+2. **Physical Interface Filtering**: Filters for Ethernet interfaces, excluding virtual interfaces (veth, tap, fw*, docker, br*)
+3. **WOL Capability Testing**: Tests each physical interface with ethtool to verify WOL support
+4. **Bridge Mapping**: Maps configured bridges to their backing WOL-capable physical NICs
+5. **Bond0 Detection**: Extracts slave interfaces from `/proc/net/bonding/bond0` when present
 
 ## Troubleshooting
 
+### "No network interfaces found that support Wake-on-LAN"
+- Check BIOS settings to ensure WOL is enabled
+- Verify NIC drivers support WOL: `ethtool <interface>`
+- Some NICs may require specific BIOS settings or driver parameters
+- Check if interfaces are properly detected: `ansible -m setup <host> | grep ansible_interfaces`
+
 ### "Unable to detect physical NIC backing bridge(s)"
 - Verify bridges exist: `bridge link show`
 - Check bridge configuration: `brctl show`
 - Ensure physical NIC is member of bridge
+- Confirm the backing interface supports WOL (listed in "Available WOL-capable interfaces")
 
 ### "Does not support Wake-on-LAN"
 - Check NIC capabilities: `ethtool <interface>`
-- Verify BIOS has WOL enabled
+- Verify BIOS has WOL enabled for the specific NIC
 - Some NICs have disabled WOL by default (check driver documentation)
+- Try different WOL modes: `p`, `u`, `m`, or `b`
 
 ### WOL not persisting after reboot
 - Check udev rules: `cat /etc/udev/rules.d/90-wol.rules`
 - Verify ethtool installed: `which ethtool`
 - Check system logs: `journalctl -u systemd-udevd -b`
+- Ensure udev service is running: `systemctl status systemd-udevd`
 
 ### Bond0 not detected
 - Check bond status: `cat /proc/net/bonding/bond0`
 - Verify bond is backing the configured bridge
-- Check bond slave interfaces
+- Check bond slave interfaces support WOL individually
 
 ## Notes for Proxmox Admins