@mdjhnson/homebridge-yoto 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2023 Bret Comnes
+Copyright (c) 2026 mdjhnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+<p align="center">
+
+<img src="https://github.com/homebridge/branding/raw/latest/logos/homebridge-wordmark-logo-vertical.png" width="150">
+
+<img src="./logo.png" width="150">
+
+</p>
+
+<span align="center">
+
+# @mdjhnson/homebridge-yoto
+
+</span>
+
+<span align="center">
+
+[![latest version](https://img.shields.io/npm/v/@mdjhnson/homebridge-yoto.svg)](https://www.npmjs.com/package/@mdjhnson/homebridge-yoto)
+[![Actions Status](https://github.com/mdjhnson/homebridge-yoto/workflows/tests/badge.svg)](https://github.com/mdjhnson/homebridge-yoto/actions)
+![Types in JS](https://img.shields.io/badge/types_in_js-yes-brightgreen)
+[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-7fffff?style=flat&labelColor=ff80ff)](https://github.com/neostandard/neostandard)
+
+</span>
+
+Homebridge plugin that exposes Yoto players to HomeKit: playback and volume, card and shortcut buttons, battery, temperature, nightlights, and more. Updates arrive in real time over MQTT, with HTTP polling as a fallback.
+
+This is a maintained fork of [bcomnes/homebridge-yoto](https://github.com/bcomnes/homebridge-yoto).
+
+## Install
+
+Search for `@mdjhnson/homebridge-yoto` in the Homebridge UI **Plugins** tab, or run:
+
+```sh
+npm install -g @mdjhnson/homebridge-yoto
+```
+
+Requires Node.js 22+ 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**.
+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.
+
+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.
+
+The plugin refreshes its tokens on its own. If the login ever expires or is revoked, the Homebridge log will say so. Sign in again from the plugin settings.
+
+## Settings
+
+All options live under **Accessory Services** in the plugin settings.
+
+**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 playback and volume.
+- **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.
+
+External accessories must be added by hand in the Home app (**Add Accessory → More options**) using the setup code in the Homebridge log.
+
+**Card Controls** (`services.cardControls`)
+- A switch on each player that plays the card ID you configure.
+- Optional **Play on All Yotos**: a separate accessory that plays the card on every online player.
+
+**Shortcuts** (`services.shortcuts`)
+- A switch for each shortcut configured on the player in the Yoto app. Turning it on plays that shortcut's card, chapter and track.
+- Switches are named after the card and update when you change the shortcuts in the Yoto app.
+
+**Service toggles**
+- **Battery**, **Temperature Sensor** (v3), **Nightlight** (v3), **Card Slot**, **Day Mode**, **Sleep Timer**, **Bluetooth**, **Volume Limits**.
+
+**Advanced**
+- **HTTP Poll Interval**: How often to poll the Yoto API as a fallback to MQTT. Defaults to 60 seconds; the minimum is 10 seconds.
+
+## HomeKit services
+
+**Playback (bridged)**
+- **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)**
+- Current/Target Media State, Volume, Mute, and online status. Stop pauses, so playback can be resumed.
+
+**TV Playback (external)**
+- Active is on while the player is playing. Turning it off pauses.
+- Inputs: **Now Playing**, then one per card control and one per shortcut. Choosing an input plays its card.
+- Remote: Play/Pause and Select toggle playback. Volume buttons step the volume.
+
+**Card Controls and Shortcuts**
+- Momentary switches that start their card and then turn back off.
+
+**Device status**
+- **Online Status**: Contact sensor. Contact Not Detected means online.
+- **Battery**: Battery level, charging state, and low battery.
+- **Temperature**: Temperature sensor (v3).
+
+**Nightlight** (v3)
+- **Day Nightlight / Night Nightlight**: Lightbulbs with On/Off, Brightness, Hue, and Saturation.
+- **Nightlight Active / Day Nightlight Active / Night Nightlight Active**: Contact sensors for the live nightlight state.
+
+**Other controls**
+- **Card Slot**: Contact sensor for card insertion.
+- **Day Mode**: Contact sensor. Contact Not Detected means day mode.
+- **Sleep Timer**: Switch that turns the sleep timer on or off.
+- **Bluetooth**: Switch that toggles Bluetooth.
+- **Day/Night Max Volume**: Lightbulbs whose brightness sets the max volume limits.
+
+## Notes
+
+- **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.
+
+## Development
+
+```sh
+npm install
+npm test   # eslint + tsc + node:test with coverage
+```
+
+Releases are cut with the **npm bump** GitHub Action (Actions → npm bump → Run workflow). It publishes with [npm trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored in the repo.
+
+## License
+
+MIT © [Bret Comnes](https://bret.io) and mdjhnson
+
+## Acknowledgments
+
+- [Bret Comnes](https://github.com/bcomnes) wrote the original plugin and [yoto-nodejs-client](https://github.com/bcomnes/yoto-nodejs-client).
+- Thanks to [Yoto](https://yoto.io) for their API.
+- Built with [Homebridge](https://homebridge.io).

package/config.schema.cjs

@@ -0,0 +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

@@ -0,0 +1,231 @@
+{
+  "pluginAlias": "Yoto",
+  "pluginType": "platform",
+  "singular": true,
+  "customUi": true,
+  "headerDisplay": "**Homebridge Yoto Plugin** - Control your Yoto players through HomeKit",
+  "footerDisplay": "For help and documentation, visit the [GitHub repository](https://github.com/mdjhnson/homebridge-yoto)",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "clientId": {
+        "title": "OAuth Client ID",
+        "type": "string",
+        "default": "tpc_ot5BY24FLyZoCX9MnykipB",
+        "required": false,
+        "description": "OAuth client ID for Yoto API authentication. The default works for most users. Only change if you've created your own OAuth app at yoto.dev.",
+        "x-schema-form": {
+          "hidden": false
+        }
+      },
+      "accessToken": {
+        "title": "Access Token",
+        "type": "string",
+        "required": false,
+        "description": "Automatically managed by the authentication flow. Do not edit manually.",
+        "x-schema-form": {
+          "type": "password"
+        }
+      },
+      "refreshToken": {
+        "title": "Refresh Token",
+        "type": "string",
+        "required": false,
+        "description": "Automatically managed by the authentication flow. Do not edit manually.",
+        "x-schema-form": {
+          "type": "password"
+        }
+      },
+      "tokenExpiresAt": {
+        "title": "Token Expiration",
+        "type": "number",
+        "required": false,
+        "description": "Automatically managed by the authentication flow. Do not edit manually.",
+        "x-schema-form": {
+          "hidden": true
+        }
+      },
+      "httpPollIntervalMs": {
+        "title": "HTTP Poll Interval (ms)",
+        "type": "integer",
+        "default": 60000,
+        "minimum": 10000,
+        "required": false,
+        "description": "How often to poll the Yoto API for device status and config as a fallback to MQTT updates. Defaults to 60000 (1 minute)."
+      },
+      "services": {
+        "title": "Accessory Services",
+        "type": "object",
+        "properties": {
+          "playbackControls": {
+            "title": "Playback Controls",
+            "type": "boolean",
+            "default": false,
+            "description": "Expose bridged playback switch and volume dimmer controls."
+          },
+          "smartSpeaker": {
+            "title": "External Smart Speaker",
+            "type": "boolean",
+            "default": false,
+            "description": "Publish an external Smart Speaker accessory for playback and volume controls. Requires additional pairing steps and appears as a separate accessory."
+          },
+          "television": {
+            "title": "TV Playback Accessory",
+            "type": "boolean",
+            "default": false,
+            "description": "Publish an external playback accessory using the TV service with input and speaker controls. Requires additional pairing steps and appears as a separate accessory."
+          },
+          "battery": {
+            "title": "Battery",
+            "type": "boolean",
+            "default": true,
+            "description": "Expose battery status service."
+          },
+          "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."
+          },
+          "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."
+                }
+              }
+            }
+          },
+          "shortcuts": {
+            "title": "Shortcuts",
+            "type": "boolean",
+            "default": false,
+            "description": "Expose a switch for each shortcut configured on the Yoto (in the Yoto app under the player's shortcut buttons). Turning a switch on plays that shortcut."
+          },
+          "dayMode": {
+            "title": "Day Mode",
+            "type": "boolean",
+            "default": true,
+            "description": "Expose day 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."
+          }
+        }
+      }
+    }
+  },
+  "layout": [
+    {
+      "type": "section",
+      "title": "Authentication",
+      "expandable": true,
+      "expanded": false,
+      "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>"
+        },
+        "clientId",
+        "accessToken",
+        "refreshToken"
+      ]
+    },
+    {
+      "type": "section",
+      "title": "Accessory Services",
+      "items": [
+        {
+          "type": "help",
+          "helpvalue": "<p>Select which HomeKit services to expose for each Yoto device.</p>"
+        },
+        {
+          "type": "help",
+          "helpvalue": "<p><strong>Playback Controls:</strong> Enable a bridged switch + dimmer for play/pause and volume. <strong>External Smart Speaker:</strong> publishes a separate accessory and requires additional pairing steps in the Home app. <strong>TV Playback Accessory:</strong> publishes an external playback accessory with input and speaker controls.</p>"
+        },
+        "services.playbackControls",
+        "services.smartSpeaker",
+        "services.television",
+        "services.volumeLimits",
+        "services.battery",
+        "services.temperature",
+        "services.cardSlot",
+        "services.dayMode",
+        "services.nightlight",
+        "services.bluetooth",
+        "services.sleepTimer",
+        "services.shortcuts",
+        {
+          "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"
+          ]
+        }
+      ]
+    },
+    {
+      "type": "section",
+      "title": "Advanced",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "httpPollIntervalMs"
+      ]
+    }
+  ]
+}