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

package/todo/completed.md

@@ -0,0 +1,309 @@
+# Completed Tasks
+
+Track completed implementation tasks from the pySwitchBot comparison roadmap.
+
+Last Updated: March 7, 2026
+
+---
+
+## Phase 3: New Devices - Other Devices Block (March 7, 2026)
+
+### Task 17.6: HubMini Matter ✅
+**Implementation Details:**
+- Created `WoHubMiniMatter` class extending `WoHub2` in `src/devices/wo-hubmini-matter.ts`
+- Inherits all hub functionality: `getStatus()` returning sensor data (temperature, humidity, lightLevel)
+- Wired through 3-layer export chain (device → devices/index.ts → src/index.ts)
+- Added to runtime registry: `DEVICE_CLASSES['WoHubMiniMatter']` in `src/switchbot.ts`
+- Added device-type mappings in `src/settings.ts`: "HubMini Matter", "SwitchBot HubMini Matter"
+- Created `test/hubmini-matter.test.ts` with 3 tests validating device-type mappings and method inheritance from WoHub2
+- Full validation passed: build ✅ tests ✅ (233 passing) lint ✅ type-check ✅
+
+### Task 17.5: Hub3 Enhancement ✅
+**Implementation Details:**
+- Enhanced existing `WoHub3` class (extends `WoHub2` in `src/devices/wo-hub3.ts`)
+- Added device-type alias in `src/settings.ts`: "SwitchBot Hub 3" (in addition to existing "Hub 3")
+- Created `test/hub3.test.ts` with 3 tests validating device-type mappings and method inheritance from WoHub2
+- Verified inheritance: `getStatus()` method returns hub sensor data (temperature, humidity, lightLevel)
+- Full validation passed: build ✅ tests ✅ (230 passing) lint ✅ type-check ✅
+
+### Task 17.4: Keypad Vision Pro ✅
+**Implementation Details:**
+- Created `WoKeypadVisionPro` class extending `WoKeypad` in `src/devices/wo-keypad-vision-pro.ts`
+- Inherits all keypad functionality: `getStatus()` methods
+- Wired through 3-layer export chain (device → devices/index.ts → src/index.ts)
+- Added to runtime registry: `DEVICE_CLASSES['WoKeypadVisionPro']` in `src/switchbot.ts`
+- Added device-type mappings in `src/settings.ts`: "Keypad Vision Pro", "SwitchBot Keypad Vision Pro"
+- Created `test/keypad-vision-pro.test.ts` with 3 tests validating device-type mapping and method inheritance
+- Full validation passed: build ✅ tests ✅ (227 passing) lint ✅ type-check ✅
+
+### Task 17.3: Keypad Vision ✅
+**Implementation Details:**
+- Created `WoKeypadVision` class extending `WoKeypad` in `src/devices/wo-keypad-vision.ts`
+- Inherits all keypad functionality: `getStatus()` methods
+- Wired through 3-layer export chain (device → devices/index.ts → src/index.ts)
+- Added to runtime registry: `DEVICE_CLASSES['WoKeypadVision']` in `src/switchbot.ts`
+- Added device-type mappings in `src/settings.ts`: "Keypad Vision", "SwitchBot Keypad Vision"
+- Created `test/keypad-vision.test.ts` with 3 tests validating device-type mapping and method inheritance
+- Full validation passed: build ✅ tests ✅ (224 passing) lint ✅ type-check ✅
+
+---
+
+## Phase 0: Foundation & Preparation ✅
+
+### BLE Infrastructure Hardening (Completed March 6, 2026)
+- [x] Add enumerable device properties for Homebridge compatibility
+- [x] Implement ID-based BLE lookups for macOS (empty MAC address support)
+- [x] Add manufacturer data MAC extraction fallback
+- [x] Broaden discovery filters for legacy UUIDs (000d)
+- [x] Add peripheral validation (connectable flag, RSSI bounds)
+- [x] Implement BLE event listener cleanup
+- [x] Add connection error cleanup (characteristics discovery failure)
+- [x] Create BLE lifecycle regression tests
+- [x] Fix resource leaks (event listeners, connection maps)
+
+### Testing & Validation (Completed March 6-7, 2026)
+- [x] 124 unit tests passing
+- [x] BLE scanner lifecycle tests
+- [x] BLE connection cleanup tests
+- [x] macOS compatibility validation (45 real devices)
+
+---
+
+## Phase 1: Core Parity Sprint ✅
+
+### Completed March 7, 2026
+- [x] Advertisement status parsing and model cache support
+	- Added richer advertisement parsing for Bot, Curtain/Curtain3, Lock/Lock Pro, and Relay Switch models
+	- Added per-discovery model cache in `BLEScanner`
+	- Stored parsed BLE service data on device info for status fallback
+
+- [x] Curtain speed control
+	- Added optional speed to `open`, `close`, and `setPosition` commands
+	- Updated BLE payload and OpenAPI `setPosition` parameter construction
+
+- [x] GCM/CTR BLE encryption plumbing
+	- Added encryption mode (`auto`/`ctr`/`gcm`) support in `BLEConnection`
+	- Added IV length validation, auto mode resolution, and GCM IV increment behavior
+
+- [x] BLE command result and password response validation
+	- Added command response checks for ack bytes (`0x01`, `0x05`, `0x06`)
+	- Added password-required (`0x07`) and password-incorrect (`0x09`) detection
+
+- [x] Persistent BLE connections + operation locking
+	- Added per-device operation lock queue in `BLEConnection`
+	- Added configurable persistent connection timer with auto-disconnect
+	- Added device-level BLE command serialization in base device class
+
+---
+
+## Phase 2: Command Enhancement (Wave 1) ✅
+
+### Completed March 7, 2026
+- [x] Bot mode configuration
+	- Implemented `setMode('press'|'switch')`, `setLongPress(duration)`, `handUp()`, and `handDown()` on `WoHand`
+
+- [x] Lock advanced features
+	- Implemented `unlockWithoutUnlatch()` on `WoSmartLockPro`
+	- Added smart pre-checks to skip lock/unlock when already in target state
+	- Added `getLockInfo()` helper on lock devices
+	- Added BLE notification subscription hooks for lock updates
+
+- [x] Light effect presets
+	- Added 20 preset effects with `setEffect(effectName, speed)` on `WoBulb`/`WoStrip`
+
+- [x] Relay power monitoring
+	- Added relay basic-info parsing for voltage/current/energy from BLE response payload
+	- Integrated parsed metrics into relay BLE status response
+
+- [x] Phase 2 regression coverage
+	- Added `test/phase2-features.test.ts` covering Bot mode config, lock smart detection, light effects, and relay metrics parsing
+
+---
+
+## Phase 2: Command Enhancement (Wave 2) ✅
+
+### Completed March 7, 2026
+- [x] Relay 2PM channel-specific control (Task 5.3)
+	- Created `WoRelaySwitch2PM` class extending `WoRelaySwitch1`
+	- Implemented `setChannel1(state: boolean)` and `setChannel2(state: boolean)` methods
+	- Added channel-specific command constants (CHANNEL1_ON/OFF, CHANNEL2_ON/OFF) to DEVICE_COMMANDS.RELAY
+
+- [x] Bulb color temperature with min/max bounds (Task 6.3)
+	- Added `setColorTemp(minTemp, maxTemp, temp)` method to `WoBulb` class
+	- Command format: `0x57 0x0F 0x47 0x01 0x17 BRIGHTNESS MIN_KEL MAX_KEL TEMP`
+	- Validates and clamps temperatures, ensures current temp within min/max bounds
+	- Auto-corrects reversed min/max values
+
+- [x] RGBIC bulb segmented control (Task 6.2)
+	- Created `WoRGBICBulb` class extending `WoBulb`
+	- Implemented `setSegmentColor(segmentId, r, g, b)` for individual LED segment color control
+	- Implemented `setSegmentEffect(segmentId, effectName, speed)` for segment-specific effects
+	- Added 25 RGBIC effects including segment_cycle, segment_wave, segment_chase, segment_strobe, segment_twinkle
+	- Inherits all standard bulb features from WoBulb (standard effects, color temperature bounds)
+
+- [x] Phase 2 Wave 2 regression coverage
+	- Added `test/phase2-remaining.test.ts` with 21 tests covering Relay 2PM channels, color temperature bounds, and RGBIC segmented control
+
+---
+
+## Phase 2: Advanced Features ✅
+
+### Completed March 7, 2026
+- [x] Sequence device pattern (Task 21.1)
+	- Added `SequenceDevice` base class
+	- Tracks advertisement `sequenceNumber` changes and emits `sequence-changed`
+	- Auto-triggers `update()` on sequence changes with in-flight suppression
+	- Applied to lock, relay switch, and air purifier device families
+	- Added regression coverage in `test/sequence-device.test.ts`
+
+- [x] Override state during connection pattern (Task 21.2)
+	- Added `DeviceOverrideStateDuringConnection` base class
+	- Ignores advertisement state (`bleServiceData`, battery, RSSI) while BLE connection is active
+	- Prevents stale advertisement fallback state during live connections
+	- Applied to bot and plug device families
+	- Added regression coverage in `test/device-override-state-during-connection.test.ts`
+
+---
+
+## Phase 3: New Device Types (Vacuum Variants) ✅
+
+### Completed March 7, 2026
+- [x] K10+ / K10+ Pro / K10+ Pro Combo vacuum variants (Tasks 12.1-12.3)
+	- Added `WoVacuumK10Plus`, `WoVacuumK10Pro`, and `WoVacuumK10ProCombo` classes
+	- Reused shared `WoVacuum` command/status behavior to avoid duplication
+	- Wired `DEVICE_CLASS_MAP` routing for K10 family API/BLE names
+
+- [x] K11+ / K20 / S10 / S20 vacuum variants (Tasks 12.4-12.7)
+	- Added `WoVacuumK11Plus`, `WoVacuumK20`, `WoVacuumS10`, and `WoVacuumS20` classes
+	- Updated `SwitchBot` runtime device registry and package exports
+	- Added regression coverage in `test/vacuum-variants.test.ts` for class mapping
+
+- [x] Lock Lite / Lock Vision variants (Tasks 13.1-13.2)
+	- Added `WoSmartLockLite` and `WoSmartLockVision` classes extending `WoSmartLock`
+	- Both variants use base lock functionality without unlatch support
+	- Wired `DEVICE_CLASS_MAP` routing for lock variant API/BLE names
+
+- [x] Lock Vision Pro / Lock Pro WiFi variants (Tasks 13.3-13.4)
+	- Added `WoSmartLockVisionPro` and `WoSmartLockProWiFi` classes extending `WoSmartLockPro`
+	- Both variants inherit pro lock features including unlatch support
+	- Updated `SwitchBot` runtime device registry and package exports
+	- Added regression coverage in `test/lock-variants.test.ts` for class mapping and method inheritance
+
+---
+
+## Phase 3: New Device Types (Relay Variants) ✅
+
+### Completed March 7, 2026
+- [x] Relay Switch 2PM wiring completion (Task 14.1)
+	- WoRelaySwitch2PM class already existed from Phase 2
+	- Completed wiring through src/index.ts exports
+	- Added to src/switchbot.ts DEVICE_CLASSES registry
+	- Added 'Relay Switch 2PM' mapping to DEVICE_CLASS_MAP in src/settings.ts
+
+- [x] Garage Door Opener relay variant (Task 14.2)
+	- Added WoGarageDoorOpener class extending WoRelaySwitch1
+	- Lightweight variant reuses relay switch control methods (turnOn/turnOff/toggle)
+	- Wired through exports, registry, and DEVICE_CLASS_MAP
+	- Added regression coverage in test/relay-variants.test.ts (4 tests)
+	- Tests verify: 2PM class mapping, Garage Door Opener mapping, channel methods on 2PM, relay methods on opener
+
+---
+
+## Phase 3: New Device Types (Climate Enhancements) ✅
+
+### Completed March 7, 2026
+- [x] Evaporative Humidifier (WoHumi2) enhancement (Task 15.1)
+	- Enhanced WoHumi2 with convenience methods: setAuto(), setManual(), setLevel(level)
+	- Added evaporative humidifier API aliases in DEVICE_CLASS_MAP to map to WoHumi2
+	- Added regression coverage in test/humidifier2-enhancement.test.ts (4 tests)
+	- Tests verify WoHumi2 method delegation and evaporative humidifier device-type mapping
+
+- [x] Circulator Fan (Battery/USB) variant (Task 15.2)
+	- Added WoCirculatorFan class extending WoAirPurifier
+	- Wired fan class through exports and SwitchBot runtime DEVICE_CLASSES registry
+	- Added device-type aliases in DEVICE_CLASS_MAP for Battery/USB fan names
+	- Added regression coverage in test/circulator-fan-variants.test.ts (4 tests)
+	- Tests verify model mapping and inherited control methods (turnOn/turnOff/setFanSpeed)
+
+- [x] Smart Thermostat Radiator variant (Task 15.3)
+	- Added WoSmartThermostatRadiator class extending WoAirPurifier
+	- Wired class through exports and SwitchBot runtime DEVICE_CLASSES registry
+	- Added device-type aliases in DEVICE_CLASS_MAP for thermostat radiator names
+	- Added regression coverage in test/thermostat-radiator-variants.test.ts (4 tests)
+	- Tests verify model mapping and inherited climate control methods (turnOn/turnOff/setMode)
+
+- [x] Climate Panel variant (Task 15.4)
+	- Added WoClimatePanel class extending WoAirPurifier
+	- Wired class through exports and SwitchBot runtime DEVICE_CLASSES registry
+	- Added climate panel aliases in DEVICE_CLASS_MAP
+	- Added regression coverage in test/climate-panel-variants.test.ts (3 tests)
+	- Tests verify model mapping and inherited climate control methods (turnOn/turnOff/setMode)
+
+## Phase 3: New Device Types (Lighting Variants) ⏳
+
+### Completed March 7, 2026
+- [x] Strip Light 3 (Task 16.1)
+	- Added WoStripLight3 class extending WoBulb for color control
+	- Wired class through exports and SwitchBot runtime DEVICE_CLASSES registry
+	- Added device-type mappings: "Strip Light 3", "SwitchBot Strip Light 3"
+	- Added regression coverage in test/strip-light-3.test.ts (3 tests)
+	- Tests verify device-type mapping for both aliases and inherited color control methods
+
+- [x] Floor Lamp (Task 16.2)
+	- Added WoFloorLamp class extending WoBulb for color control
+	- Wired class through exports and SwitchBot runtime DEVICE_CLASSES registry
+	- Added device-type mappings: "Floor Lamp", "SwitchBot Floor Lamp"
+	- Added regression coverage in test/floor-lamp.test.ts (3 tests)
+	- Tests verify device-type mapping for both aliases and inherited color control methods
+
+- [x] RGBICWW Strip Light (Task 16.3)
+	- Added WoRGBICWWStripLight class extending WoRGBICBulb for segmented control
+	- Wired class through exports and SwitchBot runtime DEVICE_CLASSES registry
+	- Added device-type mappings: "RGBICWW Strip Light", "SwitchBot RGBICWW Strip Light"
+	- Added regression coverage in test/rgbicww-strip-light.test.ts (3 tests)
+	- Tests verify device-type mapping and inherited RGBIC methods (setSegmentColor, setSegmentEffect)
+	- Note: Also wired WoRGBICBulb through exports for completeness
+
+- [x] RGBICWW Floor Lamp (Task 16.4)
+	- Added WoRGBICWWFloorLamp class extending WoRGBICBulb for segmented control
+	- Wired class through exports and SwitchBot runtime DEVICE_CLASSES registry
+	- Added device-type mappings: "RGBICWW Floor Lamp", "SwitchBot RGBICWW Floor Lamp"
+	- Added regression coverage in test/rgbicww-floor-lamp.test.ts (3 tests)
+	- Tests verify device-type mapping and inherited RGBIC methods (setSegmentColor, setSegmentEffect)
+
+- [x] Art Frame (Task 16.5)
+	- Added WoArtFrame class extending WoBulb for color control
+	- Wired class through exports and SwitchBot runtime DEVICE_CLASSES registry
+	- Added device-type mappings: "Art Frame", "SwitchBot Art Frame"
+	- Added regression coverage in test/art-frame.test.ts (3 tests)
+	- Tests verify device-type mapping for both aliases and inherited color control methods
+	- **Lighting variants block (Tasks 16.1-16.5) complete!** ✅
+
+## Phase 3: New Device Types (Other Devices) ⏳
+
+### Completed March 7, 2026
+- [x] Plug Mini EU verification (Task 17.1)
+	- Verified WoPlugMiniEU exists in runtime registry (aliased to WoPlugMiniUS)
+	- Verified device-type mapping: "Plug Mini (EU)" → WoPlugMiniEU
+	- Added regression coverage in test/plug-mini-eu.test.ts (2 tests)
+	- Tests verify EU variant maps to WoPlugMiniUS class and inherits plug control methods
+	- Note: WoPlugMiniEU shares implementation with WoPlugMiniUS (regional variant)
+
+- [x] Roller Shade (Task 17.2)
+	- Added WoRollerShade class extending WoCurtain for motorized window covering control
+	- Wired class through exports and SwitchBot runtime DEVICE_CLASSES registry
+	- Added device-type mappings: "Roller Shade", "SwitchBot Roller Shade"
+	- Added regression coverage in test/roller-shade.test.ts (3 tests)
+	- Tests verify device-type mapping and inherited curtain control methods (open, close, pause, setPosition)
+
+---
+
+## Notes
+
+When moving a task from todo.md to this file:
+1. Add the completion date
+2. Note any implementation details or deviations
+3. Link to relevant PRs or commits if applicable
+4. Update "Last Updated" timestamp
+
+Format: `- [x] **Task X.Y**: Description (Completed: YYYY-MM-DD)`

package/todo/todo.md

@@ -0,0 +1,302 @@
+# TODO: pySwitchBot Feature Parity Roadmap
+
+Implementation tasks to achieve feature parity with pySwitchBot.
+
+Last Updated: March 7, 2026  
+Source: [PYSWITCHBOT_COMPARISON.md](./PYSWITCHBOT_COMPARISON.md)
+
+---
+
+## 📅 Phase 2: Command Enhancement (Q2 2026)
+
+### 🤖 Bot (WoHand) Commands
+
+### 🔒 Lock Commands
+
+### 💡 Light (Bulb/Strip) Commands
+
+### ⚡ Relay Switch Commands
+
+### ✨ Advanced Features
+
+- ✅ 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 ✅
+
+### 🎛️ Other Devices
+
+✅ **Phase 3 Other Devices block completed!** See `todo/completed.md` for 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)
+
+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 4: Advanced Features (Q4 2026)
+
+### 🎨 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
+
+### 💧 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.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.2**: Add status with AQI/PM2.5
+  - Parse air quality index from response
+  - PM2.5 levels
+  - Fan speed and mode
+
+### 🔐 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
+  - `verifyEncryptionKey()` - Test key validity
+  - Try commands with key before assuming valid
+  - Better error messages for invalid keys
+
+### 📊 Status & Response Parsing
+
+- [x] **Task 10.1**: Implement passive status from advertisements ✅
+  - Parse device state from BLE advertisements
+  - No connection needed for basic status
+  - Cache last known state
+
+- [x] **Task 10.2**: Add sequence number tracking ✅
+  - Monitor `sequence_number` in advertisements
+  - 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
+  - DBus error backoff (0.25s)
+  - `BLEAK_RETRY_EXCEPTIONS` handling
+  - Better context in retry errors
+
+- [ ] **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
+  - Queue multiple commands
+  - Send in sequence on single connection
+  - Share connection overhead
+
+- [ ] **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
+  - Per-command notification futures
+  - Timeout handling (5s default)
+  - Log unsolicited notifications
+
+- [ ] **Task 20.6**: Add characteristic caching
+  - Cache read/write characteristics
+  - Clear cache on characteristic missing error
+  - Avoid repeated characteristic discovery
+
+### 🎯 Advanced Patterns
+
+- [ ] **Task 21.3**: Add multi-command support
+  - `sendMultipleCommands()` - Send series, return if any succeed
+  - `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
+  - Per-device mode enums
+
+- [ ] **Task 21.6**: Add passive polling
+  - `PASSIVE_POLL_INTERVAL = 60 * 60 * 24` (24 hours)
+  - `pollNeeded()` method
+  - Auto-poll inactive devices periodically
+
+- [ ] **Task 21.7**: Implement cloud device fetching
+  - `getDevices()` - Fetch devices from SwitchBot account
+  - Auto-populate model cache from cloud
+  - Handle regional APIs (US/CN/EU)
+
+---
+
+## 📈 Medium Priority Enhancements
+
+### Discovery & Advertisement
+
+- [ ] **Task 1.4**: Enhance advertisement data structure
+  - Add `rawAdvData` field
+  - Add `isEncrypted` flag
+  - Add `modelFriendlyName` field
+
+- [ ] **Task 1.5**: Add advertisement data merging
+  - Preserve old values when new data is None
+  - Recursive dict merging for nested structures
+  - Implement `_merge_data()` helper
+
+### Relay Switch Additional Features
+
+- [ ] **Task 5.4**: Add time/energy tracking
+  - `getCurrentTimeAndStartTime()` - For energy calculations
+  - Command: `0x57 0x0F 0x51 0x01 0x05 0x01 0x00 0x00 0x00`
+
+- [ ] **Task 5.5**: Add garage door opener support
+  - Variant of relay switch
+  - Specific command sequences
+  - Model: SwitchBot Relay Switch (garage mode)
+
+### Status Parsing
+
+- [ ] **Task 11.1**: Add byte-by-byte response validation
+  - Check response length
+  - Validate specific byte positions
+  - Compare against expected value sets: `{1}`, `{1, 5}`, `{1, 6}`
+
+---
+
+## 🎯 Success Metrics
+
+- **Feature Parity**: 90%+ of pySwitchBot commands implemented
+- **Device Coverage**: 95%+ of SwitchBot device types supported
+- **Status Accuracy**: Advertisement-based status for all devices
+- **Connection Efficiency**: 50% reduction in connection overhead via batching
+- **Error Clarity**: Specific error types for all failure modes
+
+---
+
+## 📝 Notes
+
+### Task Completion Process
+1. Move completed task from this file to `completed.md`
+2. Add completion date and any notes
+3. Update "Last Updated" timestamp
+4. Reference any relevant PRs or commits
+
+### Priority Levels
+- **High Priority**: Core functionality, user-facing features
+- **Medium Priority**: Enhancements, optimizations
+- **Low Priority**: Nice-to-have features
+
+### Reference
+- 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

package/tsconfig.build.json

@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src"
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "test",
+    "**/*.spec.ts",
+    "**/*.test.ts",
+    ".dev-archive/**/*",
+    "dist",
+    "node_modules"
+  ]
+}