@mdjhnson/homebridge-yoto 0.1.0

package/lib/speaker-accessory.js

@@ -0,0 +1,551 @@
+/**
+ * @fileoverview Yoto SmartSpeaker accessory implementation for external accessories.
+ */
+
+/** @import { PlatformAccessory, CharacteristicValue, Service, Logger } from 'homebridge' */
+/** @import { YotoPlatform } from './platform.js' */
+/** @import { YotoDeviceModel } from 'yoto-nodejs-client' */
+/** @import { YotoDeviceModelEventMap } from 'yoto-nodejs-client/lib/yoto-device.js' */
+/** @import { YotoDevice } from 'yoto-nodejs-client/lib/api-endpoints/devices.js' */
+/** @import { YotoAccessoryContext } from './platform.js' */
+
+import {
+  DEFAULT_MANUFACTURER,
+  DEFAULT_MODEL,
+  LOG_PREFIX,
+} from './settings.js'
+import { sanitizeName } from './utils/sanitize-name.js'
+import { syncServiceNames } from './sync-service-names.js'
+import { formatError } from './utils/error-format.js'
+import { ListenerGroup } from './utils/listener-group.js'
+import { setDeviceVolume } from './utils/set-device-volume.js'
+import {
+  clampPercent,
+  clampSteps,
+  percentToSteps,
+  stepsToPercent,
+} from './utils/volume.js'
+
+/**
+ * Yoto SmartSpeaker Accessory Handler (external)
+ * Manages SmartSpeaker service and characteristics for a single Yoto player.
+ */
+export class YotoSpeakerAccessory {
+  /** @type {YotoPlatform} */ #platform
+  /** @type {PlatformAccessory<YotoAccessoryContext>} */ #accessory
+  /** @type {YotoDeviceModel} */ #deviceModel
+  /** @type {Logger} */ #log
+  /** @type {YotoDevice} */ #device
+  /** @type {Service | undefined} */ speakerService
+  /** @type {number} */ #lastNonZeroVolume = 50
+  /** @type {Set<Service>} */ #currentServices = new Set()
+  /** @type {ListenerGroup<YotoDeviceModelEventMap>} */ #listeners
+
+  /**
+   * @param {Object} params
+   * @param {YotoPlatform} params.platform - Platform instance
+   * @param {PlatformAccessory<YotoAccessoryContext>} params.accessory - Platform accessory
+   * @param {YotoDeviceModel} params.deviceModel - Yoto device model with live state
+   */
+  constructor ({ platform, accessory, deviceModel }) {
+    this.#platform = platform
+    this.#accessory = accessory
+    this.#deviceModel = deviceModel
+    this.#listeners = new ListenerGroup(deviceModel)
+    this.#log = platform.log
+
+    this.#device = accessory.context.device
+    this.#currentServices = new Set()
+  }
+
+  /**
+   * Setup accessory - create services and setup event listeners
+   * @returns {Promise<void>}
+   */
+  async setup () {
+    this.#log.debug(LOG_PREFIX.ACCESSORY, `Setting up speaker for ${this.#device.name}`)
+
+    this.#currentServices.clear()
+
+    this.setupAccessoryInformation()
+    this.setupSmartSpeakerService()
+
+    // Iterate a copy: removeService splices the live array
+    for (const service of [...this.#accessory.services]) {
+      if (service.UUID !== this.#platform.Service.AccessoryInformation.UUID &&
+          !this.#currentServices.has(service)) {
+        this.#log.debug(LOG_PREFIX.ACCESSORY, `Removing stale speaker service: ${service.displayName || service.UUID}`)
+        this.#accessory.removeService(service)
+      }
+    }
+
+    this.setupEventListeners()
+
+    this.#log.debug(LOG_PREFIX.ACCESSORY, `✓ ${this.#device.name} speaker ready`)
+  }
+
+  /**
+   * Setup AccessoryInformation service
+   */
+  setupAccessoryInformation () {
+    const { Service, Characteristic } = this.#platform
+    const service = this.#accessory.getService(Service.AccessoryInformation) ||
+      this.#accessory.addService(Service.AccessoryInformation)
+    const displayName = sanitizeName(this.#accessory.displayName)
+    const nameCharacteristic = service.getCharacteristic(Characteristic.Name)
+    const configuredCharacteristic = service.getCharacteristic(Characteristic.ConfiguredName)
+    const previousName = nameCharacteristic.value
+    const configuredName = configuredCharacteristic.value
+
+    const hardwareRevision = [
+      this.#device.generation,
+      this.#device.formFactor,
+    ].filter(Boolean).join(' ') || 'Unknown'
+
+    const model = this.#device.deviceFamily || this.#device.deviceType || DEFAULT_MODEL
+
+    service
+      .setCharacteristic(Characteristic.Name, displayName)
+      .setCharacteristic(Characteristic.Manufacturer, DEFAULT_MANUFACTURER)
+      .setCharacteristic(Characteristic.Model, model)
+      .setCharacteristic(Characteristic.SerialNumber, this.#device.deviceId)
+      .setCharacteristic(Characteristic.HardwareRevision, hardwareRevision)
+
+    if (typeof configuredName !== 'string' || configuredName === previousName) {
+      service.setCharacteristic(Characteristic.ConfiguredName, displayName)
+    }
+
+    if (this.#deviceModel.status.firmwareVersion) {
+      service.setCharacteristic(
+        Characteristic.FirmwareRevision,
+        this.#deviceModel.status.firmwareVersion
+      )
+    }
+
+    this.#currentServices.add(service)
+  }
+
+  /**
+   * Setup SmartSpeaker service (PRIMARY)
+   */
+  setupSmartSpeakerService () {
+    const { Service, Characteristic } = this.#platform
+    const serviceName = sanitizeName(this.#accessory.displayName)
+
+    const service = this.#accessory.getService(Service.SmartSpeaker) ||
+      this.#accessory.addService(Service.SmartSpeaker, serviceName)
+
+    service.setPrimaryService(true)
+
+    syncServiceNames({ Characteristic, service, name: serviceName })
+
+    service
+      .getCharacteristic(Characteristic.CurrentMediaState)
+      .onGet(this.getCurrentMediaState.bind(this))
+
+    service
+      .getCharacteristic(Characteristic.TargetMediaState)
+      .onGet(this.getTargetMediaState.bind(this))
+      .onSet(this.setTargetMediaState.bind(this))
+
+    // Advertise AirPlay support so Home keeps transport controls enabled.
+    // AirPlayEnable is a writable uint8 (0/1); ignore writes and always report enabled.
+    service
+      .getCharacteristic(Characteristic.AirPlayEnable)
+      .onGet(() => 1)
+      .onSet(() => {
+        service.getCharacteristic(Characteristic.AirPlayEnable).updateValue(1)
+      })
+      .updateValue(1)
+
+    service
+      .getCharacteristic(Characteristic.Volume)
+      .setProps({
+        minValue: 0,
+        maxValue: 100,
+        minStep: 1,
+      })
+      .onGet(this.getVolume.bind(this))
+      .onSet(this.setVolume.bind(this))
+
+    service
+      .getCharacteristic(Characteristic.Mute)
+      .onGet(this.getMute.bind(this))
+      .onSet(this.setMute.bind(this))
+
+    // StatusActive isn't in the SmartSpeaker spec; declare it optional to avoid HAP warnings
+    const statusActiveUuid = Characteristic.StatusActive.UUID
+    const hasStatusActive = service.characteristics.some(c => c.UUID === statusActiveUuid)
+    const hasStatusActiveOptional = service.optionalCharacteristics.some(c => c.UUID === statusActiveUuid)
+    if (!hasStatusActive && !hasStatusActiveOptional) {
+      service.addOptionalCharacteristic(Characteristic.StatusActive)
+    }
+
+    service
+      .getCharacteristic(Characteristic.StatusActive)
+      .onGet(this.getStatusActive.bind(this))
+
+    this.speakerService = service
+    this.#currentServices.add(service)
+  }
+
+  /**
+   * Setup event listeners for device model updates
+   */
+  setupEventListeners () {
+    this.#listeners.on('statusUpdate', (status, _source, changedFields) => {
+      for (const field of changedFields) {
+        switch (field) {
+          case 'volume':
+            this.updateVolumeCharacteristic(status.volume)
+            break
+
+          case 'isOnline':
+            this.updateOnlineStatusCharacteristic(status.isOnline)
+            break
+
+          case 'firmwareVersion':
+            this.updateFirmwareVersionCharacteristic(status.firmwareVersion)
+            break
+
+          // Available but not mapped to SmartSpeaker characteristics
+          case 'batteryLevelPercentage':
+          case 'isCharging':
+          case 'maxVolume':
+          case 'temperatureCelsius':
+          case 'nightlightMode':
+          case 'dayMode':
+          case 'cardInsertionState':
+          case 'activeCardId':
+          case 'powerSource':
+          case 'wifiStrength':
+          case 'freeDiskSpaceBytes':
+          case 'totalDiskSpaceBytes':
+          case 'isAudioDeviceConnected':
+          case 'isBluetoothAudioConnected':
+          case 'ambientLightSensorReading':
+          case 'displayBrightness':
+          case 'timeFormat':
+          case 'uptime':
+          case 'updatedAt':
+          case 'source':
+            break
+
+          default: {
+            /** @type {never} */
+            const _exhaustive = field
+            this.#log.debug('Unhandled speaker status field:', _exhaustive)
+            break
+          }
+        }
+      }
+    })
+
+    this.#listeners.on('playbackUpdate', (playback, changedFields) => {
+      for (const field of changedFields) {
+        switch (field) {
+          case 'playbackStatus':
+            this.updateSmartSpeakerMediaStateCharacteristic(playback.playbackStatus)
+            break
+
+          case 'sleepTimerActive':
+          case 'position':
+          case 'trackLength':
+          case 'cardId':
+          case 'cardTitle':
+          case 'cardSlug':
+          case 'cardCoverImageUrl':
+          case 'cardAuthor':
+          case 'cardReadBy':
+          case 'cardDurationSeconds':
+          case 'source':
+          case 'trackTitle':
+          case 'trackKey':
+          case 'chapterTitle':
+          case 'chapterKey':
+          case 'sleepTimerSeconds':
+          case 'streaming':
+          case 'updatedAt':
+            break
+
+          default: {
+            /** @type {never} */
+            const _exhaustive = field
+            this.#log.debug('Unhandled speaker playback field:', _exhaustive)
+            break
+          }
+        }
+      }
+    })
+
+    this.#listeners.on('online', () => {
+      this.updateOnlineStatusCharacteristic(true)
+    })
+
+    this.#listeners.on('offline', () => {
+      this.updateOnlineStatusCharacteristic(false)
+    })
+
+    this.#listeners.on('error', (error) => {
+      const details = formatError(error)
+      this.#log.error(`[${this.#device.name}] Speaker device error:`, details)
+    })
+  }
+
+  /**
+   * @param { "playing" | "paused" | "stopped" | "loading" | null} playbackStatus
+   * @returns {{ current: CharacteristicValue, target: CharacteristicValue }}
+   */
+  getMediaStateValues (playbackStatus) {
+    const { Characteristic } = this.#platform
+
+    if (playbackStatus === 'playing') {
+      return {
+        current: Characteristic.CurrentMediaState.PLAY,
+        target: Characteristic.TargetMediaState.PLAY,
+      }
+    }
+
+    if (playbackStatus === 'paused') {
+      return {
+        current: Characteristic.CurrentMediaState.PAUSE,
+        target: Characteristic.TargetMediaState.PAUSE,
+      }
+    }
+
+    if (playbackStatus === 'loading') {
+      return {
+        current: Characteristic.CurrentMediaState.LOADING,
+        target: Characteristic.TargetMediaState.PLAY,
+      }
+    }
+
+    return {
+      current: Characteristic.CurrentMediaState.STOP,
+      target: Characteristic.TargetMediaState.STOP,
+    }
+  }
+
+  /**
+   * Get current media state from live playback state
+   * @returns {Promise<CharacteristicValue>}
+   */
+  async getCurrentMediaState () {
+    const playbackStatus = this.#deviceModel.playback.playbackStatus ?? null
+    const current = this.getMediaStateValues(playbackStatus).current
+    this.#log.debug(
+      LOG_PREFIX.ACCESSORY,
+      `[${this.#device.name}] Get current media state -> ${current} (${playbackStatus ?? 'unknown'})`
+    )
+    return current
+  }
+
+  /**
+   * Get target media state (follows current state)
+   * @returns {Promise<CharacteristicValue>}
+   */
+  async getTargetMediaState () {
+    const playbackStatus = this.#deviceModel.playback.playbackStatus ?? null
+    const target = this.getMediaStateValues(playbackStatus).target
+    this.#log.debug(
+      LOG_PREFIX.ACCESSORY,
+      `[${this.#device.name}] Get target media state -> ${target} (${playbackStatus ?? 'unknown'})`
+    )
+    return target
+  }
+
+  /**
+   * Set target media state (play/pause/stop)
+   * @param {CharacteristicValue} value - Target state
+   * @returns {Promise<void>}
+   */
+  async setTargetMediaState (value) {
+    const { Characteristic } = this.#platform
+    const targetValue = typeof value === 'number' ? value : Number(value)
+    this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Set target media state:`, value)
+
+    try {
+      if (targetValue === Characteristic.TargetMediaState.PLAY) {
+        await this.#deviceModel.resumeCard()
+        return
+      }
+
+      if (targetValue === Characteristic.TargetMediaState.PAUSE) {
+        await this.#deviceModel.pauseCard()
+        return
+      }
+
+      if (targetValue === Characteristic.TargetMediaState.STOP) {
+        // Pause rather than stop so playback can be resumed (matches the TV accessory)
+        await this.#deviceModel.pauseCard()
+      }
+    } catch (error) {
+      this.#log.error(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Failed to set media state:`, formatError(error))
+      throw new this.#platform.api.hap.HapStatusError(
+        this.#platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE
+      )
+    }
+  }
+
+  /**
+   * Get volume level as percentage (mapped from 0-16 steps)
+   * @returns {Promise<CharacteristicValue>}
+   */
+  async getVolume () {
+    const volumeSteps = this.#deviceModel.status.volume
+    const percent = stepsToPercent(volumeSteps)
+    this.#log.debug(
+      LOG_PREFIX.ACCESSORY,
+      `[${this.#device.name}] Get speaker volume -> ${percent} (rawSteps=${volumeSteps})`
+    )
+    return percent
+  }
+
+  /**
+   * Set volume level as percentage (mapped to 0-16 steps)
+   * @param {CharacteristicValue} value - Volume level percent
+   * @returns {Promise<void>}
+   */
+  async setVolume (value) {
+    const deviceModel = this.#deviceModel
+    this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Set speaker volume:`, value)
+
+    const requestedPercent = typeof value === 'number' ? value : Number(value)
+    if (!Number.isFinite(requestedPercent)) {
+      throw new this.#platform.api.hap.HapStatusError(
+        this.#platform.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST
+      )
+    }
+
+    const normalizedPercent = clampPercent(requestedPercent)
+    const requestedSteps = percentToSteps(normalizedPercent)
+    const steps = clampSteps(requestedSteps)
+
+    if (steps > 0) {
+      this.#lastNonZeroVolume = stepsToPercent(steps)
+    }
+
+    try {
+      await setDeviceVolume(deviceModel, steps)
+      this.updateVolumeCharacteristic(steps)
+    } catch (error) {
+      this.#log.error(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Failed to set speaker volume:`, formatError(error))
+      throw new this.#platform.api.hap.HapStatusError(
+        this.#platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE
+      )
+    }
+  }
+
+  /**
+   * Get mute state (derived from volume === 0)
+   * @returns {Promise<CharacteristicValue>}
+   */
+  async getMute () {
+    const isMuted = this.#deviceModel.status.volume === 0
+    this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Get speaker mute -> ${isMuted}`)
+    return isMuted
+  }
+
+  /**
+   * Set mute state
+   * @param {CharacteristicValue} value - Mute state
+   * @returns {Promise<void>}
+   */
+  async setMute (value) {
+    const isMuted = Boolean(value)
+    this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Set speaker mute:`, isMuted)
+
+    if (isMuted) {
+      await this.setVolume(0)
+      return
+    }
+
+    await this.setVolume(this.#lastNonZeroVolume)
+  }
+
+  /**
+   * Get status active (online/offline)
+   * @returns {Promise<CharacteristicValue>}
+   */
+  async getStatusActive () {
+    const isOnline = this.#deviceModel.status.isOnline
+    this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Get speaker status active -> ${isOnline}`)
+    return isOnline
+  }
+
+  /**
+   * Update online status characteristic
+   * @param {boolean} isOnline - Online status
+   */
+  updateOnlineStatusCharacteristic (isOnline) {
+    if (!this.speakerService) return
+
+    this.speakerService
+      .getCharacteristic(this.#platform.Characteristic.StatusActive)
+      .updateValue(isOnline)
+  }
+
+  /**
+   * Update SmartSpeaker media state characteristics
+   * @param { "playing" | "paused" | "stopped" | "loading" | null} playbackStatus - Playback status
+   */
+  updateSmartSpeakerMediaStateCharacteristic (playbackStatus) {
+    if (!this.speakerService) return
+
+    const { Characteristic } = this.#platform
+    const { current, target } = this.getMediaStateValues(playbackStatus)
+
+    this.speakerService
+      .getCharacteristic(Characteristic.CurrentMediaState)
+      .updateValue(current)
+
+    this.speakerService
+      .getCharacteristic(Characteristic.TargetMediaState)
+      .updateValue(target)
+  }
+
+  /**
+   * Update volume and mute characteristics
+   * @param {number} volumeSteps - Volume level (0-16)
+   */
+  updateVolumeCharacteristic (volumeSteps) {
+    if (!this.speakerService) return
+
+    const percent = stepsToPercent(volumeSteps)
+    const isMuted = clampSteps(volumeSteps) === 0
+
+    this.speakerService
+      .getCharacteristic(this.#platform.Characteristic.Volume)
+      .updateValue(percent)
+
+    this.speakerService
+      .getCharacteristic(this.#platform.Characteristic.Mute)
+      .updateValue(isMuted)
+  }
+
+  /**
+   * Update firmware version characteristic
+   * @param {string} firmwareVersion - Firmware version
+   */
+  updateFirmwareVersionCharacteristic (firmwareVersion) {
+    const { Service, Characteristic } = this.#platform
+    const infoService = this.#accessory.getService(Service.AccessoryInformation)
+    if (!infoService) return
+
+    infoService.setCharacteristic(
+      Characteristic.FirmwareRevision,
+      firmwareVersion
+    )
+  }
+
+  /**
+   * Stop accessory - cleanup event listeners
+   * @returns {Promise<void>}
+   */
+  async stop () {
+    this.#log.debug(LOG_PREFIX.ACCESSORY, `Stopping speaker for ${this.#device.name}`)
+
+    // Only remove our own listeners; the device model is shared
+    this.#listeners.removeAll()
+  }
+}

package/lib/sync-service-names.js

@@ -0,0 +1,39 @@
+// Use syncServiceNames for every visible service so HomeKit labels stay stable.
+// Exceptions: AccessoryInformation (named in platform) and Battery (set Characteristic.Name only).
+/** @import { Service, Characteristic } from 'homebridge' */
+import { sanitizeName } from './utils/sanitize-name.js'
+
+/**
+ * Apply HomeKit-visible naming to a service.
+ *
+ * We set both `Name` and `ConfiguredName` on every service we manage so HomeKit tiles are consistently labeled.
+ *
+ * @param {object} params
+ * @param {Service} params.service
+ * @param {string} params.name
+ * @param {typeof Characteristic} params.Characteristic
+ * @returns {void}
+ */
+export function syncServiceNames ({
+  Characteristic,
+  service,
+  name
+}) {
+  const sanitizedName = sanitizeName(name)
+  service.displayName = sanitizedName
+
+  service.updateCharacteristic(Characteristic.Name, sanitizedName)
+
+  // Add ConfiguredName when missing so we avoid HAP warnings on update.
+  const configuredNameUuid = Characteristic.ConfiguredName.UUID
+  const hasConfiguredNameCharacteristic = service.characteristics
+    .some((characteristic) => characteristic.UUID === configuredNameUuid)
+  const hasConfiguredNameOptional = service.optionalCharacteristics
+    .some((characteristic) => characteristic.UUID === configuredNameUuid)
+
+  if (!hasConfiguredNameCharacteristic && !hasConfiguredNameOptional) {
+    service.addOptionalCharacteristic(Characteristic.ConfiguredName)
+  }
+
+  service.updateCharacteristic(Characteristic.ConfiguredName, sanitizedName)
+}