From baee2b057cc83b1876510c2e96d00fd0f90ab8f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Falusi=20Tam=C3=A1s?= Date: Wed, 12 Aug 2026 18:39:05 +0200 Subject: [PATCH] apc-hid: map shutdown.return for APC Back-UPS BX*MI units [#2683] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 #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 Claude-Session: https://claude.ai/code/session_01QQEAfDBxtHupEdAcv3Bgz2 Signed-off-by: Falusi Tamás --- NEWS.adoc | 12 ++++++++++++ docs/nut.dict | 3 ++- drivers/apc-hid.c | 7 +++++++ 3 files changed, 21 insertions(+), 1 deletion(-) diff --git a/NEWS.adoc b/NEWS.adoc index 16e339db4a..02f61fe65b 100644 --- a/NEWS.adoc +++ b/NEWS.adoc @@ -162,6 +162,18 @@ https://github.com/networkupstools/nut/milestone/13 - `usbhid-ups` driver updates: * When reconnecting, report success more visibly (not only in debug), and do not reset driver state to "quiet" when it will loop trying. [PR #3423] + * `apc-hid` subdriver: mapped `shutdown.return` to + `UPS.APCGeneralCollection.APCDelayBeforeReboot` with value "1", for + newer APC Back-UPS devices (e.g. Back-UPS BX750MI) where that usage + is the only shutdown-capable one. Their firmware accepts but never + executes the value "10" written by the previously only matching + command `shutdown.reboot`, so the built-in shutdown sequence reported + success without ever powering the load off. The value "1" is what APC + PowerChute writes (confirmed by decoding USB captures of the vendor + software, and by live tests on another unit): the load is cycled after + a fixed ~2 minute grace, the command is executed only while on battery, + and output returns when wall power is present, even if AC came back + during the grace period. [issue #2683, PR #3566] * `idowell-hid` subdriver now also supports GoldenMate 1000VA/800W LiFePO4 battery packs (`0x06da:0xffff`), which carry the same `-BMS-` firmware and HID descriptor as the existing `0x075d:0x0300` device. The shared diff --git a/docs/nut.dict b/docs/nut.dict index 52faedf9ec..bf27da2ebc 100644 --- a/docs/nut.dict +++ b/docs/nut.dict @@ -1,4 +1,4 @@ -personal_ws-1.1 en 3800 utf-8 +personal_ws-1.1 en 3801 utf-8 AAC AAS ABI @@ -1050,6 +1050,7 @@ PowerPC PowerPS PowerPal PowerPanel +PowerChute PowerShare PowerShell PowerShield diff --git a/drivers/apc-hid.c b/drivers/apc-hid.c index da34dba7eb..d117ab076b 100644 --- a/drivers/apc-hid.c +++ b/drivers/apc-hid.c @@ -457,6 +457,13 @@ static hid_info_t apc_hid2nut[] = { { "load.on.delay", 0, 0, "UPS.APCGeneralCollection.APCDelayBeforeStartup", NULL, DEFAULT_ONDELAY, HU_TYPE_CMD, NULL }, { "shutdown.stop", 0, 0, "UPS.APCGeneralCollection.APCDelayBeforeShutdown", NULL, "-1", HU_TYPE_CMD, NULL }, { "shutdown.reboot", 0, 0, "UPS.APCGeneralCollection.APCDelayBeforeReboot", NULL, "10", HU_TYPE_CMD, NULL }, + /* used by APC Back-UPS BX series (e.g. BX750MI), where this usage is the + * only shutdown-capable one: value "1" is what APC PowerChute writes + * (fixed ~2 min grace, executed only while on battery, output returns + * when wall power is present, even if AC came back during the grace); + * the "10" written by shutdown.reboot above is ACKed but never executed + * by that firmware. See issue #2683. */ + { "shutdown.return", 0, 0, "UPS.APCGeneralCollection.APCDelayBeforeReboot", NULL, "1", HU_TYPE_CMD, NULL }, /* used by APC BackUPS CS */ { "shutdown.return", 0, 0, "UPS.Output.APCDelayBeforeReboot", NULL, "1", HU_TYPE_CMD, NULL },