homebridge-yoto 0.0.39 → 0.0.40

package/README.md

@@ -25,6 +25,56 @@
 
 THIS PLUGIN IS A WIP. DO NOT USE YET.
 
+Homebridge plugin that exposes Yoto players to HomeKit with optional playback controls, device status, and nightlight settings.
+
+## Settings
+
+**Playback Controls** (`services.playbackAccessory`)
+- **Bridged (Switch + Dimmer)**: Adds Playback and Volume services on the main accessory.
+- **External Smart Speaker**: Publishes a separate Smart Speaker accessory for playback and volume. Requires pairing the extra accessory in the Home app.
+- **None**: Disables playback and volume services entirely.
+
+**Card Controls** (`services.cardControls`)
+- Adds a per-device switch that plays the configured card ID.
+- Optional "Play on All Yotos" accessory per card control.
+
+**Service toggles**
+- **Temperature Sensor**: Adds a temperature sensor when supported by the device.
+- **Nightlight**: Adds day/night nightlight controls and status sensors.
+- **Card Slot**: Adds a card insertion sensor.
+- **Day Mode**: Adds a day/night mode sensor.
+- **Sleep Timer**: Adds a sleep timer switch.
+- **Bluetooth**: Adds a Bluetooth toggle switch.
+- **Volume Limits**: Adds day/night max volume controls.
+
+## HomeKit Services
+
+**Playback (bridged)**
+- **Playback**: Switch; On resumes, Off pauses.
+- **Volume**: Lightbulb; On unmutes, Off mutes, Brightness maps 0-100% to device volume steps.
+
+**Smart Speaker (external)**
+- **Smart Speaker**: Current/Target Media State, Volume, Mute, and StatusActive (online state).
+
+**Card Controls**
+- **Card Control**: Switch on each device that plays the configured card ID.
+- **Card Control (All Yotos)**: Optional switch accessory that plays the card on every Yoto.
+
+**Device status**
+- **Online Status**: Contact sensor; Contact Not Detected = online.
+- **Battery**: Battery level, charging state, and low battery.
+- **Temperature**: Temperature sensor with fault status when offline/unavailable.
+
+**Nightlight**
+- **Day Nightlight / Night Nightlight**: Lightbulbs with On/Off, Brightness, Hue, and Saturation.
+- **Nightlight Active / Day Nightlight Active / Night Nightlight Active**: Contact sensors for live nightlight state.
+
+**Other controls**
+- **Card Slot**: Contact sensor for card insertion.
+- **Day Mode**: Contact sensor; Contact Not Detected = day mode.
+- **Sleep Timer**: Switch to enable/disable sleep timer.
+- **Bluetooth**: Switch to toggle Bluetooth.
+- **Day/Night Max Volume**: Lightbulb brightness sets max volume limits.
 
 ## License
 

package/config.schema.json

@@ -49,17 +49,17 @@
         "title": "Accessory Services",
         "type": "object",
         "properties": {
-          "playback": {
-            "title": "Playback",
-            "type": "boolean",
-            "default": true,
-            "description": "Expose a playback switch."
-          },
-          "volume": {
-            "title": "Volume",
-            "type": "boolean",
-            "default": true,
-            "description": "Expose volume controls."
+          "playbackAccessory": {
+            "title": "Playback Controls",
+            "type": "string",
+            "default": "none",
+            "enum": ["bridged", "external", "none"],
+            "enumNames": [
+              "Bridged (Switch + Dimmer)",
+              "External Smart Speaker",
+              "None"
+            ],
+            "description": "Choose how playback and volume controls are exposed. External Smart Speaker requires additional pairing steps and appears as a separate accessory."
           },
           "temperature": {
             "title": "Temperature Sensor",
@@ -79,11 +79,40 @@
             "default": true,
             "description": "Expose card insertion status."
           },
-          "nightMode": {
-            "title": "Night Mode",
+          "cardControls": {
+            "title": "Card Controls",
+            "type": "array",
+            "description": "Add switches that play a specific card ID on each Yoto device. Optionally add an accessory that plays the card on all Yotos.",
+            "items": {
+              "title": "Card Control",
+              "type": "object",
+              "properties": {
+                "label": {
+                  "title": "Label",
+                  "type": "string",
+                  "required": true,
+                  "description": "Name shown in HomeKit for this card control."
+                },
+                "cardId": {
+                  "title": "Card ID",
+                  "type": "string",
+                  "required": true,
+                  "description": "The Yoto card ID to play."
+                },
+                "playOnAll": {
+                  "title": "Play on All Yotos",
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Create a separate accessory that plays this card on every Yoto."
+                }
+              }
+            }
+          },
+          "dayMode": {
+            "title": "Day Mode",
             "type": "boolean",
             "default": true,
-            "description": "Expose night mode status."
+            "description": "Expose day mode status."
           },
           "sleepTimer": {
             "title": "Sleep Timer",
@@ -133,12 +162,29 @@
           "type": "help",
           "helpvalue": "<p>Select which HomeKit services to expose for each Yoto device.</p>"
         },
-        "services.playback",
-        "services.volume",
+        {
+          "type": "help",
+          "helpvalue": "<p><strong>Playback Controls:</strong> External Smart Speaker requires additional pairing steps in the Home app and will appear as a separate accessory.</p>"
+        },
+        "services.playbackAccessory",
         "services.temperature",
         "services.nightlight",
         "services.cardSlot",
-        "services.nightMode",
+        {
+          "type": "help",
+          "helpvalue": "<p><strong>Card Controls:</strong> Add switches that play a specific card ID on each Yoto. Enable \"Play on All Yotos\" to create a separate accessory.</p>"
+        },
+        {
+          "key": "services.cardControls",
+          "type": "array",
+          "buttonText": "Add Card Control",
+          "items": [
+            "services.cardControls[].label",
+            "services.cardControls[].cardId",
+            "services.cardControls[].playOnAll"
+          ]
+        },
+        "services.dayMode",
         "services.sleepTimer",
         "services.bluetooth",
         "services.volumeLimits"

package/lib/accessory.js

@@ -8,6 +8,7 @@
 /** @import { YotoDevice } from 'yoto-nodejs-client/lib/api-endpoints/devices.js' */
 /** @import { YotoAccessoryContext } from './platform.js' */
 /** @import { ServiceSchemaKey } from '../config.schema.cjs' */
+/** @import { CardControlConfig } from './card-controls.js' */
 
 /**
  * Device capabilities detected from metadata
@@ -25,7 +26,7 @@
  * @property {boolean} temperature
  * @property {boolean} nightlight
  * @property {boolean} cardSlot
- * @property {boolean} nightMode
+ * @property {boolean} dayMode
  * @property {boolean} sleepTimer
  * @property {boolean} bluetooth
  * @property {boolean} volumeLimits
@@ -41,6 +42,8 @@ import {
 import { sanitizeName } from './sanitize-name.js'
 import { syncServiceNames } from './sync-service-names.js'
 import { serviceSchema } from '../config.schema.cjs'
+import { getPlaybackAccessoryConfig } from './service-config.js'
+import { getCardControlConfigs } from './card-controls.js'
 
 // Use syncServiceNames for every visible service so HomeKit labels stay stable.
 // Exceptions: AccessoryInformation (named in platform) and Battery (set Characteristic.Name only).
@@ -60,7 +63,7 @@ function getBooleanSetting (value, fallback) {
  */
 function getServiceDefault (key) {
   const entry = serviceSchema[key]
-  if (entry?.default !== undefined && typeof entry.default === 'boolean') {
+  if (entry && 'default' in entry && typeof entry.default === 'boolean') {
     return entry.default
   }
   return false
@@ -87,7 +90,7 @@ export class YotoPlayerAccessory {
   /** @type {Service | undefined} */ dayNightlightActiveService
   /** @type {Service | undefined} */ nightNightlightActiveService
   /** @type {Service | undefined} */ cardSlotService
-  /** @type {Service | undefined} */ nightModeService
+  /** @type {Service | undefined} */ dayModeService
   /** @type {Service | undefined} */ sleepTimerService
   /** @type {Service | undefined} */ bluetoothService
   /** @type {Service | undefined} */ dayMaxVolumeService
@@ -127,14 +130,15 @@ export class YotoPlayerAccessory {
     const serviceConfig = typeof services === 'object' && services !== null
       ? /** @type {Record<string, unknown>} */ (services)
       : {}
+    const playbackConfig = getPlaybackAccessoryConfig(this.#platform.config)
 
     return {
-      playback: getBooleanSetting(serviceConfig['playback'], getServiceDefault('playback')),
-      volume: getBooleanSetting(serviceConfig['volume'], getServiceDefault('volume')),
+      playback: playbackConfig.playbackEnabled,
+      volume: playbackConfig.volumeEnabled,
       temperature: getBooleanSetting(serviceConfig['temperature'], getServiceDefault('temperature')),
       nightlight: getBooleanSetting(serviceConfig['nightlight'], getServiceDefault('nightlight')),
       cardSlot: getBooleanSetting(serviceConfig['cardSlot'], getServiceDefault('cardSlot')),
-      nightMode: getBooleanSetting(serviceConfig['nightMode'], getServiceDefault('nightMode')),
+      dayMode: getBooleanSetting(serviceConfig['dayMode'], getServiceDefault('dayMode')),
       sleepTimer: getBooleanSetting(serviceConfig['sleepTimer'], getServiceDefault('sleepTimer')),
       bluetooth: getBooleanSetting(serviceConfig['bluetooth'], getServiceDefault('bluetooth')),
       volumeLimits: getBooleanSetting(serviceConfig['volumeLimits'], getServiceDefault('volumeLimits')),
@@ -188,8 +192,8 @@ export class YotoPlayerAccessory {
     if (serviceToggles.cardSlot) {
       this.setupCardSlotService()
     }
-    if (serviceToggles.nightMode) {
-      this.setupNightModeService()
+    if (serviceToggles.dayMode) {
+      this.setupDayModeService()
     }
     if (serviceToggles.sleepTimer) {
       this.setupSleepTimerService()
@@ -200,6 +204,7 @@ export class YotoPlayerAccessory {
     if (serviceToggles.volumeLimits) {
       this.setupVolumeLimitServices()
     }
+    this.setupCardControlServices()
 
     // Remove any services that aren't in our current set
     // (except AccessoryInformation which should always be preserved)
@@ -515,21 +520,21 @@ export class YotoPlayerAccessory {
   }
 
   /**
-   * Setup night mode ContactSensor service
-   * Shows if device is in night mode (vs day mode)
+   * Setup day mode ContactSensor service
+   * Shows if device is in day mode (vs night mode)
    */
-  setupNightModeService () {
+  setupDayModeService () {
     const { Service, Characteristic } = this.#platform
-    const serviceName = this.generateServiceName('Night Mode')
+    const serviceName = this.generateServiceName('Day Mode')
 
-    const service = this.#accessory.getServiceById(Service.ContactSensor, 'NightModeStatus') ||
-      this.#accessory.addService(Service.ContactSensor, serviceName, 'NightModeStatus')
+    const service = this.#accessory.getServiceById(Service.ContactSensor, 'DayModeStatus') ||
+      this.#accessory.addService(Service.ContactSensor, serviceName, 'DayModeStatus')
     syncServiceNames({ Characteristic, service, name: serviceName })
 
     service.getCharacteristic(Characteristic.ContactSensorState)
-      .onGet(this.getNightModeStatus.bind(this))
+      .onGet(this.getDayModeStatus.bind(this))
 
-    this.nightModeService = service
+    this.dayModeService = service
     this.#currentServices.add(service)
   }
 
@@ -632,6 +637,39 @@ export class YotoPlayerAccessory {
     this.#currentServices.add(nightService)
   }
 
+  /**
+   * Setup card control Switch services
+   */
+  setupCardControlServices () {
+    const cardControls = getCardControlConfigs(this.#platform.config)
+    if (cardControls.length === 0) {
+      return
+    }
+
+    const { Service, Characteristic } = this.#platform
+
+    for (const control of cardControls) {
+      const serviceName = this.generateServiceName(control.label)
+      const subtype = `CardControl:${control.id}`
+
+      const service = this.#accessory.getServiceById(Service.Switch, subtype) ||
+        this.#accessory.addService(Service.Switch, serviceName, subtype)
+
+      syncServiceNames({ Characteristic, service, name: serviceName })
+
+      service
+        .getCharacteristic(Characteristic.On)
+        .onGet(() => false)
+        .onSet(async (value) => {
+          await this.setCardControl(service, control, value)
+        })
+
+      service.updateCharacteristic(Characteristic.On, false)
+
+      this.#currentServices.add(service)
+    }
+  }
+
   /**
    * Setup event listeners for device model updates
    * Uses exhaustive switch pattern for type safety
@@ -677,8 +715,8 @@ export class YotoPlayerAccessory {
             break
 
           case 'dayMode':
-            // Update night mode ContactSensor
-            this.updateNightModeCharacteristic()
+            // Update day mode ContactSensor
+            this.updateDayModeCharacteristic()
             // Update nightlight status ContactSensors (depends on dayMode)
             if (this.#deviceModel.capabilities.hasColoredNightlight) {
               this.updateNightlightStatusCharacteristics()
@@ -927,7 +965,7 @@ export class YotoPlayerAccessory {
     const percent = Math.round((clampedSteps / 16) * 100)
     this.#log.debug(
       LOG_PREFIX.ACCESSORY,
-      `[${this.#device.name}] Get volume rawSteps=${volumeSteps} steps=${clampedSteps} percent=${percent}`
+      `[${this.#device.name}] Get volume rawSteps=${volumeSteps} percent=${percent}`
     )
     return percent
   }
@@ -966,13 +1004,12 @@ export class YotoPlayerAccessory {
       await deviceModel.setVolume(steps)
       if (this.volumeService) {
         const { Characteristic } = this.#platform
-
+        const clampedPercent = Math.round((steps / 16) * 100)
         this.volumeService
           .getCharacteristic(Characteristic.On)
           .updateValue(steps > 0)
 
         if (steps !== requestedSteps || normalizedPercent !== requestedPercent) {
-          const clampedPercent = Math.round((steps / 16) * 100)
           this.volumeService
             .getCharacteristic(Characteristic.Brightness)
             .updateValue(clampedPercent)
@@ -1489,17 +1526,17 @@ export class YotoPlayerAccessory {
     return hasCard ? Characteristic.ContactSensorState.CONTACT_NOT_DETECTED : Characteristic.ContactSensorState.CONTACT_DETECTED
   }
 
-  // ==================== Night Mode ContactSensor Getter ====================
+  // ==================== Day Mode ContactSensor Getter ====================
 
   /**
-   * Get night mode status
+   * Get day mode status
    * @returns {Promise<CharacteristicValue>}
    */
-  async getNightModeStatus () {
+  async getDayModeStatus () {
     const { Characteristic } = this.#platform
     const status = this.#deviceModel.status
-    const isNightMode = status.dayMode === 'night'
-    return isNightMode
+    const isDayMode = status.dayMode === 'day'
+    return isDayMode
       ? Characteristic.ContactSensorState.CONTACT_NOT_DETECTED
       : Characteristic.ContactSensorState.CONTACT_DETECTED
   }
@@ -1560,6 +1597,54 @@ export class YotoPlayerAccessory {
     await this.#deviceModel.updateConfig({ bluetoothEnabled: enabled })
   }
 
+  // ==================== Card Control Switch Setter ====================
+
+  /**
+   * Trigger card playback for a configured card control.
+   * @param {Service} service
+   * @param {CardControlConfig} control
+   * @param {CharacteristicValue} value
+   * @returns {Promise<void>}
+   */
+  async setCardControl (service, control, value) {
+    const { Characteristic } = this.#platform
+    const isOn = Boolean(value)
+
+    if (!isOn) {
+      service.getCharacteristic(Characteristic.On).updateValue(false)
+      return
+    }
+
+    if (!this.#deviceModel.status.isOnline) {
+      this.#log.warn(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Card control skipped (offline): ${control.label}`)
+      service.getCharacteristic(Characteristic.On).updateValue(false)
+      throw new this.#platform.api.hap.HapStatusError(
+        this.#platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE
+      )
+    }
+
+    this.#log.debug(
+      LOG_PREFIX.ACCESSORY,
+      `[${this.#device.name}] Play card control: ${control.label} (${control.cardId})`
+    )
+
+    try {
+      await this.#deviceModel.startCard({ cardId: control.cardId })
+    } catch (error) {
+      this.#log.error(
+        LOG_PREFIX.ACCESSORY,
+        `[${this.#device.name}] Failed to play card ${control.cardId}:`,
+        error
+      )
+      service.getCharacteristic(Characteristic.On).updateValue(false)
+      throw new this.#platform.api.hap.HapStatusError(
+        this.#platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE
+      )
+    }
+
+    service.getCharacteristic(Characteristic.On).updateValue(false)
+  }
+
   // ==================== Volume Limit Lightbulb Getters/Setters ====================
 
   /**
@@ -1573,7 +1658,7 @@ export class YotoPlayerAccessory {
     const percent = Math.round((clampedSteps / 16) * 100)
     this.#log.debug(
       LOG_PREFIX.ACCESSORY,
-      `[${this.#device.name}] Get day max volume limit rawSteps=${limit} steps=${clampedSteps} percent=${percent}`
+      `[${this.#device.name}] Get day max volume limit rawSteps=${limit} percent=${percent}`
     )
     return percent
   }
@@ -1612,7 +1697,7 @@ export class YotoPlayerAccessory {
     const percent = Math.round((clampedSteps / 16) * 100)
     this.#log.debug(
       LOG_PREFIX.ACCESSORY,
-      `[${this.#device.name}] Get night max volume limit rawSteps=${limit} steps=${clampedSteps} percent=${percent}`
+      `[${this.#device.name}] Get night max volume limit rawSteps=${limit} percent=${percent}`
     )
     return percent
   }
@@ -1661,9 +1746,6 @@ export class YotoPlayerAccessory {
    * @param {number} volumeSteps - Volume level (0-16)
    */
   updateVolumeCharacteristic (volumeSteps) {
-    if (!this.volumeService) return
-
-    const { Characteristic } = this.#platform
     if (volumeSteps > 0) {
       this.#lastNonZeroVolume = Math.round((volumeSteps / 16) * 100)
     }
@@ -1673,8 +1755,11 @@ export class YotoPlayerAccessory {
     const percent = Math.round((clampedVolume / 16) * 100)
     this.#log.debug(
       LOG_PREFIX.ACCESSORY,
-      `[${this.#device.name}] Update volume characteristic rawSteps=${volumeSteps} steps=${clampedVolume} percent=${percent}`
+      `[${this.#device.name}] Update volume characteristic rawSteps=${volumeSteps} percent=${percent}`
     )
+    if (!this.volumeService) return
+
+    const { Characteristic } = this.#platform
     this.volumeService
       .getCharacteristic(Characteristic.Brightness)
       .updateValue(percent)
@@ -1797,9 +1882,9 @@ export class YotoPlayerAccessory {
         .updateValue(isOnline)
     }
 
-    // Update night mode ContactSensor (device state)
-    if (this.nightModeService) {
-      this.nightModeService
+    // Update day mode ContactSensor (device state)
+    if (this.dayModeService) {
+      this.dayModeService
         .getCharacteristic(Characteristic.StatusActive)
         .updateValue(isOnline)
     }
@@ -1883,20 +1968,20 @@ export class YotoPlayerAccessory {
   }
 
   /**
-   * Update night mode ContactSensor characteristic
+   * Update day mode ContactSensor characteristic
    */
-  updateNightModeCharacteristic () {
-    if (!this.nightModeService) {
+  updateDayModeCharacteristic () {
+    if (!this.dayModeService) {
       return
     }
 
     const { Characteristic } = this.#platform
     const status = this.#deviceModel.status
-    const isNightMode = status.dayMode === 'night'
+    const isDayMode = status.dayMode === 'day'
 
-    this.nightModeService
+    this.dayModeService
       .getCharacteristic(Characteristic.ContactSensorState)
-      .updateValue(isNightMode ? Characteristic.ContactSensorState.CONTACT_NOT_DETECTED : Characteristic.ContactSensorState.CONTACT_DETECTED)
+      .updateValue(isDayMode ? Characteristic.ContactSensorState.CONTACT_NOT_DETECTED : Characteristic.ContactSensorState.CONTACT_DETECTED)
   }
 
   /**
@@ -1944,7 +2029,7 @@ export class YotoPlayerAccessory {
       const percent = Math.round((clampedLimit / 16) * 100)
       this.#log.debug(
         LOG_PREFIX.ACCESSORY,
-        `[${this.#device.name}] Update day max volume characteristic rawSteps=${limit} steps=${clampedLimit} percent=${percent}`
+        `[${this.#device.name}] Update day max volume characteristic rawSteps=${limit} percent=${percent}`
       )
       this.dayMaxVolumeService
         .getCharacteristic(Characteristic.Brightness)
@@ -1957,7 +2042,7 @@ export class YotoPlayerAccessory {
       const percent = Math.round((clampedLimit / 16) * 100)
       this.#log.debug(
         LOG_PREFIX.ACCESSORY,
-        `[${this.#device.name}] Update night max volume characteristic rawSteps=${limit} steps=${clampedLimit} percent=${percent}`
+        `[${this.#device.name}] Update night max volume characteristic rawSteps=${limit} percent=${percent}`
       )
       this.nightMaxVolumeService
         .getCharacteristic(Characteristic.Brightness)