Merge pull request #2221 from aquette/nutscanner-trim-output

nut-scanner USB: disable some output results

NEWS.adoc

@@ -72,21 +72,30 @@ https://github.com/networkupstools/nut/milestone/10
      and `py3qt5` implementations verbosely, even if one is not installed.
      [#2199, #2201]
    * Set the `DesktopFileName` in `scripts/python/app/NUT-Monitor-py3qt5`,
-     this binds the application with the desktop file and allow the Desktop
-     implementation to display the proper icon and application name. [#2205]
+     this binds the application with the desktop file and allow the Open
+     Desktop compatible implementation to display the proper icon and
+     application name. [#2205]
    * Original recipe for `apc_modbus` strictly required USB support even if
      building NUT without it. [#2262]
 
  - nut-usbinfo.pl, nut-scanner and libnutscan:
+   * Library API version for `libnutscan` was bumped from 2.2.0 to 2.5.0
+     during evolution of this NUT release.
    * USB VendorID:ProductID support list files generated by the script for
      different OS frameworks now include a comment with other possibly
      compatible driver names, where the respective file format allows for
      comments.
    * Added the concept of `alt_driver_names` in `nutscan_device_t` structure
      for ability to suggest a comment with other possibly compatible driver
      names in configuration snippets generated by `nut-scanner`; practical
-     support implemented for USB connected drivers. Library API version
-     bumped to 2.3.0 accordingly.
+     support implemented for USB connected drivers.
+   * Added the concept of commented-away suggested option values `comment_tag`
+     and a method to `nutscan_add_commented_option_to_device()`, instead of
+     hacks in prepared config data which broke some use-cases. [#2221]
+   * Command-line option `-U` for USB scan can now be specified several times
+     to increase the detail level about hardware link to the device (this was
+     previously always suggested, but may be not reliable if USB enumeration
+     gets changed over time). [#2221]
    * Added generation of FreeBSD/pfSense quirks for USB devices supported
      by NUT (may get installed to `$datadir` e.g. `/usr/local/share/nut`
      and need to be pasted into your `/boot/loader.conf.local`). [#2159]

UPGRADING.adoc

@@ -34,6 +34,11 @@ Changes from 2.8.1 to 2.8.2
   by NUT (may get installed to `$datadir` e.g. `/usr/local/share/nut`
   and need to be pasted into your `/boot/loader.conf.local`). [#2159]
 
+- nut-scanner now does not propose active `bus`, `busport` and `device`
+  values when generating device configurations by default. They may
+  appear as comments, or enabled by specifying the `-U` command-line
+  option several times. [#2221]
+
 Changes from 2.8.0 to 2.8.1
 ---------------------------
 

docs/man/Makefile.am

@@ -305,6 +305,7 @@ MAN3_DEV_PAGES = \
 	nutscan_new_device.3 \
 	nutscan_free_device.3 \
 	nutscan_add_option_to_device.3 \
+	nutscan_add_commented_option_to_device.3 \
 	nutscan_add_device_to_device.3 \
 	nutscan_get_serial_ports_list.3 \
 	nutscan_init.3
@@ -315,6 +316,10 @@ upscli_readline_timeout.3: upscli_readline.3
 upscli_sendline_timeout.3: upscli_sendline.3
 	touch $@
 
+# Alias page for one text describing two commands:
+nutscan_add_commented_option_to_device.3: nutscan_add_option_to_device.3
+	touch $@
+
 MAN1_DEV_PAGES = \
 	libupsclient-config.1
 
@@ -382,6 +387,13 @@ HTML_DEV_MANS = \
 	sockdebug.html \
 	skel.html
 
+# Can't make this work on all make implementations at once, so disabled for now
+# Anyway it would be the same man-like page for several functions
+HTML_DEV_MANS_FICTION = \
+	nutscan_add_commented_option_to_device.html
+
+nutscan_add_commented_option_to_device.html: nutscan_add_option_to_device.html
+	test -n "$?" -a -s "$@" && rm -f $@ && ln -s $? $@
 
 # Drivers related manpages
 
@@ -890,7 +902,7 @@ check-html-man: $(HTML_MANS)
 	@FAILED=""; CHECKED=0; LANG=C; LC_ALL=C; export LANG; export LC_ALL; \
 	for F in $(HTML_MANS) ; do \
 	    CHECKED="`expr $$CHECKED + 1`"; \
-	    test -s "$$F" && { file "$$F" | $(EGREP) -i '(XML|HTML.*document)' > /dev/null ; } || FAILED="$$FAILED $$F" ; \
+	    test -s "$$F" && { file "$$F" | $(EGREP) -i '(XML|HTML.*document|symbolic link)' > /dev/null ; } || FAILED="$$FAILED $$F" ; \
 	done; if test -n "$$FAILED" ; then \
 	    echo "FAILED HTML-man sanity check for:$$FAILED" >&2 ; file $$FAILED >&2 ; exit 1; \
 	fi; echo "PASSED HTML-man sanity check (checked $$CHECKED files)"; exit 0

docs/man/nut-scanner.txt

@@ -59,6 +59,18 @@ Scan all available communication buses (default behavior)
 
 *-U* | *--usb_scan*::
 List all NUT-compatible USB devices currently plugged in.
++
+This option can be specified several times, for more hardware link-specific
+details; these can be counter-productive in case of USB enumeration changes
+over time:
++
+| `-U`    | do not report any bus/device/busport details |
+| `-UU`   | report bus and busport, if available |
+| `-UUU`  | report bus/device/busport details |
+| `-UUUU` | report bus/device/busport details, and bcdDevice (limited use and benefit) |
++
+NOTE: For reliability, it is preferable to match just by vendor and product
+identification, and a serial number if available and unique.
 
 *-S* | *--snmp_scan*::
 Scan SNMP devices. Requires at least a 'start IP', and optionally,

docs/man/nutscan_add_option_to_device.txt

@@ -4,18 +4,30 @@ NUTSCAN_ADD_OPTION_TO_DEVICE(3)
 NAME
 ----
 
-nutscan_add_option_to_device - Add option data to the specified device.
+nutscan_add_option_to_device, nutscan_add_commented_option_to_device - Add
+option data to the specified device.
+
 
 SYNOPSIS
 --------
 
  #include <nut-scan.h>
 
+ /* Add enabled option data to the specified device. */
  void nutscan_add_option_to_device(
         nutscan_device_t * device,
         char * option_name,
         char * value);
 
+ /* Since libnutscan version 2.5.0:
+  * Add option data to the specified device with an optional comment tag
+  * for options suggested, but not currently enabled for actual use. */
+ void nutscan_add_commented_option_to_device(
+        nutscan_device_t * device,
+        char * option_name,
+        char * value,
+        char * comment_tag);
+
 
 DESCRIPTION
 -----------
@@ -35,9 +47,15 @@ its `type`, its `driver` name, its `port` and any number of optional data.
 
 The *nutscan_add_option_to_device()* adds an optional data in the
 given device. Optional data are made of an 'option_name' and an
-associated 'value'. Copies of 'option_name' and 'value' are stored
-in the device, so the caller can safely free both of the original
-strings used as arguments.
+associated 'value', and optionally a 'comment_tag'. Copies of the
+'option_name', 'value' and 'comment_tag' are stored in the device,
+so the caller can safely free all of the original strings used as
+arguments.
+
+NOTE: A non-`NULL` value of the 'comment_tag' makes the option not-enabled
+for current use. Depending on the output format, it may be either completely
+ignored, or rendered as a comment with this value as a prefix (a zero-length
+string `"\0"` may be passed to have no prefix).
 
 Such options and their values may be further sanity-checked and reported
 as warnings by *nutscan_display_sanity_check()* dispatcher and its related

docs/man/nutscan_scan_usb.txt

@@ -11,12 +11,43 @@ SYNOPSIS
 
  #include <nut-scan.h>
 
+ nutscan_device_t * nutscan_scan_usb(nutscan_usb_t * scanopts);
+
+NOTE
+----
+
+Before `libnutscan` version 2.5.0 there was no argument:
+
  nutscan_device_t * nutscan_scan_usb(void);
 
+After the API update to have an argument, equivalent default activity can
+be achieved by passing `NULL` value for the argument.
+
 DESCRIPTION
 -----------
 
-The *nutscan_scan_usb()* function try to detect NUT compatible USB devices.
+The *nutscan_scan_usb()* function tries to detect NUT compatible USB devices.
+
+The `scanopts` argument contains toggles about values that would be reported
+into the generated device section. Currently they regard physical link details
+which can change over time (e.g. USB re-enumeration due to software or hardware
+re-connections); see `nut-scan.h` for current details:
+
+----
+/* USB scan options structure */
+typedef struct nutscan_usb {
+    /* Hardware link related values below are not reliable for run-time
+     * matching (they can change over time) but can be useful if e.g.
+     * "serial" is not available or unique */
+    int report_bus;
+    int report_busport;
+    int report_device;
+
+    /* The value is not currently used for device matching, but might be
+     * used later, and it is available from discovery */
+    int report_bcdDevice;
+} nutscan_usb_t;
+----
 
 You MUST call linkman:nutscan_init[3] before using this function.
 

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3424 utf-8
+personal_ws-1.1 en 3427 utf-8
 AAC
 AAS
 ABI
@@ -1409,6 +1409,7 @@ USVs
 UTC
 UTalk
 UUU
+UUUU
 UX
 Ubuntu
 Ulf
@@ -2915,6 +2916,7 @@ safenet
 salicru
 sbin
 sbindir
+scanopts
 scd
 sched
 scm
@@ -3285,6 +3287,7 @@ usbhid
 usbif
 usbinfo
 usbmisc
+usbscan
 usbups
 usbus
 usd

tools/nut-scanner/Makefile.am

@@ -91,7 +91,7 @@ endif
 # object .so names would differ)
 #
 # libnutscan version information
-libnutscan_la_LDFLAGS += -version-info 2:4:0
+libnutscan_la_LDFLAGS += -version-info 2:5:0
 
 # libnutscan exported symbols regex
 # WARNING: Since the library includes parts of libcommon (as much as needed

tools/nut-scanner/README.adoc

@@ -39,10 +39,11 @@ iteration function to display results:
 	{
 		nutscan_options_t * opt;
 		nutscan_device_t *device;
+		nutscan_usb_t usb_scanopts;
 
 		nutscan-init();
 
-		if ((device = nutscan_scan_usb()) == NULL) {
+		if ((device = nutscan_scan_usb(&usb_scanopts)) == NULL) {
 			printf("No device found\n");
 			exit(EXIT_FAILURE);
 		}

tools/nut-scanner/nut-scan.h

@@ -4,7 +4,7 @@
  *    2012 - 2024 Arnaud Quette <[email protected]>
  *    2016 - EATON - IP addressed XML scan
  *    2016 - 2021 - EATON - Various threads-related improvements
- *    2023 - Jim Klimov <[email protected]>
+ *    2023 - 2024 - Jim Klimov <[email protected]>
  *
  *  This program is free software; you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
@@ -144,10 +144,24 @@ typedef struct nutscan_xml {
 	char *peername;		/* Hostname or NULL for broadcast mode */
 } nutscan_xml_t;
 
+/* USB scan options structure */
+typedef struct nutscan_usb {
+	/* Hardware link related values below are not reliable for run-time
+	 * matching (they can change over time) but can be useful if e.g.
+	 * "serial" is not available or unique */
+	int report_bus;
+	int report_busport;
+	int report_device;
+
+	/* The value is not currently used for device matching, but might be
+	 * used later, and it is available from discovery */
+	int report_bcdDevice;
+} nutscan_usb_t;
+
 /* Scanning */
 nutscan_device_t * nutscan_scan_snmp(const char * start_ip, const char * stop_ip, useconds_t usec_timeout, nutscan_snmp_t * sec);
 
-nutscan_device_t * nutscan_scan_usb(void);
+nutscan_device_t * nutscan_scan_usb(nutscan_usb_t * scanopts);
 
 /* If "ip" == NULL, do a broadcast scan */
 /* If sec->usec_timeout <= 0 then the common usec_timeout arg overrides it */

tools/nut-scanner/nut-scanner.c

@@ -112,15 +112,62 @@ static char * start_ip = NULL;
 static char * end_ip = NULL;
 static char * port = NULL;
 static char * serial_ports = NULL;
+static int cli_link_detail_level = -1;
 
 #ifdef HAVE_PTHREAD
 static pthread_t thread[TYPE_END];
 
 static void * run_usb(void *arg)
 {
-	NUT_UNUSED_VARIABLE(arg);
+	nutscan_usb_t scanopts, *scanopts_ptr = &scanopts;
+
+	if (!arg) {
+		/* null => use library defaults; should not happen here anyway */
+		scanopts_ptr = NULL;
+	} else {
+		/* 0: do not report bus/device/busport details
+		 * 1: report bus and busport, if available
+		 * 2: report bus/device/busport details
+		 * 3: like (2) and report bcdDevice (limited use and benefit)
+		 */
+		int link_detail_level = *((int*)arg);
+
+		switch (link_detail_level) {
+			case 0:
+				scanopts.report_bus = 0;
+				scanopts.report_busport = 0;
+				scanopts.report_device = 0;
+				scanopts.report_bcdDevice = 0;
+				break;
+
+			case 1:
+				scanopts.report_bus = 1;
+				scanopts.report_busport = 1;
+				scanopts.report_device = 0;
+				scanopts.report_bcdDevice = 0;
+				break;
+
+			case 2:
+				scanopts.report_bus = 1;
+				scanopts.report_busport = 1;
+				scanopts.report_device = 1;
+				scanopts.report_bcdDevice = 0;
+				break;
+
+			case 3:
+				scanopts.report_bus = 1;
+				scanopts.report_busport = 1;
+				scanopts.report_device = 1;
+				scanopts.report_bcdDevice = 1;
+				break;
+
+			default:
+				upsdebugx(1, "%s: using library default link_detail_level settings", __func__);
+				scanopts_ptr = NULL;
+		}
+	}
 
-	dev[TYPE_USB] = nutscan_scan_usb();
+	dev[TYPE_USB] = nutscan_scan_usb(scanopts_ptr);
 	return NULL;
 }
 
@@ -192,7 +239,8 @@ static void show_usage(void)
 	puts("OPTIONS:");
 	printf("  -C, --complete_scan: Scan all available devices except serial ports (default).\n");
 	if (nutscan_avail_usb) {
-		printf("  -U, --usb_scan: Scan USB devices.\n");
+		printf("  -U, --usb_scan: Scan USB devices. Specify twice or more to report different\n"
+			"                  detail levels of (change-prone) physical properties.\n");
 	} else {
 		printf("* Options for USB devices scan not enabled: library not detected.\n");
 	}
@@ -636,6 +684,9 @@ int main(int argc, char *argv[])
 					goto display_help;
 				}
 				allow_usb = 1;
+				/* NOTE: Starts as -1, so the first -U sets it to 0 (minimal detail) */
+				if (cli_link_detail_level < 3)
+					cli_link_detail_level++;
 				break;
 			case 'M':
 				if (!nutscan_avail_xml_http) {
@@ -774,13 +825,13 @@ int main(int argc, char *argv[])
 	if (allow_usb && nutscan_avail_usb) {
 		upsdebugx(quiet, "Scanning USB bus.");
 #ifdef HAVE_PTHREAD
-		if (pthread_create(&thread[TYPE_USB], NULL, run_usb, NULL)) {
+		if (pthread_create(&thread[TYPE_USB], NULL, run_usb, &cli_link_detail_level)) {
 			upsdebugx(1, "pthread_create returned an error; disabling this scan mode");
 			nutscan_avail_usb = 0;
 		}
 #else
 		upsdebugx(1, "USB SCAN: no pthread support, starting nutscan_scan_usb...");
-		dev[TYPE_USB] = nutscan_scan_usb();
+		dev[TYPE_USB] = nutscan_scan_usb(&cli_link_detail_level);
 #endif /* HAVE_PTHREAD */
 	} else {
 		upsdebugx(1, "USB SCAN: not requested, SKIPPED");