homebridge-yoto 0.0.35 → 0.0.36

package/config.schema.cjs

@@ -1,3 +1,11 @@
+/** @type {import('./config.schema.json')} */
 const configSchema = require('./config.schema.json')
 
+const serviceSchema = configSchema.schema.properties.services.properties
+
+/**
+ * @typedef {keyof typeof serviceSchema} ServiceSchemaKey
+ */
+
 exports.configSchema = configSchema
+exports.serviceSchema = serviceSchema

package/config.schema.json

@@ -44,6 +44,66 @@
         "x-schema-form": {
           "hidden": true
         }
+      },
+      "services": {
+        "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."
+          },
+          "temperature": {
+            "title": "Temperature Sensor",
+            "type": "boolean",
+            "default": true,
+            "description": "Expose temperature sensor when supported."
+          },
+          "nightlight": {
+            "title": "Nightlight",
+            "type": "boolean",
+            "default": false,
+            "description": "Expose day/night nightlight controls and status."
+          },
+          "cardSlot": {
+            "title": "Card Slot",
+            "type": "boolean",
+            "default": true,
+            "description": "Expose card insertion status."
+          },
+          "nightMode": {
+            "title": "Night Mode",
+            "type": "boolean",
+            "default": true,
+            "description": "Expose night mode status."
+          },
+          "sleepTimer": {
+            "title": "Sleep Timer",
+            "type": "boolean",
+            "default": false,
+            "description": "Expose sleep timer switch."
+          },
+          "bluetooth": {
+            "title": "Bluetooth",
+            "type": "boolean",
+            "default": false,
+            "description": "Expose Bluetooth toggle."
+          },
+          "volumeLimits": {
+            "title": "Volume Limits",
+            "type": "boolean",
+            "default": true,
+            "description": "Expose day/night max volume controls."
+          }
+        }
       }
     }
   },
@@ -62,6 +122,27 @@
         "accessToken",
         "refreshToken"
       ]
+    },
+    {
+      "type": "section",
+      "title": "Accessory Services",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        {
+          "type": "help",
+          "helpvalue": "<p>Select which HomeKit services to expose for each Yoto device.</p>"
+        },
+        "services.playback",
+        "services.volume",
+        "services.temperature",
+        "services.nightlight",
+        "services.cardSlot",
+        "services.nightMode",
+        "services.sleepTimer",
+        "services.bluetooth",
+        "services.volumeLimits"
+      ]
     }
   ]
 }

package/homebridge-ui/public/client.js

@@ -52,8 +52,7 @@ async function initializeUI () {
   if (retryBtn) retryBtn.addEventListener('click', retryAuth)
   if (logoutBtn) logoutBtn.addEventListener('click', logout)
 
-  // Show schema-based config form below custom UI
-  homebridge.showSchemaForm()
+  homebridge.hideSchemaForm()
 
   // Load auth config and check authentication status
   await loadAuthConfig()
@@ -63,6 +62,17 @@ async function initializeUI () {
 // Initialize on ready
 homebridge.addEventListener('ready', initializeUI)
 
+/**
+ * @param {boolean} shouldShow
+ */
+function setSchemaFormVisibility (shouldShow) {
+  if (shouldShow) {
+    homebridge.showSchemaForm()
+  } else {
+    homebridge.hideSchemaForm()
+  }
+}
+
 /**
  * Show a specific UI section and hide all others
  * @param {string} sectionToShow - ID of section to show
@@ -90,6 +100,8 @@ function showSection (sectionToShow, options = {}) {
     const errorMessageEl = document.getElementById('errorMessage')
     if (errorMessageEl) errorMessageEl.textContent = options.errorMessage
   }
+
+  setSchemaFormVisibility(sectionToShow === 'authSuccess')
 }
 
 /**
@@ -298,12 +310,6 @@ function startPolling () {
         await homebridge.updatePluginConfig(pluginConfig)
         await homebridge.savePluginConfig()
 
-        // Refresh the schema form to show updated token fields
-        homebridge.hideSchemaForm()
-        setTimeout(() => {
-          homebridge.showSchemaForm()
-        }, 100)
-
         homebridge.toast.success('Authentication successful!')
         homebridge.toast.info('Please restart the plugin for changes to take effect', 'Restart Required')
         showAuthSuccess()

package/lib/accessory.js

@@ -7,6 +7,7 @@
 /** @import { YotoDeviceModel } from 'yoto-nodejs-client' */
 /** @import { YotoDevice } from 'yoto-nodejs-client/lib/api-endpoints/devices.js' */
 /** @import { YotoAccessoryContext } from './platform.js' */
+/** @import { ServiceSchemaKey } from '../config.schema.cjs' */
 
 /**
  * Device capabilities detected from metadata
@@ -16,6 +17,20 @@
  * @property {string | undefined} generation - Device generation (e.g., 'gen3')
  */
 
+/**
+ * Accessory service toggles from config.
+ * @typedef {Object} YotoServiceToggles
+ * @property {boolean} playback
+ * @property {boolean} volume
+ * @property {boolean} temperature
+ * @property {boolean} nightlight
+ * @property {boolean} cardSlot
+ * @property {boolean} nightMode
+ * @property {boolean} sleepTimer
+ * @property {boolean} bluetooth
+ * @property {boolean} volumeLimits
+ */
+
 import convert from 'color-convert'
 import {
   DEFAULT_MANUFACTURER,
@@ -25,6 +40,31 @@ import {
 } from './constants.js'
 import { sanitizeName } from './sanitize-name.js'
 import { syncServiceNames } from './sync-service-names.js'
+import { serviceSchema } from '../config.schema.cjs'
+
+// Use syncServiceNames for every visible service so HomeKit labels stay stable.
+// Exceptions: AccessoryInformation (named in platform) and Battery (set Characteristic.Name only).
+
+/**
+ * @param {unknown} value
+ * @param {boolean} fallback
+ * @returns {boolean}
+ */
+function getBooleanSetting (value, fallback) {
+  return typeof value === 'boolean' ? value : fallback
+}
+
+/**
+ * @param {ServiceSchemaKey} key
+ * @returns {boolean}
+ */
+function getServiceDefault (key) {
+  const entry = serviceSchema[key]
+  if (entry?.default !== undefined && typeof entry.default === 'boolean') {
+    return entry.default
+  }
+  return false
+}
 
 /**
  * Yoto Player Accessory Handler
@@ -39,6 +79,7 @@ export class YotoPlayerAccessory {
   /** @type {Service | undefined} */ playbackService
   /** @type {Service | undefined} */ volumeService
   /** @type {Service | undefined} */ batteryService
+  /** @type {Service | undefined} */ onlineStatusService
   /** @type {Service | undefined} */ temperatureSensorService
   /** @type {Service | undefined} */ dayNightlightService
   /** @type {Service | undefined} */ nightNightlightService
@@ -77,6 +118,29 @@ export class YotoPlayerAccessory {
     this.#currentServices = new Set()
   }
 
+  /**
+   * @returns {YotoServiceToggles}
+   */
+  getServiceToggles () {
+    const config = this.#platform.config
+    const services = config && typeof config === 'object' ? config['services'] : undefined
+    const serviceConfig = typeof services === 'object' && services !== null
+      ? /** @type {Record<string, unknown>} */ (services)
+      : {}
+
+    return {
+      playback: getBooleanSetting(serviceConfig.playback, getServiceDefault('playback')),
+      volume: getBooleanSetting(serviceConfig.volume, getServiceDefault('volume')),
+      temperature: getBooleanSetting(serviceConfig.temperature, getServiceDefault('temperature')),
+      nightlight: getBooleanSetting(serviceConfig.nightlight, getServiceDefault('nightlight')),
+      cardSlot: getBooleanSetting(serviceConfig.cardSlot, getServiceDefault('cardSlot')),
+      nightMode: getBooleanSetting(serviceConfig.nightMode, getServiceDefault('nightMode')),
+      sleepTimer: getBooleanSetting(serviceConfig.sleepTimer, getServiceDefault('sleepTimer')),
+      bluetooth: getBooleanSetting(serviceConfig.bluetooth, getServiceDefault('bluetooth')),
+      volumeLimits: getBooleanSetting(serviceConfig.volumeLimits, getServiceDefault('volumeLimits')),
+    }
+  }
+
   /**
    * Setup accessory - create services and setup event listeners
    * @returns {Promise<void>}
@@ -96,25 +160,46 @@ export class YotoPlayerAccessory {
     this.#currentServices.clear()
 
     // 1. Setup services
+    const serviceToggles = this.getServiceToggles()
+
     this.setupAccessoryInformation()
-    this.setupPlaybackServices()
+    this.setupOnlineStatusService()
+
+    if (serviceToggles.playback) {
+      this.setupPlaybackSwitchService()
+    }
+
+    if (serviceToggles.volume) {
+      this.setupVolumeService()
+    }
+
     this.setupBatteryService()
 
     // Setup optional services based on device capabilities
-    if (this.#deviceModel.capabilities.hasTemperatureSensor) {
+    if (serviceToggles.temperature && this.#deviceModel.capabilities.hasTemperatureSensor) {
       this.setupTemperatureSensorService()
     }
 
-    if (this.#deviceModel.capabilities.hasColoredNightlight) {
+    if (serviceToggles.nightlight && this.#deviceModel.capabilities.hasColoredNightlight) {
       this.setupNightlightServices()
     }
 
     // Setup universal services (available on all devices)
-    this.setupCardSlotService()
-    this.setupNightModeService()
-    this.setupSleepTimerService()
-    this.setupBluetoothService()
-    this.setupVolumeLimitServices()
+    if (serviceToggles.cardSlot) {
+      this.setupCardSlotService()
+    }
+    if (serviceToggles.nightMode) {
+      this.setupNightModeService()
+    }
+    if (serviceToggles.sleepTimer) {
+      this.setupSleepTimerService()
+    }
+    if (serviceToggles.bluetooth) {
+      this.setupBluetoothService()
+    }
+    if (serviceToggles.volumeLimits) {
+      this.setupVolumeLimitServices()
+    }
 
     // Remove any services that aren't in our current set
     // (except AccessoryInformation which should always be preserved)
@@ -178,15 +263,29 @@ export class YotoPlayerAccessory {
   }
 
   /**
-   * Setup basic playback services (non-SmartSpeaker)
+   * Setup online/offline ContactSensor service (PRIMARY)
    */
-  setupPlaybackServices () {
-    this.setupPlaybackSwitchService()
-    this.setupVolumeService()
+  setupOnlineStatusService () {
+    const { Service, Characteristic } = this.#platform
+    const serviceName = this.generateServiceName('Online Status')
+
+    const service = this.#accessory.getServiceById(Service.ContactSensor, 'OnlineStatus') ||
+      this.#accessory.addService(Service.ContactSensor, serviceName, 'OnlineStatus')
+
+    service.setPrimaryService(true)
+
+    syncServiceNames({ Characteristic, service, name: serviceName })
+
+    service
+      .getCharacteristic(Characteristic.ContactSensorState)
+      .onGet(this.getOnlineStatus.bind(this))
+
+    this.onlineStatusService = service
+    this.#currentServices.add(service)
   }
 
   /**
-   * Setup play/pause Switch service (PRIMARY)
+   * Setup play/pause Switch service
    */
   setupPlaybackSwitchService () {
     const { Service, Characteristic } = this.#platform
@@ -195,15 +294,8 @@ export class YotoPlayerAccessory {
     const service = this.#accessory.getServiceById(Service.Switch, 'Playback') ||
       this.#accessory.addService(Service.Switch, serviceName, 'Playback')
 
-    service.setPrimaryService(true)
-
     syncServiceNames({ Characteristic, service, name: serviceName })
 
-    service.addOptionalCharacteristic(Characteristic.StatusActive)
-    service
-      .getCharacteristic(Characteristic.StatusActive)
-      .onGet(this.getStatusActive.bind(this))
-
     service
       .getCharacteristic(Characteristic.On)
       .onGet(this.getPlaybackOn.bind(this))
@@ -214,28 +306,23 @@ export class YotoPlayerAccessory {
   }
 
   /**
-   * Setup Fanv2 service for volume/mute controls (Speaker service isn't shown in Home)
+   * Setup Lightbulb service for volume/mute controls (Speaker service isn't shown in Home)
    */
   setupVolumeService () {
     const { Service, Characteristic } = this.#platform
     const serviceName = this.generateServiceName('Volume')
 
-    const service = this.#accessory.getServiceById(Service.Fanv2, 'Volume') ||
-      this.#accessory.addService(Service.Fanv2, serviceName, 'Volume')
+    const service = this.#accessory.getServiceById(Service.Lightbulb, 'Volume') ||
+      this.#accessory.addService(Service.Lightbulb, serviceName, 'Volume')
     syncServiceNames({ Characteristic, service, name: serviceName })
 
-    service.addOptionalCharacteristic(Characteristic.StatusActive)
-    service
-      .getCharacteristic(Characteristic.StatusActive)
-      .onGet(this.getStatusActive.bind(this))
-
     service
-      .getCharacteristic(Characteristic.Active)
-      .onGet(this.getVolumeActive.bind(this))
-      .onSet(this.setVolumeActive.bind(this))
+      .getCharacteristic(Characteristic.On)
+      .onGet(this.getVolumeOn.bind(this))
+      .onSet(this.setVolumeOn.bind(this))
 
     service
-      .getCharacteristic(Characteristic.RotationSpeed)
+      .getCharacteristic(Characteristic.Brightness)
       .setProps({
         minValue: 0,
         maxValue: 16,
@@ -256,7 +343,7 @@ export class YotoPlayerAccessory {
     const serviceName = this.generateServiceName('Battery')
     const service = this.#accessory.getService(Service.Battery) ||
       this.#accessory.addService(Service.Battery, serviceName)
-    syncServiceNames({ Characteristic, service, name: serviceName })
+    service.setCharacteristic(Characteristic.Name, serviceName)
 
     // BatteryLevel (GET only)
     service.getCharacteristic(Characteristic.BatteryLevel)
@@ -428,18 +515,18 @@ export class YotoPlayerAccessory {
   }
 
   /**
-   * Setup night mode OccupancySensor service
+   * Setup night mode ContactSensor service
    * Shows if device is in night mode (vs day mode)
    */
   setupNightModeService () {
     const { Service, Characteristic } = this.#platform
     const serviceName = this.generateServiceName('Night Mode')
 
-    const service = this.#accessory.getServiceById(Service.OccupancySensor, 'NightModeStatus') ||
-      this.#accessory.addService(Service.OccupancySensor, serviceName, 'NightModeStatus')
+    const service = this.#accessory.getServiceById(Service.ContactSensor, 'NightModeStatus') ||
+      this.#accessory.addService(Service.ContactSensor, serviceName, 'NightModeStatus')
     syncServiceNames({ Characteristic, service, name: serviceName })
 
-    service.getCharacteristic(Characteristic.OccupancyDetected)
+    service.getCharacteristic(Characteristic.ContactSensorState)
       .onGet(this.getNightModeStatus.bind(this))
 
     this.nightModeService = service
@@ -487,7 +574,7 @@ export class YotoPlayerAccessory {
   }
 
   /**
-   * Setup volume limit Fanv2 services
+   * Setup volume limit Lightbulb services
    * Control day and night mode max volume limits
    */
   setupVolumeLimitServices () {
@@ -495,16 +582,22 @@ export class YotoPlayerAccessory {
 
     // Day Max Volume
     const dayName = this.generateServiceName('Day Max Volume')
-    const dayService = this.#accessory.getServiceById(Service.Fanv2, 'DayMaxVolume') ||
-      this.#accessory.addService(Service.Fanv2, dayName, 'DayMaxVolume')
+    const dayService = this.#accessory.getServiceById(Service.Lightbulb, 'DayMaxVolume') ||
+      this.#accessory.addService(Service.Lightbulb, dayName, 'DayMaxVolume')
     syncServiceNames({ Characteristic, service: dayService, name: dayName })
 
     dayService
-      .getCharacteristic(Characteristic.Active)
-      .onGet(() => Characteristic.Active.ACTIVE)
+      .getCharacteristic(Characteristic.On)
+      .onGet(() => true)
+      .onSet((value) => {
+        if (!value) {
+          dayService.updateCharacteristic(Characteristic.On, true)
+        }
+      })
+    dayService.setCharacteristic(Characteristic.On, true)
 
     dayService
-      .getCharacteristic(Characteristic.RotationSpeed)
+      .getCharacteristic(Characteristic.Brightness)
       .setProps({ minValue: 0, maxValue: 16, minStep: 1 })
       .onGet(this.getDayMaxVolume.bind(this))
       .onSet(this.setDayMaxVolume.bind(this))
@@ -513,16 +606,22 @@ export class YotoPlayerAccessory {
 
     // Night Max Volume
     const nightName = this.generateServiceName('Night Max Volume')
-    const nightService = this.#accessory.getServiceById(Service.Fanv2, 'NightMaxVolume') ||
-      this.#accessory.addService(Service.Fanv2, nightName, 'NightMaxVolume')
+    const nightService = this.#accessory.getServiceById(Service.Lightbulb, 'NightMaxVolume') ||
+      this.#accessory.addService(Service.Lightbulb, nightName, 'NightMaxVolume')
     syncServiceNames({ Characteristic, service: nightService, name: nightName })
 
     nightService
-      .getCharacteristic(Characteristic.Active)
-      .onGet(() => Characteristic.Active.ACTIVE)
+      .getCharacteristic(Characteristic.On)
+      .onGet(() => true)
+      .onSet((value) => {
+        if (!value) {
+          nightService.updateCharacteristic(Characteristic.On, true)
+        }
+      })
+    nightService.setCharacteristic(Characteristic.On, true)
 
     nightService
-      .getCharacteristic(Characteristic.RotationSpeed)
+      .getCharacteristic(Characteristic.Brightness)
       .setProps({ minValue: 0, maxValue: 16, minStep: 1 })
       .onGet(this.getNightMaxVolume.bind(this))
       .onSet(this.setNightMaxVolume.bind(this))
@@ -582,7 +681,7 @@ export class YotoPlayerAccessory {
             break
 
           case 'dayMode':
-            // Update night mode OccupancySensor
+            // Update night mode ContactSensor
             this.updateNightModeCharacteristic()
             // Update nightlight status ContactSensors (depends on dayMode)
             if (this.#deviceModel.capabilities.hasColoredNightlight) {
@@ -861,17 +960,13 @@ export class YotoPlayerAccessory {
       if (this.volumeService) {
         const { Characteristic } = this.#platform
 
-        const active = steps === 0
-          ? Characteristic.Active.INACTIVE
-          : Characteristic.Active.ACTIVE
-
         this.volumeService
-          .getCharacteristic(Characteristic.Active)
-          .updateValue(active)
+          .getCharacteristic(Characteristic.On)
+          .updateValue(steps > 0)
 
         if (steps !== requestedSteps) {
           this.volumeService
-            .getCharacteristic(Characteristic.RotationSpeed)
+            .getCharacteristic(Characteristic.Brightness)
             .updateValue(steps)
         }
       }
@@ -884,45 +979,34 @@ export class YotoPlayerAccessory {
   }
 
   /**
-   * Get volume Active state (derived from volume === 0)
+   * Get volume On state (derived from volume > 0)
    * @returns {Promise<CharacteristicValue>}
    */
-  async getVolumeActive () {
-    const { Characteristic } = this.#platform
-    return this.#deviceModel.status.volume === 0
-      ? Characteristic.Active.INACTIVE
-      : Characteristic.Active.ACTIVE
+  async getVolumeOn () {
+    return this.#deviceModel.status.volume > 0
   }
 
   /**
-   * Set volume Active state (mute/unmute)
+   * Set volume On state (mute/unmute)
    * @param {CharacteristicValue} value
    * @returns {Promise<void>}
    */
-  async setVolumeActive (value) {
-    this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Set volume active:`, value)
+  async setVolumeOn (value) {
+    this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Set volume on:`, value)
 
-    const { Characteristic } = this.#platform
-    const active = typeof value === 'number' ? value : Number(value)
-    if (!Number.isFinite(active)) {
-      throw new this.#platform.api.hap.HapStatusError(
-        this.#platform.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST
-      )
-    }
+    const isOn = Boolean(value)
+    const currentVolume = this.#deviceModel.status.volume
 
-    if (active === Characteristic.Active.INACTIVE) {
-      await this.setVolume(0)
+    if (!isOn) {
+      if (currentVolume !== 0) {
+        await this.setVolume(0)
+      }
       return
     }
 
-    if (active === Characteristic.Active.ACTIVE) {
+    if (currentVolume === 0) {
       await this.setVolume(this.#lastNonZeroVolume)
-      return
     }
-
-    throw new this.#platform.api.hap.HapStatusError(
-      this.#platform.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST
-    )
   }
 
   /**
@@ -933,6 +1017,17 @@ export class YotoPlayerAccessory {
     return this.#deviceModel.status.isOnline
   }
 
+  /**
+   * Get online status as a ContactSensorState
+   * @returns {Promise<CharacteristicValue>}
+   */
+  async getOnlineStatus () {
+    const { Characteristic } = this.#platform
+    return this.#deviceModel.status.isOnline
+      ? Characteristic.ContactSensorState.CONTACT_DETECTED
+      : Characteristic.ContactSensorState.CONTACT_NOT_DETECTED
+  }
+
   // ==================== Battery Characteristic Handlers ====================
 
   /**
@@ -940,7 +1035,8 @@ export class YotoPlayerAccessory {
    * @returns {Promise<CharacteristicValue>}
    */
   async getBatteryLevel () {
-    return this.#deviceModel.status.batteryLevelPercentage || 100
+    const battery = this.#deviceModel.status.batteryLevelPercentage
+    return Number.isFinite(battery) ? battery : 100
   }
 
   /**
@@ -959,8 +1055,9 @@ export class YotoPlayerAccessory {
    * @returns {Promise<CharacteristicValue>}
    */
   async getStatusLowBattery () {
-    const battery = this.#deviceModel.status.batteryLevelPercentage || 100
-    return battery <= LOW_BATTERY_THRESHOLD
+    const battery = this.#deviceModel.status.batteryLevelPercentage
+    const batteryLevel = Number.isFinite(battery) ? battery : 100
+    return batteryLevel <= LOW_BATTERY_THRESHOLD
       ? this.#platform.Characteristic.StatusLowBattery.BATTERY_LEVEL_LOW
       : this.#platform.Characteristic.StatusLowBattery.BATTERY_LEVEL_NORMAL
   }
@@ -1077,7 +1174,14 @@ export class YotoPlayerAccessory {
    * @param {CharacteristicValue} value
    */
   async setDayNightlightBrightness (value) {
-    const brightnessValue = Math.round(Number(value))
+    const rawBrightness = Number(value)
+    if (!Number.isFinite(rawBrightness)) {
+      throw new this.#platform.api.hap.HapStatusError(
+        this.#platform.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST
+      )
+    }
+
+    const brightnessValue = Math.max(0, Math.min(Math.round(rawBrightness), 100))
     this.#log.debug(LOG_PREFIX.ACCESSORY, `Setting day display brightness: ${brightnessValue}`)
     await this.#deviceModel.updateConfig({
       dayDisplayBrightness: brightnessValue,
@@ -1104,7 +1208,13 @@ export class YotoPlayerAccessory {
    * @param {CharacteristicValue} value
    */
   async setDayNightlightHue (value) {
-    const hue = Number(value)
+    const rawHue = Number(value)
+    if (!Number.isFinite(rawHue)) {
+      throw new this.#platform.api.hap.HapStatusError(
+        this.#platform.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST
+      )
+    }
+    const hue = Math.max(0, Math.min(rawHue, 360))
 
     // Get current saturation to maintain it
     const currentColor = this.#deviceModel.config.ambientColour
@@ -1142,7 +1252,13 @@ export class YotoPlayerAccessory {
    * @param {CharacteristicValue} value
    */
   async setDayNightlightSaturation (value) {
-    const saturation = Number(value)
+    const rawSaturation = Number(value)
+    if (!Number.isFinite(rawSaturation)) {
+      throw new this.#platform.api.hap.HapStatusError(
+        this.#platform.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST
+      )
+    }
+    const saturation = Math.max(0, Math.min(rawSaturation, 100))
 
     // Get current hue to maintain it
     const currentColor = this.#deviceModel.config.ambientColour
@@ -1210,7 +1326,14 @@ export class YotoPlayerAccessory {
    * @param {CharacteristicValue} value
    */
   async setNightNightlightBrightness (value) {
-    const brightnessValue = Math.round(Number(value))
+    const rawBrightness = Number(value)
+    if (!Number.isFinite(rawBrightness)) {
+      throw new this.#platform.api.hap.HapStatusError(
+        this.#platform.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST
+      )
+    }
+
+    const brightnessValue = Math.max(0, Math.min(Math.round(rawBrightness), 100))
     this.#log.debug(LOG_PREFIX.ACCESSORY, `Setting night display brightness: ${brightnessValue}`)
     await this.#deviceModel.updateConfig({
       nightDisplayBrightness: brightnessValue,
@@ -1237,7 +1360,13 @@ export class YotoPlayerAccessory {
    * @param {CharacteristicValue} value
    */
   async setNightNightlightHue (value) {
-    const hue = Number(value)
+    const rawHue = Number(value)
+    if (!Number.isFinite(rawHue)) {
+      throw new this.#platform.api.hap.HapStatusError(
+        this.#platform.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST
+      )
+    }
+    const hue = Math.max(0, Math.min(rawHue, 360))
 
     // Get current saturation to maintain it
     const currentColor = this.#deviceModel.config.nightAmbientColour
@@ -1275,7 +1404,13 @@ export class YotoPlayerAccessory {
    * @param {CharacteristicValue} value
    */
   async setNightNightlightSaturation (value) {
-    const saturation = Number(value)
+    const rawSaturation = Number(value)
+    if (!Number.isFinite(rawSaturation)) {
+      throw new this.#platform.api.hap.HapStatusError(
+        this.#platform.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST
+      )
+    }
+    const saturation = Math.max(0, Math.min(rawSaturation, 100))
 
     // Get current hue to maintain it
     const currentColor = this.#deviceModel.config.nightAmbientColour
@@ -1346,7 +1481,7 @@ export class YotoPlayerAccessory {
     return hasCard ? Characteristic.ContactSensorState.CONTACT_DETECTED : Characteristic.ContactSensorState.CONTACT_NOT_DETECTED
   }
 
-  // ==================== Night Mode OccupancySensor Getter ====================
+  // ==================== Night Mode ContactSensor Getter ====================
 
   /**
    * Get night mode status
@@ -1356,7 +1491,9 @@ export class YotoPlayerAccessory {
     const { Characteristic } = this.#platform
     const status = this.#deviceModel.status
     const isNightMode = status.dayMode === 'night'
-    return isNightMode ? Characteristic.OccupancyDetected.OCCUPANCY_DETECTED : Characteristic.OccupancyDetected.OCCUPANCY_NOT_DETECTED
+    return isNightMode
+      ? Characteristic.ContactSensorState.CONTACT_DETECTED
+      : Characteristic.ContactSensorState.CONTACT_NOT_DETECTED
   }
 
   // ==================== Sleep Timer Switch Getter/Setter ====================
@@ -1402,7 +1539,7 @@ export class YotoPlayerAccessory {
    * @returns {Promise<CharacteristicValue>}
    */
   async getBluetoothState () {
-    return this.#deviceModel.config.bluetoothEnabled
+    return this.#deviceModel.config.bluetoothEnabled ?? false
   }
 
   /**
@@ -1415,7 +1552,7 @@ export class YotoPlayerAccessory {
     await this.#deviceModel.updateConfig({ bluetoothEnabled: enabled })
   }
 
-  // ==================== Volume Limit Fanv2 Getters/Setters ====================
+  // ==================== Volume Limit Lightbulb Getters/Setters ====================
 
   /**
    * Get day max volume limit
@@ -1498,7 +1635,7 @@ export class YotoPlayerAccessory {
     }
 
     this.volumeService
-      .getCharacteristic(Characteristic.RotationSpeed)
+      .getCharacteristic(Characteristic.Brightness)
       .updateValue(volumeSteps)
   }
 
@@ -1513,7 +1650,7 @@ export class YotoPlayerAccessory {
     const maxVolumeSteps = Number.isFinite(maxVolume) ? maxVolume : 16
     const clampedMaxVolume = Math.max(0, Math.min(maxVolumeSteps, 16))
     this.volumeService
-      .getCharacteristic(Characteristic.RotationSpeed)
+      .getCharacteristic(Characteristic.Brightness)
       .setProps({
         minValue: 0,
         maxValue: clampedMaxVolume,
@@ -1531,12 +1668,9 @@ export class YotoPlayerAccessory {
     if (!this.volumeService) return
 
     const { Characteristic } = this.#platform
-    const active = volume === 0
-      ? Characteristic.Active.INACTIVE
-      : Characteristic.Active.ACTIVE
     this.volumeService
-      .getCharacteristic(Characteristic.Active)
-      .updateValue(active)
+      .getCharacteristic(Characteristic.On)
+      .updateValue(volume > 0)
   }
 
   /**
@@ -1590,17 +1724,12 @@ export class YotoPlayerAccessory {
    * Update online status characteristic for all device-state services
    *
    * Services that need StatusActive (read device state, unavailable when offline):
-   * - Switch services (playback, seek)
-   * - Speaker (volume, mute)
-   * - Battery (battery level, charging state)
    * - TemperatureSensor (temperature reading)
-   * - ContactSensor (card insertion state) - when implemented
-   * - OccupancySensor (day/night mode from device) - when implemented
-   * - Switch (Sleep Timer - reads device playback state) - when implemented
+   * - ContactSensor (online status, card insertion, day/night mode, nightlight status)
    *
    * Services that DON'T need StatusActive (config-based, work offline):
    * - Lightbulb services (ambient lights - config only)
-   * - Fanv2 services (max volume - config only)
+   * - Lightbulb services (max volume - config only)
    * - Switch (Bluetooth - config only)
    * - StatelessProgrammableSwitch (shortcuts - config only)
    *
@@ -1609,26 +1738,14 @@ export class YotoPlayerAccessory {
   updateOnlineStatusCharacteristic (isOnline) {
     const { Characteristic } = this.#platform
 
-    // Update playback/volume services (device state)
-    if (this.playbackService) {
-      this.playbackService
-        .getCharacteristic(Characteristic.StatusActive)
-        .updateValue(isOnline)
-    }
-    if (this.volumeService) {
-      this.volumeService
-        .getCharacteristic(Characteristic.StatusActive)
-        .updateValue(isOnline)
+    if (this.onlineStatusService) {
+      this.onlineStatusService
+        .getCharacteristic(Characteristic.ContactSensorState)
+        .updateValue(isOnline
+          ? Characteristic.ContactSensorState.CONTACT_DETECTED
+          : Characteristic.ContactSensorState.CONTACT_NOT_DETECTED)
     }
 
-    // Update Battery (battery level, charging state)
-    // Battery Doesn't support this
-    // if (this.batteryService) {
-    //   this.batteryService
-    //     .getCharacteristic(Characteristic.StatusActive)
-    //     .updateValue(isOnline)
-    // }
-
     // Update TemperatureSensor (temperature reading)
     if (this.temperatureSensorService) {
       this.temperatureSensorService
@@ -1660,21 +1777,14 @@ export class YotoPlayerAccessory {
         .updateValue(isOnline)
     }
 
-    // Update night mode OccupancySensor (device state)
+    // Update night mode ContactSensor (device state)
     if (this.nightModeService) {
       this.nightModeService
         .getCharacteristic(Characteristic.StatusActive)
         .updateValue(isOnline)
     }
 
-    // Update sleep timer Switch (reads device playback state)
-    if (this.sleepTimerService) {
-      this.sleepTimerService
-        .getCharacteristic(Characteristic.StatusActive)
-        .updateValue(isOnline)
-    }
-
-    // Note: Config-based services (Nightlight Lightbulbs, Fanv2, Bluetooth Switch, Shortcuts)
+    // Note: Config-based services (Nightlight Lightbulbs, Volume Limit Lightbulbs, Bluetooth Switch, Shortcuts)
     // do NOT get StatusActive updated - they work offline since they only read/write config
 
     // TODO: Add shortcut services when implemented
@@ -1753,7 +1863,7 @@ export class YotoPlayerAccessory {
   }
 
   /**
-   * Update night mode OccupancySensor characteristic
+   * Update night mode ContactSensor characteristic
    */
   updateNightModeCharacteristic () {
     if (!this.nightModeService) {
@@ -1765,8 +1875,8 @@ export class YotoPlayerAccessory {
     const isNightMode = status.dayMode === 'night'
 
     this.nightModeService
-      .getCharacteristic(Characteristic.OccupancyDetected)
-      .updateValue(isNightMode ? Characteristic.OccupancyDetected.OCCUPANCY_DETECTED : Characteristic.OccupancyDetected.OCCUPANCY_NOT_DETECTED)
+      .getCharacteristic(Characteristic.ContactSensorState)
+      .updateValue(isNightMode ? Characteristic.ContactSensorState.CONTACT_DETECTED : Characteristic.ContactSensorState.CONTACT_NOT_DETECTED)
   }
 
   /**
@@ -1782,7 +1892,7 @@ export class YotoPlayerAccessory {
 
     this.sleepTimerService
       .getCharacteristic(Characteristic.On)
-      .updateValue(playback.sleepTimerActive)
+      .updateValue(playback.sleepTimerActive ?? false)
   }
 
   /**
@@ -1794,7 +1904,7 @@ export class YotoPlayerAccessory {
     }
 
     const { Characteristic } = this.#platform
-    const enabled = this.#deviceModel.config.bluetoothEnabled
+    const enabled = this.#deviceModel.config.bluetoothEnabled ?? false
 
     this.bluetoothService
       .getCharacteristic(Characteristic.On)
@@ -1802,7 +1912,7 @@ export class YotoPlayerAccessory {
   }
 
   /**
-   * Update volume limit Fanv2 characteristics
+   * Update volume limit Lightbulb characteristics
    */
   updateVolumeLimitCharacteristics () {
     const config = this.#deviceModel.config
@@ -1811,14 +1921,14 @@ export class YotoPlayerAccessory {
     if (this.dayMaxVolumeService) {
       const limit = Number.isFinite(config.maxVolumeLimit) ? config.maxVolumeLimit : 16
       this.dayMaxVolumeService
-        .getCharacteristic(Characteristic.RotationSpeed)
+        .getCharacteristic(Characteristic.Brightness)
         .updateValue(limit)
     }
 
     if (this.nightMaxVolumeService) {
       const limit = Number.isFinite(config.nightMaxVolumeLimit) ? config.nightMaxVolumeLimit : 10
       this.nightMaxVolumeService
-        .getCharacteristic(Characteristic.RotationSpeed)
+        .getCharacteristic(Characteristic.Brightness)
         .updateValue(limit)
     }
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-yoto",
   "description": "Control your Yoto players through Apple HomeKit with real-time MQTT updates",
-  "version": "0.0.35",
+  "version": "0.0.36",
   "author": "Bret Comnes <bcomnes@gmail.com> (https://bret.io)",
   "bugs": {
     "url": "https://github.com/bcomnes/homebridge-yoto/issues"