@homebridge-plugins/homebridge-ewelink 12.6.2 → 12.7.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to homebridge-ewelink will be documented in this file.
 
+### v12.7.0 (2025-09-19)
+
+- dependency updates
+- added new devices
+
 ## v12.6.2 (2025-07-24)
 
 ### Other Changes

package/CLAUDE.md

@@ -0,0 +1,144 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Development
+- **Lint code**: `npm run lint`
+- **Fix lint issues**: `npm run lint:fix`
+
+## Architecture
+
+### Core Structure
+This is a Homebridge plugin that integrates eWeLink devices into HomeKit. The main entry point is `lib/index.js` which registers the platform with Homebridge.
+
+### Key Components
+
+**Platform Layer** (`lib/platform.js`)
+- Main platform class that coordinates all plugin operations
+- Manages device discovery, initialization, and lifecycle
+- Handles configuration and storage via node-persist
+- Implements request queue with p-queue for rate limiting
+- Routes devices to appropriate handlers based on UIID and configuration
+
+**Connection Layer** (`lib/connection/`)
+- `api.js`: Internal HTTP API server for local control
+- `http.js`: eWeLink cloud API client
+- `lan.js`: Local network device control
+- `ws.js`: WebSocket client for real-time updates
+
+**Device Layer** (`lib/device/`)
+- Individual device type implementations (switches, lights, sensors, etc.)
+- Each device type extends base functionality with specific HomeKit characteristics
+- Supports various Sonoff/eWeLink device models
+- Device types include:
+  - Single/Multi switches with optional power monitoring
+  - RGB/CCT/Dimmable lights
+  - Sensors (ambient, contact, motion, water)
+  - Thermostats, fans, curtains
+  - RF Bridge devices
+  - Zigbee devices (via bridge)
+  - Groups and simulations
+
+**Utilities** (`lib/utils/`)
+- `constants.js`: Device configurations and UIID mappings
+- `functions.js`: Shared utility functions
+- `custom-chars.js`: Custom HomeKit characteristics
+- `eve-chars.js`: Eve Home app specific characteristics
+- Language files for internationalization
+
+### Device Identification (UIID)
+Every eWeLink device has a UIID (unique interface ID) that determines its capabilities:
+
+**Key UIID Categories** (defined in `lib/utils/constants.js`):
+- `switchSingle`: [1, 6, 14, 24, 27, etc.] - Basic on/off switches
+- `switchSinglePower`: [5, 32] - Switches with power monitoring
+- `switchMulti`: [2, 3, 4, 7, 8, 9, etc.] - Multi-channel switches
+- `lightRGB`: [22] - RGB color lights
+- `lightCCT`: [103] - Color temperature lights
+- `lightRGBCCT`: [33, 59, 104, etc.] - Full color + temperature lights
+- `lightDimmer`: [36, 44, 57] - Dimmable lights
+- `sensorContact`: [102, 154] - Door/window sensors
+- `sensorAmbient`: [15, 181] - Temperature/humidity sensors
+- `thermostat`: [127] - Smart thermostats
+- `rfBridge`: [28, 98] - RF 433MHz bridges
+- `zbBridge`: [66, 128, 168] - Zigbee bridges
+- Zigbee prefixed devices (1000-7000 range)
+
+**Device Routing Logic** (in `lib/platform.js:initialiseDevice()`):
+1. Checks device UIID against category arrays in constants
+2. Considers user configuration (showAs property for simulations)
+3. Creates appropriate device handler instance
+4. Special handling for:
+   - Power monitoring devices (different decimal places)
+   - Multi-channel devices (individual switches/outlets)
+   - Bridge devices (RF/Zigbee sub-devices)
+   - Simulated accessories (garage doors, valves, etc.)
+
+### Communication Flow
+1. Plugin authenticates with eWeLink cloud to fetch device list
+2. Attempts local (LAN) control first for supported devices
+3. Falls back to cloud control via HTTP/WebSocket if local fails
+4. Maintains real-time sync through WebSocket connection
+5. Exposes optional internal API for external control
+
+### Command & Payload Structure
+
+**HTTP Connection** (`lib/connection/http.js`)
+- **Login**: POST to `/v2/user/login`
+  - Request: `{email/phoneNumber, password, countryCode}`
+  - Response: Returns `at` (access token) and `apikey`
+  - Uses HMAC-SHA256 signature with app secret
+- **Get Homes**: GET to `/v2/family`
+  - Headers: Bearer token authentication
+- **Get Devices**: GET to `/v2/device` and `/v2/group`
+  - Fetches device list per home with full params
+
+**WebSocket Connection** (`lib/connection/ws.js`)
+- **Authentication**: Action `userOnline`
+  - Payload: `{action: 'userOnline', apikey, appid, at, nonce, sequence, ts, version: 8}`
+- **Device Update**: Action `update`
+  - Payload: `{action: 'update', apikey, deviceid, params, sequence, ts: 0, userAgent: 'app'}`
+  - Params vary by device type (see below)
+- **Query State**: Action `query`
+  - Payload: `{action: 'query', apikey, deviceid, params: [], sequence}`
+- **Heartbeat**: Sends `'ping'` at intervals to keep connection alive
+
+**LAN Connection** (`lib/connection/lan.js`)
+- Uses mDNS discovery for `_ewelink._tcp.local` services
+- **Encryption**: AES-128-CBC with MD5 hashed device key
+- **Update Request**: POST to `http://{device_ip}:8081/zeroconf/{suffix}`
+  - Suffixes: `switch`, `switches`, `dimmable`, `light`, `fan`, `transmit`, `location`, `monitor`
+  - Encrypted payload with IV
+  - Data structure: `{data, deviceid, encrypt: true, iv, selfApikey: '123', sequence}`
+- **DNS Monitoring**: Listens for TXT records with encrypted device updates
+
+**Common Device Parameters**
+- **Single Switch**: `{switch: 'on'/'off'}`
+- **Multi Switch**: `{switches: [{outlet: 0-3, switch: 'on'/'off'}]}`
+- **SCM Devices**: Uses switches array even for single switch (UIID 77/78/81/107/112/138/160)
+- **Dimmable**: `{brightness: 0-100, mode: 0}`
+- **RGB Light**: `{ltype: 'color'/'white', color: {br, r, g, b}, white: {br, ct}}`
+- **Power Monitor**: `{uiActive: 120}` to request power updates
+- **Curtain/Motor**: `{location: 0-100}` for position
+- **RF Bridge**: `{cmd: 'transmit', rfChl: channel}`
+- **TH10/16**: `{switch, mainSwitch, deviceType: 'normal'}`
+- **Fan (iFan)**: `{light: 'on'/'off', fan: 'on'/'off', speed: 1-3}`
+
+**Update Priority**
+1. Try LAN if device supports it (check `constants.devices.lan` array)
+2. Fall back to WebSocket if LAN fails
+3. Queue updates with 250ms intervals to prevent rate limiting
+4. Power monitoring devices poll every 120 seconds
+
+### State Management
+- Device states cached using node-persist
+- Queue system (p-queue) prevents API rate limiting
+- Fakegato history service for Eve Home app integration
+
+## Important Notes
+- ES modules with Node.js 20/22/24 support required
+- Uses @antfu/eslint-config for code style
+- No test suite - manual testing required
+- Verified Homebridge plugin following official standards

package/lib/connection/lan.js

@@ -242,6 +242,9 @@ export default class {
       } else if (json.params.uiActive && deviceInfo.uiid === 32) {
         params.uiActive = json.params.uiActive
         suffix = 'monitor'
+      } else if (json.params.uiActive && [126, 165].includes(deviceInfo.uiid)) {
+        // DualR3 uses statistics endpoint in LAN mode
+        suffix = 'statistics'
       } else if (json.params.cmd) {
         params.cmd = 'transmit'
         params.rfChl = json.params.rfChl

package/lib/utils/constants.js

@@ -284,7 +284,7 @@ export default {
       211,
       212,
     ],
-    switchSingle: [1, 6, 14, 24, 27, 226, 1009, 1256, 7004, 7005, 7010],
+    switchSingle: [1, 6, 14, 24, 27, 225, 226, 1009, 1256, 7004, 7005, 7010, 7032],
     switchSCM: [77, 78, 81, 107, 112, 138, 160, 191, 209],
     switchSCMPower: [182, 190],
     switchSinglePower: [5, 32],
@@ -312,18 +312,19 @@ export default {
       210,
       211,
       212,
+      262,
       2256,
       3256,
       4256,
     ],
-    switchMultiPower: [126, 165],
+    switchMultiPower: [126, 165, 262],
     switchMate: [177],
     switchMan: [174],
     lightDimmer: [36, 44, 57],
     lightRGB: [22],
     lightCCT: [103],
     lightRGBCCT: [33, 59, 104, 135, 136, 137, 173],
-    curtain: [11, 67],
+    curtain: [11, 67, 91, 258],
     sensorContact: [102, 154],
     sensorAmbient: [15, 181],
     sensorTempHumi: [18],
@@ -344,7 +345,7 @@ export default {
     zbSensorMotion: [2026, 7002],
     zbSensorOccupancy: [7016],
     zbSensorContact: [3026, 7003],
-    zbSensorWater: [4026],
+    zbSensorWater: [4026, 7019],
     zbSensorSmoke: [5026],
     zbThermostat: [7017],
     zbWaterValve: [7027],
@@ -468,6 +469,7 @@ export default {
     83: 3, // "GSM_SOCKET_3_NO_FLOW"
     84: 4, // "GSM_SOCKET_4_NO_FLOW"
     87: 1, // "EWELINK_IOT_CAMERA" (GK-200MP2B)
+    91: 1, // "ROLLING_DOOR" (Cover/Curtain device)
     98: 1, // "DOORBELL_RFBRIDGE"
     102: 1, // "DOOR_MAGNETIC" (OPL-DMA, DW2)
     103: 1, // "WOTEWODE_TEM_LIGHT" (B02-F)
@@ -506,8 +508,11 @@ export default {
     210: 2, // Sonoff Ultimate Switch T5-2C-86
     211: 3, // Sonoff Ultimate Switch T5-3C-86
     212: 4, // Sonoff Ultimate Switch T5-4C-86
+    225: 1, // CK-BL602-PCSW-01 (Single switch with power monitoring)
     226: 1, // https://github.com/homebridge-plugins/homebridge-ewelink/issues/636
     243: 1, // Zigbee Bridge Ultra
+    258: 1, // Additional Cover device
+    262: 4, // CK-BL602-SWP1-02 (4-channel switch with power monitoring)
     1000: 1, // "zigbee_ON_OFF_SWITCH_1000" (button device)
     1009: 1, // "" (Some sort of single switch device)
     1256: 1, // "ZIGBEE_SINGLE_SWITCH"
@@ -535,7 +540,9 @@ export default {
     7014: 1, // some sensor https://github.com/homebridge-plugins/homebridge-ewelink/issues/494
     7016: 1, // https://sonoff.tech/product/gateway-and-sensors/snzb-06p/
     7017: 1, // https://github.com/homebridge-plugins/homebridge-ewelink/issues/518
+    7019: 1, // Zigbee Water Sensor
     7027: 1, // Zigbee Smart Water Valve
+    7032: 1, // Zigbee Power Monitoring Switch
   },
 
   cannotSupportDevices: {
@@ -582,7 +589,6 @@ export default {
     88: 0, // "YK_INFRARED"
     89: 0, // "SMART_OPEN_MACHINE"
     90: 0, // "GSM_RFBridge"
-    91: 0, // "ROLLING_DOOR_91"
     93: 0, // "HTHD_AIR_CLEANER"
     94: 0, // "YIAN_ELECTRIC_PROTECT"
     109: 0, // "YK_INFRARED_2"

package/package.json

@@ -3,7 +3,7 @@
   "displayName": "Homebridge eWeLink",
   "alias": "eWeLink",
   "type": "module",
-  "version": "12.6.2",
+  "version": "12.7.0",
   "description": "Homebridge plugin to integrate eWeLink devices into HomeKit.",
   "author": {
     "name": "bwp91",
@@ -62,13 +62,13 @@
   },
   "dependencies": {
     "@homebridge/plugin-ui-utils": "^2.1.0",
-    "axios": "^1.11.0",
+    "axios": "^1.12.2",
     "node-persist": "^4.0.4",
-    "p-queue": "^8.1.0",
+    "p-queue": "^8.1.1",
     "websocket-as-promised": "^3.0.1",
     "ws": "^8.18.3"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^4.19.0"
+    "@antfu/eslint-config": "^5.4.1"
   }
 }