Merge branch 'master' into armac-2023

.github/pull_request_template.md

@@ -27,6 +27,8 @@
   of "real" changes in the other commits. Similarly for typo fixes in
   comments or text documents.
 
+- [ ] Please star NUT on GitHub, this helps with sponsorships! ;)
+
 ## Frequent "underwater rocks" for driver addition/update PRs
 
 - [ ] Revised existing driver families and added a sub-driver if applicable

README.adoc

@@ -1,5 +1,5 @@
 Network UPS Tools Overview
-===========================
+==========================
 // NOTE: No blank line here, document-header include processing should kick in!
 //GH_MARKUP_1095//ifdef::top_srcdir[]
 //GH_MARKUP_1095//include::{top_srcdir}docs/asciidoc-vars.conf[]
@@ -128,6 +128,9 @@ endif::env-github[]
 //
 // - on GitHub:
 ifdef::env-github[]
+//     In our normal builds, Makefile variables convey the needed paths
+//     (used relatively below as `image:images/ci/...png` etc.)
+:imagesdir:	docs
 //   * xref -> link
 //     syntax: {xref}<id>{x-s}[<caption>]
 //     In order for it to work, <id> can reference at most a section of
@@ -158,6 +161,7 @@ endif::asciidoc-vars-nut-included[]
 //
 //GH_MARKUP_1095_INCLUDE_END//
 
+
 Description
 -----------
 
@@ -187,6 +191,44 @@ also provided to log information regularly, monitor status through your
 web browser, and more.
 
 
+NUT and the ecosystem
+---------------------
+
+NUT comes pre-packaged for many operating systems and embedded in storage,
+automation or virtualization appliances, and is also often shipped as the
+software companion by several UPS vendors. Of course, it is quite normal
+and supported to build your own -- whether for an operating system which
+lacks it yet, or for an older distribution which lacks the current NUT
+version; whether to take advantage of new features or to troubleshoot a
+new UPS deployment with a debugger in hand.
+
+Given its core position at the heart of your systems' lifecycle, we make
+it a point to have current NUT building and running anywhere, especially
+where older releases did work before (including "abandonware" like the
+servers and OSes from the turn of millennium): if those boxes are still
+alive and in need of power protection, they should be able to get it.
+
+[TIP]
+=====
+If you like how the NUT project helps protect your systems from power
+outages, please consider sponsoring or at least "starring" it on GitHub at
+https://github.com/networkupstools/nut/ - these stars are among metrics
+which the larger potential sponsors consider when choosing how to help
+FOSS projects. Keeping the lights shining in such a large non-regression
+build matrix is a big undertaking!
+
+See <<acknowledgements-ci-ops,acknowledgements of organizations which help
+with NUT CI and other daily operations>> for an overview of the shared effort.
+=====
+
+As a FOSS project, for over a quarter of a century we welcome contributions
+of both core code (drivers and other features), build recipes and other
+integration elements to make it work on your favourite system, documentation
+revisions to make it more accessible to newcomers, as well as hardware vendor
+cooperation with first-hand driver and protocol submissions, and just about
+anything else you can think of.
+
+
 Installing
 ----------
 
@@ -709,3 +751,87 @@ Acknowledgements / Contributions
 
 The many people who have participated in creating and improving NUT are
 listed in the user manual {xref}Acknowledgements{x-s}[acknowledgements appendix].
+
+[[acknowledgements-ci-ops]]
+
+We would like to highlight some organizations which provide continuous
+support to the NUT project (and many other FOSS projects) on technological
+and organizational sides, such as helping keep the donations transparent,
+NUT CI farm afloat, and public resources visible. Thanks for keeping the
+clocks ticking, day and night:
+
+////////////
+FIXME: Use different (better-resolution) images for PDF rendering?
+
+FIXME: PDF cells seem to align weirdly, like setting the bottom of the first
+line of text to be on the same level as bottom of the image, or similar to that.
+
+NOTE: GitHub renderer (or CSS stack?) ignores style settings and squashes the
+logo column into a fixed-width monster with either our specified heights, or
+with teeny-tiny thumbnail magnitude images, so it is prettier to leave it as
+a "single-column table" by default. Grid/Frame settings are also ignored, but
+we can try our best anyway.
+
+NOTE: The classic asciidoc/a2x renderer seems to not support link/url options,
+but at least does not complain about them either.
+////////////
+
+ifndef::env-github[]
+[frame="none",grid="none",cols="^.<1,<.<2"]
+endif::env-github[]
+ifdef::env-github[]
+[frame="none",grid="none",cols="<1*"]
+endif::env-github[]
+|===
+| image:images/ci/GitHub-Mark-140pxW.png[alt="GitHub logo",width="140",height="140",link="https://github.com/"]
+| The link:https://github.com/networkupstools/["NetworkUPSTools" organization
+  on GitHub] arranges a lot of things, including source code hosting for NUT
+  itself and several related projects, team management, projects, issue and
+  pull request discussions, sponsorship, nut-website rendering and hosting,
+  some automated actions, and more...
+
+| image:images/ci/jenkins-nut-transparent-bg-140pxW.png[alt="Jenkins and NUT logo",width="139",height="104",link="https://www.jenkins.io/"]
+| The link:https://www.jenkins.io/[Jenkins CI] project and its huge plugin
+  ecosystem provides the technological foundation for the largest island of
+  the link:https://ci.networkupstools.org/[self-hosted NUT CI farm].
+  There is a fair amount of cross-pollination between the upstream project
+  and community, and the development done originally for the NUT CI farm.
+
+  See more at link:https://stories.jenkins.io/user-story/jenkins-is-the-way-for-networkupstools/[Jenkins
+  is the way to build multi-platform NUT] article.
+
+| image:images/ci/fosshost.org_Host_Light_38px.png[alt="Fosshost logo",width="112",height="38"]
+| Fosshost provided virtual machines where the multi-platform NUT CI farm with
+  a link:https://github.com/networkupstools/jenkins-dynamatrix/[jenkins-dynamatrix]
+  link:https://github.com/networkupstools/nut/blob/master/Jenkinsfile-dynamatrix[setup]
+  runs to arrange builds in numerous operating environments and a lot of toolkit
+  versions and implementations. Some workers running on NUT community members'
+  machines can also dial in to provide an example of their favourite platforms.
+  Literally hundreds of NUT builds run for each iteration, to make sure NUT can
+  always build and work everywhere.
+
+  This allows us to ensure that NUT remains portable across two decades' worth
+  of operating systems, compilers, script interpreters, tools and third-party
+  dependencies.
+
+| image:images/ci/CircleCI_vertical_black_logo.png[alt="CircleCI logo",width="130",height="107",link="https://circleci.com/"]
+| The
+  link:https://app.circleci.com/pipelines/github/networkupstools/nut/[CircleCI
+  NUT pipeline] allows us to test NUT CI builds on MacOS.
+
+| image:images/ci/AppVeyor_logo-ar21.png[alt="AppVeyor logo",width="120",height="60",link="https://www.appveyor.com/"]
+| The link:https://ci.appveyor.com/project/nut-travis/nut/[AppVeyor
+  NUT pipeline] allows us to test NUT CI builds on Windows (and publish
+  preview tarballs with binaries).
+
+| image:images/ci/DO_Powered_by_Badge_blue_140pxW.png[alt="DigitalOcean logo",width="140",height="29",link="https://www.digitalocean.com/"]
+| The link:https://www.digitalocean.com/[DigitalOcean] droplets allow us to host
+  NUT CI farm build agents, and eventually re-house the Jenkins controller too.
+
+| image:images/ci/gandi-ar21.png[alt="Gandi.Net logo",width="120",height="60",link="https://www.gandi.net/"]
+| link:https://www.gandi.net/[Gandi.Net] took up the costs of NUT DNS hosting.
+
+| image:images/ci/OC_logo_merged_140x26.png[alt="Open Collective logo",width="140",height="26",link="https://opencollective.com/"]
+| https://opencollective.com/networkupstools allows us to arrange monetary
+  donations and spending, with public transparency of everything that happens.
+|===

docs/Makefile.am

@@ -18,6 +18,41 @@ IMAGE_FILES = images/asciidoc.png \
 	images/bizarre.png \
 	images/old-cgi.png
 
+# Logos which pop up in README.adoc acknowledgements and maybe other places:
+IMAGE_LOGO_FILES = \
+	images/ci/AppVeyor_logo-2x.png \
+	images/ci/AppVeyor_logo-ar21.png \
+	images/ci/CircleCI_vertical_black_logo.png \
+	images/ci/DO_Powered_by_Badge_blue.png \
+	images/ci/DO_Powered_by_Badge_blue_140pxW.png \
+	images/ci/fosshost.org_Host_Dark_56px.png \
+	images/ci/fosshost.org_Host_Light_309px.png \
+	images/ci/fosshost.org_Host_Light_38px.png \
+	images/ci/gandi-ar21.png \
+	images/ci/gandi-ar21.svg \
+	images/ci/GitHub-Mark-140pxW.png \
+	images/ci/GitHub-Mark-ea2971cee799.png \
+	images/ci/OC_logotype.png \
+	images/ci/OC_logo-watercolor-256.png \
+	images/ci/OC_logo_merged_171x32.png \
+	images/ci/OC_logo_merged_140x26.png
+
+IMAGE_LOGO_FILES_JENKINS_NUT = \
+	images/ci/jenkins-nut-large-256px.png \
+	images/ci/jenkins-nut-large-squared.png \
+	images/ci/jenkins-nut-large.pdn \
+	images/ci/jenkins-nut-large.png \
+	images/ci/jenkins-nut-small-256px.png \
+	images/ci/jenkins-nut-small.pdn \
+	images/ci/jenkins-nut-small.png \
+	images/ci/jenkins-nut-squared.png \
+	images/ci/jenkins-nut-transparent-bg-140pxW.png \
+	images/ci/jenkins-nut-transparent-bg-40px.png \
+	images/ci/jenkins-nut-transparent-bg.png \
+	images/ci/jenkins-nut.css \
+	images/ci/jenkins-nut.png \
+	images/ci/jenkins-nut.txt
+
 # Only track here the local deps
 SHARED_DEPS = nut-names.txt daisychain.txt asciidoc.conf asciidoc.txt
 
@@ -51,7 +86,7 @@ ALL_TXT_SRC = nut-names.txt daisychain.txt \
 ASPELL_FILTER_PATH = @ASPELL_FILTER_PATH@
 NUT_SPELL_DICT = nut.dict
 EXTRA_DIST += $(ALL_TXT_SRC) $(SHARED_DEPS) $(IMAGE_FILES) \
- $(CABLES_IMAGES) $(NUT_SPELL_DICT) \
+ $(IMAGE_LOGO_FILES) $(IMAGE_LOGO_FILES_JENKINS_NUT) $(CABLES_IMAGES) $(NUT_SPELL_DICT) \
  docinfo.xml common.xsl xhtml.xsl chunked.xsl asciidoc.txt asciidoc-vars.conf
 
 ASCIIDOC_HTML_SINGLE = user-manual.html \

docs/asciidoc-vars.conf

@@ -118,6 +118,9 @@ endif::env-github[]
 //
 // - on GitHub:
 ifdef::env-github[]
+//     In our normal builds, Makefile variables convey the needed paths
+//     (used relatively below as `image:images/ci/...png` etc.)
+:imagesdir:	docs
 //   * xref -> link
 //     syntax: {xref}<id>{x-s}[<caption>]
 //     In order for it to work, <id> can reference at most a section of

docs/images/ci/jenkins-nut.txt

@@ -20,3 +20,7 @@ The fosshost.org_Host_Dark_56px.png was downscaled from resources
 at https://fosshost.org/media/ to fit into the Jenkins dashboard
 banner and remain readable. Thanks to Fosshost for providing the
 machines involved in the new NUT CI farm!
+
+Logos of CI hosting companies and other organizations which help
+the NUT project in daily operations were downloaded in 2023 for
+the Acknowledgements chapter in the top-level `README.adoc`.

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3411 utf-8
+personal_ws-1.1 en 3420 utf-8
 AAC
 AAS
 ABI
@@ -305,6 +305,7 @@ Dharm
 DiSplay
 Diehl
 Dietze
+DigitalOcean
 Digitus
 Digys
 Dimitris
@@ -835,6 +836,7 @@ NetPro
 NetServer
 NetUps
 Netman
+NetworkUPSTools
 Neus
 Niels
 Niklas
@@ -1518,6 +1520,7 @@ Zaika
 Zampieri
 Zawadzki
 ZeroMQ
+abandonware
 abcd
 ablerex
 abuild
@@ -1689,6 +1692,7 @@ bestfortress
 bestuferrups
 bestups
 bfe
+bg
 bigbox
 bigone
 bigserver
@@ -1742,6 +1746,7 @@ ccache
 cd
 cdc
 cdf
+cee
 centos
 cerr
 certfile
@@ -2084,6 +2089,7 @@ fuji
 fullload
 func
 gamatronic
+gandi
 gcc
 gcpp
 gd
@@ -2208,6 +2214,7 @@ ignoresab
 ignset
 illumos
 im
+imagesdir
 img
 imv
 includePath
@@ -2557,6 +2564,7 @@ nashkaminski
 natively
 nb
 nbr
+nbsp
 nd
 ndcv
 nds
@@ -2799,6 +2807,7 @@ pwl
 pwmib
 pwro
 px
+pxW
 pxg
 pxgx
 py

drivers/libusb1.c

@@ -263,14 +263,7 @@ static int nut_libusb_open(libusb_device_handle **udevp,
 			libusb_free_device_list(devlist, 1);
 			fatal_with_errno(EXIT_FAILURE, "Out of memory");
 		}
-		if (bus_num > 0) {
-			sprintf(curDevice->Bus, "%03d", bus_num);
-		} else {
-			upsdebugx(1, "%s: invalid libusb bus number %i",
-				__func__, bus_num);
-			free(curDevice->Bus);
-			curDevice->Bus = NULL;
-		}
+		sprintf(curDevice->Bus, "%03d", bus_num);
 
 		device_addr = libusb_get_device_address(device);
 		curDevice->Device = (char *)malloc(4);

scripts/python/module/MANIFEST.in

@@ -0,0 +1 @@
+include tox.ini

scripts/python/module/Makefile.am

@@ -14,7 +14,7 @@ check-local:
 tox: dist .pypi-tools-tox
 	tox
 
-EXTRA_DIST = tox.ini
+EXTRA_DIST = tox.ini MANIFEST.in
 
 NUT_SOURCE_GITREV_NUMERIC = @NUT_SOURCE_GITREV_NUMERIC@
 PYTHON = @PYTHON@

scripts/python/module/setup.py.in

@@ -27,7 +27,7 @@ setup(
     packages   =	find_packages(),
     #py_modules =	['PyNUT'],
     package_dir =	{'PyNUT': 'PyNUTClient'},
-    data_files =	[('', ['tox.ini'])],
+    #data_files =	[('', ['tox.ini'])],
     #scripts    =	['PyNUTClient/test_nutclient.py', 'PyNUTClient/__init__.py'],
     python_requires =	'>=2.6',
     # install_requires =	['telnetlib'],	# NOTE: telnetlib.py is part of Python core for tested 2.x and 3.x versions, not something 'pip' can download