Monitor

Monitor

The Monitor class provides event-based UPS monitoring, similar to upsmon. It polls the NUT server at regular intervals and emits typed events when status flags appear or disappear, variables change, or communication status changes.

Basic Usage

import { NUTClient, Monitor } from 'nut-client';

const client = await NUTClient.create('127.0.0.1', 3493, {
  username: 'admin',
  password: 'secret',
  autoReconnect: true,
});

const monitor = new Monitor(client, 'myups');

monitor.on('ONBATT', () => console.log('UPS on battery'));
monitor.on('ONLINE', () => console.log('UPS back online'));

await monitor.start();

Constructor

new Monitor(client: NUTClient, upsName: string, options?: IMonitorOptions)

Parameter	Type	Description
client	NUTClient	The NUT client (should have auto-reconnect enabled for production use)
upsName	string	Name of the UPS to monitor
options.pollFrequency	number	Poll interval in ms (default: 60000 = 1 minute)

Methods

Method	Description
start()	Start monitoring. Fetches initial UPS state. Throws if monitor is destroyed.
stop()	Stop monitoring (heartbeat paused, can be resumed).
pause()	Pause event emission. Heartbeat keeps running but events are suppressed. Next poll after resume is treated as fresh (no spurious events).
resume()	Resume monitoring after pause. Clears previous state to avoid stale events.
isPaused()	Check if monitoring is currently paused.
destroy()	Destroy the monitor and release all resources. Cannot be reused. Idempotent.
isDestroyed()	Check if the monitor has been destroyed.

Events

Status Events (flag appears)

Event	Description
ONLINE	UPS is back on mains power (OL appeared)
ONBATT	UPS switched to battery (OB appeared)
LOWBATT	Battery is low (LB appeared)
FSD	Forced shutdown mode activated (FSD appeared)
REPLBATT	Battery needs replacement (RB appeared)
CAL	Calibration started (CAL appeared)
OFF	UPS is off/asleep (OFF appeared)
BYPASS	UPS entered bypass mode (BYPASS appeared)

"NOT" Events (flag disappears)

Event	Description
NOTOL	No longer online (OL disappeared)
NOTOB	No longer on battery (OB disappeared)
NOTLB	Battery no longer low (LB disappeared)
NOTFSD	Forced shutdown cleared (FSD disappeared)
NOTRB	Battery replacement cleared (RB disappeared)
NOTOFF	UPS no longer off (OFF disappeared)
NOTCAL	Calibration finished (CAL disappeared)
NOTBYPASS	No longer on bypass (BYPASS disappeared)

Communication Events

Event	Description
COMMOK	Communication restored (after COMMBAD)
COMMBAD	Communication lost (UPS unreachable)
NOCOMM	Client reconnect exhausted (no more retry attempts)

Variable Events

Event	Arguments	Description
BATTERY_CHARGE	(charge: number, rawCharge: string)	Battery charge changed. charge is NaN if not a valid number.
BATTERY_RUNTIME	(runtime: number, rawRuntime: string)	Battery runtime changed.
VARIABLE_CHANGED	(key, oldValue, newValue, oldVars, newVars)	Any variable changed.
VARIABLES_CHANGED	(oldVars, newVars)	At least one variable changed in this poll cycle.
UNKNOWN_STATUS	(status: string)	An unrecognized status code was detected.

Debug Event

Event	Arguments	Description
*	(event: string, ...args)	Wildcard listener — fires for every event.

Monitor ↔ Reconnect Integration

When the NUTClient has autoReconnect: true, the Monitor automatically integrates with the reconnect system:

• Reconnected: The Monitor continues polling normally after the client reconnects. No special handling needed.
• Reconnect exhausted: When the client gives up reconnecting, the Monitor emits NOCOMM. You should handle this to avoid silent failures.

const client = new NUTClient('127.0.0.1', 3493, {
  autoReconnect: true,
  maxReconnectAttempts: 5,
});

const monitor = new Monitor(client, 'myups');

monitor.on('COMMBAD', () => console.log('Communication lost'));
monitor.on('COMMOK', () => console.log('Communication restored'));
monitor.on('NOCOMM', () => {
  console.log('Client cannot reconnect — manual intervention needed');
});

await monitor.start();

Pause / Resume

Use pause() and resume() to temporarily suppress events without a full restart:

monitor.pause();
// No events emitted while paused
// Heartbeat keeps running for timing stability

monitor.resume();
// Events resume on next poll
// Previous state is cleared to avoid spurious events

Cleanup

Always destroy the monitor when done:

monitor.destroy();  // idempotent, safe to call multiple times