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.

tasks/main.yml

@@ -22,7 +22,55 @@
     fail_msg: "wol_bridges must contain at least one bridge interface"
 
 # ============================================================
-# Detect physical NICs for all bridges (including bond0)
+# Detect physical NICs with WOL support using Ansible facts
+# ============================================================
+- name: Gather network interface facts
+  ansible.builtin.setup:
+    gather_subset:
+      - network
+  when: ansible_facts.interfaces is not defined
+
+- name: Get all physical network interfaces with WOL support
+  ansible.builtin.set_fact:
+    wol_capable_interfaces: >-
+      {{
+        ansible_facts.interfaces
+        | map('extract', hostvars[inventory_hostname]['ansible_' ~ item] | default({}))
+        | selectattr('type', 'defined')
+        | selectattr('type', 'equalto', 'ether')
+        | selectattr('device', 'defined')
+        | rejectattr('device', 'search', '^(veth|tap|fw|lo|docker|br)')
+        | map(attribute='device')
+        | list
+      }}
+
+- name: Validate WOL capability using ethtool for detected interfaces
+  ansible.builtin.command: "ethtool {{ item }}"
+  register: wol_capabilities_check
+  changed_when: false
+  failed_when: false
+  loop: "{{ wol_capable_interfaces }}"
+  loop_control:
+    label: "{{ item }}"
+
+- name: Filter interfaces that actually support WOL
+  ansible.builtin.set_fact:
+    wol_supported_interfaces: >-
+      {{
+        wol_capabilities_check.results
+        | selectattr('stdout', 'search', 'Supports Wake-on:.*[gGdDpPuU]')
+        | map(attribute='item')
+        | list
+      }}
+
+- name: Fail if no interfaces support WOL
+  ansible.builtin.assert:
+    that:
+      - wol_supported_interfaces | length > 0
+    fail_msg: "No network interfaces found that support Wake-on-LAN. Check BIOS settings and NIC capabilities."
+
+# ============================================================
+# Map bridges to physical NICs using Ansible facts
 # ============================================================
 - name: Get bridge link information
   ansible.builtin.command: "bridge link show"
@@ -30,13 +78,6 @@
   changed_when: false
   check_mode: false
 
-- name: Get bond info
-  ansible.builtin.command: "cat /proc/net/bonding/bond0"
-  register: bond_info
-  changed_when: false
-  failed_when: false
-  check_mode: false
-
 - name: Initialize detected interfaces dictionary
   ansible.builtin.set_fact:
     wol_detected_interfaces: {}
@@ -52,6 +93,7 @@
             | map('regex_replace', '^\\d+: ([a-z0-9@.]+):.*$', '\\1')
             | reject('search', '^(veth|tap|fw)')
             | reject('search', '^\\d+:')
+            | select('in', wol_supported_interfaces)
             | first | default('')
           )
         })
@@ -82,9 +124,8 @@
   ansible.builtin.fail:
     msg: >
       Unable to detect physical NIC backing bridge(s): {{ unresolved_bridges | join(', ') }}.
-      Please verify bridges exist or set wol_interfaces explicitly.
-      Bridge output:
-      {{ bridge_links.stdout_lines | join('\n') }}
+      Please verify bridges exist and are backed by WOL-capable interfaces.
+      Available WOL-capable interfaces: {{ wol_supported_interfaces | join(', ') }}
   vars:
     unresolved_bridges: "{{ wol_detected_interfaces | dict2items | selectattr('value', 'equalto', '') | map(attribute='key') | list }}"
   when: unresolved_bridges | length > 0
@@ -93,27 +134,6 @@
   ansible.builtin.set_fact:
     wol_final_interfaces: "{{ wol_detected_interfaces.values() | unique | list }}"
 
-# ============================================================
-# Validate WOL capability
-# ============================================================
-- name: Check WOL capability on all detected NICs
-  ansible.builtin.command: "ethtool {{ item }}"
-  register: wol_capabilities_check
-  changed_when: false
-  failed_when: false
-  loop: "{{ wol_final_interfaces }}"
-  loop_control:
-    label: "{{ item }}"
-
-- name: Validate all NICs support WOL
-  ansible.builtin.assert:
-    that:
-      - item.stdout is search('Supports Wake-on:.*[gGdDpPuU]')
-    fail_msg: "Interface {{ item.item }} does not support Wake-on-LAN"
-  loop: "{{ wol_capabilities_check.results }}"
-  loop_control:
-    label: "{{ item.item }}"
-
 # ============================================================
 # Check current WOL status to ensure idempotency
 # ============================================================