@homebridge-plugins/homebridge-printer 0.0.0-stage → 1.0.0

package/lib/poller.js

@@ -0,0 +1,187 @@
+import { EventEmitter } from 'node:events'
+
+import { IppPrinter, PRINTER_STATES } from './ipp.js'
+
+const REQUESTED = [
+  'printer-state',
+  'printer-state-reasons',
+  'printer-state-message',
+  'printer-make-and-model',
+  'printer-info',
+  'printer-is-accepting-jobs',
+  'queued-job-count',
+  'marker-names',
+  'marker-levels',
+  'marker-low-levels',
+  'marker-high-levels',
+  'marker-colors',
+  'marker-types',
+]
+
+const NETWORK_CODES = new Set([
+  'ECONNREFUSED',
+  'ETIMEDOUT',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'ECONNRESET',
+  'ECONNABORTED',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'EBUSY',
+  'EPIPE',
+])
+
+function arr(v) {
+  return v === undefined || v === null
+    ? []
+    : Array.isArray(v)
+      ? v
+      : [v]
+}
+
+function parseColors(c) {
+  // HP tri-color cartridges report e.g. "#00FFFF#FF00FF#FFFF00"
+  const m = String(c || '').match(/#[0-9a-f]{6}/gi)
+  return m
+    ? m.map(x => x.toUpperCase())
+    : []
+}
+
+function parseMarkers(attrs) {
+  const names = arr(attrs['marker-names'])
+  const levels = arr(attrs['marker-levels'])
+  const lows = arr(attrs['marker-low-levels'])
+  const highs = arr(attrs['marker-high-levels'])
+  const colors = arr(attrs['marker-colors'])
+  const types = arr(attrs['marker-types'])
+  const count = Math.max(names.length, levels.length)
+  const markers = []
+  for (let i = 0; i < count; i++) {
+    const raw = typeof levels[i] === 'number'
+      ? levels[i]
+      : -1
+    const high = typeof highs[i] === 'number' && highs[i] > 0
+      ? highs[i]
+      : 100
+    // -1 = unavailable, -2 = unknown, -3 = "some remaining" (RFC 3805 / PWG 5100.13)
+    const level = raw >= 0
+      ? Math.max(0, Math.min(100, Math.round((raw / high) * 100)))
+      : null
+    markers.push({
+      index: i,
+      name: names[i] || `Supply ${i + 1}`,
+      level,
+      someRemaining: raw === -3,
+      low: typeof lows[i] === 'number' && lows[i] >= 0
+        ? lows[i]
+        : null,
+      colors: parseColors(colors[i]),
+      type: types[i] || null,
+    })
+  }
+  return markers
+}
+
+class PrinterPoller extends EventEmitter {
+  constructor(config, log) {
+    super()
+    this.config = config
+    this.log = log
+    this.client = new IppPrinter(config.address, {
+      timeout: Math.min(15000, Math.max(3000, config.polling * 800)),
+    })
+    this.timer = null
+    this.stopped = false
+    this.state = {
+      id: config.id,
+      name: config.name,
+      address: config.address,
+      online: false,
+      status: 'unknown',
+      reasons: [],
+      message: null,
+      model: config.model || null,
+      queuedJobs: 0,
+      printing: false,
+      markers: [],
+      lowThreshold: config.lowInkThreshold,
+      lastUpdated: null,
+      lastSeen: null,
+      error: null,
+    }
+  }
+
+  start() {
+    this.stopped = false
+    this.poll()
+  }
+
+  stop() {
+    this.stopped = true
+    clearTimeout(this.timer)
+  }
+
+  async poll() {
+    clearTimeout(this.timer)
+    const prev = JSON.stringify(this.state)
+    try {
+      const a = await this.client.getAttributes(REQUESTED)
+      const reasons = arr(a['printer-state-reasons']).filter(r => r && r !== 'none')
+      const markers = parseMarkers(a)
+      Object.assign(this.state, {
+        online: true,
+        status: PRINTER_STATES[a['printer-state']] || 'unknown',
+        reasons,
+        message: a['printer-state-message'] || null,
+        model: this.config.model || a['printer-make-and-model'] || this.state.model,
+        queuedJobs: typeof a['queued-job-count'] === 'number'
+          ? a['queued-job-count']
+          : 0,
+        // Printing = the printer is busy AND has a job. Printers also report "processing"
+        // while warming up or cleaning heads; those have no job, so they don't count.
+        printing: a['printer-state'] === 4 && (typeof a['queued-job-count'] !== 'number' || a['queued-job-count'] > 0),
+        markers: markers.length ? markers : this.state.markers,
+        lastUpdated: new Date().toISOString(),
+        lastSeen: new Date().toISOString(),
+        error: null,
+      })
+      this.log.debug(`${this.config.name}: ${this.state.status} ${JSON.stringify(markers.map(m => [m.name, m.level]))}`)
+    } catch (err) {
+      const network = err && NETWORK_CODES.has(err.code)
+      if (network) {
+        this.log.debug(`${this.config.name}: printer not reachable (${err.code})`)
+      } else if (this.state.error !== err.message) {
+        this.log.warn(`${this.config.name}: ${err.message}`)
+      }
+      Object.assign(this.state, {
+        online: false,
+        status: 'offline',
+        printing: false,
+        lastUpdated: new Date().toISOString(),
+        error: network ? 'Printer not reachable' : err.message,
+      })
+    }
+    if (JSON.stringify(this.state) !== prev) {
+      try {
+        this.emit('update', this.state)
+      } catch (err) {
+        this.log.warn(`${this.config.name}: ${err.message}`)
+      }
+    }
+    if (!this.stopped) {
+      // a refresh from the dashboard can run while a poll is waiting: keep to one timer
+      clearTimeout(this.timer)
+      // Check more often while a job is printing, so the switch turns off promptly when it finishes
+      const secs
+        = this.state.status === 'processing' || this.state.printing
+          ? Math.min(this.config.polling, 2)
+          : this.config.polling
+      this.timer = setTimeout(() => this.poll(), secs * 1000)
+      if (this.timer.unref) {
+        this.timer.unref()
+      }
+    }
+  }
+}
+
+export { parseMarkers, PrinterPoller, REQUESTED }

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@homebridge-plugins/homebridge-printer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "alias": "Printer",
+  "displayName": "Homebridge Printer",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Homebridge plugin to show HP and other AirPrint (IPP) printers in Apple Home, with ink levels and a live dashboard.",
+  "author": "homebridge-plugins",
+  "license": "MIT",
+  "homepage": "https://github.com/homebridge-plugins/homebridge-printer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/homebridge-plugins/homebridge-printer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/homebridge-plugins/homebridge-printer/issues"
+  },
+  "keywords": [
+    "homebridge",
+    "homebridge-plugin",
+    "supports-hap",
+    "supports-matter",
+    "homebridge-printer",
+    "homekit",
+    "printer",
+    "ipp",
+    "airprint",
+    "hp",
+    "ink",
+    "energy"
+  ],
+  "main": "lib/index.js",
+  "engines": {
+    "homebridge": "^1.11.4 || ^2.0.0",
+    "node": "^22.12.0 || ^24.0.0 || ^26.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings=0",
+    "lint:fix": "npm run lint -- --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test-coverage": "npm run test -- --coverage",
+    "changelog:sync": "node .github/scripts/sync-changelog.mjs"
+  },
+  "dependencies": {
+    "@homebridge/plugin-ui-utils": "^2.2.7"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^10.0.0",
+    "@vitest/coverage-v8": "^5.1.0",
+    "ajv": "^8.20.0",
+    "homebridge": "^2.5.0",
+    "vitest": "^5.1.0"
+  }
+}