[Nut-upsdev] Upgrade Support Level Legend on Hardware Compatibility List

[Jim Klimov]

Hello Yvonne,

  Nice to hear from you again, and I've recently seen a similar question in
the issue tracker, so would re-post the answer made there (I think this
should get into the NUT FAQ and/or Wiki, if not yet covered there; but it
may be worth collecting insights from other community members while we are
here):

> Hello, our company is a manufacturer of UPS and would like to apply for
inclusion in the NUT compatibility list.
> May I inquire about the process and required documentation for joining?

Hello, and it is always great to hear such queries!

Being a loosely-knit online community around the software project, NUT
currently has no bureaucratic routine or red tape - everyone can post
GitHub Pull Requests to contribute to the source code (including the
documentation and data related to the compatibility lists). What matters
most for the community, where individual people and even companies come and
go but the project continues for over 25 years, is functionality and
maintainability - so a large part of the answer is having both NUT drivers
to communicate with the devices, and documentation to verify and evolve
them any time later.
* This includes the time-frame when UPS or similar power-management devices
still work, but the original companies that created them no longer exist,
or no longer publish relevant (old) versions of spec/protocol on their web
sites after acquisitions or re-structuring.
* There were cases of same device identification used for completely
unrelated devices (as far as communications are concerned), or of vendors
only supporting their latest iteration while the boxes in the field can not
be upgraded to newer firmware and have to work with their decade-old bugs.
* Notably, similar concerns apply to power-protection of still-running
computers made by vendors now only known in history books, but where NUT
ran at the time and new versions can still be built and used (so there are
certain constraints on the source code).

Note that beside the "HCL" (Hardware Compatibility List) with a list of
devices and matching drivers seen at
https://networkupstools.org/stable-hcl.html we also have a "DDL" (Devices
Dumps Library) shown and documented at https://networkupstools.org/ddl/
with examples of device support across different NUT releases (as well as,
to some extent, across device/firmware variants seen in the field over the
years). When a NUT driver exists, a run of
https://raw.githubusercontent.com/networkupstools/nut/master/tools/nut-ddl-dump.sh
helps prepare a DDL report to be included into the library.

The HCL source at
https://github.com/networkupstools/nut/blob/master/data/driver.list.in also
summarizes the different levels of support our rendered tables on the NUT
website report. They are a balance of as much NUT supporting the device, as
the vendor supporting NUT to do so (e.g. providing actual protocol
documentation to be used and re-published at
https://networkupstools.org/ups-protocols.html instead of people making
educated guesses about a black box, and devices to test the
theory-vs-practice against).

For inclusion into the compatibility list as such, the device has to be,
well, compatible - talking either a protocol NUT already supports, or by
the vendor contributing a driver for a new protocol (directly, or enticing
and sponsoring a developer perhaps via the NUT mailing list with at least a
device to develop/test against), or enhancing an existing NUT driver if the
device is mostly supported by one, but some interesting data points or
instant commands are not yet handled.

The general approach to "Creating a new driver to support another device"
can be seen at
https://networkupstools.org/docs/developer-guide.chunked/new-drivers.html,
ending with particular examples for popular USB HID, SNMP and Megatec Q*
dialect sub-drivers united by respective umbrella programs in NUT.

Ideally, someone from the vendor's team would actually remain in NUT orbit
as a (co-)maintainer for that driver and a sort of liaison - as both the
devices and NUT capabilities (e.g. the standard vocabulary of
vendor-neutral data points maintained at
https://github.com/networkupstools/nut/blob/master/docs/nut-names.txt and
rendered at
https://networkupstools.org/docs/developer-guide.chunked/nut-names.html)
evolve, someone should sync them. Perhaps as new revisions of the device
protocol are published, that person could make sure that NUT UPS Protocols
collection gets a copy and drivers are updated as needed. A common pain
point is that different firmware versions seen in the field need different
work-arounds for mistakes of the past, and it is beneficial when a NUT
driver can differentiate the devices to apply the correct logic to each.
This is something an UPS development team is better positioned to do, than
random people blindly hot-fixing behaviors based on devices they have (so
maybe breaking the driver for someone else with a different version of the
device).

Hope this helps,
Jim Klimov


On Thu, Apr 17, 2025 at 9:31 AM Yvonne.Chen <Yvonne.Chen at cyberenergy.com>
wrote:

> Hi Jim:
>
>
>
> We have a customer whose manufacturer is listed with an orange support
> level legend (based on fragments of publicly available protocol) on the
> Hardware Compatibility List. What kind of information does the customer
> need to provide in order to upgrade the support level legend from orange
> (based on fragments of publicly available protocol) to green (vendor
> provided protocol and hardware)? Does this need to be submitted and
> requested directly by the manufacturer? Kindly confirm. Thank you!
>
> https://networkupstools.org/stable-hcl.html?utm_source=chatgpt.com
>
>
>
> Best regards
>
> Yvonne Chen
>
>
>
> Cyber Energy Co., Ltd.
>
> Tel: +886-2-8792-9628 #605
>
> Fax: +886-2-8792-9626
>
> Email: Yvonne.Chen at cyberenergy.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/nut-upsdev/attachments/20250418/1f464c60/attachment.htm>