@switchbot/homebridge-switchbot 5.0.0-beta.112 → 5.0.0-beta.113

package/todo/COMPLETED.md

@@ -1,9 +1,309 @@
+# Batch Import & Discovery UI Enhancements ✅ COMPLETED
+
+- [x] Add checkboxes to select multiple devices
+  - Users can now select multiple discovered devices using checkboxes in the discovery UI for batch actions.
+- [x] Add "Add Selected to Config" button
+  - A prominent "Add Selected to Config" button enables batch import of all selected devices, streamlining onboarding.
+- [x] Implement bulk configuration with smart defaults
+  - When importing multiple devices, the system applies smart defaults (type, name, MAC, etc.) and auto-fills config fields, reducing manual entry and errors.
+- [x] Show firmware update available indicators
+  - Devices with available firmware updates display an orange "Update Available" badge in the discovery UI.
+- [x] Show offline/unreachable warnings
+  - Devices that are offline or unreachable show a red "Offline" badge, based on status or last-seen timestamp.
+- [x] Add "Needs Attention" section at top
+  - Devices needing action (low battery, firmware update, offline) are grouped in a "Needs Attention" section at the top of the discovery UI for quick access.
+
+**Status:** All batch import and discovery UI features are implemented and live. Only battery level trending (historical data) remains as a future enhancement.
+# Integration: node-switchbot Beta Updates (March 2026)
+
+### Duplicate Detection ✅ COMPLETED
+
+- [x] The UI disables the "Add to Config" button and shows an "Already Added" badge for devices already in the config, preventing duplicate entries. Badges for recommended connection (BLE/API) are also shown based on signal/device type.
+
+**Status:** Duplicate detection is enforced in the UI, so users cannot add the same device twice. Connection recommendation badges are also displayed.
+# Integration: node-switchbot Beta Updates (March 2026)
+
+### One-Click Device Import ✅ COMPLETED
+
+- [x] Add "Add to Config" button next to each discovered device. Dramatically speeds up onboarding, reduces manual steps for users.
+
+**Status:** Each discovered device in the UI now has an "Add to Config" button. This enables one-click import directly from the discovery list.
+
+### Auto-populate Device Config Modal ✅ COMPLETED
+
+- [x] When importing, the config modal is auto-filled with discovered values (name, type, MAC, etc). Reduces user error and makes adding devices nearly frictionless.
+
+**Status:** The import modal pre-fills all relevant fields with discovered device data, streamlining the import process.
+
+### Pre-fill MAC Address for BLE Devices ✅ COMPLETED
+
+- [x] The import modal auto-fills the MAC address field with the discovered device's address, ensuring BLE devices are always added with the correct MAC.
+
+**Status:** The MAC address is pre-filled in the config modal for BLE devices, preventing user error and connection issues.
+
+### Duplicate Detection ✅ COMPLETED
+
+- [x] The UI disables the "Add to Config" button and shows an "Already Added" badge for devices already in the config, preventing duplicate entries.
+
+**Status:** Duplicate detection is enforced in the UI, so users cannot add the same device twice.
+# Integration: node-switchbot Beta Updates (March 2026)
+
+### Duplicate Detection ✅ COMPLETED
+
+- [x] The UI disables the "Add to Config" button and shows an "Already Added" badge for devices already in the config, preventing duplicate entries.
+
+**Status:** Duplicate detection is enforced in the UI, so users cannot add the same device twice.
+# Integration: node-switchbot Beta Updates (March 2026)
+
+### Pre-fill MAC Address for BLE Devices ✅ COMPLETED
+
+- [x] The import modal auto-fills the MAC address field with the discovered device's address, ensuring BLE devices are always added with the correct MAC.
+
+**Status:** The MAC address is pre-filled in the config modal for BLE devices, preventing user error and connection issues.
+# Integration: node-switchbot Beta Updates (March 2026)
+
+### One-Click Device Import ✅ COMPLETED
+
+- [x] Add "Add to Config" button next to each discovered device. Dramatically speeds up onboarding, reduces manual steps for users.
+
+**Status:** Each discovered device in the UI now has an "Add to Config" button. This enables one-click import directly from the discovery list.
+
+### Auto-populate Device Config Modal ✅ COMPLETED
+
+- [x] When importing, the config modal is auto-filled with discovered values (name, type, MAC, etc). Reduces user error and makes adding devices nearly frictionless.
+
+**Status:** The import modal pre-fills all relevant fields with discovered device data, streamlining the import process.
+# Integration: node-switchbot Beta Updates (March 2026)
+- [x] Update device registry and class mapping to match node-switchbot
+- [x] Add notification handling for BLE devices (per-command notification futures, unsolicited notification logging)
+
+- [x] Map new device types to Homebridge plugin (HubMini Matter, Hub3, Keypad Vision/Pro, Plug Mini EU, Roller Shade, Garage Door Opener, Floor Lamp, Art Frame, RGBICWW variants, K10/K11/K20/S10/S20 vacuums, Lock Lite/Vision/Pro/WiFi, Circulator Fan, Smart Thermostat Radiator, Climate Panel, Evaporative Humidifier, Strip Light 3, etc.)
+- [x] Expose new device features in UI (air quality, preset modes, calibration, direction, multi-command, extended info, segmented control, etc.)
+- [x] Integrate BLE encryption for all supported devices (relay, lock, air purifier, light strip, bulb, etc.)
+# BLE Response Length Validation ✅ COMPLETED
+
+- [x] Implement response length validation for BLE status parsing
+
+**Status:** All BLE status parsing now validates the response buffer/array length before parsing. Invalid responses are logged and rejected, improving robustness and diagnostics for all BLE devices.
+
+---
+# Error Class Handling Integration ✅ COMPLETED
+
+- [x] Add support for new error classes and improved error handling (SwitchbotOperationError, SwitchbotAuthenticationError, CharacteristicMissingError)
+
+**Status:** The plugin now imports and uses node-switchbot v4 error classes, with robust instanceof-based handling and compatible fallbacks. All error types are logged and surfaced appropriately, and the code is ready for future node-switchbot error model changes.
+
+---
+### Batch Enable/Disable Devices ✅ COMPLETED
+
+- [x] Allow batch enable/disable of devices
+
+**Status:** The UI now provides 'Enable Selected' and 'Disable Selected' buttons, allowing users to batch enable or disable devices directly from the discovery view.
+
+---
+
+### Batch Operation Progress Indicator ✅ COMPLETED
+
+- [x] Show progress for batch operations
+
+**Status:** The UI now displays a progress indicator during batch add/configure operations, giving users real-time feedback on operation status and completion.
+
+---
+
+### Real-Time RSSI Updates During Scan ✅ COMPLETED
+
+- [x] Update RSSI values in real-time during scan
+
+**Status:** The UI now polls for BLE scan results and updates device RSSI values live during the scan window, providing real-time signal strength feedback.
+
+---
+
+### Needs Attention Section in Discovery UI ✅ COMPLETED
+
+- [x] Add 'Needs Attention' section at the top of the device discovery UI
+
+**Status:** Devices with low battery (<20%), firmware updates available, or offline/unreachable status are now aggregated and displayed in a prominent 'Needs Attention' section at the top of the discovery UI. This helps users quickly identify and address devices that require action.
+
+---
+
 # Completed TODOs
 
+### Firmware Update Available Indicator ✅ COMPLETED
+
+### Offline/Unreachable Warning Indicator ✅ COMPLETED
+
+- [x] Show offline/unreachable warnings
+
+**Status:** Devices that are offline or unreachable (either via a boolean property or if last seen > 1 hour ago) now display a red 'Offline' badge in the discovery UI next to the device name.
+
+
+- [x] Show firmware update available indicators
+
+**Status:** Devices with a firmware update available now display an orange 'Update Available' badge in the discovery UI next to the device name.
+
+
 This file tracks all completed features and improvements for the SwitchBot Homebridge Plugin.
 
 ---
 
+## Recent Completed Work
+
+### Connection Testing (First Slice) ✅ COMPLETED
+
+- [x] Added "Test Connection" button per device (discovered and configured cards)
+- [x] Added backend connectivity check endpoint (`/test-connection`)
+- [x] Attempted basic status read via device fetch during test
+- [x] Added success/failure indicator with inline result details
+- [x] Displayed measured connection latency (ms)
+- [x] Displayed connection method result (BLE/OpenAPI/Auto)
+
+  **Status:** Users can now run per-device connection checks directly from the UI and immediately see method and latency results.
+
+### Matter Neon Wire Rope Light Registration Verification ✅ COMPLETED
+
+- [x] **Verify Matter registration for "Family Room Neon Wire Rope Light" succeeds without behavior rollback**
+  - [x] Added targeted Matter integration regression test for `RGBIC Neon Wire Rope Light`
+  - [x] Verified normalization to Matter type `lightstrip`
+  - [x] Verified `colorControl.colorMode` default is present (`0`) to satisfy conformance
+  - [x] Validated registration path end-to-end with Matter harness
+
+  **Status:** Neon Wire Rope Light registration now has regression coverage and registers with conformant ColorControl defaults.
+
+### Matter Lightstrip Conformance ✅ COMPLETED
+
+- [x] **Fix Matter lightstrip registration conformance requiring `colorControl.colorMode`**
+  - [x] **Issue:** Matter accessory initialization failed for color lightstrip devices with conformance errors
+  - [x] **Error:** `Conformance "M": Matter requires you to set this attribute ... colorControl.state.colorMode`
+  - [x] **Fix:** Added required `colorMode` default for lightstrip color control state while avoiding disallowed default writes
+
+  **Status:** Lightstrip accessories now provide required ColorControl state for Matter initialization.
+
+
+### Battery Warnings in Device List ✅ COMPLETED
+
+- [x] Show battery warnings (< 20%) with yellow/red indicators
+
+**Status:** Devices with battery below 20% now display a yellow (10–19%) or red (<10%) warning badge in the discovery UI, with a tooltip for low/critical battery.
+
+### Streaming BLE Device Discovery ✅ COMPLETED
+
+- [x] Show devices as they're discovered (streaming results via polling)
+
+**Status:** Devices now appear in the UI as soon as they're discovered during BLE scan, providing a real-time streaming experience.
+
+---
+
+### Discovery Better Loading States ✅ COMPLETED
+
+- [x] Show progress indicator phases: `Scanning BLE` → `Fetching OpenAPI` → `Complete`
+- [x] Added spinner/progress visuals for each phase
+- [x] Display partial discovery results while later phases continue
+- [x] Show elapsed time for current phase and total discovery time
+- [x] Added cancel button for long discovery runs
+
+  **Status:** Discovery UX now provides real-time progress and immediate partial feedback.
+
+### Discovery Device Grouping ✅ COMPLETED
+
+- [x] Implemented grouping by connection type
+- [x] Implemented grouping by hub
+- [x] Added expandable/collapsible group headers
+- [x] Added group counts in headers
+- [x] Persisted expanded/collapsed state in localStorage
+
+  **Status:** Discovery lists are grouped, collapsible, and stateful across sessions.
+
+### Discovery Connection Recommendations ✅ COMPLETED
+
+- [x] Added `⚡ Recommended: BLE` badge for strong RSSI devices
+- [x] Added `☁️ Recommended: API` badge for hub-dependent devices
+- [x] Added recommendation tooltips explaining reasoning
+- [x] Applied device-type-aware recommendation heuristics
+
+  **Status:** Discovery cards now provide actionable connection guidance.
+
+### Configurable BLE Scan ✅ COMPLETED
+
+- [x] Added scan duration settings (3s/5s/10s/15s)
+- [x] Added option to disable BLE scanning
+- [x] Added adjustable BLE timeout setting
+- [x] Persisted BLE scan preferences in localStorage
+- [x] Added Bluetooth availability status indicator
+
+  **Status:** BLE discovery behavior is user-configurable and persisted.
+
+### Discovery History/Cache ✅ COMPLETED
+
+- [x] Cache last discovery results for 5 minutes
+- [x] Show "Last scanned: X minutes ago" with timestamp
+- [x] Add "Refresh" button to re-scan
+- [x] Show cached results immediately on page load
+- [x] Auto-refresh option with configurable interval
+
+  **Status:** Discovery now restores recent results instantly and supports manual/automatic refresh.
+
+### Discovery UX Polish ✅ COMPLETED
+
+- [x] Added `Hide Added` discovery filter to exclude already-configured devices
+- [x] Improved BLE settings row alignment (`Scan`, `Timeout`, and units)
+- [x] Reduced extra spacing between BLE settings row and Bluetooth adapter status
+- [x] Hide `Scan` and `Timeout` controls when `Disable BLE scan` is enabled
+
+  **Status:** Discovery controls are cleaner and faster to use for repeat configuration workflows.
+
+### Detailed Device Info Panel ✅ COMPLETED
+
+- [x] Added click-to-expand toggle button (▾) to device cards with rotation animation
+- [x] Created expandable details panel showing extended device information:
+  - [x] Device ID with copy button
+  - [x] MAC Address with copy button
+  - [x] Device Type
+  - [x] Model
+  - [x] Hub ID (if applicable)
+  - [x] Battery level (if available)
+  - [x] Firmware version (if available)
+  - [x] Cloud Service status (enabled/disabled)
+  - [x] Last Seen timestamp (human-readable format)
+- [x] Implemented copy-to-clipboard functionality with visual feedback (📋 → ✓ for 2s)
+- [x] Styled details panel with SwitchBot theme (light gray background, compact rows)
+- [x] Persisted expand/collapse state in-session (resets on page reload)
+
+  **Status:** Device cards now provide quick access to extended metadata with one-click copying of ID and MAC. Details panel uses clean, readable table layout within the card.
+
+### Extended Details in Configured Devices ✅ COMPLETED
+
+- [x] Added expandable toggle (▾) to configured device cards in config section
+- [x] Details panel shows same extended information as discovered devices:
+  - [x] Device ID with copy button
+  - [x] MAC Address with copy button  
+  - [x] Device Type
+  - [x] Model
+  - [x] Hub ID (if applicable)
+  - [x] Battery level (if available)
+  - [x] Firmware version (if available)
+  - [x] Cloud Service status
+  - [x] Last Seen timestamp
+- [x] Toggle button rotates when expanded/collapsed (smooth animation)
+- [x] Details available directly from card without opening Edit modal
+
+  **Status:** Configured devices now have the same quick-access details panel as discovered devices, making it easy to view metadata without opening the Edit dialog.
+
+### Real-Time BLE Scanning (Partial) ✅ PARTIALLY COMPLETED
+
+- [x] Added animated "pulsing" indicator during active BLE scan using CSS animation
+- [x] Implemented "X devices found..." counter that displays during scan
+  - Shows BLE device count after BLE phase completes
+  - Updates to merged count when OpenAPI phase completes
+  - Auto-hides when discovery finishes
+- [x] Counter shows pulse animation (1.5s opacity fade cycle) while scanning
+- [x] Gracefully removes pulse animation and hides counter on cancellation/error
+- [ ] Real-time streaming results via polling (partial implementation - displays final count per phase)
+- [ ] Real-time RSSI updates during scan (requires server-side streaming support)
+
+  **Status:** Discovery now shows visual feedback with a pulsing "X devices found" counter. Full streaming of individual results per-device would require backend support for Server-Sent Events (SSE) or WebSocket streaming. Current implementation displays phase-wise device counts (BLE count → merged final count).
+
+---
+
 ## Code Refactoring & Architecture
 
 ### Server-Side Refactoring ✅ COMPLETED

package/todo/TODO.md

@@ -1,104 +1,118 @@
-# SwitchBot Plugin TODO List
+# SwitchBot Plugin TODO List (2026)
 
-## Active Tasks
 
-### Bug Fixes (Priority: Critical)
+#### 8. Batch Import
 
-- No active critical bug fixes right now.
+- [x] Add checkboxes to select multiple devices
+- [x] Add "Add Selected to Config" button
+- [x] Implement bulk configuration with smart defaults
+
+- [x] Show firmware update available indicators
+- [x] Show offline/unreachable warnings
+- [x] Add "Needs Attention" section at top
+- [ ] Implement battery level trending (if historical data available)
+
+#### 10. Export/Import Discovery
+
+- [ ] Add "Export Results" button (JSON format)
+- [ ] Add "Import Results" for comparison or troubleshooting
+- [ ] Share with support for debugging
+- [ ] Compare current vs previous discovery (show differences)
+- [ ] Generate discovery report (formatted summary)
 
 ---
 
-## Discovery System Enhancements
+## Bug Fixes & Technical Debt
 
-### Quick Wins (Priority: High)
+### Testing & Quality Assurance
 
-#### 1. Better Loading States
+- [ ] **Test discovery with real hardware**
+  - [ ] Test BLE discovery with nearby devices
+  - [ ] Test OpenAPI discovery with cloud-registered devices
+  - [ ] Test with mixed BLE+API devices
+  - [ ] Test connection type badge display
+  - [ ] Verify deduplication works correctly
 
-- [ ] Show progress indicator: "Scanning BLE... (5s)" → "Fetching OpenAPI..." → "Complete"
-- [ ] Add progress bar or spinner for each discovery phase
-- [ ] Display partial results as they arrive (streaming)
-- [ ] Show elapsed time for each phase
-- [ ] Add "Cancel" button to abort long scans
+- [ ] **Add error handling improvements**
+  - [ ] Better error messages for users
+  - [ ] Retry logic with exponential backoff
+  - [ ] Graceful degradation when BLE unavailable
+  - [ ] Network timeout handling
 
-### Medium Effort (Priority: Medium)
+---
 
-#### 2. Device Grouping
+## Documentation
 
-- [ ] Implement grouping by Hub (show which devices are on which hub)
-- [ ] Implement grouping by Connection Type
-- [ ] Add expandable/collapsible group headers
-- [ ] Show device count per group
-- [ ] Remember expanded/collapsed state
+- [ ] **Update README with discovery features**
+  - [ ] Document BLE vs OpenAPI discovery
+  - [ ] Add screenshots of new UI features
+  - [ ] Explain connection type badges
+  - [ ] Add troubleshooting guide for discovery issues
 
-#### 3. Connection Recommendations
+- [ ] **Create developer documentation**
+  - [ ] Document new modular structure
+  - [ ] API documentation for endpoints
+  - [ ] Contributing guidelines for UI changes
 
-- [ ] Add badge: "⚡ Recommended: BLE" for devices with strong signal (> -70 dBm)
-- [ ] Add badge: "☁️ Recommended: API" for hub-dependent devices
-- [ ] Show tooltip explaining why recommendation is made
-- [ ] Consider device type (some work better with BLE vs API)
+---
 
-#### 4. Configurable BLE Scan
+## Priority Summary
 
-- [ ] Add settings panel with scan duration options (3s/5s/10s/15s)
-- [ ] Add option to disable BLE scanning if no Bluetooth adapter
-- [ ] Add option to adjust BLE timeout
-- [ ] Remember user preferences in localStorage
-- [ ] Show system Bluetooth availability status
+### Must Do (Next Release)
 
-#### 5. Discovery History/Cache
+1. Better Loading States
 
-- [ ] Cache last discovery results for 5 minutes
-- [ ] Show "Last scanned: X minutes ago" with timestamp
-- [ ] Add "Refresh" button to re-scan
-- [ ] Show cached results immediately on page load
-- [ ] Auto-refresh option with configurable interval
+### Should Do (Soon)
 
-#### 6. Detailed Device Info Panel
+1. Connection Recommendations
+2. Device Grouping
+3. Test discovery with real hardware
+4. Update README with new features
 
-- [ ] Add click-to-expand device details panel
-- [ ] Show extended information:
-  - [ ] Battery level (if available)
-  - [ ] Firmware version
-  - [ ] Cloud service enabled/disabled status
-  - [ ] Last seen timestamp
-  - [ ] Full MAC address
-  - [ ] Device capabilities/features
-- [ ] Add "Copy ID" and "Copy MAC" buttons
+### Nice to Have (Future)
 
-### Advanced Features (Priority: Low)
+1. Configurable BLE Scan
+2. Discovery History/Cache
+3. Connection Testing
+4. Batch Import
+5. Device Health Dashboard
 
-#### 7. Real-Time BLE Scanning
+---
+
+## Notes
+
+- See [COMPLETED.md](COMPLETED.md) for all completed features
+- UI mockups available in [mockups/](mockups/) directory
+- Consider user feedback on most-wanted features
+- Test all changes with real SwitchBot devices
+- Maintain backwards compatibility with existing configs
+- Keep UI responsive and fast (< 500ms interactions)
+- Follow Homebridge UI/UX conventions
+# Integration: node-switchbot Beta Updates (March 2026)
+
+## Tasks to Integrate Latest node-switchbot Features
+
+
+## Next Features
+
+### Advanced Features (Priority: Low)
 
-- [ ] Show devices as they're discovered (streaming results)
-- [ ] Add animated "pulsing" indicator for active BLE scan
-- [ ] Update RSSI values in real-time during scan
-- [ ] Show "X devices found..." counter during scan
 
-#### 8. Connection Testing
 
-- [ ] Add "Test Connection" button per device
-- [ ] Attempt to connect and read basic device status
-- [ ] Show success/failure indicator with details
-- [ ] Display connection latency
-- [ ] Show which connection method succeeded (BLE/API)
 
-#### 9. Batch Import
+#### 8. Batch Import
 
 - [ ] Add checkboxes to select multiple devices
 - [ ] Add "Add Selected to Config" button
 - [ ] Implement bulk configuration with smart defaults
-- [ ] Show progress for batch operations
-- [ ] Allow batch enable/disable of devices
 
-#### 10. Device Health Dashboard
 
-- [ ] Show battery warnings (< 20%) with yellow/red indicators
-- [ ] Show firmware update available indicators
-- [ ] Show offline/unreachable warnings
+- [x] Show firmware update available indicators
+- [x] Show offline/unreachable warnings
 - [ ] Add "Needs Attention" section at top
 - [ ] Implement battery level trending (if historical data available)
 
-#### 11. Export/Import Discovery
+#### 10. Export/Import Discovery
 
 - [ ] Add "Export Results" button (JSON format)
 - [ ] Add "Import Results" for comparison or troubleshooting