@mdjhnson/homebridge-yoto 0.1.2 → 0.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 <img src="https://github.com/homebridge/branding/raw/latest/logos/homebridge-wordmark-logo-vertical.png" width="150">
 
-<img src="./logo.png" width="150">
+<img src="https://raw.githubusercontent.com/mdjhnson/homebridge-yoto/master/logo.png" width="150">
 
 </p>
 
@@ -33,16 +33,16 @@ Search for `@mdjhnson/homebridge-yoto` in the Homebridge UI **Plugins** tab, or
 npm install -g @mdjhnson/homebridge-yoto
 ```
 
-Requires Node.js 22+ and Homebridge 1.8+ or 2.x.
+Requires Node.js 22, 24 or 26 and Homebridge 1.8+ or 2.x.
 
 ## Sign in
 
 1. Open the plugin's **Settings** in the Homebridge UI and click **Sign in with Yoto**. Yoto's sign-in page opens in a new tab.
 2. Sign in and approve access.
-3. Your browser then shows *"This site can't be reached"* at `127.0.0.1`. That's expected. Copy the full address from the address bar, paste it into the plugin settings, and click **Finish Sign-in**.
+3. Your browser then shows *"This site can't be reached"* at `127.0.0.1`. That's expected. Copy the full address from the address bar, paste it into the **Address from your browser** box on the sign-in screen, and click **Finish Sign-in**.
 4. Restart Homebridge.
 
-Using your own Yoto developer app? Make it a **Public Client**, add `http://127.0.0.1:8787/callback` as an allowed callback URL, enable the `family:devices:*`, `family:library:view`, `user:content:view` and `offline_access` scopes, and enter its client ID under **Advanced Settings** before signing in.
+Using your own Yoto developer app? Make it a **Public Client**, add `http://127.0.0.1:8787/callback` as an allowed callback URL, enable the `family:devices:*`, `family:library:view`, `user:content:view` and `offline_access` scopes, and enter its client ID in the **Advanced Settings** panel on the sign-in screen before signing in. (That panel is only shown while you're signed out, and is separate from the **Advanced** section of the plugin settings.)
 
 The plugin asks for access to view, configure and control your players, plus read-only access to your card library (used to name shortcut switches). If you signed in with an older version, sign in again so the new permissions apply.
 
@@ -50,14 +50,13 @@ The plugin refreshes its tokens on its own. If the login ever expires or is revo
 
 ## Settings
 
-All options live under **Accessory Services** in the plugin settings.
+Most options live under **Accessory Services** in the plugin settings. The settings form, including **Advanced**, appears once you've signed in.
 
 **Playback**
-- **Playback Controls**: Adds a play/pause switch and a volume dimmer to each player's bridged accessory.
-- **External Smart Speaker**: Publishes a separate Smart Speaker accessory for Home app scenes and automations (pause, resume, set volume). The Home app shows *"Controls not available"* when you open it, because iOS only offers live controls for AirPlay speakers. It does not make the Yoto an AirPlay target.
-- **TV Playback Accessory**: Publishes a separate TV-style accessory. Its inputs play your card controls and shortcuts, and you control it with the iOS remote.
+- **Playback Controls**: Adds a play/pause switch and a volume dimmer to each player's bridged accessory. This is the simplest option and needs no extra pairing.
+- **TV Playback Accessory**: Publishes a separate TV-style accessory. You control it with the iOS remote (play/pause, volume buttons), and its inputs play your card controls and shortcuts.
 
-External accessories must be added by hand in the Home app (**Add Accessory → More options**) using the setup code in the Homebridge log. Each one listens on its own port (logged as `... is running on port N`), so open those ports if Homebridge runs behind a firewall, or set a fixed port range under Homebridge **Settings → Network**.
+The TV accessory, and the legacy Smart Speaker below, are external accessories. External accessories must be added by hand in the Home app (**Add Accessory → More options**) using the setup code in the Homebridge log. Each one listens on its own port (logged as `... is running on port N`), so open those ports if Homebridge runs behind a firewall, or set a fixed port range under Homebridge **Settings → Network**.
 
 **Card Controls** (`services.cardControls`)
 - A switch on each player that plays the card ID you configure.
@@ -70,8 +69,9 @@ External accessories must be added by hand in the Home app (**Add Accessory →
 **Service toggles**
 - **Battery**, **Temperature Sensor** (v3), **Nightlight** (v3), **Card Slot**, **Day Mode**, **Sleep Timer**, **Bluetooth**, **Volume Limits**.
 
-**Advanced**
+**Advanced** (collapsed section at the bottom of the plugin settings)
 - **HTTP Poll Interval**: How often to poll the Yoto API as a fallback to MQTT. Defaults to 60 seconds; the minimum is 10 seconds.
+- **External Smart Speaker (Legacy)**: Kept for existing setups. It publishes a separate Smart Speaker accessory that only works in Home app scenes and automations. When you open it, the Home app shows *"Controls not available"* and can't show what's playing, because iOS only offers live controls for AirPlay speakers. It does not make the Yoto an AirPlay target. For more features, use the **TV Playback Accessory** instead. If you switch, remove the old Smart Speaker from the Home app by hand (Homebridge can't unpublish external accessories).
 
 ## HomeKit services
 
@@ -79,7 +79,7 @@ External accessories must be added by hand in the Home app (**Add Accessory →
 - **Playback**: Switch. On resumes, Off pauses.
 - **Volume**: Lightbulb. On unmutes, Off mutes, and Brightness maps 0–100% to the player's volume steps.
 
-**Smart Speaker (external)**
+**Smart Speaker (external, legacy)**
 - Current/Target Media State, Volume, Mute, and online status. Stop pauses, so playback can be resumed.
 
 **TV Playback (external)**
@@ -110,6 +110,11 @@ External accessories must be added by hand in the Home app (**Add Accessory →
 
 - **Switching from `homebridge-yoto`:** uninstall the original plugin first. Both register the `Yoto` platform and would conflict. Your existing `Yoto` config block keeps working, but bridged accessories are re-created, so you'll need to re-add them to rooms and automations.
 - **Removed external accessories:** if you turn off the Smart Speaker or TV accessory, or a player leaves your account, remove the old accessory from the Home app by hand. Homebridge can't unpublish external accessories.
+- **Yoto unreachable at startup:** if the network or Yoto's API is down when Homebridge starts, the plugin keeps retrying, waiting longer each time (up to 10 minutes between tries). You don't need to restart Homebridge. If Yoto rejects the saved login, the log asks you to sign in again instead of retrying.
+
+## Privacy
+
+The plugin only connects to Yoto's API and MQTT service, using your own sign-in. It has no analytics or tracking. The only file it changes is Homebridge's `config.json`, to save refreshed sign-in tokens. It writes a temporary copy next to `config.json` first and renames it into place, so an interrupted save can't corrupt the file.
 
 ## Development
 

package/config.schema.json

@@ -61,13 +61,13 @@
             "title": "Playback Controls",
             "type": "boolean",
             "default": false,
-            "description": "Expose bridged playback switch and volume dimmer controls."
+            "description": "Add a play/pause switch and a volume dimmer to each player. Simplest option, with no extra pairing."
           },
           "smartSpeaker": {
-            "title": "External Smart Speaker",
+            "title": "External Smart Speaker (Legacy)",
             "type": "boolean",
             "default": false,
-            "description": "Publish an external Smart Speaker accessory for use in Home app scenes and automations (pause, resume, set volume). The Home app shows \"Controls not available\" for it; for tap-to-control use Playback Controls or the TV Playback Accessory. Requires pairing and its own network port."
+            "description": "Legacy option kept for existing setups. Publishes a separate Smart Speaker accessory that only works in Home app scenes and automations. Requires pairing and its own network port."
           },
           "television": {
             "title": "TV Playback Accessory",
@@ -171,7 +171,7 @@
       "items": [
         {
           "type": "help",
-          "helpvalue": "<p><strong>Authentication Instructions:</strong></p><ol><li>Click the <strong>\"Start Authentication\"</strong> button in the custom UI above</li><li>Follow the on-screen instructions to authorize with your Yoto account</li><li>Tokens will be saved automatically when authorization completes</li><li>Homebridge will restart and connect to your devices</li></ol><p><strong>Advanced:</strong> The default OAuth Client ID works for all users. The token fields below are automatically managed by the plugin and should not be edited manually.</p>"
+          "helpvalue": "Sign in and out from the Yoto panel above. The default OAuth Client ID works for all users. The token fields below are managed by the plugin and should not be edited by hand."
         },
         "clientId",
         "accessToken",
@@ -188,10 +188,9 @@
         },
         {
           "type": "help",
-          "helpvalue": "<p><strong>Playback Controls:</strong> Enable a bridged switch + dimmer for play/pause and volume. <strong>External Smart Speaker:</strong> a separate accessory for scenes and automations only (the Home app shows \"Controls not available\"). <strong>TV Playback Accessory:</strong> a separate accessory controlled with the iPhone remote, with inputs for card controls and shortcuts. External accessories need pairing and each uses its own network port.</p>"
+          "helpvalue": "<p>The older <strong>External Smart Speaker</strong> option has moved to the <em>Advanced</em> section below.</p>"
         },
         "services.playbackControls",
-        "services.smartSpeaker",
         "services.television",
         "services.volumeLimits",
         "services.battery",
@@ -225,7 +224,12 @@
       "expandable": true,
       "expanded": false,
       "items": [
-        "httpPollIntervalMs"
+        "httpPollIntervalMs",
+        {
+          "type": "help",
+          "helpvalue": "<p><strong>Legacy: External Smart Speaker.</strong> Older playback option kept for existing setups. It only works in scenes and automations. The Home app shows \"Controls not available\" for it and can't show what's playing, because iOS only offers those for AirPlay speakers. For more features, turn on the <strong>TV Playback Accessory</strong> under <em>Accessory Services</em> instead. It supports the iPhone remote, volume buttons, and inputs for card controls and shortcuts. If you switch, remove the old Smart Speaker from the Home app by hand.</p>"
+        },
+        "services.smartSpeaker"
       ]
     }
   ]

package/lib/accessory.js

@@ -50,7 +50,7 @@ import { getPlaybackAccessoryConfig } from './service-config.js'
 import { getCardControlConfigs } from './card-controls.js'
 import { getCardStartOptions, getShortcutEntries, getShortcutsSignature, toPlayableCard } from './shortcuts.js'
 import { formatError } from './utils/error-format.js'
-import { ListenerGroup } from './utils/listener-group.js'
+import { ListenerGroup, logListenerError } from './utils/listener-group.js'
 import { setDeviceVolume } from './utils/set-device-volume.js'
 import { getBooleanSetting } from './utils/get-boolean-setting.js'
 import {
@@ -118,7 +118,10 @@ export class YotoPlayerAccessory {
     this.#platform = platform
     this.#accessory = accessory
     this.#deviceModel = deviceModel
-    this.#listeners = new ListenerGroup(deviceModel)
+    this.#listeners = new ListenerGroup(
+      deviceModel,
+      logListenerError(platform.log, `${LOG_PREFIX.ACCESSORY} [${accessory.context.device.name}]`)
+    )
     this.#log = platform.log
 
     // Extract device info from context

package/lib/platform.js

@@ -5,6 +5,7 @@
 /** @import { API, DynamicPlatformPlugin, Logger, PlatformAccessory, PlatformConfig, Service, Characteristic } from 'homebridge' */
 /** @import { YotoDevice } from 'yoto-nodejs-client/lib/api-endpoints/devices.js' */
 /** @import { YotoDeviceModel } from 'yoto-nodejs-client' */
+/** @import { YotoAccountEventMap } from 'yoto-nodejs-client/lib/yoto-account.js' */
 /** @import { PlaybackAccessoryConfig } from './service-config.js' */
 /** @import { CardControlConfig } from './card-controls.js' */
 
@@ -29,6 +30,7 @@ import {
   PLATFORM_NAME,
   PLUGIN_NAME,
   DEFAULT_CLIENT_ID,
+  LOG_PREFIX,
 } from './settings.js'
 import { YotoPlayerAccessory } from './accessory.js'
 import { YotoSpeakerAccessory } from './speaker-accessory.js'
@@ -37,10 +39,28 @@ import { YotoCardControlAccessory } from './card-control-accessory.js'
 import { sanitizeName } from './utils/sanitize-name.js'
 import { getPlaybackAccessoryConfig } from './service-config.js'
 import { getCardControlConfigs } from './card-controls.js'
-import { formatError } from './utils/error-format.js'
+import { errorMessage, formatError, getStatusCode } from './utils/error-format.js'
+import { ListenerGroup, logListenerError } from './utils/listener-group.js'
 import { applyTokenUpdate } from './utils/token-config.js'
 import { tolerateMissingStatusScope } from './utils/status-scope-fallback.js'
 
+/** First retry delay when the Yoto API can't be reached at startup; doubles each attempt */
+const START_RETRY_BASE_MS = 30 * 1000
+/** Longest wait between startup retries */
+const START_RETRY_MAX_MS = 10 * 60 * 1000
+
+/**
+ * Whether a failed account start could succeed if tried again. Network errors
+ * and 5xx responses are transient; other 4xx responses won't change on retry.
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isRetryableStartError (error) {
+  const statusCode = getStatusCode(error)
+  if (statusCode === undefined) return true
+  return statusCode >= 500 || statusCode === 408 || statusCode === 429
+}
+
 /**
  * Yoto Platform implementation
  * This class is the main constructor for your plugin, this is where you should
@@ -63,8 +83,13 @@ export class YotoPlatform {
   /** @type {Map<string, YotoTelevisionAccessory>} */ televisionAccessoryHandlers = new Map()
   /** @type {Map<string, YotoCardControlAccessory>} */ cardAccessoryHandlers = new Map()
   /** @type {YotoAccount | null} */ yotoAccount = null
+  /** @type {ListenerGroup<YotoAccountEventMap> | null} */ accountListeners = null
   /** @type {string} */ sessionId = randomUUID()
   /** @type {Map<string, Promise<string | null>>} */ cardTitleCache = new Map()
+  /** @type {boolean} */ authInvalid = false
+  /** @type {number} */ startRetryCount = 0
+  /** @type {ReturnType<typeof setTimeout> | null} */ startRetryTimer = null
+  /** @type {boolean} */ shuttingDown = false
 
   /**
    * @param {Logger} log - Homebridge logger
@@ -102,63 +127,83 @@ export class YotoPlatform {
     const { sessionId } = this
     const updateHomebridgeConfig = this.updateHomebridgeConfig.bind(this)
 
-    // Initialize YotoAccount with client and device options
-    this.yotoAccount = new YotoAccount({
-      clientOptions: {
-        clientId,
-        refreshToken,
-        accessToken,
-        onTokenRefresh: async ({ updatedAccessToken, updatedRefreshToken, updatedExpiresAt, prevAccessToken, prevRefreshToken }) => {
-          // Client reports expiry in seconds; config.json stores milliseconds (matches the UI)
-          const tokenExpiresAt = updatedExpiresAt * 1000
-          log.debug('Access token refreshed, expires at:', new Date(tokenExpiresAt).toISOString())
-
-          // Keep the in-memory config in sync so later reads see current tokens
-          config['accessToken'] = updatedAccessToken
-          config['refreshToken'] = updatedRefreshToken
-          config['tokenExpiresAt'] = tokenExpiresAt
-
-          await updateHomebridgeConfig((configContents) => applyTokenUpdate(configContents, {
-            platform: PLATFORM_NAME,
-            accessToken: updatedAccessToken,
-            refreshToken: updatedRefreshToken,
-            tokenExpiresAt,
-            prevAccessToken,
-            prevRefreshToken,
-          }))
-        },
-        onRefreshStart: () => {
-          log.debug('Refreshing Yoto access token...')
-        },
-        onRefreshError: (error) => {
-          log.warn('Yoto token refresh failed, will retry:', error.message)
-          log.debug('Token refresh error details:', formatError(error))
-        },
-        onInvalid: (error) => {
-          log.error(
-            'Yoto login has expired or been revoked. Open the plugin settings in the Homebridge UI and sign in again.',
-            error.message
-          )
+    // Initialize YotoAccount with client and device options. It decodes the saved
+    // access token, which throws if config.json holds a malformed one; Homebridge
+    // doesn't catch errors from platform constructors, so it would crash on every start.
+    /** @type {YotoAccount} */
+    let account
+    try {
+      account = new YotoAccount({
+        clientOptions: {
+          clientId,
+          refreshToken,
+          accessToken,
+          onTokenRefresh: async ({ updatedAccessToken, updatedRefreshToken, updatedExpiresAt, prevAccessToken, prevRefreshToken }) => {
+            // Client reports expiry in seconds; config.json stores milliseconds (matches the UI)
+            const tokenExpiresAt = updatedExpiresAt * 1000
+            log.debug('Access token refreshed, expires at:', new Date(tokenExpiresAt).toISOString())
+
+            // Keep the in-memory config in sync so later reads see current tokens
+            config['accessToken'] = updatedAccessToken
+            config['refreshToken'] = updatedRefreshToken
+            config['tokenExpiresAt'] = tokenExpiresAt
+
+            await updateHomebridgeConfig((configContents) => applyTokenUpdate(configContents, {
+              platform: PLATFORM_NAME,
+              accessToken: updatedAccessToken,
+              refreshToken: updatedRefreshToken,
+              tokenExpiresAt,
+              prevAccessToken,
+              prevRefreshToken,
+            }))
+          },
+          onRefreshStart: () => {
+            log.debug('Refreshing Yoto access token...')
+          },
+          onRefreshError: (error) => {
+            log.warn('Yoto token refresh failed, will retry:', error.message)
+            log.debug('Token refresh error details:', formatError(error))
+          },
+          onInvalid: (error) => {
+            this.authInvalid = true
+            log.error(
+              'Yoto login has expired or been revoked. Open the plugin settings in the Homebridge UI and sign in again.',
+              error.message
+            )
+          },
         },
-      },
-      deviceOptions: {
-        httpPollIntervalMs: Math.max(10000, Number(config['httpPollIntervalMs']) || 60000),
-        yotoDeviceMqttOptions: {
-          sessionId
+        deviceOptions: {
+          httpPollIntervalMs: Math.max(10000, Number(config['httpPollIntervalMs']) || 60000),
+          yotoDeviceMqttOptions: {
+            sessionId
+          }
         }
-      }
-    })
+      })
+    } catch (error) {
+      log.error(
+        'Could not load the saved Yoto login. Open the plugin settings in the Homebridge UI and sign in again.',
+        errorMessage(error)
+      )
+      return
+    }
+    this.yotoAccount = account
+    // The account re-emits device events from MQTT and timer callbacks, so a
+    // throwing listener would be an uncaught exception that stops Homebridge
+    this.accountListeners = new ListenerGroup(account, logListenerError(log, LOG_PREFIX.PLATFORM))
 
     // The status endpoint needs a scope the Yoto dashboard doesn't offer yet
     tolerateMissingStatusScope(this.yotoAccount.client, (message) => log.debug(message))
 
     // Listen to account-level events
-    this.yotoAccount.on('error', ({ error, context }) => {
+    this.accountListeners.on('error', ({ error, context }) => {
       const details = formatError(error)
       if (context.deviceId) {
         const label = this.formatDeviceLabel(context.deviceId)
         log.error(`Device error [${label} ${context.operation} ${context.source}]:`, details)
         log.debug('Device error context:', context)
+      } else if (context.operation === 'start') {
+        // connectAccount() logs the failure and schedules a retry
+        log.debug('Account start error:', details)
       } else {
         log.error('Account error:', details)
         log.debug('Account error context:', context)
@@ -178,7 +223,9 @@ export class YotoPlatform {
     // When homebridge shuts down, cleanup all handlers and MQTT connections
     api.on('shutdown', () => {
       log.debug('Homebridge shutting down, cleaning up accessories...')
-      this.shutdown()
+      this.shutdown().catch(error => {
+        log.error('Error while shutting down:', formatError(error))
+      })
     })
   }
 
@@ -215,7 +262,8 @@ export class YotoPlatform {
    * Start YotoAccount - discovers devices and creates device models
    */
   async startAccount () {
-    if (!this.yotoAccount) {
+    const listeners = this.accountListeners
+    if (!this.yotoAccount || !listeners) {
       this.log.error('Cannot start account - YotoAccount not initialized')
       return
     }
@@ -229,37 +277,45 @@ export class YotoPlatform {
         `smartSpeaker=${this.playbackAccessoryConfig.smartSpeakerEnabled}`,
         `tvPlayback=${this.playbackAccessoryConfig.televisionEnabled}`
       )
+      if (this.playbackAccessoryConfig.smartSpeakerEnabled && !this.playbackAccessoryConfig.televisionEnabled) {
+        this.log.info('The External Smart Speaker is a legacy option: the Home app shows "Controls not available" for it. For the iPhone remote, volume buttons, and inputs for card controls and shortcuts, turn on the TV Playback Accessory instead.')
+      }
 
       // Listen for devices being added
-      this.yotoAccount.on('deviceAdded', async ({ deviceId }) => {
-        // Homebridge may shut down while the account is still starting
-        if (!this.yotoAccount) return
-        const deviceModel = this.yotoAccount.getDevice(deviceId)
-        if (!deviceModel) {
-          const label = this.formatDeviceLabel(deviceId)
-          this.log.warn(`Device added but no model found for ${label}`)
-          return
+      listeners.on('deviceAdded', async ({ deviceId }) => {
+        // The account doesn't await this listener, so errors must not escape it
+        try {
+          // Homebridge may shut down while the account is still starting
+          if (this.shuttingDown || !this.yotoAccount) return
+          const deviceModel = this.yotoAccount.getDevice(deviceId)
+          if (!deviceModel) {
+            const label = this.formatDeviceLabel(deviceId)
+            this.log.warn(`Device added but no model found for ${label}`)
+            return
+          }
+
+          const device = deviceModel.device
+          this.log.info(`Device discovered: ${device.name} (${deviceId})`)
+          this.log.debug('Registering device from account discovery:', device.name, deviceId)
+          await this.registerDevice(device, deviceModel)
+        } catch (error) {
+          this.log.error(`Failed to set up ${this.formatDeviceLabel(deviceId)}:`, formatError(error))
         }
-
-        const device = deviceModel.device
-        this.log.info(`Device discovered: ${device.name} (${deviceId})`)
-        this.log.debug('Registering device from account discovery:', device.name, deviceId)
-        await this.registerDevice(device, deviceModel)
       })
 
-      this.yotoAccount.on('deviceRemoved', ({ deviceId }) => {
+      listeners.on('deviceRemoved', ({ deviceId }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`Device removed: ${label}`)
         this.removeStaleAccessories()
       })
 
-      this.yotoAccount.on('online', ({ deviceId, metadata }) => {
+      listeners.on('online', ({ deviceId, metadata }) => {
         const label = this.formatDeviceLabel(deviceId)
         const reason = metadata?.reason ? ` (${metadata.reason})` : ''
         this.log.info(`Device online: ${label}${reason}`)
       })
 
-      this.yotoAccount.on('offline', ({ deviceId, metadata }) => {
+      listeners.on('offline', ({ deviceId, metadata }) => {
         const label = this.formatDeviceLabel(deviceId)
         const reason = metadata?.reason ? ` (${metadata.reason})` : ''
         this.log.info(`Device offline: ${label}${reason}`)
@@ -279,74 +335,74 @@ export class YotoPlatform {
         return ` fields: ${preview}${suffix}`
       }
 
-      this.yotoAccount.on('statusUpdate', ({ deviceId, source, changedFields }) => {
+      listeners.on('statusUpdate', ({ deviceId, source, changedFields }) => {
         const label = this.formatDeviceLabel(deviceId)
         const fields = Array.from(changedFields).join(', ')
         this.log.debug(`Status update [${label} ${source}]: ${fields}`)
       })
 
-      this.yotoAccount.on('configUpdate', ({ deviceId, changedFields }) => {
+      listeners.on('configUpdate', ({ deviceId, changedFields }) => {
         const label = this.formatDeviceLabel(deviceId)
         const fields = Array.from(changedFields).join(', ')
         this.log.debug(`Config update [${label}]: ${fields}`)
       })
 
-      this.yotoAccount.on('playbackUpdate', ({ deviceId, changedFields }) => {
+      listeners.on('playbackUpdate', ({ deviceId, changedFields }) => {
         const label = this.formatDeviceLabel(deviceId)
         const fields = Array.from(changedFields).join(', ')
         this.log.debug(`Playback update [${label}]: ${fields}`)
       })
 
-      this.yotoAccount.on('mqttConnect', ({ deviceId }) => {
+      listeners.on('mqttConnect', ({ deviceId }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT connected: ${label}`)
       })
 
-      this.yotoAccount.on('mqttDisconnect', ({ deviceId, metadata }) => {
+      listeners.on('mqttDisconnect', ({ deviceId, metadata }) => {
         const label = this.formatDeviceLabel(deviceId)
         const reasonCode = metadata?.packet?.reasonCode
         const reason = typeof reasonCode === 'number' ? ` (code ${reasonCode})` : ''
         this.log.warn(`MQTT disconnected: ${label}${reason}`)
       })
 
-      this.yotoAccount.on('mqttClose', ({ deviceId, metadata }) => {
+      listeners.on('mqttClose', ({ deviceId, metadata }) => {
         const label = this.formatDeviceLabel(deviceId)
         const reason = metadata?.reason ? ` (${metadata.reason})` : ''
         this.log.debug(`MQTT closed: ${label}${reason}`)
       })
 
-      this.yotoAccount.on('mqttReconnect', ({ deviceId }) => {
+      listeners.on('mqttReconnect', ({ deviceId }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT reconnecting: ${label}`)
       })
 
-      this.yotoAccount.on('mqttOffline', ({ deviceId }) => {
+      listeners.on('mqttOffline', ({ deviceId }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT offline: ${label}`)
       })
 
-      this.yotoAccount.on('mqttEnd', ({ deviceId }) => {
+      listeners.on('mqttEnd', ({ deviceId }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT ended: ${label}`)
       })
 
-      this.yotoAccount.on('mqttStatus', ({ deviceId, topic }) => {
+      listeners.on('mqttStatus', ({ deviceId, topic }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT status [${label}]: ${topic}`)
       })
 
-      this.yotoAccount.on('mqttEvents', ({ deviceId, topic }) => {
+      listeners.on('mqttEvents', ({ deviceId, topic }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT events [${label}]: ${topic}`)
       })
 
-      this.yotoAccount.on('mqttStatusLegacy', ({ deviceId, topic, message }) => {
+      listeners.on('mqttStatusLegacy', ({ deviceId, topic, message }) => {
         const label = this.formatDeviceLabel(deviceId)
         const fields = formatLegacyStatusFields(message)
         this.log.debug(`MQTT legacy status [${label}]: ${topic}${fields}`)
       })
 
-      this.yotoAccount.on('mqttResponse', ({ deviceId, topic, message }) => {
+      listeners.on('mqttResponse', ({ deviceId, topic, message }) => {
         const label = this.formatDeviceLabel(deviceId)
         let payload = ''
         try {
@@ -357,32 +413,80 @@ export class YotoPlatform {
         this.log.debug(`MQTT response [${label}]: ${topic}${payload}`)
       })
 
-      this.yotoAccount.on('mqttUnknown', ({ deviceId, topic }) => {
+      listeners.on('mqttUnknown', ({ deviceId, topic }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT unknown [${label}]: ${topic}`)
       })
 
-      // Start the account (discovers devices, creates device models, starts MQTT)
-      const account = this.yotoAccount
+      await this.connectAccount()
+    } catch (error) {
+      this.log.error('Failed to start account:', errorMessage(error))
+    }
+  }
+
+  /**
+   * Start the account (discovers devices, creates device models, starts MQTT).
+   * If the Yoto API can't be reached, e.g. because the network isn't up yet
+   * when Homebridge boots, retry with backoff instead of giving up. Errors that
+   * a retry won't fix (an invalid login, other 4xx responses) are logged once.
+   * @returns {Promise<void>}
+   */
+  async connectAccount () {
+    const account = this.yotoAccount
+    if (!account || this.shuttingDown) return
+
+    try {
       await account.start()
+    } catch (error) {
+      // Homebridge shut down while the account was starting
+      if (this.shuttingDown) return
+      if (this.authInvalid) {
+        this.log.error('Failed to start account:', errorMessage(error))
+        return
+      }
+      const statusCode = getStatusCode(error)
+      if (statusCode === 401 || statusCode === 403) {
+        this.log.error(
+          `Yoto rejected the saved login (HTTP ${statusCode}). Open the plugin settings in the Homebridge UI and sign in again.`,
+          formatError(error)
+        )
+        return
+      }
+      if (!isRetryableStartError(error)) {
+        this.log.error('Failed to start account:', formatError(error))
+        return
+      }
+      const delayMs = Math.min(START_RETRY_MAX_MS, START_RETRY_BASE_MS * 2 ** this.startRetryCount)
+      this.startRetryCount++
+      this.log.warn(`Could not connect to Yoto (${errorMessage(error)}). Retrying in ${Math.round(delayMs / 1000)} seconds.`)
+      this.startRetryTimer = setTimeout(() => {
+        this.startRetryTimer = null
+        this.connectAccount().catch(retryError => {
+          this.log.error('Failed to start account:', formatError(retryError))
+        })
+      }, delayMs)
+      return
+    }
 
-      // Homebridge shut down while the account was starting; shutdown() cleans up
-      if (this.yotoAccount !== account) return
+    // Homebridge shut down while the account was starting. shutdown()'s stop() ran
+    // before start() finished, so stop the device models and MQTT start() just opened.
+    if (this.shuttingDown) {
+      await account.stop()
+      return
+    }
 
-      this.log.info(`✓ Yoto account started with ${account.devices.size} device(s)`)
-      this.log.debug(
-        'Account devices:',
-        Array.from(account.devices.keys()).join(', ') || 'none'
-      )
+    this.startRetryCount = 0
+    this.log.info(`✓ Yoto account started with ${account.devices.size} device(s)`)
+    this.log.debug(
+      'Account devices:',
+      Array.from(account.devices.keys()).join(', ') || 'none'
+    )
 
-      // Remove stale accessories after all devices are registered
-      this.removeStaleAccessories()
+    // Remove stale accessories after all devices are registered
+    this.removeStaleAccessories()
 
-      this.log.debug('Registering card control accessories (playOnAll).')
-      await this.registerCardControlAccessories()
-    } catch (error) {
-      this.log.error('Failed to start account:', error instanceof Error ? error.message : String(error))
-    }
+    this.log.debug('Registering card control accessories (playOnAll).')
+    await this.registerCardControlAccessories()
   }
 
   /**
@@ -925,6 +1029,11 @@ export class YotoPlatform {
    */
   async shutdown () {
     this.log.debug('Shutting down Yoto platform...')
+    this.shuttingDown = true
+    if (this.startRetryTimer) {
+      clearTimeout(this.startRetryTimer)
+      this.startRetryTimer = null
+    }
     this.log.debug(
       'Handlers to stop:',
       `devices=${this.accessoryHandlers.size}`,
@@ -1001,7 +1110,13 @@ export class YotoPlatform {
       // Keep the original file mode, since config.json holds tokens.
       const { mode } = await stat(configPath)
       const tmpPath = `${configPath}.${process.pid}.tmp`
-      await writeFile(tmpPath, updatedContents, { encoding: 'utf8', mode: mode & 0o777 })
+      try {
+        await writeFile(tmpPath, updatedContents, { encoding: 'utf8', mode: mode & 0o777 })
+      } catch (writeError) {
+        // Don't leave a partial copy of the tokens next to config.json
+        await unlink(tmpPath).catch(() => {})
+        throw writeError
+      }
       try {
         await rename(tmpPath, configPath)
       } catch (renameError) {
@@ -1012,8 +1127,7 @@ export class YotoPlatform {
       }
       this.log.debug('Updated config.json with new tokens')
     } catch (error) {
-      const details = error instanceof Error ? error.message : String(error)
-      this.log.error(`Failed to update config.json at ${configPath}. Refreshed tokens may not persist:`, details)
+      this.log.error(`Failed to update config.json at ${configPath}. Refreshed tokens may not persist:`, errorMessage(error))
     }
   }
 }

package/lib/speaker-accessory.js

@@ -17,7 +17,7 @@ import {
 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 { ListenerGroup, logListenerError } from './utils/listener-group.js'
 import { setDeviceVolume } from './utils/set-device-volume.js'
 import {
   clampPercent,
@@ -51,7 +51,10 @@ export class YotoSpeakerAccessory {
     this.#platform = platform
     this.#accessory = accessory
     this.#deviceModel = deviceModel
-    this.#listeners = new ListenerGroup(deviceModel)
+    this.#listeners = new ListenerGroup(
+      deviceModel,
+      logListenerError(platform.log, `${LOG_PREFIX.ACCESSORY} [${accessory.context.device.name}]`)
+    )
     this.#log = platform.log
 
     this.#device = accessory.context.device
@@ -148,7 +151,9 @@ export class YotoSpeakerAccessory {
       .onGet(this.getTargetMediaState.bind(this))
       .onSet(this.setTargetMediaState.bind(this))
 
-    // Advertise AirPlay support so Home keeps transport controls enabled.
+    // Report AirPlay as enabled. Kept from earlier versions so already-paired speakers keep
+    // the same characteristics; removing it hasn't been tested on real players. It does not
+    // make the Yoto an AirPlay target, and the Home app still shows "Controls not available".
     // AirPlayEnable is a writable uint8 (0/1); ignore writes and always report enabled.
     service
       .getCharacteristic(Characteristic.AirPlayEnable)

package/lib/television-accessory.js

@@ -26,7 +26,7 @@ import {
 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 { ListenerGroup, logListenerError } from './utils/listener-group.js'
 import { setDeviceVolume } from './utils/set-device-volume.js'
 import { getTrimmedString } from './utils/get-trimmed-string.js'
 import { getCardControlConfigs } from './card-controls.js'
@@ -79,7 +79,10 @@ export class YotoTelevisionAccessory {
     this.#platform = platform
     this.#accessory = accessory
     this.#deviceModel = deviceModel
-    this.#listeners = new ListenerGroup(deviceModel)
+    this.#listeners = new ListenerGroup(
+      deviceModel,
+      logListenerError(platform.log, `${LOG_PREFIX.ACCESSORY} [${accessory.context.device.name}]`)
+    )
     this.#log = platform.log
 
     this.#device = accessory.context.device

package/lib/utils/error-format.js

@@ -1,3 +1,26 @@
+/**
+ * A one-line description of an error for user-facing logs. Includes the HTTP
+ * status for Yoto API errors, whose message alone is always
+ * "Unexpected response status code".
+ * @param {unknown} error
+ * @returns {string}
+ */
+export function errorMessage (error) {
+  const message = error instanceof Error ? error.message : String(error)
+  const statusCode = getStatusCode(error)
+  return statusCode === undefined ? message : `${message} (HTTP ${statusCode})`
+}
+
+/**
+ * The HTTP status of a Yoto API error, if the error has one.
+ * @param {unknown} error
+ * @returns {number | undefined}
+ */
+export function getStatusCode (error) {
+  if (!error || typeof error !== 'object' || !('statusCode' in error)) return undefined
+  return typeof error.statusCode === 'number' ? error.statusCode : undefined
+}
+
 /**
  * @param {unknown} error
  * @returns {string}

package/lib/utils/listener-group.js

@@ -1,4 +1,19 @@
 /** @import { EventEmitter } from 'node:events' */
+/** @import { Logger } from 'homebridge' */
+
+import { formatError } from './error-format.js'
+
+/**
+ * A `ListenerGroup` error callback that logs the failure.
+ * @param {Logger} log
+ * @param {string} label - Names the listener's owner, e.g. `[Accessory] [Kitchen Yoto]`
+ * @returns {(event: string, error: unknown) => void}
+ */
+export function logListenerError (log, label) {
+  return (event, error) => {
+    log.error(`${label} Failed to handle ${event} event:`, formatError(error))
+  }
+}
 
 /**
  * Tracks listeners registered on a shared emitter so they can be removed
@@ -11,24 +26,44 @@
  */
 export class ListenerGroup {
   /** @type {EventEmitter} */ #emitter
+  /** @type {((event: string, error: unknown) => void) | undefined} */ #onListenerError
   /** @type {Array<[string, Parameters<EventEmitter['on']>[1]]>} */ #entries = []
 
   /**
    * @param {EventEmitter<TEvents>} emitter
+   * @param {(event: string, error: unknown) => void} [onListenerError] - Called when a
+   *   listener throws or its returned promise rejects. The device model emits from inside
+   *   MQTT and timer callbacks, where an escaping error would be an uncaught exception
+   *   (or unhandled rejection) that stops Homebridge.
    */
-  constructor (emitter) {
+  constructor (emitter, onListenerError) {
     this.#emitter = /** @type {EventEmitter} */ (/** @type {unknown} */ (emitter))
+    this.#onListenerError = onListenerError
   }
 
   /**
    * @template {keyof TEvents & string} K
    * @param {K} event
-   * @param {(...args: TEvents[K]) => void} listener
+   * @param {(...args: TEvents[K]) => unknown} listener
    * @returns {this}
    */
   on (event, listener) {
-    this.#emitter.on(event, listener)
-    this.#entries.push([event, listener])
+    const onListenerError = this.#onListenerError
+    const registered = onListenerError
+      ? (/** @type {TEvents[K]} */ ...args) => {
+          try {
+            const result = listener(...args)
+            if (result instanceof Promise) {
+              result.catch(error => { onListenerError(event, error) })
+            }
+          } catch (error) {
+            onListenerError(event, error)
+          }
+        }
+      : listener
+    const untyped = /** @type {Parameters<EventEmitter['on']>[1]} */ (registered)
+    this.#emitter.on(event, untyped)
+    this.#entries.push([event, untyped])
     return this
   }
 

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@mdjhnson/homebridge-yoto",
+  "displayName": "Homebridge Yoto",
   "description": "Control your Yoto players through Apple HomeKit with real-time MQTT updates",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "author": "mdjhnson (https://github.com/mdjhnson)",
   "contributors": [
     "Bret Comnes <bcomnes@gmail.com> (https://bret.io)"
@@ -9,6 +10,10 @@
   "bugs": {
     "url": "https://github.com/mdjhnson/homebridge-yoto/issues"
   },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/mdjhnson"
+  },
   "dependencies": {
     "@homebridge/plugin-ui-utils": "^2.2.6",
     "color-convert": "3.1.3",
@@ -27,20 +32,24 @@
     "typescript": "~5.9.3"
   },
   "engines": {
-    "node": ">=22",
+    "node": "^22.12.0 || ^24.0.0 || ^26.0.0",
     "npm": ">=10",
     "homebridge": "^1.8.0 || ^2.0.0"
   },
   "homepage": "https://github.com/mdjhnson/homebridge-yoto",
   "keywords": [
     "homebridge-plugin",
-    "yoto"
+    "supports-hap",
+    "homebridge",
+    "homekit",
+    "yoto",
+    "yoto-player",
+    "yoto-mini"
   ],
   "license": "MIT",
   "type": "module",
   "module": "index.js",
   "main": "index.js",
-  "types": "index.d.ts",
   "files": [
     "index.js",
     "config.schema.json",