APC UPS (SNMP)

Schneider Electric APC Smart-UPS, Symmetra and Back-UPS Pro units fitted with an APC Network Management Card (NMC) — AP9630 / AP9631 / AP9635 / AP9640 / AP9641 / AP9644 — talk to GEM over SNMP using the published PowerNet-MIB (.1.3.6.1.4.1.318.1.1.1). This driver covers health monitoring, the canonical UPS control verbs, and outlet-group switching on NMC2 / NMC3 cards.

PDU users. APC's switched / metered rack PDUs (AP86xx / AP78xx / AP89xx) are a distinct product family on a different MIB branch (rPDU2, .1.3.6.1.4.1.318.1.1.26) and are intentionally not covered by this driver. If you need outlet control on an APC PDU, file a follow-up — the cyberpower driver is the structural reference for a combined UPS+PDU driver.

What's controlled

Telemetry (read on each `status_interval`)

Identity: model, ups_name, firmware_version, serial_number, manufacture_date
Battery: battery_status (normal / low / unknown), battery_level (%), battery_temperature (°C), runtime_remaining (minutes), time_on_battery (seconds), low_battery, battery_replace_needed, battery_packs_total, battery_packs_bad
Input line: input_voltage, input_voltage_max, input_voltage_min, input_frequency, last_transfer_cause (e.g. brownout / blackout / large_momentary_spike)
Output: output_status (online / on_battery / off / rebooting / …), output_voltage, output_frequency, output_load (%), output_current (A), on_battery (bool)
Self-test: self_test_result (passed / failed / invalid / in_progress), self_test_date, runtime_calibration_result

Control (SNMP SET — needs write access)

self_test — start a battery self test (brief, non-disruptive)
runtime_calibration — start a runtime calibration (the UPS will discharge on battery to recalibrate the estimate; disruptive on a depleted battery)
ups_reboot — power-cycle the entire UPS output (entire load off then on)
ups_power_off — turn the entire UPS output off (whole load loses power)
ups_sleep — sleep until utility power returns
flash_and_beep — locate the unit in a rack
turn_on — re-enable the UPS output after a software-issued off/sleep
power_on / power_off / reboot on address = outlet-group number — outlet-group control on NMC2 / NMC3 (Smart-UPS) cards

Auto-created zones

On the first poll, the driver enumerates the UPS outlet groups (PowerNet-MIB .1.3.6.1.4.1.318.1.1.1.12) and creates one GEM zone per switchable group in the power subsystem (control = power_default, address = outlet-group index). The "main" outlet group is reported as a device attribute (outlet_group_<n>_state) but not zoned — switching it would kill the entire UPS output, which is what ups_power_off is for.

Prerequisites

A Smart-UPS, Symmetra or Back-UPS Pro with an APC NMC.
SNMP enabled on the NMC. The factory default is SNMPv1 read-only with community public and write disabled. To use this driver's control verbs you must either:
- enable an SNMPv1/v2c write community on the NMC (factory write community is private), OR
- configure an SNMPv3 user with write access.
The GEM host's IP added to the NMC's SNMP access list. APC NMCs restrict SNMP to a configured access list by default — SNMP from any other IP is silently dropped.

Setup

In the NMC web UI (https://<nmc-ip>/):
- Navigate to Configuration → Network → SNMPv1 (or SNMPv3 if you prefer v3).
- Enable SNMP. Set a read community (default public) and a write community (default private). On the NMC2/NMC3 set the access type to Read+Write for the GEM host's access-list entry.
- Under Access Control add the GEM host IP / subnet so SNMP requests from it are accepted.
In GEM (/admin/devices):
- Add a device with driver apc_ups.
- Set ip to the NMC's IP. Leave port at 161.
- For SNMPv2c set community to the read community and write_community to the write community.
- For SNMPv3 set version = v3, v3_username, v3_security_level, and the auth + priv key fields.
On the first poll the driver pulls the full PowerNet-MIB UPS surface and writes every non-null reading to device attributes. If the NMC is NMC2 / NMC3 with switched outlet groups, one GEM zone per switchable group is auto-created in the power subsystem.

Attributes

Device — required

Attribute	Type	Description
`ip`	string	NMC LAN IP.

Device — optional

Attribute	Type	Default	Description
`port`	int	161	SNMP UDP port.
`version`	string	`v2c`	SNMP version: `v1`, `v2c`, or `v3`.
`community`	string	`public`	v1/v2c read community used for polling.
`write_community`	string (secure)	`private`	v1/v2c write community used for control. Falls back to `community` if blank.
`v3_username`	string		v3 username (USM).
`v3_security_level`	string	`authPriv`	v3 level: `noAuthNoPriv`, `authNoPriv`, `authPriv`.
`v3_auth_protocol`	string	`SHA`	`MD5`, `SHA`, `SHA224`, `SHA256`, `SHA384`, `SHA512`.
`v3_auth_key`	string (secure)		v3 auth passphrase.
`v3_priv_protocol`	string	`AES`	`DES`, `AES`, `AES256B`, `AES256R`.
`v3_priv_key`	string (secure)		v3 priv passphrase.
`status_interval`	int	30000	Poll interval in ms.
`timeout`	int	5000	SNMP request timeout in ms.
`retries`	int	1	SNMP retry count.
`reboot_delay`	int	5000	Fallback off → delay → on duration if the NMC firmware refuses the native immediateReboot command on an outlet group. The fallback runs only after an explicit refusal, never after an unanswered reboot that may have applied.

Zone address format

Outlet-group control zones (auto-created): address = the 1-based outlet-group index reported by the NMC (.1.3.6.1.4.1.318.1.1.1.12.x). control = power_default, subsystem = power. power_on / power_off / reboot translate to the upsOutletGroupControlGroupCommand enum (immediateOn / immediateOff / immediateReboot). The address must be a plain integer (2, 2, 02, +2 and 2.0 all mean group 2); values such as 1e3 or 2abc are refused.
Whole-UPS status zone (manually created): leave address blank. The driver mirrors output_status → state, plus battery_level, runtime_remaining, output_load, on_battery, battery_status, low_battery onto the zone for dashboards.

Known limitations

No PDU control. APC switched / metered PDUs use a different MIB branch and are out of scope for this driver. The cyberpower driver shows the dual-mode UPS+PDU pattern if you need an APC PDU driver in the future.
NMC1 cards (AP9617 / AP9618 / AP9619) lack the outlet-group MIB branch. Outlet-group zones will not auto-create on those cards; everything else (telemetry, UPS-wide control verbs) still works.
No load-shed configuration writes. Per-group reboot duration, off-delay, shutdown-on-battery thresholds, etc. are read-only in this revision. Set those in the NMC web UI.
No SNMP trap / event listener. This driver polls only. The NMC's trap configuration is independent of GEM.

Troubleshooting

Symptom	Check
All attributes empty / device disconnected	A timeout before anything answers ends the sweep and marks the device disconnected; after 3 failed sweeps polling backs off to every 5 min until the UPS answers again. Verify the enabled SNMP version on the NMC matches the driver, the GEM host is in the SNMP access list, and UDP/161 is reachable. APC NMC restricts SNMP to a configured access list by default.
Polling works but control returns an error	Control requires write access. On v2c, set a non-empty `write_community` (default `private`). On v3, the user must have write permission. The factory NMC is read-only until write is explicitly enabled.
Outlet-group commands return an error	Confirm the NMC is NMC2 or NMC3 — NMC1 cards do not implement the outlet-group MIB. Also confirm the group is configured as `switchableGroup` in the NMC UI; `mainGroup` is intentionally not exposed as a zone.
`runtime_remaining` is wildly large or zero on first connect	PowerNet-MIB reports runtime as TimeTicks (1/100 sec). The driver converts to minutes. A zero / spurious value on first connect usually means the NMC has not yet computed a runtime estimate after boot — wait one full poll cycle.
`output_status` shows `software_bypass` after a config change	Some Smart-UPS firmware briefly transits bypass during a NMC reboot. If it persists, check the NMC's event log for an alarm and verify the input voltage is in range.

What's controlled​

Telemetry (read on each status_interval)​

Control (SNMP SET — needs write access)​

Auto-created zones​

Prerequisites​

Setup​

Attributes​

Device — required​

Device — optional​

Zone address format​

Known limitations​

Troubleshooting​

See also​