apc-hid: map shutdown.return for APC Back-UPS BX*MI units [#2683] - #3566
Open
faluc-dev wants to merge 1 commit into
Open
apc-hid: map shutdown.return for APC Back-UPS BX*MI units [#2683]#3566faluc-dev wants to merge 1 commit into
faluc-dev wants to merge 1 commit into
Conversation
|
A ZIP file with standard source tarball and another tarball with pre-built docs for commit baee2b0 is temporarily available: NUT-tarballs-PR-3566.zip. |
faluc-dev
force-pushed
the
apc-hid-bxmi-shutdown-return
branch
from
August 12, 2026 17:03
62344ae to
20c223c
Compare
|
❌ Build nut 2.8.5.5045-master failed (commit bc87be2d16 by @faluc-dev) |
faluc-dev
force-pushed
the
apc-hid-bxmi-shutdown-return
branch
from
August 12, 2026 17:40
20c223c to
243d712
Compare
…tools#2683] On newer APC Back-UPS devices (e.g. Back-UPS BX750MI, 051d:0002) the only shutdown-capable HID usage is UPS.APCGeneralCollection.APCDelayBeforeReboot. The previously only matching command mapped to it, shutdown.reboot, writes the default value 10, which this firmware accepts (USB-level success) but never executes — so the built-in shutdown sequence reported success without ever powering the load off. Map shutdown.return to the same usage with value 1, matching the write APC PowerChute Serial Shutdown performs (confirmed by decoding the USBPcap captures archived in issue networkupstools#2683, and live on a 2025-11 BX750MI-GR unit): the load is cycled after a fixed ~2 minute grace (the value is not a seconds count on this firmware), the command executes only while on battery, and output returns when wall power is present, even if AC came back during the grace period. With this mapping the driver-default shutdown command chain (shutdown.return,shutdown.reboot,load.off.delay,shutdown.stayoff) succeeds on its first command: verified on battery with 'usbhid-ups -k' on a BX750MI-GR — output cut 2 min 2 s after the write and re-energized on AC restore. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QQEAfDBxtHupEdAcv3Bgz2 Signed-off-by: Falusi Tamás <tamas.falusi@gmail.com>
faluc-dev
force-pushed
the
apc-hid-bxmi-shutdown-return
branch
from
August 12, 2026 18:07
243d712 to
baee2b0
Compare
|
✅ Build nut 2.8.5.5047-master completed (commit 871ea658ed by @faluc-dev)
|
|
✅ Build nut 2.8.5.5047-master completed (commit 871ea658ed by @faluc-dev) |
|
✅ Build nut 2.8.5.5048-master completed (commit 171b34d07d by @faluc-dev)
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the practical side of #2683 (and matches the empirical conclusion of #2666): on newer APC Back-UPS units such as the BX750MI, the built-in
upsdrvctl shutdown/usbhid-ups -ksequence reports success but never powers the load off.Why: on these units the only shutdown-capable HID usage is
UPS.APCGeneralCollection.APCDelayBeforeReboot. The only command previously mapped to that path,shutdown.reboot, writes its default value "10" — which this firmware ACKs at the USB level but never executes. The shutdown chain then stops at that first "successful" command.Fix (one table line): map
shutdown.returnto the same usage with value "1" — the exact write APC's own PowerChute Serial Shutdown performs (singleSET_REPORT(Feature, 0x40) = 01, decoded from the USBPcap captures archived in #2683). With it, the driver-default chain (shutdown.return,shutdown.reboot,load.off.delay,shutdown.stayoff) succeeds on its first command with a write that actually works. This mirrors the existing "Back-UPS CS"shutdown.returnentry, which uses the same value "1" on theUPS.Outputpath.Semantics of the write, per our bench work on a 2025-11 BX750MI-GR unit (051d:0002) — complementing the PowerChute captures in #2683, which came from the original reporter's 2024-build unit:
11-14-2and our live retest).shutdown.returnbehavior.Verification of this patch (2026-08-12, BX750MI-GR, macOS/arm64 bench, libusb 1.0.30):
usbhid-ups -a ups4 -k -u root→ chain usedshutdown.returnviaUPS.APCGeneralCollection.APCDelayBeforeReboot,Report[set]: (2 bytes) => 40 01, "Shutdown successful with 'shutdown.return'". Output cut 2 min 2 s after the write; replugging the wall re-energized the output within seconds. Full debug logs available.40 01on the same path, driver reports success) but is silently dropped by the firmware: no output cut within 8 minutes, a subsequent register read showedups.timer.reboot: 0(disarmed — an armed timer holds1), and a battery transition several minutes after the write produced no delayed fire either. So on this family no on-line/on-battery conditional command logic is needed: the write only ever does anything when issued on battery, and there it is race-immune. The unconditional default chain is safe on both sides of the power race.Review point worth flagging: older Back-UPS ES devices also expose the
APCGeneralCollectionpath. Previouslyshutdown.returndid not match on them at all, and the default chain usedshutdown.reboot(value "10"). With this patch the chain will prefershutdown.return(value "1") on those units too. If their firmware honors the value as a seconds delay, this shortens the pre-cut delay from 10 s to 1 s; we could not test an ES unit. If that is a concern, the entry could be gated by product string instead — happy to rework it that way.The NEWS.adoc entry currently references issue #2683; I can amend it with this PR's number once known (or per your preference).
Transparency, as discussed in #2683: I am not a programmer — the analysis, this patch, and this PR text were authored by an AI assistant (Claude / Fable 5, via Claude Code) under my direction; I performed the hardware tests on my BX750MI unit. Maintainer OK for AI-assisted contribution: #2683 comment follow-up.
🤖 Generated with Claude Code
https://claude.ai/code/session_01QQEAfDBxtHupEdAcv3Bgz2