node-switchbot 4.0.0-beta.7 → 4.0.0-beta.9

package/todo/todo.md

@@ -0,0 +1,369 @@
+# 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
+
+- [ ] **Task 2.1**: Add `setMode(mode: 'switch' | 'press')` command
+  - Switch mode: Toggle on/off
+  - Press mode: Momentary press
+  - Command: `0x57 0x0F 0x47 0x01 MODE` (MODE: 0x00=press, 0x01=switch)
+
+- [ ] **Task 2.2**: Add `setLongPress(duration: number)` command
+  - Configure press duration (1-255 deciseconds)
+  - Command: `0x57 0x0F 0x47 0x03 DURATION`
+
+- [ ] **Task 2.3**: Add direct arm control
+  - `handUp()` - Raise arm
+  - `handDown()` - Lower arm
+  - More precise than toggle
+
+### 🔒 Lock Commands
+
+- [ ] **Task 4.1**: Add `unlockWithoutUnlatch()` command
+  - EU firmware feature
+  - Unlocks without unlatching door
+  - Command: Different from standard unlock
+
+- [ ] **Task 4.2**: Implement notification handling
+  - Subscribe to lock notifications
+  - Real-time status updates
+  - Handle unsolicited notifications
+
+- [ ] **Task 4.3**: Add smart lock state detection
+  - Check current state before sending command
+  - Avoid unnecessary unlock/lock commands
+  - Return early if already in target state
+
+- [ ] **Task 4.4**: Add `getLockInfo()` command
+  - Get detailed lock configuration
+  - Battery, firmware, settings
+  - Command: `0x57 0x02`
+
+### 💡 Light (Bulb/Strip) Commands
+
+- [ ] **Task 6.1**: Add effect presets (20+ effects)
+  - Christmas, Halloween, Sunset, Rainbow, etc.
+  - Command: `0x57 0x0F 0x47 0x01 EFFECT_ID 0xFF SPEED 0x00 0x00 0x00`
+  - Effect IDs: 0x00-0x13 (20 effects)
+  - Speed: 0x01 (slow) to 0x64 (fast)
+
+- [ ] **Task 6.2**: Add RGBIC segmented control
+  - Control individual LED segments
+  - RGBIC-specific effects
+  - Multi-zone color control
+
+- [ ] **Task 6.3**: Add color temperature with min/max
+  - `setColorTemp(minTemp: number, maxTemp: number, temp: number)`
+  - Command: `0x57 0x0F 0x47 0x01 0x17 BRIGHTNESS MIN_KEL MAX_KEL TEMP`
+
+### ⚡ Relay Switch Commands
+
+- [ ] **Task 5.1**: Add `toggle()` command
+  - Toggle current state
+  - Command: `0x57 0x0F 0x50 0x01 0x01 0x02`
+
+- [ ] **Task 5.2**: Implement power monitoring
+  - `getBasicInfo()` - Returns voltage, current, power, energy
+  - Parse response: 11 bytes with power data at specific offsets
+  - Command: `0x57 0x02`
+
+- [ ] **Task 5.3**: Add channel-specific control (2PM model)
+  - `setChannel1(state: boolean)`
+  - `setChannel2(state: boolean)`
+  - Detect 2PM vs 1PM model
+
+### ✨ Advanced Features
+
+- [ ] **Task 21.1**: Implement sequence device pattern
+  - `SequenceDevice` base class
+  - Monitor `sequence_number` from advertisements
+  - Auto-trigger `update()` when sequence changes
+  - Use for: locks, relay switches, vacuums, air purifiers
+
+- [ ] **Task 21.2**: Add override state during connection pattern
+  - `DeviceOverrideStateDuringConnection` base class
+  - Ignore advertisement data while connected
+  - Prevents stale data issues
+  - Use for: bot, plugs
+
+---
+
+## 📅 Phase 3: New Devices (Q3 2026)
+
+### 🧹 Vacuum Cleaners
+
+- [ ] **Task 12.1**: K10+ Vacuum
+- [ ] **Task 12.2**: K10+ Pro Vacuum
+- [ ] **Task 12.3**: K10+ Pro Combo Vacuum
+- [ ] **Task 12.4**: K11+ Vacuum
+- [ ] **Task 12.5**: K20 Vacuum
+- [ ] **Task 12.6**: S10 Vacuum
+- [ ] **Task 12.7**: S20 Vacuum
+
+#### Vacuum Commands
+- [ ] **Task 9.2**: Add basic vacuum commands
+  - `cleanUp(protocolVersion: number)` - Start cleaning
+  - `returnToDock(protocolVersion: number)` - Return to base
+  - Support protocol versions 1 and 2
+
+- [ ] **Task 9.3**: Add vacuum status getters
+  - Battery level
+  - Work status (cleaning, returning, docked, etc.)
+  - Dustbin status
+  - Network status
+
+### 🔐 Lock Variants
+
+- [ ] **Task 13.1**: Lock Lite
+- [ ] **Task 13.2**: Lock Vision
+- [ ] **Task 13.3**: Lock Vision Pro
+- [ ] **Task 13.4**: Lock Pro WiFi
+
+### ⚡ Power & Climate
+
+- [ ] **Task 14.1**: Relay Switch 2PM
+- [ ] **Task 14.2**: Garage Door Opener (relay variant)
+- [ ] **Task 15.2**: Circulator Fan (Battery/USB)
+- [ ] **Task 15.3**: Smart Thermostat Radiator
+- [ ] **Task 15.4**: Climate Panel
+
+### 💡 Lighting Variants
+
+- [ ] **Task 16.1**: Strip Light 3
+- [ ] **Task 16.2**: Floor Lamp
+- [ ] **Task 16.3**: RGBICWW Strip Light
+- [ ] **Task 16.4**: RGBICWW Floor Lamp
+- [ ] **Task 16.5**: Art Frame
+
+### 🎛️ Other Devices
+
+- [ ] **Task 17.2**: Roller Shade
+- [ ] **Task 17.3**: Keypad Vision
+- [ ] **Task 17.4**: Keypad Vision Pro
+- [ ] **Task 17.6**: 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
+
+- [ ] **Task 10.1**: Implement passive status from advertisements
+  - Parse device state from BLE advertisements
+  - No connection needed for basic status
+  - Cache last known state
+
+- [ ] **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/PRODUCTION_READY.md

@@ -1,135 +0,0 @@
-# Production Readiness Status - v4.0.0
-
-## ✅ Completed Production Enhancements
-
-### 📦 Code Quality
-
-- ✅ **Build**: TypeScript compilation passes with zero errors
-- ✅ **Tests**: 40/40 tests passing (5 test suites)
-- ✅ **Lint**: ESLint passes with @antfu/eslint-config rules
-- ✅ **Type Safety**: Full TypeScript coverage with strict mode
-- ✅ **ES Modules**: Native ES2022 module implementation
-
-### 🎯 Error Handling
-
-- ✅ **Custom Error Classes**: 9 specific error types for better debugging
-  - `SwitchBotError` (base)
-  - `BLENotAvailableError`
-  - `APINotAvailableError`
-  - `DeviceNotFoundError`
-  - `CommandFailedError`
-  - `ConnectionTimeoutError`
-  - `DiscoveryError`
-  - `APIError`
-  - `ValidationError`
-- ✅ **Error Codes**: Each error has a unique code for programmatic handling
-- ✅ **Error Context**: Errors include relevant context (device IDs, connection types, etc.)
-
-### 📚 Documentation
-
-- ✅ **README**: Updated with v4 quick start and migration guide
-- ✅ **CHANGELOG**: Comprehensive v4.0.0 release notes
-- ✅ **Examples**: 6 complete usage examples
-  - `basic-usage.js` - Hybrid BLE + API mode
-  - `ble-only.js` - Linux BLE-only mode
-  - `api-only.js` - Cross-platform API mode
-  - `device-control.js` - All device types
-  - `event-handling.js` - Event listeners
-  - `typescript-usage.ts` - Type-safe usage
-- ✅ **Examples README**: Comprehensive examples documentation
-- ✅ **API Docs**: TypeDoc-generated documentation (run `npm run docs`)
-
-### 🧪 Testing
-
-- ✅ **Unit Tests**: 5 test suites covering core functionality
-  - Export validation (v4-only, no v3 legacy)
-  - Device manager operations
-  - Error class behaviors
-  - Utility functions
-  - Device base functionality
-- ✅ **Test Coverage**: Key paths validated
-- ✅ **Vitest Config**: Proper test exclusions for .dev-archive
-
-### 🔧 Development Tools
-
-- ✅ **ESLint**: Auto-formatting with lint:fix
-- ✅ **TypeScript**: Strict compilation settings
-- ✅ **Vitest**: Modern testing framework
-- ✅ **TypeDoc**: API documentation generation
-- ✅ **NPM Scripts**: Complete build/test/lint workflow
-
-### 📦 Package Configuration
-
-- ✅ **package.json**: Updated to v4.0.0 with correct metadata
-- ✅ **.npmignore**: Excludes test/, examples/, .dev-archive/ from npm package
-- ✅ **Engine Requirements**: Node.js ^20 || ^22 || ^24
-- ✅ **Type Exports**: Full TypeScript definitions exported
-
-### 🏗️ Architecture
-
-- ✅ **Hybrid BLE/API**: Unified approach with automatic fallback
-- ✅ **Device Manager**: Centralized device access pattern
-- ✅ **Event-Driven**: EventEmitter for discovery and commands
-- ✅ **30 Device Types**: Full support for all SwitchBot devices
-- ✅ **Platform Support**:
-  - Linux: Full BLE + API
-  - Windows/macOS: API-only (graceful BLE degradation)
-
-### 🔐 Security
-
-- ✅ **Credential Handling**: Secure HMAC-SHA256 for API auth
-- ✅ **Optional Credentials**: Works in BLE-only mode without API credentials
-- ✅ **No Hardcoded Secrets**: Examples use environment variables
-
-## 📊 Test Results
-
-```
-Test Files  5 passed (5)
-     Tests  40 passed (40)
-  Duration  431ms
-```
-
-### Test Coverage Breakdown
-
-- ✅ `v4-exports.test.ts` (3 tests) - Export validation
-- ✅ `device-manager.test.ts` (6 tests) - Device management
-- ✅ `errors.test.ts` (15 tests) - Error handling
-- ✅ `utils.test.ts` (9 tests) - Utility functions
-- ✅ `devices.test.ts` (7 tests) - Device functionality
-
-## 🚢 Release Readiness
-
-### Pre-Release Checklist
-
-- ✅ All tests passing
-- ✅ Build succeeds
-- ✅ Lint passes
-- ✅ Documentation complete
-- ✅ Examples working
-- ✅ CHANGELOG updated
-- ✅ README updated
-- ✅ No TODO/FIXME comments
-- ✅ Type definitions exported
-- ✅ Error handling comprehensive
-
-### Deployment Steps
-
-1. ✅ Version bumped to 4.0.0
-2. ✅ CHANGELOG updated
-3. ⏳ Tag release: `git tag v4.0.0`
-4. ⏳ Push to GitHub: `git push origin latest --tags`
-5. ⏳ CI will auto-publish to npm via GitHub Actions
-
-## 🎉 Ready for Production
-
-All production readiness criteria have been met. The v4.0.0 codebase is:
-
-- ✅ **Stable**: All tests passing, no known bugs
-- ✅ **Documented**: Comprehensive docs and examples
-- ✅ **Type-Safe**: Full TypeScript definitions
-- ✅ **Tested**: 40 tests covering core functionality
-- ✅ **Clean**: Linted and formatted code
-- ✅ **Maintainable**: Clear architecture and error handling
-- ✅ **Production-Grade**: Enterprise-ready error handling and logging
-
-**Status**: 🟢 PRODUCTION READY