node-switchbot 4.0.0-beta.11 → 4.0.0-beta.13

package/todo/todo.md

@@ -1,3 +1,14 @@
+# Completed
+
+- [x] Enhance retry logic: DBus backoff, BLEAK exceptions, error context
+- [x] Add/expand tests for retry logic (DBus, BLEAK, error context)
+- [x] Add response length validation (min length, error for truncated, actual vs expected)
+- [x] Implement command batching (queue, sequence, share connection)
+- [x] Implement expected disconnect tracking (track disconnects that are expected as part of command flow)
+
+# Next
+
+- [x] Implement notification handling (per-command notification futures, timeout, unsolicited log)
 # TODO: pySwitchBot Feature Parity Roadmap
 
 Implementation tasks to achieve feature parity with pySwitchBot.
@@ -13,75 +24,32 @@ Source: [PYSWITCHBOT_COMPARISON.md](./PYSWITCHBOT_COMPARISON.md)
 
 ### 🔒 Lock Commands
 
+<!-- Task 18.8 moved to completed.md -->
 ### 💡 Light (Bulb/Strip) Commands
 
-### ⚡ Relay Switch Commands
-
-### ✨ Advanced Features
+### Task 18.8: Implement key verification ✅
+**Completed: March 7, 2026**
+**Implementation Details:**
+- Added verifyEncryptionKey() to WoRelaySwitch1, WoAirPurifier, WoBulb (and WoStrip).
+- Method attempts a BLE command with the provided encryption key and throws a clear error if the key is invalid or rejected by the device.
+- Ensures users get immediate feedback on key validity before encrypted operations.
+- Validated by build, test, and lint cycle.
+- See PR/commit: Task 18.8 implementation, March 7, 2026.
 
-- ✅ Phase 2 completed. See `todo/completed.md` for completed task details.
 
----
-
-## 📅 Phase 3: New Devices (Q3 2026)
 
-### 🧹 Vacuum Cleaners
 
-- [x] **Task 12.1**: K10+ Vacuum ✅
-- [x] **Task 12.2**: K10+ Pro Vacuum ✅
-- [x] **Task 12.3**: K10+ Pro Combo Vacuum ✅
-- [x] **Task 12.4**: K11+ Vacuum ✅
-- [x] **Task 12.5**: K20 Vacuum ✅
-- [x] **Task 12.6**: S10 Vacuum ✅
-- [x] **Task 12.7**: S20 Vacuum ✅
-
-#### Vacuum Commands
-- [x] **Task 9.2**: Add basic vacuum commands ✅
-  - `cleanUp(protocolVersion: number)` - Start cleaning
-  - `returnToDock(protocolVersion: number)` - Return to base
-  - Support protocol versions 1 and 2
-
-- [x] **Task 9.3**: Add vacuum status getters ✅
-  - Battery level
-  - Work status (cleaning, returning, docked, etc.)
-  - Dustbin status
-  - Network status
-
-### 🔐 Lock Variants
-
-- [x] **Task 13.1**: Lock Lite ✅
-- [x] **Task 13.2**: Lock Vision ✅
-- [x] **Task 13.3**: Lock Vision Pro ✅
-- [x] **Task 13.4**: Lock Pro WiFi ✅
-
-### ⚡ Power & Climate
-
-- [x] **Task 14.1**: Relay Switch 2PM ✅
-- [x] **Task 14.2**: Garage Door Opener (relay variant) ✅
-- [x] **Task 15.1**: Evaporative Humidifier (WoHumi2) - Already exists, enhance ✅
-- [x] **Task 15.2**: Circulator Fan (Battery/USB) ✅
-- [x] **Task 15.3**: Smart Thermostat Radiator ✅
-- [x] **Task 15.4**: Climate Panel ✅
+### ⚡ Relay Switch Commands
 
-### 🎛️ Other Devices
+### ✨ Advanced Features
 
-✅ **Phase 3 Other Devices block completed!** See `todo/completed.md` for task details.
+- ✅ Phase 2 completed. See `todo/completed.md` for completed task details.
 
 ---
 
-### ✅ Completed in Phase 3
-
-- [x] **Task 10.1**: Implement passive status from advertisements ✅
-- [x] **Task 10.2**: Add sequence number tracking ✅
-
-### 🎯 Next Steps (Phase 3)
+## 📅 Phase 3: New Devices (Q3 2026)
 
-1. **Climate Control**
-  - Climate control block complete ✅
-2. **Lighting Variants**
-  - Tasks 16.1-16.5: Strip Light 3, Floor Lamp, RGBICWW Strip/Floor, Art Frame
-3. **Other Devices**
-  - Tasks 17.1-17.6: Plug Mini EU verify, Roller Shade, Keypad Vision/Pro, Hub3 enhance, HubMini Matter
+✅ **Phase 3 completed!** All vacuum cleaners, lock variants, power/climate devices, lighting variants, and other devices implemented. See `todo/completed.md` for detailed task completion records.
 
 ---
 
@@ -89,64 +57,32 @@ Source: [PYSWITCHBOT_COMPARISON.md](./PYSWITCHBOT_COMPARISON.md)
 
 ### 🎨 Enhanced Device Control
 
-- [ ] **Task 3.2**: Add Curtain 3 specific commands
-  - Support Curtain 3 model detection
-  - Implement multi-command sequences
-  - Add extended info retrieval
-
-- [ ] **Task 3.3**: Add `getExtendedInfo()` command for curtains
-  - Returns device chain information
-  - Grouped curtain status
-  - Command: `0x57 0x0F 0x46 0x01`
-
-- [ ] **Task 6.4**: Implement multi-command sequences for lights
-  - Send multiple commands in series
-  - Used for complex light patterns
-  - Support for Strip Light 3
+- ✅ Task 6.4 completed. See `todo/completed.md` for implementation details.
 
 ### 💧 Humidifier Commands
 
-- [ ] **Task 7.1**: Add humidity level control
-  - `setLevel(level: number)` - Set target humidity (1-100)
-  - Command: `0x57 0x0F 0xXX 0x01 LEVEL` (XX varies by model)
+- ✅ Task 7.1 completed. See `todo/completed.md` for implementation details.
+
+<!-- Task 7.2 moved to completed.md -->
 
-- [ ] **Task 7.2**: Add mode control
-  - `setAuto()` - Automatic mode
-  - `setManual()` - Manual mode
-  - Get target humidity level
 
 ### 🌬️ Air Purifier Commands
 
-- [ ] **Task 8.1**: Add preset modes
-  - Modes: `level_1`, `level_2`, `level_3`, `auto`, `sleep`, `pet`
-  - `setPresetMode(mode: string)`
-  - Command: `0x57 0x0F 0x4E 0x01 MODE_ID`
+<!-- Task 8.1 moved to completed.md -->
 
-- [ ] **Task 8.2**: Add status with AQI/PM2.5
-  - Parse air quality index from response
-  - PM2.5 levels
-  - Fan speed and mode
+<!-- Task 8.2 moved to completed.md -->
 
 ### 🔐 Encryption Enhancements
 
-- [ ] **Task 18.4**: Add encryption for relay switches
-  - Newer relay switches require encryption
-  - Same key retrieval process as locks
 
-- [ ] **Task 18.5**: Add encryption for air purifiers
-  - Newer air purifiers require encryption
-  - Command encryption for all control commands
 
-- [ ] **Task 18.6**: Add encryption for light strips
-  - Newer light strips require encryption
-  - Effect commands need encryption
 
-- [ ] **Task 18.7**: Add encryption state reset on disconnect
-  - Clear IV, cipher, encryption mode
-  - Re-initialize on next connection
-  - Handle firmware updates that change encryption
 
-- [ ] **Task 18.8**: Implement key verification
+
+
+<!-- Task 18.7 moved to completed.md -->
+
+- [x] **Task 18.8**: Implement key verification
   - `verifyEncryptionKey()` - Test key validity
   - Try commands with key before assuming valid
   - Better error messages for invalid keys
@@ -163,44 +99,35 @@ Source: [PYSWITCHBOT_COMPARISON.md](./PYSWITCHBOT_COMPARISON.md)
   - Auto-trigger status update when sequence changes
   - Implement for: locks, relay switches, vacuums, air purifiers
 
-- [ ] **Task 10.3**: Add calibration status tracking
-  - Parse calibration bit from advertisements
-  - Track for: curtains, blind tilts
-  - Warn if device not calibrated
 
-- [ ] **Task 10.4**: Add direction detection for covers
-  - Track `_is_opening` / `_is_closing` states
-  - Update based on position changes
-  - Help UI show proper icons
+
+
 
 ### 🔗 Connection & Error Improvements
 
-- [ ] **Task 19.1**: Add specific BLE exceptions
-  - `SwitchbotOperationError` - Operation failures
-  - `SwitchbotAuthenticationError` - Auth failures
-  - `CharacteristicMissingError` - BLE characteristic missing
 
-- [ ] **Task 19.4**: Enhance retry logic
+
+- [x] **Task 19.4**: Enhance retry logic
   - DBus error backoff (0.25s)
   - `BLEAK_RETRY_EXCEPTIONS` handling
   - Better context in retry errors
 
-- [ ] **Task 19.5**: Add response length validation
+- [x] **Task 19.5**: Add response length validation ✅
   - Check minimum expected length
   - Throw errors for truncated responses
   - Include actual vs expected length in error
 
-- [ ] **Task 20.3**: Implement command batching
+- [x] **Task 20.3**: Implement command batching ✅
   - Queue multiple commands
   - Send in sequence on single connection
   - Share connection overhead
 
-- [ ] **Task 20.4**: Add expected disconnect tracking
+- [x] **Task 20.4**: Add expected disconnect tracking ✅
   - `_expected_disconnect` flag
   - Differentiate expected vs unexpected disconnects
   - Better error handling for unexpected disconnects
 
-- [ ] **Task 20.5**: Implement notification handling
+- [ ] **Task 20.5**: Implement notification handling ⏳
   - Per-command notification futures
   - Timeout handling (5s default)
   - Log unsolicited notifications
@@ -217,11 +144,6 @@ Source: [PYSWITCHBOT_COMPARISON.md](./PYSWITCHBOT_COMPARISON.md)
   - `sendCommandSequence()` - Send series, must all succeed
   - Used for Curtain 3 and newer devices
 
-- [ ] **Task 21.4**: Implement basic settings command
-  - `getBasicInfo()` - Universal settings retrieval
-  - Returns: battery, firmware, device-specific settings
-  - Command: `0x57 0x02`
-
 - [ ] **Task 21.5**: Add mode setting commands
   - Universal mode setting command: `0x57 0x03`
   - Extended settings command
@@ -300,3 +222,13 @@ Source: [PYSWITCHBOT_COMPARISON.md](./PYSWITCHBOT_COMPARISON.md)
 - Full comparison details: [PYSWITCHBOT_COMPARISON.md](../PYSWITCHBOT_COMPARISON.md)
 - pySwitchBot Repository: https://github.com/Danielhiversen/pySwitchbot
 - SwitchBot BLE API: https://github.com/OpenWonderLabs/SwitchBotAPI-BLE
+
+---
+
+## 📋 Todo List
+
+- [x] Enhance retry logic: DBus backoff, BLEAK exceptions, error context
+- [x] Add/expand tests for retry logic (DBus, BLEAK, error context)
+- [x] Add response length validation (min length, error for truncated, actual vs expected)
+- [x] Implement command batching (queue, sequence, share connection)
+- [x] Implement expected disconnect tracking (track disconnects that are expected as part of command flow)