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 rejects the native immediateReboot command on an outlet group.

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).
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	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​