homebridge-yoto 0.0.27 → 0.0.31

package/PLAN.md

@@ -1,609 +1,425 @@
-# Homebridge Yoto Plugin - Implementation Plan
+# Homebridge Yoto Plugin - Implementation Status
 
-## Overview
+## ✅ What's Implemented
 
-A Homebridge plugin that integrates Yoto audio players with Apple HomeKit, providing comprehensive control over playback, volume, display settings, and status monitoring through MQTT.
+### Architecture
+- ✅ Platform plugin using `yoto-nodejs-client` for device management
+- ✅ One accessory per Yoto device (published as external accessory for SmartSpeaker support)
+- ✅ Real-time updates via MQTT + periodic HTTP polling fallback
+- ✅ Offline detection and "No Response" status handling
+- ✅ Capability-based service registration (v2/v3/mini device support)
 
-## ✅ Current Status: Phase 1 Complete + Phase 2 Enhancements
+### Core Services (Always Present)
+- ✅ **AccessoryInformation** - Device metadata (manufacturer, model, serial, firmware)
+- ✅ **SmartSpeaker** (PRIMARY) - Playback control and volume
+- ✅ **Battery** - Battery level, charging state, low battery indicator
+- ✅ **ContactSensor (CardSlot)** - Card insertion detection
+- ✅ **OccupancySensor (NightModeStatus)** - Day/night mode indicator
+- ✅ **Switch (SleepTimer)** - Toggle sleep timer (30 min default)
+- ✅ **Switch (Bluetooth)** - Toggle Bluetooth on/off
+- ✅ **Fanv2 (DayMaxVolume)** - Day mode max volume limit control
+- ✅ **Fanv2 (NightMaxVolume)** - Night mode max volume limit control
 
-**MVP Complete!** All Phase 1 features implemented and tested. Additional Phase 2 features added including display brightness control, sleep timer, and advanced control switches.
+### Optional Services (Capability-Based)
+- ✅ **TemperatureSensor** - Temperature reading (v3 only)
+- ✅ **Lightbulb (DayNightlight)** - Day nightlight color/brightness control (v3 only)
+- ✅ **Lightbulb (NightNightlight)** - Night nightlight color/brightness control (v3 only)
+- ✅ **ContactSensor (NightlightActive)** - Live nightlight status (v3 only)
+- ✅ **ContactSensor (DayNightlightActive)** - Day nightlight status (v3 only)
+- ✅ **ContactSensor (NightNightlightActive)** - Night nightlight status (v3 only)
 
-## Project Structure
+## Service & Characteristic Reference
 
-```
-homebridge-yoto/
-├── lib/
-│   ├── platform.js              # Main YotoPlatform class
-│   ├── playerAccessory.js       # YotoPlayerAccessory handler
-│   ├── yotoApi.js               # Yoto REST API client wrapper
-│   ├── yotoMqtt.js              # MQTT client for real-time updates
-│   ├── auth.js                  # OAuth2 authentication handler
-│   ├── types.js                 # JSDoc type definitions
-│   └── constants.js             # Plugin constants and defaults
-├── index.js                     # Plugin entry point
-├── config.schema.json           # Homebridge config UI schema
-└── package.json
-```
+All services are named consistently using `generateServiceName()` helper: `"[Device Name] [Service Name]"`
 
-## Phase 1: Core Foundation (MVP) ✅ COMPLETE
+### Yoto Player Accessory
 
-### 1.1 Authentication System ✅
+Each Yoto device is represented as a single HomeKit accessory with multiple services.
 
-**Status:** COMPLETE
+**Category**: `SPEAKER` (required for SmartSpeaker service)
 
-**Goal:** Implement OAuth2 Device Authorization Flow for Yoto API
+---
 
-**Files:**
-- `lib/auth.js`
+#### Service: AccessoryInformation (Required)
 
-**Implementation:**
-- Use `POST /oauth/device/code` to initiate device flow
-- Display user_code and verification_uri in Homebridge logs
-- Poll `POST /oauth/token` until user completes authorization
-- Store access_token and refresh_token in platform config
-- Implement automatic token refresh logic
-- Handle token expiration gracefully
+Standard HomeKit service providing device identification.
 
-**API Endpoints:**
-- `POST /oauth/device/code`
-- `POST /oauth/token` (with grant_type: 'device_code' and 'refresh_token')
+**Characteristics:**
+- `Manufacturer` (GET) - "Yoto Inc."
+- `Model` (GET) - Device family (e.g., "v3", "v2", "mini")
+- `SerialNumber` (GET) - Device ID
+- `HardwareRevision` (GET) - Generation and form factor
+- `FirmwareRevision` (GET) - Firmware version from device status
 
-**Config Structure:**
-```javascript
-{
-  "platform": "Yoto",
-  "name": "Yoto",
-  "clientId": "YOUR_CLIENT_ID",
-  "accessToken": "(stored after auth)",
-  "refreshToken": "(stored after auth)",
-  "tokenExpiresAt": 0
-}
-```
+**Source:** `device` metadata + `status.firmwareVersion`
 
-### 1.2 API Client ✅
+---
 
-**Status:** COMPLETE
+#### Service: SmartSpeaker (PRIMARY)
 
-**Goal:** Create robust API wrapper for Yoto endpoints
+Controls playback and volume. Marked as primary service for the accessory.
 
-**Files:**
-- `lib/yotoApi.js` (REST endpoints)
-- `lib/yotoMqtt.js` (MQTT client)
+**Characteristics:**
+- `CurrentMediaState` (GET) - PLAY/PAUSE/STOP based on playback status
+- `TargetMediaState` (GET/SET) - Control playback (play/pause/stop)
+- `Volume` (GET/SET) - Volume level (0-16 native scale, dynamic max based on volume limit)
+- `Mute` (GET/SET) - Mute state (derived from volume === 0)
+- `StatusActive` (GET) - Online/offline indicator
 
-**REST API Features:**
-- Centralized fetch wrapper with auth headers
-- Automatic token refresh on 401 responses
-- Error handling and retry logic
-- Rate limiting protection
-- Request/response logging for debugging
+**Source:** `status.volume`, `playback.playbackStatus`  
+**Control:** `sendCommand({ action: 'play' | 'pause' | 'stop' | 'volume', volume: N })`
 
-**Key REST Methods:**
-```javascript
-class YotoApi {
-  async getDevices()              // GET /device-v2/devices/mine
-  async getDeviceConfig(deviceId) // GET /device-v2/{deviceId}/config
-  async updateDeviceConfig(deviceId, config) // PUT /device-v2/{deviceId}/config
-  async getContent(cardId)        // GET /content/{cardId}
-  async getLibraryGroups()        // GET /card/family/library/groups
-}
-```
+---
 
-**MQTT Client Features:**
-- Real-time device status updates via `/device/{id}/data/status`
-- Real-time playback events via `/device/{id}/data/events`
-- Command publishing to control devices
-- Automatic reconnection on disconnect
-- Per-device topic subscriptions
+#### Service: Battery
 
-**Key MQTT Methods:**
-```javascript
-class YotoMqtt {
-  async connect(accessToken)
-  async disconnect()
-  subscribeToDevice(deviceId, callback)
-  unsubscribeFromDevice(deviceId)
-  
-  // Command methods
-  async setVolume(deviceId, volume)
-  async startCard(deviceId, uri, options)
-  async pauseCard(deviceId)
-  async resumeCard(deviceId)
-  async stopCard(deviceId)
-  async setSleepTimer(deviceId, seconds)
-  async setAmbientLight(deviceId, r, g, b)
-  async requestStatus(deviceId)
-  async requestEvents(deviceId)
-}
-```
+Battery status information.
 
-### 1.3 Platform Setup ✅
+**Characteristics:**
+- `BatteryLevel` (GET) - Battery percentage (0-100)
+- `ChargingState` (GET) - CHARGING or NOT_CHARGING
+- `StatusLowBattery` (GET) - LOW when ≤20%, NORMAL otherwise
+- `StatusActive` (GET) - Online/offline indicator
 
-**Status:** COMPLETE
+**Source:** `status.batteryLevelPercentage`, `status.isCharging`
 
-**Goal:** Implement DynamicPlatformPlugin for device discovery
+---
 
-**Files:**
-- `lib/platform.js`
-- `index.js`
+#### Service: TemperatureSensor (OPTIONAL - v3 only)
 
-**Implementation:**
-- Register platform in `index.js`
-- Implement `configureAccessory()` to restore cached accessories
-- Implement `discoverDevices()` called on `didFinishLaunching`
-- Create Map to track accessories by deviceId
-- Handle device addition/removal/updates
-- Store device metadata in `accessory.context`
+Temperature reading from device sensor.
 
-**Platform Lifecycle:**
-1. Constructor: Initialize API client, Service/Characteristic refs
-2. configureAccessory: Restore cached accessories from disk
-3. didFinishLaunching: Discover devices and register new ones
-4. Device sync: Update existing, add new, remove stale accessories
+**Characteristics:**
+- `CurrentTemperature` (GET) - Temperature in Celsius
+- `StatusFault` (GET) - NO_FAULT (only shown when temperature available)
+- `StatusActive` (GET) - Online/offline indicator
 
-### 1.4 Player Accessory (Basic) ✅
+**Source:** `status.temperatureCelsius`  
+**Availability:** `deviceModel.capabilities.hasTemperatureSensor`
 
-**Status:** COMPLETE
+---
 
-**Goal:** Create accessory with essential playback controls
+#### Service: Lightbulb (subtype: "DayNightlight") - OPTIONAL - v3 only
 
-**Files:**
-- `lib/playerAccessory.js`
+Day mode nightlight color and brightness control (config-based).
 
-**Services (Phase 1):**
-1. **AccessoryInformation** (required)
-   - Manufacturer: "Yoto"
-   - Model: from device.deviceType
-   - SerialNumber: device.deviceId
-   - FirmwareRevision: device.releaseChannel
+**Characteristics:**
+- `On` (GET/SET) - Turn nightlight on/off (off states: '0x000000', 'off')
+- `Brightness` (GET/SET) - Screen brightness 0-100% (or 'auto')
+- `Hue` (GET/SET) - Color hue 0-360° (derived from hex color)
+- `Saturation` (GET/SET) - Color saturation 0-100% (derived from hex color)
 
-2. **SmartSpeaker** (primary service)
-   - CurrentMediaState: PLAYING/PAUSED/STOPPED (read-only)
-   - TargetMediaState: PLAY/PAUSE/STOP (write)
-   - Volume: 0-100 (read/write)
-   - Mute: boolean (read/write)
+**Source:** `config.ambientColour`, `config.dayDisplayBrightness`  
+**Control:** `updateConfig({ ambientColour: '0xRRGGBB', dayDisplayBrightness: 'N' })`  
+**Availability:** `deviceModel.capabilities.hasColoredNightlight`
 
-3. **Battery**
-   - BatteryLevel: 0-100
-   - ChargingState: NOT_CHARGING/CHARGING
-   - StatusLowBattery: NORMAL/LOW (< 20%)
+**Color Conversion:** Uses `color-convert` library for hex ↔ HSV conversion
 
-**Implementation:**
-- Constructor: Set up services and characteristics
-- Implement onGet/onSet handlers for each characteristic
-- Subscribe to MQTT topics for real-time updates
-- Use `updateCharacteristic()` when MQTT messages arrive
-- Cache last known state for onGet handlers
+---
 
-### 1.5 MQTT Real-Time Updates ✅
+#### Service: Lightbulb (subtype: "NightNightlight") - OPTIONAL - v3 only
 
-**Status:** COMPLETE
+Night mode nightlight color and brightness control (config-based).
 
-**Goal:** Keep HomeKit in sync with device state using MQTT
+**Characteristics:**
+- `On` (GET/SET) - Turn nightlight on/off (off states: '0x000000', 'off')
+- `Brightness` (GET/SET) - Screen brightness 0-100% (or 'auto')
+- `Hue` (GET/SET) - Color hue 0-360° (derived from hex color)
+- `Saturation` (GET/SET) - Color saturation 0-100% (derived from hex color)
 
-**Implementation:**
-- Connect to Yoto MQTT broker on platform init
-- Subscribe to `/device/{id}/data/status` for each device
-- Subscribe to `/device/{id}/data/events` for playback events
-- Update characteristics immediately when MQTT messages arrive
-- Request initial status via `/device/{id}/command/status/request` on startup
-- Implement reconnection logic with exponential backoff
-- Handle offline devices (no recent MQTT messages)
+**Source:** `config.nightAmbientColour`, `config.nightDisplayBrightness`  
+**Control:** `updateConfig({ nightAmbientColour: '0xRRGGBB', nightDisplayBrightness: 'N' })`  
+**Availability:** `deviceModel.capabilities.hasColoredNightlight`
 
-**MQTT Topic Subscriptions:**
-```javascript
-// Per device subscriptions
-/device/{deviceId}/data/status   → Battery, volume, config state
-/device/{deviceId}/data/events   → Playback state, current track
-/device/{deviceId}/response      → Command confirmations
-```
+---
 
-**Status Mapping:**
-```javascript
-// MQTT data/status → HomeKit
-batteryLevel → BatteryLevel
-charging (0/1) → ChargingState (NOT_CHARGING/CHARGING)
-userVolume → Volume
-activeCard → CurrentMediaState context
-
-// MQTT data/events → HomeKit  
-playbackStatus ("playing"/"paused"/"stopped") → CurrentMediaState
-volume → Volume (real-time)
-cardId → Active content tracking
-```
+#### Service: ContactSensor (subtype: "NightlightActive") - OPTIONAL - v3 only
 
-**Command Publishing:**
-```javascript
-// HomeKit actions → MQTT commands
-Set Volume → /device/{id}/command/volume/set
-Play/Pause → /device/{id}/command/card/pause or /resume
-Stop → /device/{id}/command/card/stop
-```
+Shows if nightlight is currently active (live device state).
 
-## Phase 2: Enhanced Controls (Partially Complete)
+**Characteristics:**
+- `ContactSensorState` (GET) - CONTACT_DETECTED when nightlight on
+- `StatusActive` (GET) - Online/offline indicator
+
+**Source:** `status.nightlightMode !== 'off'`  
+**Availability:** `deviceModel.capabilities.hasColoredNightlight`
 
-### 2.1 Display Control ✅
+---
 
-**Status:** COMPLETE
+#### Service: ContactSensor (subtype: "DayNightlightActive") - OPTIONAL - v3 only
 
-**Service:** Lightbulb (for brightness control)
+Shows if day nightlight is currently active and showing.
 
 **Characteristics:**
-- On: Display on/off
-- Brightness: 0-100 mapped to display brightness settings
+- `ContactSensorState` (GET) - CONTACT_DETECTED when day mode + nightlight on
+- `StatusActive` (GET) - Online/offline indicator
 
-**Implementation:**
-- Map to `dayDisplayBrightness` and `nightDisplayBrightness`
-- Handle "auto" mode as max brightness (100)
-- Numeric values map directly to percentage
-- Create separate services for day/night if needed
+**Source:** `status.dayMode === 'day' && status.nightlightMode !== 'off'`  
+**Availability:** `deviceModel.capabilities.hasColoredNightlight`
 
-### 2.2 Temperature Sensor ✅
+---
 
-**Status:** COMPLETE
+#### Service: ContactSensor (subtype: "NightNightlightActive") - OPTIONAL - v3 only
 
-**Service:** TemperatureSensor (optional, enabled via config)
+Shows if night nightlight is currently active and showing.
 
 **Characteristics:**
-- CurrentTemperature: From `temperatureCelcius`
+- `ContactSensorState` (GET) - CONTACT_DETECTED when night mode + nightlight on
+- `StatusActive` (GET) - Online/offline indicator
 
-**Config:**
-```javascript
-{
-  "exposeTemperature": true
-}
-```
+**Source:** `status.dayMode === 'night' && status.nightlightMode !== 'off'`  
+**Availability:** `deviceModel.capabilities.hasColoredNightlight`
 
-### 2.3 Connection Status ✅
+---
 
-**Status:** COMPLETE
+#### Service: ContactSensor (subtype: "CardSlot")
 
-**Service:** ContactSensor or OccupancySensor
+Shows if a card is currently inserted.
 
 **Characteristics:**
-- ContactSensorState or OccupancyDetected: Based on `isOnline`
-- StatusActive: `isOnline`
+- `ContactSensorState` (GET) - CONTACT_DETECTED when card present
+- `StatusActive` (GET) - Online/offline indicator
 
-**Use Cases:**
-- Automation triggers when player comes online
-- Notifications when player goes offline
-- Parent monitoring of device usage
+**Source:** `status.cardInsertionState !== 'none'`
 
-### 2.4 Configuration Switches ✅
+---
 
-**Status:** COMPLETE
+#### Service: OccupancySensor (subtype: "NightModeStatus")
 
-**Goal:** Expose device settings as HomeKit switches
+Shows if device is in night mode (vs day mode).
 
-**Switches:**
-1. Bluetooth Enabled → `bluetoothEnabled`
-2. Bluetooth Headphones → `btHeadphonesEnabled`
-3. Repeat All → `repeatAll`
+**Characteristics:**
+- `OccupancyDetected` (GET) - OCCUPANCY_DETECTED when in night mode
+- `StatusActive` (GET) - Online/offline indicator
 
-**Implementation:**
-- Create Switch service for each setting
-- onSet: Update via `PUT /device-v2/{deviceId}/config`
-- onGet: Read from cached config or status
-- Refresh config on status poll
+**Source:** `status.dayMode === 'night'`
 
-**Config:**
-```javascript
-{
-  "exposeAdvancedControls": true
-}
-```
+**Use Case:** Trigger automations based on device's day/night schedule
 
-## Phase 3: Advanced Features
+---
 
-### 3.1 Volume Limits
+#### Service: Switch (subtype: "SleepTimer")
 
-**Implementation Options:**
+Toggle sleep timer on/off.
 
-**Option A: Custom Characteristics (via Eve)**
-- Requires homebridge-lib for custom characteristics
-- Create slider characteristics for max volume
+**Characteristics:**
+- `On` (GET/SET) - Sleep timer active state
+- `StatusActive` (GET) - Online/offline indicator
 
-**Option B: Additional Lightbulb Services**
-- Use brightness as volume limit (0-16 → 0-100 scale)
-- Name: "Max Volume Day" and "Max Volume Night"
+**Source:** `playback.sleepTimerActive`  
+**Control:** `sendCommand({ action: 'sleep-timer', minutes: 30 })` (on) or `minutes: 0` (off)
 
-**Settings:**
-- Max Volume Limit (Day): `maxVolumeLimit` (0-16)
-- Max Volume Limit (Night): `nightMaxVolumeLimit` (0-16)
+---
 
-### 3.2 Ambient Light Control
+#### Service: Switch (subtype: "Bluetooth")
 
-**Service:** Lightbulb (with color)
+Toggle Bluetooth on/off (config-based, works offline).
 
 **Characteristics:**
-- On: Ambient light enabled
-- Brightness: Light intensity
-- Hue/Saturation: Parse `ambientColour` hex to HSV
+- `On` (GET/SET) - Bluetooth enabled state
 
-**Implementation:**
-- Parse hex color (e.g., "#ff3900") to Hue/Saturation
-- Separate services for day and night colors
-- Update via config: `ambientColour`, `nightAmbientColour`
+**Source:** `config.bluetoothEnabled` (string '0' or '1')  
+**Control:** `updateConfig({ bluetoothEnabled: '1' | '0' })`
 
-### 3.3 Card Detection ✅
+**Note:** No StatusActive - config-based services work offline
 
-**Status:** COMPLETE
+---
 
-**Service:** ContactSensor
+#### Service: Fanv2 (subtype: "DayMaxVolume")
+
+Control day mode maximum volume limit (config-based, works offline).
 
 **Characteristics:**
-- ContactSensorState: DETECTED when card inserted
-- StatusActive: true
+- `Active` (GET) - Always ACTIVE
+- `RotationSpeed` (GET/SET) - Volume limit 0-100%
 
-**Status Mapping:**
-```javascript
-cardInsertionState === 0 → CONTACT_NOT_DETECTED
-cardInsertionState === 1 → CONTACT_DETECTED (physical)
-cardInsertionState === 2 → CONTACT_DETECTED (remote)
-```
+**Source:** `config.maxVolumeLimit` (device: 0-16, HomeKit: 0-100%)  
+**Control:** `updateConfig({ maxVolumeLimit: 'N' })`  
+**Conversion:** `percentage = (limit / 16) * 100`
 
-**Use Cases:**
-- Trigger automations when card inserted
-- Parent monitoring of what's playing
-- Bedtime routine detection
+---
 
-### 3.4 Sleep Timer ✅
+#### Service: Fanv2 (subtype: "NightMaxVolume")
 
-**Status:** COMPLETE
+Control night mode maximum volume limit (config-based, works offline).
 
-**Implementation:**
-- ✅ Uses Fanv2 service with rotation speed as timer minutes (0-120 minutes)
-- ✅ Active characteristic controls timer on/off
-- ✅ Real-time updates from MQTT events
-- Or use Valve service with duration
-- Map to `shutdownTimeout` setting (in seconds)
-- Convert minutes to seconds for API
+**Characteristics:**
+- `Active` (GET) - Always ACTIVE
+- `RotationSpeed` (GET/SET) - Volume limit 0-100%
+
+**Source:** `config.nightMaxVolumeLimit` (device: 0-16, HomeKit: 0-100%)  
+**Control:** `updateConfig({ nightMaxVolumeLimit: 'N' })`  
+**Conversion:** `percentage = (limit / 16) * 100`
+
+---
+
+#### Service: StatelessProgrammableSwitch (DYNAMIC) - NOT YET IMPLEMENTED
+
+One service per shortcut configured on device. Trigger shortcuts from HomeKit.
+
+**Characteristics:**
+- `ProgrammableSwitchEvent` (READ/NOTIFY) - SINGLE_PRESS event
+- `ServiceLabelIndex` (GET) - Index in shortcuts array
+
+**Source:** `config.shortcuts.modes.day.content[]` and `config.shortcuts.modes.night.content[]`  
+**Control:** `sendCommand({ action: 'play', shortcut: X })`
+
+**Note:** Dynamic services - created based on device configuration
+
+---
+
+### Service Availability Matrix
+
+| Service | v2 | v3 | mini |
+|---------|----|----|------|
+| AccessoryInformation | ✅ | ✅ | ✅ |
+| SmartSpeaker | ✅ | ✅ | ✅ |
+| Battery | ✅ | ✅ | ✅ |
+| ContactSensor (CardSlot) | ✅ | ✅ | ✅ |
+| OccupancySensor (NightMode) | ✅ | ✅ | ✅ |
+| Switch (SleepTimer) | ✅ | ✅ | ✅ |
+| Switch (Bluetooth) | ✅ | ✅ | ✅ |
+| Fanv2 (Volume Limits) | ✅ | ✅ | ✅ |
+| TemperatureSensor | ❌ | ✅ | ❌ |
+| Lightbulb (Nightlights) | ❌ | ✅ | ❌ |
+| ContactSensor (Nightlight Status) | ❌ | ✅ | ❌ |
+| StatelessProgrammableSwitch | 🚧 | 🚧 | 🚧 |
+
+---
+
+## Offline Behavior
+
+### What Gets Marked as "No Response"
+
+Services are categorized by data source:
 
-## Phase 4: Content Integration
+**Device State Services** (require online connection):
+- SmartSpeaker (playback, volume)
+- Battery (level, charging)
+- TemperatureSensor (temperature)
+- ContactSensor - all variants (card, nightlight status)
+- OccupancySensor (night mode)
+- Switch (SleepTimer) - reads playback state
 
-### 4.1 Active Content Info
+**Config-Based Services** (work offline):
+- Lightbulb (nightlight color/brightness)
+- Fanv2 (volume limits)
+- Switch (Bluetooth)
+- StatelessProgrammableSwitch (shortcuts)
 
-**Goal:** Display currently playing content information
+### Implementation
 
-**Implementation:**
-- When `activeCard` changes, fetch via `GET /content/{cardId}`
-- Store card metadata in accessory context
-- Display title/author in logs or as custom characteristics
-- Update accessory display name with current content (optional)
+Device state services use `StatusActive` characteristic to indicate offline status. When `StatusActive` is false, HomeKit shows "No Response" for the service.
 
-### 4.2 Shortcuts (Future)
+Config-based services do NOT have `StatusActive` and remain accessible when offline since they only read/write device configuration (cached in `deviceModel.config`).
 
-**Goal:** Expose device shortcuts as programmable switches
+---
 
-**API Endpoint:**
-- `PUT /device-v2/{deviceId}/shortcuts`
+## ❌ What's Left to Implement
 
-**Service:** StatelessProgrammableSwitch
+### StatelessProgrammableSwitch Services (Shortcuts)
 
-**Implementation:**
-- Create button for each configured shortcut
-- Press triggers associated content/command
-- Separate buttons for day/night mode shortcuts
-- Read from device config: `dayYotoDaily`, `nightYotoRadio`, etc.
+Dynamic services created based on `config.shortcuts` configuration.
 
-**Note:** Library groups functionality has been removed from the plan as it's not essential for MVP.
+**Implementation Notes:**
+- Parse `config.shortcuts.modes.day.content[]` and `config.shortcuts.modes.night.content[]`
+- Create one service per unique shortcut
+- Handle shortcuts refresh when config changes
+- Trigger with `sendCommand({ action: 'play', shortcut: X })`
 
-## Configuration Schema
+**Complexity:** Dynamic service lifecycle management, shortcut identification
 
-### Basic Config
-```json
-{
-  "platform": "Yoto",
-  "name": "Yoto",
-  "clientId": "",
-  "accessToken": "",
-  "refreshToken": "",
-  "tokenExpiresAt": 0
-}
+---
+
+## API Reference Documentation
+
+### YotoDeviceModel - State & Events
+
+**State Properties:**
+- `device` - Device metadata (deviceId, name, deviceType, etc.)
+- `status` - Live device status (volume, battery, temperature, etc.)
+- `config` - Device configuration (nightlight colors, volume limits, etc.)
+- `shortcuts` - Configured shortcuts
+- `playback` - Playback state (status, track, sleep timer, etc.)
+
+**Events:**
+- `statusUpdate(status, source, changedFields)` - Device status changed
+- `configUpdate(config, changedFields)` - Configuration changed
+- `playbackUpdate(playback, changedFields)` - Playback state changed
+- `online({ reason })` - Device came online
+- `offline({ reason })` - Device went offline
+
+### Device API Endpoints
+
+- `GET /devices` - List all devices
+- `GET /devices/:deviceId/config` - Get device config
+- `GET /devices/:deviceId/status` - Get device status
+- `POST /devices/:deviceId/config` - Update device config
+- `POST /devices/:deviceId/mq` - Send device command
+
+### Command Examples
+
+```javascript
+// Playback control
+await deviceModel.sendCommand({ action: 'play' })
+await deviceModel.sendCommand({ action: 'pause' })
+await deviceModel.sendCommand({ action: 'stop' })
+
+// Volume control
+await deviceModel.sendCommand({ action: 'volume', volume: 10 })
+
+// Sleep timer
+await deviceModel.sendCommand({ action: 'sleep-timer', minutes: 30 })
 ```
 
-### Advanced Config
-```json
-{
-  "platform": "Yoto",
-  "name": "Yoto",
-  "clientId": "",
-  "mqttBroker": "mqtt://mqtt.yotoplay.com:1883",
-  "exposeTemperature": true,
-  "exposeBattery": true,
-  "exposeAdvancedControls": false,
-  "exposeConnectionStatus": true,
-  "exposeCardDetection": false,
-  "volumeControlType": "speaker",
-  "statusTimeoutSeconds": 120,
-  "debug": false
-}
+### Config Update Examples
+
+```javascript
+// Nightlight colors
+await deviceModel.updateConfig({ ambientColour: '0xff5733' })
+await deviceModel.updateConfig({ nightAmbientColour: '0x3366ff' })
+
+// Volume limits
+await deviceModel.updateConfig({ maxVolumeLimit: '12' })
+await deviceModel.updateConfig({ nightMaxVolumeLimit: '8' })
+
+// Bluetooth
+await deviceModel.updateConfig({ bluetoothEnabled: '1' })
 ```
 
-### config.schema.json Structure
-- OAuth setup instructions in description
-- clientId field (required)
-- MQTT broker URL (with default)
-- Feature toggles for optional sensors
-- Status timeout slider (60-300 seconds) - mark device offline if no updates
-- Debug mode toggle
-
-## Error Handling Strategy
-
-### API Errors
-- 401 Unauthorized → Trigger token refresh
-- 403 Forbidden → Log error, mark device unavailable
-- 404 Not Found → Device may be deleted, unregister accessory
-- 429 Too Many Requests → Implement exponential backoff
-- 500+ Server Errors → Retry with backoff, log for user
-
-### Device Offline
-- Mark services as "No Response" in HomeKit if no MQTT updates for statusTimeoutSeconds
-- MQTT client will automatically attempt reconnection
-- Resume normal operation when MQTT messages resume
-- Log connection status changes
-
-### MQTT Connection Issues
-- Implement exponential backoff for reconnection attempts
-- Use Last Will and Testament (LWT) if supported by broker
-- Maintain connection state per device
-- Gracefully handle broker unavailability
-
-### Token Expiration
-- Proactively refresh before expiration
-- If refresh fails, require user re-authentication
-- Clear tokens from config on auth failure
-- Display clear instructions in logs
-
-### Homebridge Crashes
-- Persist all state in accessory.context
-- Gracefully restore on restart
-- Re-establish API connection
-- Resume polling from last known state
-
-## Testing Strategy
-
-### Unit Tests
-- API client methods (mock fetch)
-- Token refresh logic
-- Status mapping functions
-- Config validation
-
-### Integration Tests
-- OAuth flow (with mock server)
-- Device discovery
-- Characteristic updates
-- Error recovery
-
-### Manual Testing Checklist
-- [ ] Initial OAuth setup flow
-- [ ] Device discovery and registration
-- [ ] Play/pause control
-- [ ] Volume adjustment
-- [ ] Battery status display
-- [ ] MQTT connection establishment
-- [ ] Real-time status updates via MQTT
-- [ ] Device offline handling
-- [ ] Token refresh
-- [ ] Homebridge restart recovery
-- [ ] Multiple device support
-- [ ] Device removal from account
-
-## Documentation
-
-### README.md
-- Overview and features
-- Prerequisites (Yoto account, Homebridge)
-- Installation instructions
-- OAuth setup guide with screenshots
-- Configuration options
-- Troubleshooting common issues
-- Supported devices
-
-### CHANGELOG.md
-- Version history
-- Feature additions
-- Bug fixes
-- Breaking changes
-
-### Contributing Guide
-- Development setup
-- Code style (JSDoc, ESLint)
-- Testing requirements
-- Pull request process
-
-## Future Enhancements (Post-MVP)
-
-### Content Management
-- [ ] Recently played content tracking
-- [ ] MYO card management
-- [ ] Active content information display
-
-### Advanced Device Control
-- [ ] Alarm management
-- [ ] Clock face selection
-- [ ] Scheduled ambient light changes
-- [ ] Audio output routing
-
-### Multi-Device Features
-- [ ] Synchronized playback
-- [ ] Family dashboard accessory
-- [ ] Group controls
-
-### Parental Controls
-- [ ] Time-based restrictions
-- [ ] Content filtering
-- [ ] Usage monitoring
-
-### Automation Integration
-- [ ] Bedtime scene triggers
-- [ ] Presence detection
-- [ ] Weather-based content
-- [ ] HomeKit Secure Video integration (if camera added)
-
-## Success Metrics
-
-### MVP Success Criteria
-- [ ] Successfully authenticate with Yoto API
-- [ ] Discover and register all user devices
-- [ ] Control play/pause from Home app
-- [ ] Adjust volume from Home app
-- [ ] Display accurate battery status
-- [ ] Status updates within 60 seconds
-- [ ] Survive Homebridge restart
-- [ ] Handle device offline gracefully
-
-### Phase 2 Success Criteria
-- [ ] Brightness control functional
-- [ ] Temperature sensor (if enabled)
-- [ ] Connection status monitoring
-- [ ] Configuration switches work
-
-### User Satisfaction Goals
-- Setup time under 5 minutes
-- No more than 2 second latency for controls
-- Clear error messages and recovery steps
-- Stable over 7 days continuous operation
-
-## Development Phases Timeline
-
-### Week 1: Foundation
-- Day 1-2: Project setup, REST API client, auth
-- Day 3-4: MQTT client implementation
-- Day 5-7: Platform implementation with MQTT integration
-
-### Week 2: Core Features
-- Day 1-2: Basic accessory with playback/volume controls via MQTT
-- Day 3-4: Battery service, real-time status updates
-- Day 5-7: Display control, temperature sensor
-
-### Week 3: Advanced Features
-- Day 1-3: Advanced controls, volume limits
-- Day 4-5: Card detection, connection status
-- Day 6-7: Integration testing, polish
-
-### Week 4: Release Prep
-- Day 1-3: Documentation, examples
-- Day 4-5: Beta testing with users
-- Day 6-7: Bug fixes, npm publish
-
-## Next Steps
-
-1. ✅ Review and approve plan
-2. ✅ Discover MQTT integration capability
-3. ✅ Set up project structure and dependencies (including MQTT library)
-4. ✅ Implement auth.js with OAuth flow
-5. ✅ Create REST API client wrapper
-6. ✅ Create MQTT client wrapper with subscriptions
-7. ✅ Build platform foundation with MQTT connection
-8. ✅ Implement basic player accessory with real-time updates
-9. ✅ Add display brightness control
-10. ✅ Add sleep timer control
-11. ✅ Add advanced control switches
-12. ✅ Improve MQTT reconnection logic
-13. 🔄 Test with real Yoto devices (PRIORITY)
-14. 🔄 Add volume limit controls (IN PROGRESS)
-15. 🔄 Add ambient light color control (IN PROGRESS)
-16. ⏳ Add active content information display
-17. ⏳ Add shortcuts support (future)
-18. ⏳ Publish to npm
-19. ⏳ Iterate based on user feedback
+---
+
+## Testing Checklist
+
+### Basic Functionality
+- [ ] Device discovery and accessory creation
+- [ ] Playback control (play/pause/stop)
+- [ ] Volume control (0-16 range)
+- [ ] Battery status updates
+- [ ] Online/offline detection
+- [ ] Firmware version display
+
+### Optional Services
+- [ ] Temperature sensor (v3 only)
+- [ ] Nightlight color control (v3 only)
+- [ ] Nightlight brightness control (v3 only)
+- [ ] Nightlight status sensors (v3 only)
+- [ ] Card slot detection (all devices)
+- [ ] Night mode detection (all devices)
+- [ ] Sleep timer control (all devices)
+- [ ] Bluetooth toggle (all devices)
+- [ ] Volume limit controls (all devices)
+
+### Edge Cases
+- [ ] Device goes offline during operation
+- [ ] MQTT disconnection with HTTP fallback
+- [ ] Multiple devices in one account
+- [ ] Device rename handling
+- [ ] Config changes from Yoto app
+
+### Automations
+- [ ] Trigger on card insertion
+- [ ] Trigger on night mode change
+- [ ] Trigger on nightlight activation
+- [ ] Volume limit changes based on time
+- [ ] Sleep timer activation