[PR #8076/6298ad4f backport][stable-8] Implement usb_facts module (#8115)

Implement usb_facts module (#8076) * First implementation of usb module * Rename to usb_facts * Working tests * Appease linter * Fix author * Remove splitlines arg for python 2.7 compat * indent usb test further * indent usb test a bit less * Remove trailing whitespace * Update plugins/modules/usb_facts.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/usb_facts.py Co-authored-by: Felix Fontein <felix@fontein.de> * Apply suggestions from code review Co-authored-by: Felix Fontein <felix@fontein.de> * Adjust usb_facts PR based on feedback * Add usage example and extend correct documentation fragment * Add myself to BOTMETA.yml * Apply suggestions from code review Co-authored-by: Felix Fontein <felix@fontein.de> --------- Co-authored-by: Felix Fontein <felix@fontein.de> (cherry picked from commit 6298ad4faa) Co-authored-by: Maxopoly <max@dermax.org>
2025-05-02 15:21:25 -07:00 · 2024-03-19 06:39:46 +01:00 · 2024-03-19 06:39:46 +01:00 · 6071bbc200
commit 6071bbc200
parent a63bb9405a
3 changed files with 220 additions and 0 deletions
--- a/plugins/modules/usb_facts.py
+++ b/plugins/modules/usb_facts.py
@ -0,0 +1,113 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2024, Max Maxopoly <max@dermax.org>
+#
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: usb_facts
+short_description: Allows listing information about USB devices
+version_added: 8.5.0
+description:
+  - Allows retrieving information about available USB devices through C(lsusb).
+author:
+  - Max Maxopoly (@maxopoly)
+extends_documentation_fragment:
+  - community.general.attributes
+  - community.general.attributes.facts
+  - community.general.attributes.facts_module
+requirements:
+  - lsusb binary on PATH (usually installed through the package usbutils and preinstalled on many systems)
+'''
+
+EXAMPLES = '''
+- name: Get information about USB devices
+  community.general.usb_facts:
+
+- name: Print information about USB devices
+  ansible.builtin.debug:
+    msg: "On bus {{ item.bus }} device {{ item.device }} with id {{ item.id }} is {{ item.name }}"
+  loop: "{{ ansible_facts.usb_devices }}"
+'''
+
+RETURN = r'''
+ansible_facts:
+  description: Dictionary containing details of connected USB devices.
+  returned: always
+  type: dict
+  contains:
+    usb_devices:
+      description: A list of USB devices available.
+      returned: always
+      type: list
+      elements: dict
+      contains:
+        bus:
+          description: The bus the usb device is connected to.
+          returned: always
+          type: str
+          sample: "001"
+        device:
+          description: The device number occupied on the bus.
+          returned: always
+          type: str
+          sample: "002"
+        id:
+          description: ID of the USB device.
+          returned: always
+          type: str
+          sample: "1d6b:0002"
+        name:
+          description: Human readable name of the device.
+          returned: always
+          type: str
+          sample: Linux Foundation 2.0 root hub
+'''
+
+import re
+from ansible.module_utils.basic import AnsibleModule
+
+
+def parse_lsusb(module, lsusb_path):
+    rc, stdout, stderr = module.run_command(lsusb_path, check_rc=True)
+    regex = re.compile(r'^Bus (\d{3}) Device (\d{3}): ID ([0-9a-f]{4}:[0-9a-f]{4}) (.*)$')
+    usb_devices = []
+    for line in stdout.splitlines():
+        match = re.match(regex, line)
+        if not match:
+            module.fail_json(msg="failed to parse unknown lsusb output %s" % (line), stdout=stdout, stderr=stderr)
+        current_device = {
+            'bus': match.group(1),
+            'device': match.group(2),
+            'id': match.group(3),
+            'name': match.group(4)
+        }
+        usb_devices.append(current_device)
+    return_value = {
+        "usb_devices": usb_devices
+    }
+    module.exit_json(msg="parsed %s USB devices" % (len(usb_devices)), stdout=stdout, stderr=stderr, ansible_facts=return_value)
+
+
+def main():
+    module = AnsibleModule(
+        {},
+        supports_check_mode=True
+    )
+
+    # Set LANG env since we parse stdout
+    module.run_command_environ_update = dict(LANGUAGE='C', LC_ALL='C')
+
+    lsusb_path = module.get_bin_path('lsusb', required=True)
+    parse_lsusb(module, lsusb_path)
+
+
+if __name__ == '__main__':
+    main()