NUT: Network UPS Tools: APC's smart protocol
Description
Here's the information on the elusive APC smart signalling protocol used by their higher end units (Back-UPS Pro, Smart-UPS, Matrix-UPS, etc). What you see here has been collected from a variety of sources. Some people analyzed the chatter between PowerChute and their hardware. Others sent various characters to the UPS and figured out what the results meant.
RS-232 differences
Normal 9 pin serial connections have TxD on 3 and RxD on 2. APC's smart serial ports put TxD on pin 1 and RxD on pin 2. This means you go nowhere if you use a normal straight through serial cable. In fact, you might even power down the load if you plug one of those cables in. This is due to the odd routing of pins - DTR and RTS from the PC usually wind up driving the on/off line. So, when you open the port, they go high and *poof* your computer dies.
Originally this evil hack was used to connect the UPS to the PC when this page was first being built. As you can see, I cheated and neglected the ground (only 2 wires!) and it still worked. This method can be used for playing around, but for professional systems this is obviously not a viable option.
That hack didn't work out so well (damned cats), so it was retired quite awhile back. The most practical solution was to go out and BUY the DOS/Win version of Powerchute just for the black (smart) cable. I recommend doing the same thing if you actually care about this thing working properly. Of course, if you have one of the newer packages that came with PowerChute, you already have the cable you need.
Diagram for cable hackers
If you are handy with cable creation tools, check out the. That's the black "smart" cable normally provided with APC models sold after 1996. The loopback pins on that diagram are used to keep PowerChute happy by allowing cable detection. If you use the NUTapcsmart driver, those pins don't matter.
Many thanks to Steve Draper for providing this scan.
The Smart Protocol
Despite the lack of official information from APC, this table has been constructed. It's standard RS-232 serial communications at 2400 bps/8N1. Don't rush the UPS while transmitting or it may stop talking to you. This isn't a problem with the normal single character queries, but it really does matter for multi-char things like "@000". Sprinkle a few calls to usleep() in your code and everything will work a lot better.
| Code | Meaning | Typical results |
|---|---|---|
| ^A | Model string | SMART-UPS 700 |
| ^N | Turn on UPS (send twice, with > 1.5s delay between chars) Only on 3rd gen SmartUPS and Black Back-UPS Pros |
n/a |
| ^Z | Capability string | Now understood - see below |
| A | Front panel test | Light show + "OK" (and 2s beep) |
| B | Battery voltage | Ranges - typical "27.87" |
| C | Internal temperature (degrees C) | Ranges - typical "036.0" |
| D | Runtime calibration - runs until battery is below 25% (35% for Matrix) This updates the 'j' values - only works at 100% battery charge Can be aborted with a second "D" |
! when on battery, $ on line |
| E | Automatic selftest intervals | Default = 336 (14 days) (336=14 days, 168=7 days, ON=power on, OFF=never) |
| F | Line frequency, Hz | 60.00 |
| G | Cause of transfer | R = unacceptable utility voltage rate of change, H = high utility voltage, L = low utility voltage, T = line voltage notch or spike, O = no transfers yet (since turnon), S = transfer due to U command or activation of UPS test |
| K--K | Shutdown with grace period (set with 'p') - need > 1.5s between first and second K | Matrix/3rd gen SmartUPS/Black Back-UPS Pros: "OK", all others: "*" |
| L | Input line voltage | Ranges - typical "118.3" |
| M | Maximum line voltage received since last M query | Ranges - typical "118.9" |
| N | Minimum line voltage received since last N query | Ranges - typical "118.9" |
| O | Output voltage | Ranges - typical "118.3" |
| P | Power load % | Ranges - typical "000.0" |
| Q | Status flags | Bitmapped, see below |
| R | Turn dumb Only on 3rd gen SmartUPS, SmartUPS v/s, BackUPS Pro |
"BYE" |
| S | Soft shutdown after 'p' delay, return online when power returns Only works when UPS is on battery |
OK |
| U | Simulate power failure | !! when switching to battery, then $ when back on line |
| V | Firmware revision | "GWD" |
| W | Self test (battery), results stored in "X" | "OK" |
| X | Results of last selftest | "OK" - good battery, "BT" - failed due to insufficient capacity, "NG" - failed due to overload, "NO" - no results available (no test performed in last 5 minutes) |
| Y | Enter smart mode | "SM" |
| Z--Z | Shutdown immediately (no delay) | n/a |
| a | Show protocol version/alert messages/valid commands | "3.!$%+?=#|.^A^N^Z+-789<@ABCDEFGKLMNOPQRSUVWXYZ'abcefgjklmnopqrsuvzy~^?" - Link-Level.alert-messages.commands |
| b | Firmware revision | "50.9.D" - 50 = SKU (variable length), 9 = firmware revision, D = country code |
| c | UPS local id | UPS_IDEN |
| e | Return threshold | % battery charge threshold for return(00=00%, 01=15%, 02=25%, 03=90%) |
| f | Battery level % | Ranges - typical "099.0" |
| g | Nominal battery voltage (not actual voltage - see B) | "024" |
| h | Measure-UPS: ambient humidity (%) | "nnn.n" - percentage |
| i | Measure-UPS: dry contacts | 10 = contact 1, 20 = 2, 40 = 3, 80 = 4 |
| j | Estimated runtime at current load (minutes) | "0327:" |
| k | Alarm delay | 0=5 second delay after fail/T=30 second delay/L=alarm at low battery only/N=no alarm |
| l | Low transfer voltage | Default "103" |
| m | Manufacturing date | Unique within groups of UPSes (production runs) |
| n | Serial number | Unique for each UPS |
| o | Output voltage | Default "115" |
| p | Shutdown grace delay, seconds | Default "020" (020/180/300/600) |
| q | Low battery warning, minutes | Default "02" |
| r | Wakeup delay (time) - seconds | Default "000" (000/060/180/300) |
| s | Sensitivity | "H" - highest, "M" - medium, "L" - lowest, "A" - autoadjust (Matrix only) |
| u | Upper transfer voltage | Default "132" |
| t | Measure-UPS: ambient temperature (degrees C) | "nn.nn" |
| x | Last battery change | Varies |
| y | Copyright notice | "(C) APCC" - only works if firmware letter (from "V") is later than O |
| z | Reset to factory settings (but not ident or batt replacement date) Not on SmartUPS v/s or BackUPS Pro |
"CLEAR" |
| - | Capability cycle | Cycle through possible values ("|" from UPS afterward to confirm change) |
| @nnn | Shutdown (after delay 'p') with delayed wakeup of nnn tenths of an hour (after 'r' time) | Matrix/3rd gen UPS: "OK", others "*" |
| 0x7f (DEL key) | Abort shutdown - use to abort @, S, K--K | "OK" |
| ~ | Register #1 | See below |
| ' | Register #2 | See below |
| 7 | Dip switch positions (if applicable) | See below |
| 8 | Register #3 | See below |
| 9 | Line quality | "FF" acceptable, "00" unacceptable |
| > | Number of battery packs attached | SmartCell models: "nnn" where nnn is how many packs are connected Non-SmartCell units: whatever has been set with >+ and >- by the user |
| Matrix UPS (and possibly Symmetra) specific commands | ||
| ^ | Run in bypass mode | If online, "BYP" is received as bypass mode starts If already in bypass, "INV" is received and UPS goes online "ERR" received if UPS is unable to transfer |
| < | Number of bad battery packs | "nnn" - count of bad packs connected to the UPS |
| / | Load current | "nn.nn" - true RMS load current drawn by UPS |
| \ | Apparent load power | "nnn.nn" - output load as percentage of full rated load in VA. |
| ^V | Output voltage selection (editable) | "A" - automatic according to input tap, "M" - 208 VAC, "I" - 240 VAC |
| ^L | Front panel language | "E" - English, "F" - French, "G" - German, "S" - Spanish, "1" "2" "3" "4" - ? |
| w | Run time conservation | "NO" (disabled) or "02" "05" "08" - minutes of runtime to leave in battery (UPS shuts down "early") |
Dip switch info
| Bit | Switch | Option when bit=1 |
|---|---|---|
| 0 | 4 | Low battery alarm changed from 2 to 5 mins. Autostartup disabled on SU370ci and 400 |
| 1 | 3 | Audible alarm delayed 30 seconds |
| 2 | 2 | Output transfer set to 115 VAC (from 120 VAC) or to 240 VAC (from 230 VAC) |
| 3 | 1 | UPS desensitized - input voltage range expanded |
| 4-7 | - | Unused at this time |
Status bits
Some common things you'll see:
- 08 = on line, battery OK
- 10 = on battery, battery OK
- 50 = on battery, battery low
| Bit | Meaning |
|---|---|
| 0 | 1 = runtime calibration occurring Not reported by Smart UPS v/s and BackUPS Pro |
| 1 | 1 = SmartTrim Not reported by 1st and 2nd generation SmartUPS models |
| 2 | 1 = SmartBoost |
| 3 | 1 = on line |
| 4 | 1 = on battery |
| 5 | 1 = overloaded output |
| 6 | 1 = battery low |
| 7 | 1 = replace battery |
Alert messages
| Character | Description |
|---|---|
| ! | Line Fail - sent when the UPS goes on-battery, repeated every 30 seconds until low battery condition reached. Sometimes occurs more than once in the first 30 seconds. |
| $ | Return from line fail - UPS back on line power, only sent if a ! has been sent. |
| % | Low battery - Sent to indicate low battery, but not on SmartUPS v/s or BackUPS Pro models |
| + | Return from low battery - Sent when the battery has been recharged to some level only if a % has been sent previously |
| ? | Abnormal condition - sent for conditions such as "shutdown due to overload" or "shutdown due to low battery capacity". Also occurs within 10 minutes of turnon. |
| = | Return from abnormal condition - Sent when the UPS returns from an abnormal condition where ? was sent, but not a turn-on. Not implemented on SmartUPS v/s or BackUPS Pro models. |
| * | About to turn off - Sent when the UPS is about to switch off the load. No commands are processed after this character is sent. Not implemented on SmartUPS v/s, BackUPS Pro, or 3rd generation SmartUPS models. |
| # | Replace battery - Sent when the UPS detects that the battery needs to be replaced. Sent every 5 hours until a new battery test is run or the UPS is shut off. Not implemented on SmartUPS v/s or BackUPS Pro models. |
| & | Check alarm register for fault (Measure-UPS) - sent to signal that temp or humidity out of set limits. Also sent when one of the contact closures changes states. Sent every 2 minutes, stops when the alarm conditions are reset. Only sent for alarms enabled with I. Cause of alarm may be determined with J. Not on SmartUPS v/s or BackUPS Pro. |
| | | Variable change in EEPROM - Sent whenever any EEPROM variable is changed. Only supported on Matrix UPS and 3rd generation SmartUPS models. |
Register 1
All bits are valid on the Matrix UPS. SmartUPS models only support bits 6 and 7. Other models do not respond.
| Bit | Meaning |
|---|---|
| 0 | In wakeup mode (typically lasts < 2s) |
| 1 | In bypass mode due to internal fault - see register 2 or 3 |
| 2 | Going to bypass mode due to command |
| 3 | In bypass mode due to command |
| 4 | Returning from bypass mode |
| 5 | In bypass mode due to manual bypass control |
| 6 | Ready to power load on user command |
| 7 | Ready to power load on user command or return of line power |
Register 2
Matrix UPS models report bits 0-5. SmartUPS models only support bits 4 and 6. SmartUPS v/s and BackUPS Pro report bits 4, 6, 7. Unused bits are set to 0. Other models do not respond.
| Bit | Meaning |
|---|---|
| 0 | Fan failure in electronics, UPS in bypass |
| 1 | Fan failure in isolation unit |
| 2 | Bypass supply failure |
| 3 | Output voltage select failure, UPS in bypass |
| 4 | DC imbalance, UPS in bypass |
| 5 | Command sent to stop bypass with no battery connected - UPS still in bypass |
| 6 | Relay fault in SmartTrim or SmartBoost |
| 7 | Bad output voltage |
Register 3
All bits are valid on the Matrix UPS and 3rd generation SmartUPS models. SmartUPS v/s and BackUPS Pro models report bits 0-5. All others report 0-4. State change of bits 1,2,5,6,7 are reported asynchronously with ? and = messages.
| Bit | Meaning |
|---|---|
| 0 | Output unpowered due to shutdown by low battery |
| 1 | Unable to transfer to battery due to overload |
| 2 | Main relay malfunction - UPS turned off |
| 3 | In sleep mode from @ (maybe others) |
| 4 | In shutdown mode from S |
| 5 | Battery charger failure |
| 6 | Bypass relay malfunction |
| 7 | Normal operating temperature exceeded |
Capabilities
Upon sending a ^Z, your UPS will probably spit back something like this (truncated here for the example):
#uD43132135138129uM43229234239224uA43110112114108 ....
It looks bizarre and ugly, but is easily parsed. The # is some kind of marker/ident character. Skip it. The rest fits this form:
- Command character - use this to select the value
- Locale - use 'b' to find out what yours is, '4' applies to all
- Number of choices - '4' means there are 4 possibilities coming up
- Choice length - '3' means they are all 3 chars long
Then it's followed by the choices, and it starts over.
Matrix-UPS models have ## between each grouping for some reason.
Acknowledgements
Large parts of this data were contributed or corrected by Steven Freed. This guy is some sort of APC UPS god. Many thanks.
Russell Kroll
26 November 1999