@homebridge-plugins/homebridge-printer 0.0.0-stage → 1.0.1-beta.0

package/lib/ipp.js

@@ -0,0 +1,352 @@
+/**
+ * Minimal, dependency-free IPP/2.0 client for Get-Printer-Attributes.
+ * Replaces @sealsystems/ipp, which is unmaintained.
+ */
+
+import { Buffer } from 'node:buffer'
+import dns from 'node:dns'
+import http from 'node:http'
+import https from 'node:https'
+
+import { resolveLocal } from './discovery.js'
+
+const localCache = new Map() // "printer.local" -> { ip, at }
+
+/**
+ * dns.lookup replacement: uses the normal system lookup, and for ".local"
+ * names falls back to asking the network directly (mDNS) if that fails.
+ */
+function lookupWithMdns(hostname, options, callback) {
+  if (typeof options === 'function') {
+    callback = options
+    options = {}
+  }
+  const reply = (ip) => {
+    if (options && options.all) {
+      callback(null, [
+        { address: ip, family: 4 },
+      ])
+    } else {
+      callback(null, ip, 4)
+    }
+  }
+  dns.lookup(hostname, options, (err, address, family) => {
+    if (!err || !/\.local\.?$/i.test(hostname)) {
+      return callback(err, address, family)
+    }
+    const hit = localCache.get(hostname.toLowerCase())
+    if (hit && Date.now() - hit.at < 10 * 60 * 1000) {
+      return reply(hit.ip)
+    }
+    resolveLocal(hostname).then(
+      (ip) => {
+        localCache.set(hostname.toLowerCase(), {
+          ip,
+          at: Date.now(),
+        })
+        reply(ip)
+      },
+      () => callback(err),
+    )
+  })
+}
+
+const TAG = {
+  OPERATION: 0x01,
+  JOB: 0x02,
+  END: 0x03,
+  PRINTER: 0x04,
+  UNSUPPORTED_GROUP: 0x05,
+  INTEGER: 0x21,
+  BOOLEAN: 0x22,
+  ENUM: 0x23,
+  TEXT_LANG: 0x35,
+  NAME_LANG: 0x36,
+  KEYWORD: 0x44,
+  URI: 0x45,
+  CHARSET: 0x47,
+  LANGUAGE: 0x48,
+}
+
+const PRINTER_STATES = { 3: 'idle', 4: 'processing', 5: 'stopped' }
+
+const STRING_TAGS = new Set([
+  0x41,
+  0x42,
+  0x44,
+  0x45,
+  0x46,
+  0x47,
+  0x48,
+  0x49,
+  0x4A,
+])
+
+let requestId = 1
+
+function encodeAttr(tag, name, value) {
+  const nameBuf = Buffer.from(name, 'utf8')
+  let valBuf
+  if (typeof value === 'number') {
+    valBuf = Buffer.alloc(4)
+    valBuf.writeInt32BE(value)
+  } else {
+    valBuf = Buffer.from(String(value), 'utf8')
+  }
+  const head = Buffer.alloc(3)
+  head.writeUInt8(tag, 0)
+  head.writeUInt16BE(nameBuf.length, 1)
+  const len = Buffer.alloc(2)
+  len.writeUInt16BE(valBuf.length)
+  return Buffer.concat([head, nameBuf, len, valBuf])
+}
+
+function buildGetPrinterAttributes(printerUri, requested) {
+  const parts = []
+  const header = Buffer.alloc(8)
+  header.writeUInt8(2, 0) // version 2.0
+  header.writeUInt8(0, 1)
+  header.writeUInt16BE(0x000B, 2) // Get-Printer-Attributes
+  header.writeInt32BE(requestId++ & 0x7FFFFFFF || 1, 4)
+  parts.push(header, Buffer.from([TAG.OPERATION]))
+  parts.push(encodeAttr(TAG.CHARSET, 'attributes-charset', 'utf-8'))
+  parts.push(encodeAttr(TAG.LANGUAGE, 'attributes-natural-language', 'en'))
+  parts.push(encodeAttr(TAG.URI, 'printer-uri', printerUri))
+  requested.forEach((attr, i) => {
+    parts.push(encodeAttr(TAG.KEYWORD, i === 0
+      ? 'requested-attributes'
+      : '', attr))
+  })
+  parts.push(Buffer.from([TAG.END]))
+  return Buffer.concat(parts)
+}
+
+function decodeValue(tag, buf) {
+  if (tag === TAG.INTEGER || tag === TAG.ENUM) {
+    return buf.length === 4
+      ? buf.readInt32BE(0)
+      : null
+  }
+  if (tag === TAG.BOOLEAN) {
+    return buf.length
+      ? buf.readUInt8(0) !== 0
+      : false
+  }
+  if (tag === TAG.TEXT_LANG || tag === TAG.NAME_LANG) {
+    const langLen = buf.readUInt16BE(0)
+    const textLen = buf.readUInt16BE(2 + langLen)
+    return buf.toString('utf8', 4 + langLen, 4 + langLen + textLen)
+  }
+  if (STRING_TAGS.has(tag)) {
+    return buf.toString('utf8')
+  }
+  if (tag >= 0x10 && tag <= 0x1F) {
+    return null
+  } // out-of-band (unknown, no-value, ...)
+  return buf // octetString, dateTime, resolution, ranges ... (raw)
+}
+
+/**
+ * Parse an IPP response. Returns { version, statusCode, requestId, groups: { operation, printer, ... } }
+ * Multi-valued attributes become arrays. Collections are skipped (not needed here).
+ */
+function parseResponse(buf) {
+  if (!buf || buf.length < 9) {
+    throw new Error('IPP response too short')
+  }
+  const res = {
+    version: `${buf[0]}.${buf[1]}`,
+    statusCode: buf.readUInt16BE(2),
+    requestId: buf.readInt32BE(4),
+    groups: {},
+  }
+  const groupNames = {
+    1: 'operation',
+    2: 'job',
+    4: 'printer',
+    5: 'unsupported',
+  }
+  let off = 8
+  let group = null
+  let lastName = null
+  let collectionDepth = 0
+
+  while (off < buf.length) {
+    const tag = buf[off++]
+    if (tag === TAG.END) {
+      break
+    }
+    if (tag < 0x10) {
+      const gname = groupNames[tag] || `group${tag}`
+      group = res.groups[gname] = res.groups[gname] || {}
+      lastName = null
+      continue
+    }
+    if (off + 2 > buf.length) {
+      break
+    }
+    const nameLen = buf.readUInt16BE(off)
+    off += 2
+    const name = buf.toString('utf8', off, off + nameLen)
+    off += nameLen
+    const valLen = buf.readUInt16BE(off)
+    off += 2
+    const raw = buf.subarray(off, off + valLen)
+    off += valLen
+
+    if (tag === 0x34) {
+      // begCollection
+      if (collectionDepth === 0 && name) {
+        lastName = name
+      }
+      collectionDepth++
+      continue
+    }
+    if (tag === 0x37) {
+      collectionDepth = Math.max(0, collectionDepth - 1)
+      continue
+    }
+    if (collectionDepth > 0 || !group) {
+      continue
+    }
+
+    const value = decodeValue(tag, raw)
+    if (name) {
+      lastName = name
+      group[name] = value
+    } else if (lastName) {
+      if (!Array.isArray(group[lastName])) {
+        group[lastName] = [group[lastName]]
+      }
+      group[lastName].push(value)
+    }
+  }
+  return res
+}
+
+/**
+ * Normalises whatever the user typed into an http(s) endpoint + ipp printer-uri.
+ * Accepts: 192.168.1.20 | HPF92BAB.local | ipp://host/ipp/print | ipps://host | http://host:631/ipp/printer
+ */
+function normaliseAddress(address) {
+  let a = String(address || '').trim()
+  if (!/^[a-z]+:\/\//i.test(a)) {
+    a = `ipp://${a}`
+  }
+  const u = new URL(a)
+  const scheme = u.protocol.replace(':', '').toLowerCase()
+  const secure = scheme === 'ipps' || scheme === 'https'
+  const port = u.port
+    ? Number(u.port)
+    : scheme === 'http'
+      ? 80
+      : scheme === 'https'
+        ? 443
+        : 631
+  const explicitPath = u.pathname && u.pathname !== '/'
+    ? u.pathname
+    : null
+  return {
+    host: u.hostname,
+    port,
+    secure,
+    explicitPath,
+  }
+}
+
+class IppPrinter {
+  /**
+   * @param {string} address
+   * @param {{timeout?: number}} [opts]
+   */
+  constructor(address, opts = {}) {
+    this.target = normaliseAddress(address)
+    this.timeout = opts.timeout || 8000
+    // HP printers use /ipp/print; some older models and CUPS use /ipp/printer or /ipp
+    this.paths = this.target.explicitPath
+      ? [this.target.explicitPath]
+      : ['/ipp/print', '/ipp/printer', '/ipp']
+    this.resolvedPath = this.target.explicitPath || null
+  }
+
+  printerUri(path) {
+    const t = this.target
+    return `${t.secure ? 'ipps' : 'ipp'}://${t.host.includes(':')
+      ? `[${t.host}]`
+      : t.host}:${t.port}${path}`
+  }
+
+  post(path, body) {
+    const t = this.target
+    const lib = t.secure ? https : http
+    return new Promise((resolve, reject) => {
+      const req = lib.request(
+        {
+          host: t.host,
+          port: t.port,
+          path,
+          method: 'POST',
+          headers: { 'Content-Type': 'application/ipp', 'Content-Length': body.length },
+          timeout: this.timeout,
+          lookup: lookupWithMdns,
+          // Printers ship self-signed certificates
+          rejectUnauthorized: false,
+        },
+        (res) => {
+          const chunks = []
+          res.on('data', c => chunks.push(c))
+          res.on('end', () => {
+            if (res.statusCode === 426 && !t.secure) {
+              // "Upgrade Required" - printer insists on TLS
+              t.secure = true
+              return this.post(path, body).then(resolve, reject)
+            }
+            if (res.statusCode !== 200) {
+              const err = new Error(`HTTP ${res.statusCode} from printer at ${path}`)
+              err.httpStatus = res.statusCode
+              return reject(err)
+            }
+            resolve(Buffer.concat(chunks))
+          })
+          res.on('error', reject)
+        },
+      )
+      req.on('timeout', () => {
+        const err = new Error('Request timed out')
+        err.code = 'ETIMEDOUT'
+        req.destroy(err)
+      })
+      req.on('error', reject)
+      req.end(body)
+    })
+  }
+
+  async getAttributes(requested) {
+    const candidates = this.resolvedPath
+      ? [this.resolvedPath]
+      : this.paths
+    let lastErr
+    for (const path of candidates) {
+      try {
+        const body = buildGetPrinterAttributes(this.printerUri(path), requested)
+        const res = parseResponse(await this.post(path, body))
+        if (res.statusCode > 0x00FF) {
+          const err = new Error(`IPP status 0x${res.statusCode.toString(16).padStart(4, '0')}`)
+          err.ippStatus = res.statusCode
+          throw err
+        }
+        this.resolvedPath = path
+        return res.groups.printer || {}
+      } catch (err) {
+        lastErr = err
+        // Network errors won't be fixed by trying another path
+        if (err.code && !err.httpStatus) {
+          throw err
+        }
+      }
+    }
+    throw lastErr
+  }
+}
+
+export { buildGetPrinterAttributes, IppPrinter, lookupWithMdns, normaliseAddress, parseResponse, PRINTER_STATES }

package/lib/platform.js

@@ -0,0 +1,335 @@
+import fs from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+import { OnlineSwitchAccessory, PrinterAccessory, PrintingSwitchAccessory } from './accessories.js'
+import { createCharacteristics } from './characteristics.js'
+import { DashboardServer } from './dashboard-server.js'
+import { MatterEnergyPublisher, normaliseEnergyConfig } from './energy.js'
+import eveService from './fakegato/fakegato-history.js'
+import { normaliseAddress } from './ipp.js'
+import { PrinterPoller } from './poller.js'
+
+const require = createRequire(import.meta.url)
+const pkg = require('../package.json')
+
+const PLUGIN_NAME = '@homebridge-plugins/homebridge-printer'
+const PLATFORM_NAME = 'Printer'
+
+class PrinterPlatform {
+  constructor(log, config, api) {
+    this.log = log
+    this.config = config || {}
+    this.api = api
+    this.version = pkg.version
+    this.cached = new Map() // UUID -> PlatformAccessory
+    this.handlers = []
+    this.pollers = new Map() // printer id -> PrinterPoller
+    this.devices = this.normaliseConfig(this.config)
+    this.customChars = createCharacteristics(api.hap)
+    this.pluginName = PLUGIN_NAME
+    this.platformName = PLATFORM_NAME
+    this.energy = new MatterEnergyPublisher(this)
+
+    if (this.config.debug) {
+      // Show debug output without having to start Homebridge with -D
+      this.log = {
+        info: (...a) => log.info(...a),
+        warn: (...a) => log.warn(...a),
+        error: (...a) => log.error(...a),
+        success: (...a) => (log.success || log.info)(...a),
+        debug: (...a) => log.info('[debug]', ...a),
+      }
+    }
+
+    api.on('didFinishLaunching', () => this.didFinishLaunching())
+    api.on('shutdown', () => this.shutdown())
+  }
+
+  normaliseConfig(config) {
+    const list = Array.isArray(config.printers)
+      ? config.printers
+      : Array.isArray(config.printer)
+        ? config.printer
+        : []
+    const seen = new Set()
+    const out = []
+    list.forEach((p, i) => {
+      if (!p || !String(p.address || '').trim()) {
+        this.log.warn(`Printer ${i + 1} has no IP address or .local name yet - add one in the plugin settings.`)
+        return
+      }
+      const address = String(p.address).trim()
+      try {
+        normaliseAddress(address)
+      } catch {
+        this.log.warn(`Printer ${i + 1}: "${address}" is not an address the plugin can use - check it in the plugin settings.`)
+        return
+      }
+      // Name is optional: default to "Printer", "Printer 2", ...
+      let name = String(p.name || '').trim()
+      if (!name) {
+        name = 'Printer'
+        for (let n = 2; seen.has(name); n++) {
+          name = `Printer ${n}`
+        }
+      }
+      if (seen.has(name)) {
+        this.log.warn(
+          `${name}: two printers have the same name - give one of them a different name. Skipping the second.`,
+        )
+        return
+      }
+      // the accessories' ids come from the name, so "Office" and "Office:online" would clash
+      const seeds = [name, `${name}:online`, `${name}:printing`]
+      if (seeds.some(seed => seen.has(`seed:${seed}`))) {
+        this.log.warn(`${name}: this name clashes with another printer's - give it a different name. Skipping it.`)
+        return
+      }
+      seen.add(name)
+      seeds.forEach(seed => seen.add(`seed:${seed}`))
+      // Older configs used one "switchType" setting; NONE / CHARACTERISTIC meant "no switch"
+      const legacyType = String(p.switchType || '').toUpperCase()
+      const legacyNoSwitch = legacyType === 'NONE' || legacyType === 'CHARACTERISTIC'
+      out.push({
+        id: this.api.hap.uuid.generate(`hp-printer:${name}`),
+        name,
+        printingSwitch: typeof p.printingSwitch === 'boolean'
+          ? p.printingSwitch
+          : !legacyNoSwitch,
+        printingName: `${name} Printing`,
+        onlineSwitch: typeof p.onlineSwitch === 'boolean'
+          ? p.onlineSwitch
+          : !legacyNoSwitch,
+        onlineName: `${name} Online`,
+        onlineCharacteristic: legacyType === 'CHARACTERISTIC',
+        energy: normaliseEnergyConfig(p),
+        address,
+        polling:
+          Number.isFinite(Number(p.polling)) && Number(p.polling) > 0
+            ? Math.max(2, Math.round(Number(p.polling)))
+            : 5,
+        marker: p.marker !== false,
+        history: p.history !== false,
+        lowInkThreshold:
+          Number.isFinite(Number(p.lowInkThreshold)) && p.lowInkThreshold !== ''
+            ? Math.min(99, Math.max(0, Number(p.lowInkThreshold)))
+            : 10,
+        manufacturer: p.manufacturer,
+        model: p.model,
+        serialNumber: p.serialNumber,
+      })
+    })
+    return out
+  }
+
+  /** Homebridge 2 calls this for every Matter accessory restored from cache. */
+  configureMatterAccessory(accessory) {
+    this.energy.configureMatterAccessory(accessory)
+  }
+
+  /** Homebridge calls this for every accessory restored from cache. */
+  configureAccessory(accessory) {
+    this.cached.set(accessory.UUID, accessory)
+  }
+
+  getFakeGato() {
+    if (this._fakegato !== undefined) {
+      return this._fakegato
+    }
+    try {
+      this._fakegato = eveService(this.api)
+    } catch (err) {
+      this.log.warn(`Eve history unavailable: ${err.message}`)
+      this._fakegato = null
+    }
+    return this._fakegato
+  }
+
+  getOrCreate(uuid, name, toRegister) {
+    let acc = this.cached.get(uuid)
+    if (!acc) {
+      acc = new this.api.platformAccessory(name, uuid)
+      toRegister.push(acc)
+      this.log.info(`Adding accessory: ${name}`)
+    }
+    acc.context.hpPrinter = true
+    return acc
+  }
+
+  didFinishLaunching() {
+    const wanted = new Set()
+    const toRegister = []
+
+    // "Matter only": publish the printer over Matter alone, no HomeKit accessories.
+    // Only honoured when Matter is actually available, so nothing disappears by accident.
+    const matterReason = this.energy.unavailableReason()
+    const matterOnly = this.config.matterOnly === true && !matterReason
+    if (this.config.matterOnly === true && matterReason) {
+      this.log.warn(
+        `"Matter only" is turned on, but ${matterReason}. Keeping the HomeKit accessories until Matter is available.`,
+      )
+    } else if (matterOnly) {
+      this.log.info(
+        '"Matter only" is on: the printer is published over Matter only (no HomeKit accessories). Ink levels are shown on the dashboard.',
+      )
+    }
+
+    for (const device of this.devices) {
+      const poller = new PrinterPoller(device, this.log)
+      this.pollers.set(device.id, poller)
+
+      if (matterOnly) {
+        // No HomeKit accessory to keep the last-known ink levels in, so keep them in a file
+        this.seedFromFile(device, poller)
+        continue
+      }
+
+      // "<name>" accessory: printing sensor, fault/online status and ink tiles
+      const statusUuid = device.id
+      wanted.add(statusUuid)
+      const acc = this.getOrCreate(statusUuid, device.name, toRegister)
+      // Seed with the last known state so ink levels survive restarts while the printer is off
+      const last = acc.context.lastState
+      if (last && Array.isArray(last.markers)) {
+        Object.assign(poller.state, {
+          markers: last.markers,
+          model: device.model || last.model || null,
+          lastSeen: last.lastSeen || null,
+        })
+      }
+      poller.on('update', (s) => {
+        acc.context.lastState = { markers: s.markers, model: s.model, lastSeen: s.lastSeen }
+      })
+      this.handlers.push(new PrinterAccessory(this, acc, device, poller))
+
+      // Switch 1: "<name> Online" - on while the printer is switched on and reachable.
+      // With Matter, this is one combined "<name> Online" outlet that also carries the
+      // energy reading (published by MatterEnergyPublisher), so no separate HomeKit switch.
+      device.onlineViaMatter = device.onlineSwitch && device.energy.enabled && !this.energy.unavailableReason()
+      if (device.onlineSwitch && !device.onlineViaMatter) {
+        const uuid = this.api.hap.uuid.generate(`hp-printer:${device.name}:online`)
+        wanted.add(uuid)
+        const sw = this.getOrCreate(uuid, device.onlineName, toRegister)
+        this.handlers.push(new OnlineSwitchAccessory(this, sw, device, poller))
+      }
+
+      // Switch 2: "<name> Printing" - on only while a job is printing
+      if (device.printingSwitch) {
+        const uuid = this.api.hap.uuid.generate(`hp-printer:${device.name}:printing`)
+        wanted.add(uuid)
+        const sw = this.getOrCreate(uuid, device.printingName, toRegister)
+        this.handlers.push(new PrintingSwitchAccessory(this, sw, device, poller))
+      }
+    }
+
+    if (toRegister.length) {
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, toRegister)
+    }
+
+    const stale = [
+      ...this.cached.values(),
+    ].filter(a => !wanted.has(a.UUID))
+    if (stale.length) {
+      stale.forEach(a => this.log.info(`Removing accessory: ${a.displayName}`))
+      this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, stale)
+    }
+
+    for (const poller of this.pollers.values()) {
+      poller.start()
+    }
+
+    this.energy.start(this.devices, this.pollers, { matterOnly }).catch(err => this.log.warn(`Matter: ${err.message}`))
+
+    const dash = this.config.dashboard || {}
+    if (dash.enabled !== false && this.devices.length) {
+      this.dashboard = new DashboardServer({
+        port: Number(dash.port) || 8587,
+        host: dash.host || '0.0.0.0',
+        log: this.log,
+        getStatus: () => this.getStatus(),
+        onRefresh: () => Promise.all([
+          ...this.pollers.values(),
+        ].map(p => p.poll())),
+      })
+      for (const poller of this.pollers.values()) {
+        poller.on('update', () => this.dashboard.broadcast())
+      }
+      this.dashboard.start()
+    }
+
+    if (!this.devices.length) {
+      this.log.warn(
+        'No printers configured yet. Open Plugins → Printer → Settings and enter your printer\'s IP address or .local name.',
+      )
+    }
+  }
+
+  /** Last-known ink levels for Matter-only mode, kept in <storage>/hp-printer/state-<id>.json */
+  seedFromFile(device, poller) {
+    const file = path.join(this.api.user.storagePath(), 'hp-printer', `state-${device.id}.json`)
+    try {
+      const last = JSON.parse(fs.readFileSync(file, 'utf8'))
+      if (last && Array.isArray(last.markers)) {
+        Object.assign(poller.state, {
+          markers: last.markers,
+          model: device.model || last.model || null,
+          lastSeen: last.lastSeen || null,
+        })
+      }
+    } catch (_) {
+      /* first run */
+    }
+    let timer = null
+    poller.on('update', (st) => {
+      if (timer) {
+        return
+      }
+      timer = setTimeout(() => {
+        timer = null
+        try {
+          fs.mkdirSync(path.dirname(file), { recursive: true })
+          // through a temporary file, so a power cut can't leave it half written
+          fs.writeFileSync(`${file}.tmp`, JSON.stringify({ markers: st.markers, model: st.model, lastSeen: st.lastSeen }))
+          fs.renameSync(`${file}.tmp`, file)
+        } catch (err) {
+          this.log.debug(`${device.name}: could not save state (${err.message})`)
+        }
+      }, 2000)
+      if (timer.unref) {
+        timer.unref()
+      }
+    })
+  }
+
+  getStatus() {
+    return {
+      plugin: PLUGIN_NAME,
+      version: this.version,
+      generated: new Date().toISOString(),
+      printers: [
+        ...this.pollers.values(),
+      ].map((p) => {
+        const energy = this.energy.status()[p.state.id]
+        return energy
+          ? { ...p.state, energy }
+          : p.state
+      }),
+    }
+  }
+
+  shutdown() {
+    this.energy.shutdown()
+    for (const p of this.pollers.values()) {
+      p.stop()
+    }
+    for (const h of this.handlers) {
+      h.destroy()
+    }
+    if (this.dashboard) {
+      this.dashboard.stop()
+    }
+  }
+}
+
+export { PLATFORM_NAME, PLUGIN_NAME, PrinterPlatform }