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

package/lib/accessories.js

@@ -0,0 +1,333 @@
+const NOW_EPOCH_OFFSET = 978307200 // seconds between 1970-01-01 and 2001-01-01 (Eve epoch)
+
+class PrinterAccessory {
+  /**
+   * @param {import('./platform').PrinterPlatform} platform
+   * @param {*} accessory  PlatformAccessory
+   * @param {*} device     normalised printer config
+   * @param {import('./poller').PrinterPoller} poller
+   */
+  constructor(platform, accessory, device, poller) {
+    this.platform = platform
+    this.api = platform.api
+    this.log = platform.log
+    this.hap = platform.api.hap
+    this.C = platform.customChars
+    this.accessory = accessory
+    this.device = device
+    this.poller = poller
+    this.history = null
+
+    const { Service, Characteristic } = this.hap
+
+    accessory.on('identify', () => this.log.info(`${accessory.displayName}: identify requested`))
+
+    accessory
+      .getService(Service.AccessoryInformation)
+      .setCharacteristic(Characteristic.Manufacturer, device.manufacturer || 'HP')
+      .setCharacteristic(Characteristic.Model, device.model || 'Printer')
+      .setCharacteristic(Characteristic.SerialNumber, device.serialNumber || device.id.slice(0, 12))
+      .setCharacteristic(Characteristic.FirmwareRevision, platform.version)
+
+    // ----- "Printing" contact sensor -------------------------------------------------------
+    this.contact
+      = accessory.getServiceById(Service.ContactSensor, 'contact')
+        || accessory.getService(Service.ContactSensor)
+        || accessory.addService(Service.ContactSensor, device.name, 'contact')
+    this.ensureName(this.contact, device.name)
+
+    for (const c of [Characteristic.StatusActive, Characteristic.StatusFault]) {
+      if (!this.contact.testCharacteristic(c)) {
+        this.contact.addCharacteristic(c)
+      }
+    }
+
+    // Online state as a characteristic (visible in Eve / Controller apps)
+    if (device.onlineCharacteristic) {
+      if (!this.contact.testCharacteristic(this.C.PrinterOnline)) {
+        this.contact.addCharacteristic(this.C.PrinterOnline)
+      }
+    } else if (this.contact.testCharacteristic(this.C.PrinterOnline)) {
+      this.contact.removeCharacteristic(this.contact.getCharacteristic(this.C.PrinterOnline))
+    }
+
+    this.setupHistory()
+
+    // ----- Ink / toner levels ----------------------------------------------------------------
+    if (!device.marker) {
+      this.removeMarkerServices([])
+    }
+
+    poller.on('update', state => this.update(state))
+  }
+
+  ensureName(service, name) {
+    const { Characteristic } = this.hap
+    service.setCharacteristic(Characteristic.Name, name)
+    // iOS 16+ uses ConfiguredName for service labels inside grouped accessories
+    if (Characteristic.ConfiguredName) {
+      if (!service.testCharacteristic(Characteristic.ConfiguredName)) {
+        service.addCharacteristic(Characteristic.ConfiguredName)
+      }
+      service.updateCharacteristic(Characteristic.ConfiguredName, name)
+    }
+  }
+
+  setupHistory() {
+    const { Characteristic } = this.hap
+    const C = this.C
+    const eveChars = [
+      C.EveLastActivation,
+      C.EveTimesOpened,
+      C.EveOpenDuration,
+      C.EveClosedDuration,
+      C.EveResetTotal,
+    ]
+
+    const FakeGato = this.platform.getFakeGato()
+    if (!this.device.history || !FakeGato) {
+      for (const c of eveChars) {
+        if (this.contact.testCharacteristic(c)) {
+          this.contact.removeCharacteristic(this.contact.getCharacteristic(c))
+        }
+      }
+      return
+    }
+
+    for (const c of eveChars) {
+      if (!this.contact.testCharacteristic(c)) {
+        this.contact.addCharacteristic(c)
+      }
+    }
+    const ctx = this.accessory.context
+    ctx.timesPrinted = ctx.timesPrinted || 0
+    this.contact.updateCharacteristic(C.EveTimesOpened, ctx.timesPrinted)
+
+    this.contact.getCharacteristic(C.EveResetTotal).onSet(() => {
+      ctx.timesPrinted = 0
+      this.contact.updateCharacteristic(C.EveTimesOpened, 0)
+      this.contact.updateCharacteristic(C.EveResetTotal, Math.round(Date.now() / 1000) - NOW_EPOCH_OFFSET)
+      this.log.info(`${this.accessory.displayName}: Eve history counters reset`)
+    })
+
+    try {
+      // the org's copy of fakegato, which also re-sends the last state every 10 minutes
+      this.history = new FakeGato('door', this.accessory, {
+        log: () => {},
+      })
+    } catch (err) {
+      this.log.warn(`${this.accessory.displayName}: Eve history disabled (${err.message})`)
+      this.history = null
+      return
+    }
+
+    this.contact.getCharacteristic(Characteristic.ContactSensorState).on('change', ({ oldValue, newValue }) => {
+      if (oldValue === newValue || !this.history) {
+        return
+      }
+      const now = Math.round(Date.now() / 1000)
+      const initial = Number(this.history.getInitialTime())
+      const since = Number.isFinite(initial) && initial > 0
+        ? Math.max(0, now - initial)
+        : null
+      if (newValue) {
+        ctx.timesPrinted += 1
+        this.contact.updateCharacteristic(C.EveTimesOpened, ctx.timesPrinted)
+        if (since !== null) {
+          this.contact.updateCharacteristic(C.EveLastActivation, since)
+        }
+      }
+      this.history.addEntry({
+        time: now,
+        status: newValue ? 1 : 0,
+      })
+    })
+  }
+
+  removeMarkerServices(keepSubtypes) {
+    const { Service } = this.hap
+    const stale = this.accessory.services.filter(
+      s => s.UUID === Service.FilterMaintenance.UUID && !keepSubtypes.includes(s.subtype),
+    )
+    for (const s of stale) {
+      this.log.info(`${this.accessory.displayName}: removing ink service "${s.displayName}"`)
+      this.accessory.removeService(s)
+    }
+    return stale.length > 0
+  }
+
+  syncMarkerServices(markers) {
+    const { Service, Characteristic } = this.hap
+    let changed = false
+    const wanted = markers.map(m => `marker-${m.index}`)
+    changed = this.removeMarkerServices(wanted) || changed
+
+    for (const m of markers) {
+      const subtype = `marker-${m.index}`
+      let svc = this.accessory.getServiceById(Service.FilterMaintenance, subtype)
+      if (!svc) {
+        this.log.info(`${this.accessory.displayName}: adding ink service "${m.name}"`)
+        svc = this.accessory.addService(Service.FilterMaintenance, m.name, subtype)
+        changed = true
+      }
+      if (!svc.testCharacteristic(Characteristic.FilterLifeLevel)) {
+        svc.addCharacteristic(Characteristic.FilterLifeLevel)
+      }
+      if (svc.displayName !== m.name || !svc._hpNamed) {
+        this.ensureName(svc, m.name)
+        svc._hpNamed = true
+      }
+
+      const level = m.level !== null
+        ? m.level
+        : m.someRemaining ? 50 : 0
+      const threshold
+        = m.low !== null && m.low > 0
+          ? Math.max(m.low, this.device.lowInkThreshold)
+          : this.device.lowInkThreshold
+      const low = m.level !== null && m.level <= threshold
+      svc.updateCharacteristic(Characteristic.FilterLifeLevel, level)
+      svc.updateCharacteristic(
+        Characteristic.FilterChangeIndication,
+        low ? Characteristic.FilterChangeIndication.CHANGE_FILTER : Characteristic.FilterChangeIndication.FILTER_OK,
+      )
+    }
+    if (changed) {
+      this.api.updatePlatformAccessories([this.accessory])
+    }
+  }
+
+  update(state) {
+    const { Characteristic } = this.hap
+    const printing = state.printing
+    const fault = !state.online || state.status === 'stopped' || state.reasons.some(r => r.endsWith('-error'))
+
+    this.contact.updateCharacteristic(
+      Characteristic.ContactSensorState,
+      printing
+        ? Characteristic.ContactSensorState.CONTACT_NOT_DETECTED
+        : Characteristic.ContactSensorState.CONTACT_DETECTED,
+    )
+    this.contact.updateCharacteristic(Characteristic.StatusActive, state.online)
+    this.contact.updateCharacteristic(
+      Characteristic.StatusFault,
+      fault ? Characteristic.StatusFault.GENERAL_FAULT : Characteristic.StatusFault.NO_FAULT,
+    )
+    if (this.device.onlineCharacteristic) {
+      this.contact.updateCharacteristic(this.C.PrinterOnline, state.online)
+    }
+
+    if (this.device.marker && state.markers.length) {
+      this.syncMarkerServices(state.markers)
+    }
+  }
+
+  destroy() {
+    clearInterval(this.historyTimer)
+  }
+}
+
+/**
+ * "Printer Printing" switch: ON only while the printer is printing a job, OFF otherwise
+ * (idle, asleep or switched off). It reports state only - tapping it in the
+ * Home app snaps back to the real value, because a printer can't be started
+ * or stopped over the network.
+ */
+class PrintingSwitchAccessory {
+  constructor(platform, accessory, device, poller) {
+    const { Service, Characteristic } = platform.api.hap
+    this.accessory = accessory
+
+    accessory
+      .getService(Service.AccessoryInformation)
+      .setCharacteristic(Characteristic.Manufacturer, device.manufacturer || 'HP')
+      .setCharacteristic(Characteristic.Model, device.model || 'Printer')
+      .setCharacteristic(Characteristic.SerialNumber, `${device.serialNumber || device.id.slice(0, 12)}-P`)
+      .setCharacteristic(Characteristic.FirmwareRevision, platform.version)
+
+    const name = device.printingName
+    this.service
+      = accessory.getServiceById(Service.Switch, 'printing') || accessory.addService(Service.Switch, name, 'printing')
+    this.service.setCharacteristic(Characteristic.Name, name)
+    if (Characteristic.ConfiguredName) {
+      if (!this.service.testCharacteristic(Characteristic.ConfiguredName)) {
+        this.service.addCharacteristic(Characteristic.ConfiguredName)
+      }
+      this.service.updateCharacteristic(Characteristic.ConfiguredName, name)
+    }
+
+    const isPrinting = state => !!state.printing
+    const on = this.service.getCharacteristic(Characteristic.On)
+    on.onGet(() => isPrinting(poller.state))
+    on.onSet(() => {
+      setTimeout(() => on.updateValue(isPrinting(poller.state)), 300)
+    })
+
+    let last = null
+    poller.on('update', (state) => {
+      const now = isPrinting(state)
+      if (now !== last) {
+        if (last !== null) {
+          platform.log.info(`${name}: ${now ? 'printing started' : 'printing finished'}`)
+        }
+        last = now
+      }
+      on.updateValue(now)
+    })
+  }
+
+  destroy() {}
+}
+
+/**
+ * "Printer Online" switch: ON while the printer is switched on and answering on the
+ * network, OFF when it is off, asleep or disconnected. Reports state only.
+ */
+class OnlineSwitchAccessory {
+  constructor(platform, accessory, device, poller) {
+    const { Service, Characteristic } = platform.api.hap
+    this.accessory = accessory
+
+    accessory
+      .getService(Service.AccessoryInformation)
+      .setCharacteristic(Characteristic.Manufacturer, device.manufacturer || 'HP')
+      .setCharacteristic(Characteristic.Model, device.model || 'Printer')
+      .setCharacteristic(Characteristic.SerialNumber, `${device.serialNumber || device.id.slice(0, 12)}-S`)
+      .setCharacteristic(Characteristic.FirmwareRevision, platform.version)
+
+    const name = device.onlineName
+    this.service
+      = accessory.getServiceById(Service.Switch, 'online')
+        || accessory.getService(Service.Switch)
+        || accessory.addService(Service.Switch, name, 'online')
+    this.service.setCharacteristic(Characteristic.Name, name)
+    if (Characteristic.ConfiguredName) {
+      if (!this.service.testCharacteristic(Characteristic.ConfiguredName)) {
+        this.service.addCharacteristic(Characteristic.ConfiguredName)
+      }
+      this.service.updateCharacteristic(Characteristic.ConfiguredName, name)
+    }
+
+    const on = this.service.getCharacteristic(Characteristic.On)
+    on.onGet(() => !!poller.state.online)
+    on.onSet(() => {
+      setTimeout(() => on.updateValue(!!poller.state.online), 300)
+    })
+
+    let last = null
+    poller.on('update', (state) => {
+      const now = !!state.online
+      if (now !== last) {
+        if (last !== null) {
+          platform.log.info(`${name}: printer is ${now ? 'on' : 'off / unreachable'}`)
+        }
+        last = now
+      }
+      on.updateValue(now)
+    })
+  }
+
+  destroy() {}
+}
+
+export { OnlineSwitchAccessory, PrinterAccessory, PrintingSwitchAccessory }

package/lib/characteristics.js

@@ -0,0 +1,95 @@
+/**
+ * Custom / Eve characteristics written as ES classes.
+ *
+ * The original plugin used `Characteristic.call(this, ...)` + util.inherits and
+ * `Characteristic.Formats/Perms/Units`. HAP-NodeJS 1.x (Homebridge 2) turned
+ * Characteristic/Service into real classes (so `.call` throws
+ * "Class constructor ... cannot be invoked without 'new'") and removed the
+ * static Formats/Perms/Units aliases. Everything here uses `class extends`
+ * and `hap.Formats/Perms/Units`, which work on Homebridge 1.6+ and 2.x.
+ */
+
+const DEFS = [
+  // name, displayName, UUID, format, unit, perms
+  [
+    'PrinterOnline',
+    'Printer Online',
+    '65ede48d-5d4e-4408-8a6f-feaa57b7320e',
+    'BOOL',
+    null,
+    ['PAIRED_READ', 'NOTIFY'],
+  ],
+  [
+    'EveResetTotal',
+    'Reset Total',
+    'E863F112-079E-48FF-8F27-9C2605A29F52',
+    'UINT32',
+    'SECONDS',
+    ['PAIRED_READ', 'NOTIFY', 'PAIRED_WRITE'],
+  ],
+  [
+    'EveLastActivation',
+    'Last Activation',
+    'E863F11A-079E-48FF-8F27-9C2605A29F52',
+    'UINT32',
+    'SECONDS',
+    ['PAIRED_READ', 'NOTIFY'],
+  ],
+  [
+    'EveTimesOpened',
+    'Times Opened',
+    'E863F129-079E-48FF-8F27-9C2605A29F52',
+    'UINT32',
+    null,
+    ['PAIRED_READ', 'NOTIFY'],
+  ],
+  [
+    'EveOpenDuration',
+    'Open Duration',
+    'E863F118-079E-48FF-8F27-9C2605A29F52',
+    'UINT32',
+    'SECONDS',
+    ['PAIRED_READ', 'NOTIFY', 'PAIRED_WRITE'],
+  ],
+  [
+    'EveClosedDuration',
+    'Closed Duration',
+    'E863F119-079E-48FF-8F27-9C2605A29F52',
+    'UINT32',
+    'SECONDS',
+    ['PAIRED_READ', 'NOTIFY', 'PAIRED_WRITE'],
+  ],
+]
+
+let cache = null
+
+function createCharacteristics(hap) {
+  if (cache) {
+    return cache
+  }
+  const { Characteristic, Formats, Perms, Units } = hap
+  cache = {}
+
+  for (const [key, displayName, uuid, format, unit, perms] of DEFS) {
+    const props = {
+      format: Formats[format],
+      perms: perms.map(p => Perms[p]),
+    }
+    if (unit) {
+      props.unit = Units[unit]
+    }
+
+    const Klass = class extends Characteristic {
+      constructor() {
+        super(displayName, uuid, props)
+        this.value = this.getDefaultValue()
+      }
+    }
+    Object.defineProperty(Klass, 'name', { value: key })
+    Klass.UUID = uuid
+    cache[key] = Klass
+  }
+  return cache
+}
+
+export { createCharacteristics }

package/lib/dashboard-server.js

@@ -0,0 +1,134 @@
+/**
+ * Small built-in web dashboard: http://<homebridge-host>:8587/
+ * Serves the files in homebridge-ui/public/, plus a JSON API and a live Server-Sent Events stream.
+ */
+
+import fs from 'node:fs'
+import http from 'node:http'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PUBLIC_DIR = fileURLToPath(new URL('./homebridge-ui/public/', import.meta.url))
+const FILES = {
+  '/': ['dashboard.html', 'text/html; charset=utf-8'],
+  '/dashboard.js': ['dashboard.js', 'application/javascript; charset=utf-8'],
+  '/dashboard.css': ['dashboard.css', 'text/css; charset=utf-8'],
+}
+
+class DashboardServer {
+  constructor({ port, host, log, getStatus, onRefresh }) {
+    this.port = port
+    this.host = host
+    this.log = log
+    this.getStatus = getStatus
+    this.onRefresh = onRefresh
+    this.clients = new Set()
+    this.server = null
+  }
+
+  start() {
+    this.server = http.createServer((req, res) => this.handle(req, res))
+    this.server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        this.log.warn(
+          `Dashboard: port ${this.port} is already in use. Set a different "dashboard.port" in the plugin config.`,
+        )
+      } else {
+        this.log.warn(`Dashboard error: ${err.message}`)
+      }
+    })
+    this.server.listen(this.port, this.host, () => {
+      this.log.info(`Printer dashboard running at http://<your-homebridge-host>:${this.port}/`)
+    })
+    this.heartbeat = setInterval(() => {
+      for (const res of this.clients) {
+        res.write(': ping\n\n')
+      }
+    }, 25000)
+    if (this.heartbeat.unref) {
+      this.heartbeat.unref()
+    }
+  }
+
+  stop() {
+    clearInterval(this.heartbeat)
+    for (const res of this.clients) {
+      res.end()
+    }
+    this.clients.clear()
+    if (this.server) {
+      this.server.close()
+    }
+  }
+
+  broadcast() {
+    if (!this.clients.size) {
+      return
+    }
+    if (this._pending) {
+      return
+    }
+    this._pending = setTimeout(() => {
+      this._pending = null
+      const data = `data: ${JSON.stringify(this.getStatus())}\n\n`
+      for (const res of this.clients) {
+        res.write(data)
+      }
+    }, 200)
+  }
+
+  send(res, code, body, type = 'application/json; charset=utf-8') {
+    res.writeHead(code, {
+      'Content-Type': type,
+      'Cache-Control': 'no-store',
+      'X-Content-Type-Options': 'nosniff',
+    })
+    res.end(body)
+  }
+
+  handle(req, res) {
+    let route
+    try {
+      route = new URL(req.url, 'http://localhost').pathname
+    } catch {
+      // any device on the network can send a path the URL parser can't read
+      return this.send(res, 400, 'Bad request', 'text/plain')
+    }
+
+    if (req.method === 'GET' && route === '/api/status') {
+      return this.send(res, 200, JSON.stringify(this.getStatus()))
+    }
+
+    if (req.method === 'POST' && route === '/api/refresh') {
+      return Promise.resolve(this.onRefresh())
+        .catch(() => {})
+        .then(() => this.send(res, 200, JSON.stringify(this.getStatus())))
+    }
+
+    if (req.method === 'GET' && route === '/api/events') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-store',
+        'Connection': 'keep-alive',
+      })
+      res.write(`data: ${JSON.stringify(this.getStatus())}\n\n`)
+      this.clients.add(res)
+      req.on('close', () => this.clients.delete(res))
+      return
+    }
+
+    if (req.method === 'GET' && FILES[route]) {
+      const [file, type] = FILES[route]
+      return fs.readFile(path.join(PUBLIC_DIR, file), (err, buf) => {
+        if (err) {
+          return this.send(res, 500, 'Dashboard file missing', 'text/plain')
+        }
+        this.send(res, 200, buf, type)
+      })
+    }
+
+    this.send(res, 404, 'Not found', 'text/plain')
+  }
+}
+
+export { DashboardServer }