nutdrv_qx_masterguard: Adds battery test until battery low.

[atanas-vladimirov]

The difference between the battery test until battery low and deep battery test is that the latter is actually a battery calibration test and needs some preconditions to be met, i.e. the load must be between 30% and 100% and the battery capacity is greater than 99%.

Battery test until battery low can be started anytime.

Tested on Masterguard A1000 and A2000 units.

[AppVeyorBot]

✅ Build nut 2.8.4.3608-master completed (commit af328d7444 by @atanas-vladimirov)

[jimklimov]

Thanks! Probably not a focus of this specific PR, but got me wondering: do these UPSes report (e.g. in later status polling) that it is in calibration or some other testing mode, so a low-battery state would not mean immediate shutdown for upsmon? Does the device (or driver) report remaining "online" and/or on bypass while draining the battery?

Did any of this misfire in your tests, to initiate shutdown of the testing rig?

If any of this is a practical problem, it probably impacts all or most of the Qx subdrivers, maybe they would need to set some internal variable about a user-requested calibrarion and take it into account in the loop part where they set_status. But then it may be tricky (IF the devices do not report being in the self-testing state) how/when to lower the driver's internal flag (e.g. when battery.charge begins growing back?)

Again, this is not something to solve in this PR, if even ever, but if you with first-hand practice with the devices and protocol have any inputs about this, would be great to hear :)

[atanas-vladimirov]

Hi Jim,

Thanks for your reply and merging my PR.

I'll try to answer your questions:

do these UPSes report (e.g. in later status polling) that it is in calibration or some other testing mode, so a low-battery state would not mean immediate shutdown for upsmon? Does the device (or driver) report remaining "online" and/or on bypass while draining the battery?

Yes, they report that test or calibration is ongoing and yes, they stay "Online" even if the batteries go low on juice. Here is an example from the calibration I did today:

The battery charge went to 0 (zero), the UPS switched to bypass mode for a very short time to completes the calibration. And my server and a few other things connected to the UPS were up and running all the time.

Did any of this misfire in your tests, to initiate shutdown of the testing rig?

Till now I have used the old masterguard driver and I was always missing some commands and options. Recently, I found this new nutdrv_qx and was very impressed and happy with the options it has. Thanks for that! So, until now I have a small python script that runs once a month and do a battery test until battery low (TL)

.....
    if ups.is_open:
        while True:
            while ups.in_waiting == 0:
                ups.write(b"Q3\r\n")
                time.sleep(1)

            result = ups.read(ups.in_waiting)
            data = result.decode("us-ascii")
            status = data[53:70]
            if status == "00000100 00000001":
                break
            ups.write(b"TL,00\r\n")

        ups.close()
....

Of course, the script handles other stuffs, like stopping the ups/upsmon daemon and back starting it.
And that was the main reason I decided to contribute to the project by adding the TL command :)

While testing today I found that the test.battery.start.deep command is not working even I have all the prerequisites in place (the battery charge was >99% and the UPS load was >30%). I start debugging and think I found the problem, the command is not TUD but TUD,00 - or this is what my Windows program (ppset.exe) is sending to the UPS (I used a serial port sniffer to capture it)

[20/10/2025 09:15:58] Written data (COM3)	
    54 55 44 2c 30 30 0d 0a                           TUD,00..

I'll try to test this more and will send a new PR with a proposed fix :).

P.S: While writing this I realized that I do TL,00 in my python script but the PR I send is just TL, but it works. So this is strange. Not sure why the TUD only is not working. Let me know if you have any thoughts :)

Best wishes,
Atanas

[jimklimov]

Can't really comment on the Qx protocol (TUD,00 vs TUD etc.) or its implementations by specific vendors, not an expert here. Maybe @clepple would have some thoughts?

A guess is that the number specifies some sort of timeout ("Run the test after X minutes"?) that applies to one and not another? Or with different defaults (e.g. immediately here, after 10 or 60 minutes there)?

[efuss]

the command is not TUD but TUD,00

Sorry, my bad. According to the protocol definition, TUD requires a slave address.
So, it should be TUD,XX with masterguard_add_slaveaddr.

OTOH, TL is documented to work both with and without a slave address.

[atanas-vladimirov]

Thanks for confirming!