APCTEST(8)

✨ NAME ✨

okay so this is apctest — literally the apcupsd(8) test program 💖

---

🎀 SYNOPSIS 🎀

apctest

---

🦋 DESCRIPTION 🦋

bestie, apctest is the program that lets you run certain low-level tests to check how the attached simple signalling American Power Conversion Corp (APC) UPS is doing, and to check that your apcupsd(8) config is set up correctly and can actually establish communication with the UPS. No cap.

For an APC UPS running in APC smart protocol mode, apctest lets you read and program the values of the UPS EEPROM configuration variables, and also do a battery runtime calibration. It also gives you a simple TTY chat mode so you can directly interact with the UPS via the APC smart protocol. For the deets on that protocol and the available commands, go read the detailed "APC Smart Protocol" section in the apcupsd manual. iykyk.

IMPORTANT: Before running apctest 🚨

• Check that the UPSCABLE, UPSTYPE and DEVICE configuration directives in the apcupsd.conf(5) configuration file have been set appropriately; and
• Shutdown apcupsd if it is running. You cannot run both apcupsd and apctest at the same time. periodt.

When you run it, apctest shows a menu of options that are different depending on whether the UPS is connected to a USB port or to a serial port. For a serial port connection, there are two different menus depending on whether the UPS is operating in APC smart protocol mode or simple signalling mode — this also depends on which cable is used to connect to the UPS. If a simple signalling cable is used to connect to a Smart-UPS, the UPS will only be able to operate in simple signalling mode. the way that matters 💅

apctest saves a transcript of the session to the file apctest.out in the directory from which the program was called. Its content is useful for debugging purposes. obsessed with receipts ✨

---

🔌 USB PORT 🔌

When using a UPS connected to a USB port (eg Back-UPS RS 1500), the following menu options will appear:

🌟 Option 1) Test kill UPS power

Performs a power down of the UPS into hibernate mode. sleepy time 😴

🌟 Option 2) Perform self-test

Performs an immediate self-test (switches to battery power to do so). ⚡

🌟 Option 3) Read last self-test result

Displays the last self-test result. receipts 🧾

🌟 Option 4) View/Change battery date

Displays the current battery replacement date and optionally allows you to change it — useful when the battery is replaced so that you can accurately keep track of its age. age tracking but for batteries 🎀

🌟 Option 5) View manufacturing date

Displays the date the UPS was manufactured. born on date 🍼

🌟 Option 6) View/Change alarm behavior

Sets the delay period before the UPS starts sounding its alarm when the utility power is lost. beep beep 🚨

🌟 Option 7) View/Change sensitivity

Changes how sensitive the UPS is to the utility power quality and voltage fluctuations — (H)igh, (M)edium or (L)ow. The higher the sensitivity, the faster the UPS will switch to battery power or activate SmartBoost/SmartTrim (features that avoid using battery power provided the under/over voltage is within 12% of nominal). This setting should normally be set to High unless the UPS switches to battery power frequently, in which case a less sensitive setting will preserve UPS batteries... if the connected equipment can tolerate the power quality. vibe check on the voltage 💅

🌟 Option 8) View/Change low transfer voltage

Sets the low voltage level at which the UPS switches to battery or activates SmartBoost. lowkey ⬇️

🌟 Option 9) View/Change high transfer voltage

Sets the high voltage level at which the UPS switches to battery or activates SmartTrim. highkey ⬆️

🌟 Option 10) Perform battery calibration

This performs a battery runtime calibration. This can only be performed if your battery is charged to 100% of capacity. The runtime calibration discharges the UPS battery to approximately 25% of capacity. The exact percentage depends on the UPS model.

The advantage of doing this calibration is that the UPS will recalibrate the remaining runtime counter that it maintains and therefore report a more accurate estimated runtime. As batteries age, they tend to hold less charge, so the UPS's internal runtime counter may not be accurate after several years.

It is recommended that battery runtime calibration be performed annually. Performing it too often shortens the lifetime of the UPS batteries. do not spam this button 😭

🌟 Option 11) Test Alarm

This option will cause the UPS alarm beeper to sound for several seconds. 🔊

🌟 Option 12) View/Change self-test interval

This option allows you to change the time interval between automatic UPS self-tests. schedule that self-care 🗓️

🌟 Option Q) Quit

Exits from the program. bye bestie 👋

---

🐚 SERIAL PORT (SMART PROTOCOL MODE) 🐚

When using a UPS operating in APC smart protocol mode (eg a Smart-UPS) the following menu options will appear:

💫 Option 1) Query the UPS for all known values

Selecting this option probes the UPS for all EEPROM configuration variable values known to apctest and displays them in rather raw format. This output can be useful for providing technical support if you are having problems with the behaviour of the UPS or apcupsd(8). dump it and send it 📤

💫 Option 2) Perform a Battery Runtime Calibration

This performs a battery runtime calibration. This can only be performed if your battery is charged to 100% of capacity. The runtime calibration discharges the UPS battery to approximately 25% of capacity. The exact percentage depends on the UPS model. apctest can optionally abort the calibration if it detects that the battery charge is below 10%.

The advantage of doing this calibration is that the UPS will recalibrate the remaining runtime counter that it maintains and therefore report a more accurate estimated runtime. As batteries age, they tend to hold less charge, so the UPS's internal runtime counter may not be accurate after several years.

It is recommended that battery runtime calibration be performed annually. Performing it too often shortens the lifetime of the UPS batteries. annual, not daily ⚠️

💫 Option 3) Abort Battery Calibration

This option aborts an in progress battery runtime calibration. stop right now 🛑

💫 Option 4) Monitor Battery Calibration progress

Allows restarting of the monitoring of a battery runtime calibration. watch it like a show 🍿

💫 Option 5) Program EEPROM

Allows the programming of the values of a Smart-UPS's EEPROM configuration variables.

Choosing this option presents a sub-menu of programming options which are detailed below.

🎀 Option 1) Print EEPROM values

Prints the value of all EEPROM configuration variables known to apctest. print it 🖨️

🎀 Option 2) Change Battery date

Changes the battery date — useful when the battery is replaced so that you can accurately keep track of its age. birthday update 🎂

🎀 Option 3) Change UPS name

Changes the UPS name — use no more than 8 characters to name the UPS. short & cute ✨

🎀 Option 4) Change sensitivity

Changes how sensitive the UPS is to the utility power quality and voltage fluctuations — (H)igh, (M)edium or (L)ow. The higher the sensitivity, the faster the UPS will switch to battery power or activate SmartBoost/SmartTrim (features that avoid using battery power provided the under/over voltage is within 12% of nominal). This setting should normally be set to High unless the UPS switches to battery power frequently, in which case a less sensitive setting will preserve UPS batteries... if the connected equipment can tolerate the power quality. same vibe check, different menu 💅

🎀 Option 5) Change alarm delay

Changes the delay period before the UPS starts sounding its alarm when the utility power is lost. 🚨

🎀 Option 6) Change low battery warning delay

Changes the remaining runtime minutes at which the UPS will send the low battery signal. When the UPS internally calculates that the specified number of minutes remains before battery power will be exhausted, it sends the low battery warning. heads up bestie 🔋

🎀 Option 7) Change wakeup delay

Changes the delay before the UPS restores power to connected equipment when the utility power returns after shutting down in hibernate mode. wakey wakey ☀️

🎀 Option 8) Change shutdown delay

Changes the delay for which the UPS waits before shutting off power to the connected equipment after being commanded to power down in hibernate mode. wait for it ⏳

🎀 Option 9) Change low transfer voltage

Changes the low voltage level at which the UPS switches to battery or activates SmartBoost. ⬇️

🎀 Option 10) Change high transfer voltage

Changes the high voltage level at which the UPS switches to battery or activates SmartTrim. ⬆️

🎀 Option 11) Change battery return threshold percent

Changes the battery charge percentage required after power down in hibernate mode before to the UPS will restore power to connected equipment on the return of utility power. threshold era 💯

🎀 Option 12) Change output voltage when on batteries

Changes the nominal voltage output when the UPS is running on battery power. ⚡

🎀 Option 13) Change the self test interval

Changes or disables the automatic self-test interval. self-care schedule 🗓️

🎀 Option 14) Set EEPROM with configuration file values

This option allows the bulk programming of the EEPROM configuration variables from the values contained in the /etc/apcupsd.conf configuration file. Refer to the "APCTEST EEPROM CONFIGURATION DIRECTIVES" section of the man page for apcupsd.conf(5). bulk upload energy 📦

🎀 Option 15) Quit

This option exits back to the previous (main) menu. back it up ↩️

💫 Option 6) Enter TTY mode communicating with UPS

This option allows direct interaction with the attached UPS using the APC smart protocol commands.

WARNING: Take special care what commands you enter because it is possible to cause the UPS to suddenly shutdown or, in the worst case, modify the UPS in such a way as to permanently disable it. Do NOT experiment with unknown or unsupported commands. Caveat Utilitor! 💀

💫 Option 7) Quit

Exits from the program. bye for real 👋

✨ SERIAL PORT (SIMPLE SIGNALLING MODE) ✨

Okay bestie, when your APC UPS is out here living its simple signalling mode life, the menu gets a whole different lineup. Here's the cast of characters you'll see:

---

🌸 Option 1) Test 1 - normal mode

What you actually get from this test is fully dependent on the model of UPS you've got and the type of cable you're using — there's no universal answer, it's giving ✨situational✨. For the deets, go read the "Using apctest on Serial-Line UPSses" section in the apcupsd manual.

🎀 Option 2) Test 2 - no cable

Same energy as above, bestie: the result depends on the model of UPS and the type of cable being used. The "Using apctest on Serial-Line UPSses" section in the apcupsd manual is where you'll find the whole explanation.

🦋 Option 3) Test 3 - no power

Yeah, you already know — the outcome here hinges on the model of UPS and the type of cable in play. Hit up the "Using apctest on Serial-Line UPSses" section in the apcupsd manual for the full tea.

💜 Option 4) Test 4 - low battery (requires Test 3 first)

⚠️ Heads up: this one requires Test 3 first — do them in order, no skipping, fr fr.

And the result? Yep, it depends on the model of UPS and the type of cable being used. Check the "Using apctest on Serial-Line UPSses" section in the apcupsd manual for the details.

⭐ Option 5) Test 5 - battery exhausted

The result depends on the model of UPS and the type of cable being used — same deal as its siblings. The "Using apctest on Serial-Line UPSses" section in the apcupsd manual has the explanation you're looking for.

🔥 Option 6) Test 6 - kill UPS power

Extremely main character behaviour, honestly. And the result depends on the model of UPS and the type of cable being used. Refer to the "Using apctest on Serial-Line UPSses" section in the apcupsd manual for the details.

👑 Option 7) Test 7 - run tests 1 through 5

This one is the multitasker 💅 — it runs tests 1 through 5, and it has apctest guess which cable should be used with the attached UPS. Let it cook.

🌈 Option 9) Quit

Exits from the program. Bye bestie, it was so fun 🫶

🙈 (and yes, we jumped from 7 to 9 — that's just how the menu is, no option 8 in these streets)

---

💖 FILES 💖

• /etc/apcupsd/apcupsd.conf — the default configuration file
• apctest.out — a transcript of the apctest session

---

🌟 SEE ALSO 🌟

• apcupsd.conf(5)
• apcupsd(8)

Also, there's the HTML apcupsd manual — either installed right there on your system, or available online at http://www.apcupsd.org/ ✨

---

🎀 AUTHORS 🎀

💌 This page

• Trevor Roydhouse (current)
• Robert Huff

💻 Software

• Adam Kropelin (current Project Manager and Code Maintainer)
• Kern Sibbald (former Project Manager and Code Maintainer)
• Riccardo Facchetti (former Project Manager and Code Maintainer)
• Andre M. Hedrick (Project Founder and former Code Maintainer)

🫶 Contributors

An enormous number of users who have devoted their time and energy to this project — thanks. (No like, genuinely, an enormous number. Absolute icons, every single one of them. 😭💜)

---

And that's the whole page, bestie! This one was apctest v3.14.6, dated January 10, 2009, living under the name APCTEST(8). Now go test that UPS — you got this 💅✨🌸