printer-snmp

Read page counters, serial number and toner levels from any network printer via SNMP — no vendor‑specific code.

A tiny, dependency‑light Node.js library that talks to network printers using the standard Printer‑MIB (RFC 3805). Because it relies on the standard MIB, it works across vendors — HP, Brother, Epson, Lexmark, Kyocera, and others — without any brand‑specific handling.

It is built to be failure‑tolerant: an offline printer, or one with SNMP disabled, never throws or hangs your app — it simply resolves with { ok: false, error }.

Features

• 📄 Page counter — total pages printed over the device's lifetime.
• 🖨️ Serial number — identify each machine.
• 🎨 Toner / supply levels — percentage per supply, with proper handling of the "present but unknown level" case (-3) defined by the RFC.
• 🌐 Range scan — sweep a whole IP range and get back only the printers that answered.
• 🛡️ Never hangs — built‑in timeout + safety guard, designed for unattended use.
• 🧩 TypeScript types included.
• ⌨️ CLI included — query a printer straight from the terminal.

Install

npm install printer-snmp

Requires Node.js 18+.

Usage

const { readPrinter } = require('printer-snmp');

const reading = await readPrinter('192.168.0.50', {
  community: 'public',  // default
  version: 'v2c',       // 'v1' or 'v2c' (default 'v2c')
  timeout: 1500          // ms (default)
});

console.log(reading);
// {
//   ip: '192.168.0.50',
//   ok: true,
//   counter: 48213,
//   serial: 'CN1234ABCD',
//   toners: [ { desc: 'Black Toner', pct: 72 } ],
//   error: null,
//   at: '2026-06-06T12:00:00.000Z'
// }

Scan an IP range

const { scanRange } = require('printer-snmp');

const printers = await scanRange('192.168.0.1', '192.168.0.254', {
  community: 'public',
  concurrency: 20   // simultaneous reads (default)
});

printers.forEach((p) => {
  console.log(`${p.ip} — ${p.counter} pages`);
});

scanRange returns only the printers that responded. Pass { includeOffline: true } if you also want the ones that didn't.

CLI

After installing (globally, or via npx):

# Single printer
npx printer-snmp 192.168.0.50

# Scan a range
npx printer-snmp 192.168.0.1 192.168.0.254 --community public --version v2c

Output is JSON, so you can pipe it into other tools:

npx printer-snmp 192.168.0.50 | jq .counter

API

readPrinter(ip, options?) → Promise<PrinterReading>

| Option | Type | Default | Description | | ------------ | ---------------- | ---------- | ---------------------------------------- | | community | string | "public" | SNMP read community. | | version | "v1" | "v2c"| "v2c" | SNMP version. | | timeout | number (ms) | 1500 | Per‑request timeout. | | retries | number | 0 | Retry attempts. |

PrinterReading

| Field | Type | Description | | --------- | ------------------------ | ------------------------------------------------------- | | ip | string | IP queried. | | ok | boolean | true if the printer answered. | | counter | number \| null | Lifetime page count. | | serial | string \| null | Serial number. | | toners | { desc, pct }[] | Supplies. pct: 0–100, -3 (present/unknown), null.| | error | string \| null | Error message when ok === false. | | at | string | ISO‑8601 timestamp of the reading. |

scanRange(startIp, endIp, options?) → Promise<PrinterReading[]>

Accepts every readPrinter option plus:

| Option | Type | Default | Description | | ---------------- | --------- | ------- | ------------------------------------------ | | concurrency | number | 20 | Simultaneous reads. | | includeOffline | boolean | false | Include printers that did not respond. |

How it works

The library reads these standard OIDs from the Printer‑MIB (RFC 3805):

| Data | OID | MIB object | | --------------- | -------------------------------- | ------------------------- | | Page counter | 1.3.6.1.2.1.43.10.2.1.4.1.1 | prtMarkerLifeCount | | Serial number | 1.3.6.1.2.1.43.5.1.1.17.1 | prtGeneralSerialNumber | | Supplies table | 1.3.6.1.2.1.43.11.1.1 | prtMarkerSuppliesTable |

Toner percentage is derived as round(level / maxCapacity * 100). When a printer reports level == -3 ("there is a supply, but the exact level is unknown"), that value is preserved so the caller can show "OK" instead of a misleading number.

Notes on SNMP

• The default community public is the standard read‑only community shipped by most printers. If your network uses a different one, pass it via community.
• This library only reads data — it never writes to the device.

Development

npm install
npm test        # runs the unit tests (no printer required)

The parsing logic is covered by unit tests that run without any hardware.

License

MIT

🇧🇷 Resumo em português

Biblioteca Node.js que lê contador de páginas, número de série e nível de toner de qualquer impressora de rede usando o padrão Printer‑MIB (RFC 3805) — funciona com qualquer fabricante, sem código específico de marca. É tolerante a falhas: impressora desligada ou sem SNMP nunca quebra o seu app, apenas retorna { ok: false }.

const { readPrinter } = require('printer-snmp');
const dados = await readPrinter('192.168.0.50', { community: 'public' });
// → { ip, ok, counter, serial, toners: [{ desc, pct }], error, at }

Também varre faixas de IP (scanRange) e tem um comando de terminal (npx printer-snmp 192.168.0.50). Instale com npm install printer-snmp.