tripplitesu: Add runtime delay parameters via upscmd extra argument

[Copilot]

Description

Tripp Lite SmartOnline devices require configurable shutdown/reboot delays. Previously only configurable via ups.conf. Now supports runtime specification through upscmd's extra parameter with automatic fallback.

Changes

Runtime delay parameter parsing:

• Added parse_delay_args() helper with format "shutdown_delay" or "shutdown_delay.reboot_delay"
• Validation: strtol() with overflow checking (INT_MAX, ERANGE), trailing garbage detection, minimum value enforcement
• Fallback to ups.conf on NULL/empty/invalid input
• Example: upscmd ups shutdown.reboot 5.2 → shutdown 5s, reboot 2min

Updated instant commands:

• shutdown.reboot, shutdown.reboot.graceful, shutdown.return now parse extra parameter
• Graceful shutdown maintains 60s minimum regardless of parameter
• Removed NUT_UNUSED_VARIABLE(extra) - now actively consumed

Input handling robustness:

// Rejects malformed input, falls back to config
parse_delay_args("5abc", ...)   // returns 0
parse_delay_args("5.2.3", ...)  // returns 0
parse_delay_args("999999999999", ...) // returns 0 (overflow)

// Accepts valid formats
parse_delay_args("15", ...)     // shutdown=15s, reboot=config
parse_delay_args("5.2", ...)    // shutdown=5s, reboot=2min

Previous commits in this PR

Auto-timeout mitigation:

• Automatic command_delay activation (1s) on first timeout detection
• Helper function auto_enable_command_delay() with flag tracking

Configurable timing parameters:

• command_delay: inter-command delay in microseconds (default: -1 disabled, auto-enables on timeout)
• shutdown_delay: shutdown delay in seconds (default: 10, min: 1)
• reboot_delay: reboot delay in minutes (default: 1, min: 1)
• Used strtol() for config parsing with proper validation

General points

• Described the changes in the PR submission or a separate issue, e.g.
  known published or discovered protocols, applicable hardware (expected
  compatible and actually tested/developed against), limitations, etc.

• There may be multiple commits in the PR, aligned and commented with
  a functional change. Notably, coding style changes better belong in a
  separate PR, but certainly in a dedicated commit to simplify reviews
  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
  (nutdrv_qx, usbhid-ups...) or added a brand new driver in the other
  case.

• Did not extend obsoleted drivers with new hardware support features
  (notably blazer and other single-device family drivers for Qx protocols,
  except the new nutdrv_qx which should cover them all).

• For updated existing device drivers, bumped the DRIVER_VERSION macro
  or its equivalent.

• For USB devices (HID or not), revised that the driver uses unique
  VID/PID combinations, or raised discussions when this is not the case
  (several vendors do use same interface chips for unrelated protocols).

• For new USB devices, built and committed the changes for the
  scripts/upower/95-upower-hid.hwdb file

• Proposed NUT data mapping is aligned with existing docs/nut-names.txt
  file. If the device exposes useful data points not listed in the file, the
  experimental.* namespace can be used as documented there, and discussion
  should be raised on the NUT Developers mailing list to standardize the new
  concept.

• Updated data/driver.list.in if applicable (new tested device info)

Frequent "underwater rocks" for general C code PRs

• Did not "blindly assume" default integer type sizes and value ranges,
  structure layout and alignment in memory, endianness (layout of bytes and
  bits in memory for multi-byte numeric types), or use of generic int where
  language or libraries dictate the use of size_t (or ssize_t sometimes).

• Progress and errors are handled with upsdebugx(), upslogx(),
  fatalx() and related methods, not with direct printf() or exit().
  Similarly, NUT helpers are used for error-checked memory allocation and
  string operations (except where customized error handling is needed,
  such as unlocking device ports, etc.)

• Coding style (including whitespace for indentations) follows precedent
  in the code of the file, and examples/guide in docs/developers.txt file.

• For newly added files, the Makefile.am recipes were updated and the
  make distcheck target passes.

General documentation updates

• Updated docs/acknowledgements.txt (for vendor-backed device support)

• Added or updated manual page information in docs/man/*.txt files
  and corresponding recipe lists in docs/man/Makefile.am for new pages

• Passed make spellcheck, updated spell-checking dictionary in the
  docs/nut.dict file if needed (did not remove any words -- the make
  rule printout in case of changes suggests how to maintain it).

Additional work may be needed after posting this PR

• Propose a PR for NUT DDL with detailed device data dumps from tests
  against real hardware (the more models, the better).

• Address NUT CI farm build failures for the PR: testing on numerous
  platforms and toolkits can expose issues not seen on just one system.

• Revise suggestions from LGTM.COM analysis about "new issues" with
  the changed codebase.

Original prompt

read the following messages under a PR for tripplitesu driver (located in tripplitesu.c) then fix the issue.

@TomZanna
This PR is currently a draft. I am looking for feedback on the best implementation strategy (see below).

Intermittent communication timeouts were observed when multiple commands were sent in rapid succession. Specifically, when running the driver manually with maximum debug verbosity, a timeout occurs consistently at the second AVL message within the init_comm function.
Adding a 1-second delay at the beginning of do_command() ensures the hardware buffer is ready and prevents these "read timeout" errors.

Should we consider making this a configurable parameter in ups.conf (e.g., command_delay)? I'd appreciate the maintainers' insight on whether this hardware quirk is universal enough to justify a global delay for this driver.

@jimklimov
Thanks, the proposal looks reasonable. Hard to say if the problem is "universal", given that this is a driver aimed at certain models of UPSes by one vendor, so there are just so many devices impacted by any change here in any case.

I usually lean in favour of toggles, probably as a numeric value for that usleep argument, which would be e.g. -1 by default to disable it, and maybe flip to 1E6 in case the device saw an I/O timeout. This would allow the problem to be probably fixed out of the box, with end users free to set a specific value or disable the feature by setting 0 depending on how the fix behaves in their particular case.

@TomZanna
First of all, I apologize for the radio silence! I’ve been a bit buried lately preparing for a university exam and managing a house move at the same time.

In the meantime, I’ve done some further testing and found a couple of interesting things:

It turns out the TSU_SHUTDOWN_RESTART command can actually power on a UPS that is currently off. I’ll need to update the documentation to reflect this behavior.
I’ve been sniffing the serial traffic from the official PowerAlert software and noticed it’s possible to specify custom delays for shutdown and reboot. I’m planning to integrate this into upscmd so we have better control over the timing.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[jimklimov]

Looks like a decent improvement, a few things to fix are commented (also update NEWS.adoc about the change).

If this was all/mostly written by AI, quite impressive.

[jimklimov]

This should be bumped

[jimklimov]

Here and below, better use NOTE: Some sentence syntax so it gets rendered as a notice box for ultimate docs formats where that is supported.

[jimklimov]

Potential SEGFAULT: No sanity checks (e.g. against errors by future devs) that the two parsed* pointers are not NULL.

[jimklimov]

Is this file needed?

[TomZanna]

Sorry, I didn't realize Copilot had added you as an additional reviewer. I was testing the tool to figure out how to implement a few things, and I hope I didn't waste too much of your time with this PR.

The only thing I’m stuck on is why there’s a double call for shutdown/reboot actions:

do_command(SET, TSU_SHUTDOWN_RESTART, "1", NULL); // delay in minutes
do_command(SET, TSU_SHUTDOWN_ACTION, "10", NULL); // delay in seconds

Based on what I observed while sniffing the serial port, the parameter for TSU_SHUTDOWN_ACTION represents the delay in seconds before the UPS shuts down. Therefore, issuing two distinct and conflicting commands doesn't seem to make sense.

I won't have easy physical access to the UPS for the next few months, so in the meantime, I’ll clean up the PR networkupstools#3273 regarding the timeout issue.

[jimklimov]

Not really sure about this particular UPS, but it could be two non-conflicting settings: "what to do when power goes out", and "what to do when power comes back".

[jimklimov]

NP about time so far, was commuting to FOSDEM. After a few forays of my own, I am (still) amazed at how AI makes-believe it knows what it's doing :)

And just as well, how convincingly it hallucinates about using some feature that's not really there, but now that you saw an example, you wanna make it happen :)