$ show OpenWonderLabs/homebridge-switchbot
This is a Homebridge plugin (`@switchbot/homebridge-switchbot`) that bridges SwitchBot IoT devices (lights, curtains, locks, sensors, vacuums, etc.) into Apple HomeKit using both HAP and Matter protocols. It communicates via Bluetooth Low Energy (BLE) and the SwitchBot OpenAPI cloud API, with configurable fallback and rate-limiting. The plugin provides a rich configuration UI served through Homebridge Config UI X, including device discovery, credential management, and advanced polling settings. The architecture follows a platform plugin pattern with two platform classes (HAP and Matter), a resilient client layer (debounce, circuit breaker, daily budget tracking), a device factory and abstract base class for device-specific implementations, and extensive Matter cluster mappings. While the codebase is well-structured and actively maintained, it suffers from a large monolithic platform file (~2800 lines), low test coverage (~1.36%), and a dependency conflict requiring `--legacy-peer-deps` during installation. ESLint configuration also fails in CI. Nonetheless, the plugin is feature-rich, handles edge cases like BLE encryption and OpenAPI rate limits, and includes a polished custom UI.
The LLM identified 5 files worth highlighting for reuse:
Core client for SwitchBot communication (BLE + OpenAPI). Implements per-device write debouncing (default 100ms), retry logic with exponential backoff, a circuit breaker pattern to stop hammering a failing device, and daily API budget tracking with midnight resets. This is a reusable pattern for any IoT or external API client that must respect rate limits and network failures gracefully.
Abstract base class for all SwitchBot devices. Provides `getState()` with a 15-second TTL cache to reduce redundant API calls during characteristic bursts, configurable BLE/OpenAPI polling with jitter and concurrency control, and methods to create both HAP and Matter accessories. Device-specific subclasses only override `getState()` and `setState()` logic. The pattern is extensible and could be adapted for any multi-protocol IoT device integration.
Maps device type strings (e.g., 'Bot', 'Curtain', 'Meter') to concrete device classes via a factory function. Uses a registry of device type constants and normalization maps to handle legacy and alternate device names. This isolates device instantiation from platform logic and could be reused in any multi-dev-type integration project.
Serves the custom Homebridge configuration UI using modular endpoint registration (`registerConfigEndpoints`, `registerDeviceEndpoints`, `registerDiscoveryEndpoint`). Each endpoint file is self-contained with its own route handlers, validation, and response formatting. This pattern is cleanly separable and could be extracted as a template for other Homebridge plugins with custom UIs.
Contains Matter support mappings (device-to-cluster/attribute), a platform proxy function that selects HAP vs. Matter based on environment, and a `createMatterHandlers` factory that maps Matter cluster actions to SwitchBot API commands. The handler factory pattern is reusable for any Matter bridge that needs to translate generic cluster commands to device-specific API calls.