@switchbot/homebridge-switchbot 5.0.0-beta.112 → 5.0.0-beta.113

package/src/homebridge-ui/public/js/modals.ts

@@ -111,6 +111,47 @@ export async function importDiscoveredDevice(device: any): Promise<{ configDevic
     macInput.style.fontSize = '14px'
     macInput.style.boxSizing = 'border-box'
 
+
+    // BLE Encryption Key
+    const encryptionKeyLabel = document.createElement('label')
+    encryptionKeyLabel.textContent = 'BLE Encryption Key (optional)'
+    encryptionKeyLabel.style.display = 'block'
+    encryptionKeyLabel.style.marginBottom = '6px'
+    encryptionKeyLabel.style.fontWeight = '500'
+    encryptionKeyLabel.style.fontSize = '12px'
+    encryptionKeyLabel.style.color = '#6b7280'
+
+    const encryptionKeyInput = document.createElement('input')
+    encryptionKeyInput.type = 'password'
+    encryptionKeyInput.value = device.encryptionKey || ''
+    encryptionKeyInput.placeholder = 'Paste device BLE encryption key'
+    encryptionKeyInput.style.width = '100%'
+    encryptionKeyInput.style.marginBottom = '12px'
+    encryptionKeyInput.style.padding = '8px 10px'
+    encryptionKeyInput.style.borderRadius = '6px'
+    encryptionKeyInput.style.fontSize = '14px'
+    encryptionKeyInput.style.boxSizing = 'border-box'
+
+    // BLE Key ID
+    const keyIdLabel = document.createElement('label')
+    keyIdLabel.textContent = 'BLE Key ID (optional)'
+    keyIdLabel.style.display = 'block'
+    keyIdLabel.style.marginBottom = '6px'
+    keyIdLabel.style.fontWeight = '500'
+    keyIdLabel.style.fontSize = '12px'
+    keyIdLabel.style.color = '#6b7280'
+
+    const keyIdInput = document.createElement('input')
+    keyIdInput.type = 'text'
+    keyIdInput.value = device.keyId || ''
+    keyIdInput.placeholder = 'e.g. ff'
+    keyIdInput.style.width = '100%'
+    keyIdInput.style.marginBottom = '12px'
+    keyIdInput.style.padding = '8px 10px'
+    keyIdInput.style.borderRadius = '6px'
+    keyIdInput.style.fontSize = '14px'
+    keyIdInput.style.boxSizing = 'border-box'
+
     const buttons = document.createElement('div')
     buttons.style.display = 'flex'
     buttons.style.gap = '10px'
@@ -132,7 +173,8 @@ export async function importDiscoveredDevice(device: any): Promise<{ configDevic
     importBtn.style.padding = '8px 20px'
     importBtn.style.fontSize = '13px'
 
-    const cleanup = (result: { configDeviceName: string, configDeviceType: string, address?: string } | null) => {
+
+    const cleanup = (result: { configDeviceName: string, configDeviceType: string, address?: string, encryptionKey?: string, keyId?: string } | null) => {
       div.remove()
       resolve(result)
     }
@@ -142,6 +184,8 @@ export async function importDiscoveredDevice(device: any): Promise<{ configDevic
       configDeviceName: nameInput.value || device.name || device.id,
       configDeviceType: typeSelect.value || device.type,
       address: macInput.value || undefined,
+      encryptionKey: encryptionKeyInput.value || undefined,
+      keyId: keyIdInput.value || undefined,
     })
 
     div.addEventListener('click', (event) => {
@@ -150,6 +194,7 @@ export async function importDiscoveredDevice(device: any): Promise<{ configDevic
       }
     })
 
+
     buttons.appendChild(cancelBtn)
     buttons.appendChild(importBtn)
     contentDiv.appendChild(nameLabel)
@@ -158,6 +203,10 @@ export async function importDiscoveredDevice(device: any): Promise<{ configDevic
     contentDiv.appendChild(typeSelect)
     contentDiv.appendChild(macLabel)
     contentDiv.appendChild(macInput)
+    contentDiv.appendChild(encryptionKeyLabel)
+    contentDiv.appendChild(encryptionKeyInput)
+    contentDiv.appendChild(keyIdLabel)
+    contentDiv.appendChild(keyIdInput)
     contentDiv.appendChild(buttons)
 
     modal.appendChild(title)

package/src/homebridge-ui/public/js/render.ts

@@ -176,9 +176,235 @@ function scrollToConfiguredDevice(deviceId: string): void {
   }, 1800)
 }
 
+function createConnectionTestControls(device: any): HTMLElement {
+  const controls = document.createElement('div')
+  controls.style.display = 'inline-flex'
+  controls.style.alignItems = 'center'
+  controls.style.gap = '6px'
+
+  const button = document.createElement('button')
+  button.textContent = 'Test Connection'
+  button.className = 'secondary'
+  button.style.padding = '4px 9px'
+  button.style.fontSize = '11px'
+
+  const status = document.createElement('span')
+  status.style.fontSize = '10px'
+  status.style.opacity = '0.85'
+  status.style.whiteSpace = 'normal'
+  status.style.overflowWrap = 'anywhere'
+
+  button.onclick = async () => {
+    const startedAt = Date.now()
+    button.disabled = true
+    button.textContent = 'Testing...'
+    status.textContent = 'Checking...'
+    status.style.color = '#6b7280'
+
+    try {
+      const { testDeviceConnection } = await import('./api.js')
+      const result = await testDeviceConnection({
+        deviceId: String(device?.id || device?.deviceId || ''),
+        connectionType: device?.connectionType,
+        address: device?.address,
+      })
+
+      const measuredLatency = Number(result?.latencyMs) > 0
+        ? Number(result.latencyMs)
+        : Date.now() - startedAt
+
+      if (result?.success) {
+        const method = result?.method || 'Auto'
+        status.textContent = `✓ ${method} · ${measuredLatency}ms`
+        status.style.color = '#16a34a'
+      } else {
+        const detail = result?.message ? ` · ${result.message}` : ''
+        status.textContent = `✗ Failed · ${measuredLatency}ms${detail}`
+        status.style.color = '#dc2626'
+      }
+    } catch (e) {
+      status.textContent = `✗ Failed · ${Date.now() - startedAt}ms`
+      status.style.color = '#dc2626'
+    } finally {
+      button.disabled = false
+      button.textContent = 'Test Connection'
+    }
+  }
+
+  controls.appendChild(button)
+  controls.appendChild(status)
+  return controls
+}
+
+function formatLastSeen(value: any): string {
+  if (!value) {
+    return 'N/A'
+  }
+  try {
+    const date = new Date(value)
+    return Number.isNaN(date.getTime()) ? String(value) : date.toLocaleString()
+  } catch (_e) {
+    return String(value)
+  }
+}
+
+export function renderDeviceDetailsPanel(device: any): HTMLElement {
+  const details = document.createElement('div')
+  details.style.cssText = `
+    border-top: 1px solid #ddd;
+    padding: 8px;
+    background: #f9fafb;
+    border-radius: 4px;
+    font-size: 12px;
+    margin-top: 4px;
+  `
+
+  // --- Battery history trending ---
+  // Persist battery readings in localStorage per device
+  const batteryHistoryKey = `batteryHistory:${device?.id || device?.deviceId}`
+  let batteryHistory: Array<{ value: number, ts: number }> = []
+  try {
+    const raw = localStorage.getItem(batteryHistoryKey)
+    if (raw) batteryHistory = JSON.parse(raw)
+  } catch {}
+  const now = Date.now()
+  if (typeof device?.battery === 'number') {
+    // Only add if different from last or >1h since last
+    const last = batteryHistory[batteryHistory.length - 1]
+    if (!last || last.value !== device.battery || now - last.ts > 60 * 60 * 1000) {
+      batteryHistory.push({ value: device.battery, ts: now })
+      // Keep only last 30 entries (about a month if daily)
+      if (batteryHistory.length > 30) batteryHistory = batteryHistory.slice(-30)
+      try { localStorage.setItem(batteryHistoryKey, JSON.stringify(batteryHistory)) } catch {}
+    }
+  }
+
+  const rows: Array<{ label: string, value: string, copyable?: boolean }> = [
+    { label: 'Device ID', value: String(device?.id || device?.deviceId || 'N/A'), copyable: !!(device?.id || device?.deviceId) },
+    { label: 'MAC Address', value: String(device?.address || 'N/A'), copyable: !!device?.address },
+    { label: 'Device Type', value: String(device?.type || device?.configDeviceType || 'N/A') },
+    { label: 'Model', value: String(device?.model || 'N/A') },
+    { label: 'Hub ID', value: String(device?.hubDeviceId || 'N/A') },
+    { label: 'Battery', value: device?.battery !== undefined && device?.battery !== null ? `${device.battery}%` : 'N/A' },
+    { label: 'Firmware', value: String(device?.version || device?.firmware || 'N/A') },
+    { label: 'Cloud Service', value: device?.enabled === false ? 'Disabled' : 'Enabled' },
+    { label: 'Last Seen', value: formatLastSeen(device?.lastSeen || device?.lastseen || device?.updatedAt) },
+  ]
+
+
+  for (const row of rows) {
+    const line = document.createElement('div')
+    line.style.display = 'flex'
+    line.style.alignItems = 'center'
+    line.style.justifyContent = 'space-between'
+    line.style.gap = '8px'
+    line.style.padding = '2px 0'
+
+    const label = document.createElement('span')
+    label.style.fontWeight = '600'
+    label.style.minWidth = '110px'
+    label.textContent = `${row.label}:`
+
+    const valueWrap = document.createElement('span')
+    valueWrap.style.display = 'inline-flex'
+    valueWrap.style.alignItems = 'center'
+    valueWrap.style.gap = '6px'
+    valueWrap.style.flex = '1'
+    valueWrap.style.justifyContent = 'flex-end'
+    valueWrap.style.minWidth = '0'
+
+    const value = document.createElement('span')
+    value.style.fontFamily = 'monospace'
+    value.style.fontSize = '11px'
+    value.style.opacity = '0.9'
+    value.style.whiteSpace = 'normal'
+    value.style.overflowWrap = 'anywhere'
+    value.style.wordBreak = 'break-word'
+    value.style.textAlign = 'right'
+    value.textContent = row.value
+
+    valueWrap.appendChild(value)
+
+    if (row.copyable && row.value && row.value !== 'N/A') {
+      const copyBtn = document.createElement('button')
+      copyBtn.textContent = '📋'
+      copyBtn.title = `Copy ${row.label}`
+      copyBtn.style.padding = '2px 6px'
+      copyBtn.style.fontSize = '10px'
+      copyBtn.style.lineHeight = '1'
+      copyBtn.style.background = '#e5e7eb'
+      copyBtn.style.color = '#111827'
+
+      copyBtn.onclick = async () => {
+        try {
+          await navigator.clipboard.writeText(row.value)
+          copyBtn.textContent = '✓'
+          setTimeout(() => {
+            copyBtn.textContent = '📋'
+          }, 1200)
+        } catch (_e) {
+          copyBtn.textContent = '!'
+          setTimeout(() => {
+            copyBtn.textContent = '📋'
+          }, 1200)
+        }
+      }
+
+      valueWrap.appendChild(copyBtn)
+    }
+
+    line.appendChild(label)
+    line.appendChild(valueWrap)
+    details.appendChild(line)
+  }
+
+  // --- Expose advanced/extra features dynamically ---
+  const featureKeys = [
+    'airQuality', 'pm25', 'pm10', 'voc', 'co2', 'humidity', 'temperature',
+    'preset', 'mode', 'presetMode', 'direction', 'calibration', 'multiCommand',
+    'extendedInfo', 'segmentedControl', 'features', 'capabilities', 'state',
+  ]
+  const shown = new Set(rows.map(r => r.label.toLowerCase().replace(/\s/g, '')))
+  for (const key of featureKeys) {
+    if (device && device[key] !== undefined && !shown.has(key.toLowerCase())) {
+      const line = document.createElement('div')
+      line.style.display = 'flex'
+      line.style.alignItems = 'center'
+      line.style.justifyContent = 'space-between'
+      line.style.gap = '8px'
+      line.style.padding = '2px 0'
+
+      const label = document.createElement('span')
+      label.style.fontWeight = '600'
+      label.style.minWidth = '110px'
+      label.textContent = key.replace(/([A-Z])/g, ' $1').replace(/^./, s => s.toUpperCase()) + ':'
+
+      const value = document.createElement('span')
+      value.style.fontFamily = 'monospace'
+      value.style.fontSize = '11px'
+      value.style.opacity = '0.9'
+      value.style.whiteSpace = 'normal'
+      value.style.overflowWrap = 'anywhere'
+      value.style.wordBreak = 'break-word'
+      value.style.textAlign = 'right'
+      value.textContent = typeof device[key] === 'object' ? JSON.stringify(device[key]) : String(device[key])
+
+      line.appendChild(label)
+      line.appendChild(value)
+      details.appendChild(line)
+    }
+  }
+
+  return details
+}
+
 export async function renderDiscoveredDevices(
   devices: any[],
-  options: { configuredIds?: Set<string> } = {},
+  options: {
+    configuredIds?: Set<string>
+    selectedIds?: Set<string>
+    onToggleSelect?: (device: any, selected: boolean) => void
+  } = {},
 ): Promise<HTMLElement> {
   const ul = document.createElement('ul')
   ul.className = 'device-grid'
@@ -191,6 +417,8 @@ export async function renderDiscoveredDevices(
   const { addDeviceToConfig } = await import('./discovery.js')
   const { loadConfiguredDevices } = await import('./devices.js')
   const configuredIds = options.configuredIds ?? new Set<string>()
+  const selectedIds = options.selectedIds ?? new Set<string>()
+  const onToggleSelect = options.onToggleSelect
 
   for (const d of devices) {
     const deviceId = normalizeId(d.id)
@@ -224,8 +452,76 @@ export async function renderDiscoveredDevices(
     name.style.fontSize = '13px'
     name.textContent = d.name || d.id
 
+    const selectCheckbox = document.createElement('input')
+    selectCheckbox.type = 'checkbox'
+    selectCheckbox.style.width = 'auto'
+    selectCheckbox.style.margin = '0 2px 0 0'
+    selectCheckbox.checked = selectedIds.has(deviceId)
+    if (alreadyAdded) {
+      selectCheckbox.disabled = true
+      selectCheckbox.title = 'Already configured'
+    }
+    selectCheckbox.onchange = () => {
+      onToggleSelect?.(d, selectCheckbox.checked)
+      // Notify listeners (e.g., batch buttons) of selection change
+      window.dispatchEvent(new CustomEvent('discovery-selection-changed'))
+    }
+
+    nameContainer.appendChild(selectCheckbox)
+
+
     nameContainer.appendChild(name)
 
+    // Show firmware update available indicator if present
+    if (d.firmwareUpdateAvailable) {
+      const fwBadge = document.createElement('span');
+      fwBadge.textContent = 'Update Available';
+      fwBadge.style.cssText = 'background: #fb923c; color: #111; padding: 1px 7px; border-radius: 3px; font-size: 10px; font-weight: 600; margin-left: 6px;';
+      fwBadge.title = 'A firmware update is available for this device.';
+      nameContainer.appendChild(fwBadge);
+    }
+
+    // Show offline/unreachable indicator if device is offline
+    let offline = false;
+    let lastSeen = d.lastSeen || d.lastseen || d.updatedAt;
+    if (typeof d.offline === 'boolean') {
+      offline = d.offline;
+    } else if (lastSeen) {
+      try {
+        const last = new Date(lastSeen).getTime();
+        if (!isNaN(last) && Date.now() - last > 1000 * 60 * 60) { // 1 hour
+          offline = true;
+        }
+      } catch {}
+    }
+    if (offline) {
+      const offlineBadge = document.createElement('span');
+      offlineBadge.textContent = 'Offline';
+      offlineBadge.style.cssText = 'background: #dc2626; color: white; padding: 1px 7px; border-radius: 3px; font-size: 10px; font-weight: 600; margin-left: 6px;';
+      offlineBadge.title = 'Device is offline or unreachable.';
+      nameContainer.appendChild(offlineBadge);
+    }
+
+    const expandedDetails = document.createElement('div')
+    expandedDetails.style.display = 'none'
+    expandedDetails.appendChild(renderDeviceDetailsPanel(d))
+
+    const expandBtn = document.createElement('button')
+    expandBtn.textContent = '▾'
+    expandBtn.title = 'Show details'
+    expandBtn.style.padding = '2px 6px'
+    expandBtn.style.fontSize = '11px'
+    expandBtn.style.marginLeft = '4px'
+    expandBtn.style.background = '#e5e7eb'
+    expandBtn.style.color = '#111827'
+    expandBtn.style.transition = 'transform 0.2s ease'
+    expandBtn.onclick = () => {
+      const isHidden = expandedDetails.style.display === 'none'
+      expandedDetails.style.display = isHidden ? 'block' : 'none'
+      expandBtn.style.transform = isHidden ? 'rotate(180deg)' : 'rotate(0deg)'
+    }
+    nameContainer.appendChild(expandBtn)
+
     const duplicateBadge = document.createElement('span')
     duplicateBadge.textContent = alreadyAdded ? '✓ Already Added' : '➕ New Device'
     duplicateBadge.style.cssText = alreadyAdded
@@ -250,6 +546,18 @@ export async function renderDiscoveredDevices(
       nameContainer.appendChild(renderSignalQualityBadge(d.rssi))
     }
 
+    // Add battery warning indicator if battery < 20%
+    if (typeof d.battery === 'number' && d.battery < 20) {
+      const batteryWarn = document.createElement('span');
+      batteryWarn.textContent = `⚠️ ${d.battery}%`;
+      batteryWarn.style.cssText =
+        d.battery < 10
+          ? 'background: #dc2626; color: white; padding: 1px 6px; border-radius: 3px; font-size: 10px; font-weight: 600; margin-left: 6px;'
+          : 'background: #fbbf24; color: #111; padding: 1px 6px; border-radius: 3px; font-size: 10px; font-weight: 600; margin-left: 6px;';
+      batteryWarn.title = d.battery < 10 ? 'Battery critically low' : 'Battery low';
+      nameContainer.appendChild(batteryWarn);
+    }
+
     const details = document.createElement('div')
     details.style.fontSize = '10px'
     details.style.opacity = '0.7'
@@ -266,6 +574,7 @@ export async function renderDiscoveredDevices(
 
     info.appendChild(nameContainer)
     info.appendChild(details)
+    info.appendChild(expandedDetails)
 
     const addBtn = document.createElement('button')
     addBtn.textContent = alreadyAdded ? 'Already Added' : 'Add to Config'
@@ -312,6 +621,7 @@ export async function renderDiscoveredDevices(
       actions.style.gap = '5px'
       actions.appendChild(viewBtn)
       actions.appendChild(addBtn)
+      actions.appendChild(createConnectionTestControls(d))
       li.appendChild(actions)
       ul.appendChild(li)
       continue
@@ -327,6 +637,7 @@ export async function renderDiscoveredDevices(
     actions.style.marginTop = '2px'
     actions.style.gap = '5px'
     actions.appendChild(addBtn)
+    actions.appendChild(createConnectionTestControls(d))
 
     li.appendChild(info)
     li.appendChild(actions)
@@ -533,6 +844,25 @@ export function renderDeviceList(list: any[]): void {
     name.style.fontSize = '13px'
     name.textContent = d.name || d.id
 
+    const expandedDetails = document.createElement('div')
+    expandedDetails.style.display = 'none'
+    expandedDetails.appendChild(renderDeviceDetailsPanel(d))
+
+    const expandBtn = document.createElement('button')
+    expandBtn.textContent = '▾'
+    expandBtn.title = 'Show details'
+    expandBtn.style.padding = '2px 6px'
+    expandBtn.style.fontSize = '11px'
+    expandBtn.style.marginLeft = '4px'
+    expandBtn.style.background = '#e5e7eb'
+    expandBtn.style.color = '#111827'
+    expandBtn.style.transition = 'transform 0.2s ease'
+    expandBtn.onclick = () => {
+      const isHidden = expandedDetails.style.display === 'none'
+      expandedDetails.style.display = isHidden ? 'block' : 'none'
+      expandBtn.style.transform = isHidden ? 'rotate(180deg)' : 'rotate(0deg)'
+    }
+
     const code = document.createElement('code')
     code.textContent = d.id
     code.style.fontSize = '10px'
@@ -543,7 +873,14 @@ export function renderDeviceList(list: any[]): void {
     code.style.wordBreak = 'break-word'
     code.style.maxWidth = '100%'
 
-    nameContainer.appendChild(name)
+    const headerRow = document.createElement('div')
+    headerRow.style.display = 'inline-flex'
+    headerRow.style.alignItems = 'center'
+    headerRow.style.gap = '4px'
+    headerRow.appendChild(name)
+    headerRow.appendChild(expandBtn)
+
+    nameContainer.appendChild(headerRow)
     nameContainer.appendChild(code)
 
     // Add signal strength visualization if RSSI is available
@@ -564,6 +901,7 @@ export function renderDeviceList(list: any[]): void {
 
     info.appendChild(nameContainer)
     info.appendChild(meta)
+    info.appendChild(expandedDetails)
 
     const buttons = document.createElement('div')
     buttons.className = 'device-actions'
@@ -614,6 +952,7 @@ export function renderDeviceList(list: any[]): void {
 
     buttons.appendChild(editBtn)
     buttons.appendChild(copyBtn)
+    buttons.appendChild(createConnectionTestControls(d))
     buttons.appendChild(deleteBtn)
 
     li.appendChild(info)

package/src/platform.ts

@@ -65,7 +65,7 @@ const DEVICE_MATTER_SUPPORTED: Record<string, boolean> = {
 // Default Matter cluster configurations by device type
 // Maps device types to their Matter cluster states (used when device doesn't provide clusters)
 // Note: wosweeper/curtain/plug variants are normalized before cluster lookup (see loadDevices)
-const DEVICE_MATTER_CLUSTERS: Record<string, any> = {
+export const DEVICE_MATTER_CLUSTERS: Record<string, any> = {
   // Core devices - aligned with HAP service implementations
   bot: { onOff: { onOff: false } }, // Switch → OnOff
   vacuum: {
@@ -132,7 +132,9 @@ const DEVICE_MATTER_CLUSTERS: Record<string, any> = {
       minLevel: 0,
       maxLevel: 254,
     },
-    colorControl: {},
+    colorControl: {
+      colorMode: 0,
+    },
   }, // Lightbulb with color → OnOff + LevelControl + ColorControl
   lock: {
     doorLock: {
@@ -1094,6 +1096,8 @@ export class SwitchBotHAPPlatform {
         id: raw.deviceId ?? raw.id,
         name: raw.configDeviceName ?? raw.name,
         type: raw.configDeviceType ?? raw.type ?? raw.deviceType ?? 'unknown',
+        encryptionKey: raw.encryptionKey,
+        keyId: raw.keyId,
         _raw: raw,
       }
 

package/src/switchbotClient.ts

@@ -1,4 +1,5 @@
 import type { SwitchBotPluginConfig } from './settings.js'
+import { SwitchbotOperationError, SwitchbotAuthenticationError, CharacteristicMissingError } from './errors.js'
 
 export interface ISwitchBotClient {
   init(): Promise<void>
@@ -93,8 +94,17 @@ export class SwitchBotClient implements ISwitchBotClient {
     if (this.client?.getDevice) {
       try {
         return await this.client.getDevice(id)
-      } catch (e) {
-        this.logger?.warn?.(`Client getDevice failed for ${id}, trying OpenAPI fallback:`, e)
+      } catch (e: any) {
+        if (e instanceof SwitchbotAuthenticationError) {
+          this.logger?.error?.(`Authentication error for getDevice(${id}):`, e.message)
+          throw e
+        } else if (e instanceof SwitchbotOperationError) {
+          this.logger?.warn?.(`Operation error for getDevice(${id}):`, e.message, e.code)
+        } else if (e instanceof CharacteristicMissingError) {
+          this.logger?.warn?.(`Characteristic missing for getDevice(${id}):`, e.characteristic)
+        } else {
+          this.logger?.warn?.(`Client getDevice failed for ${id}, trying OpenAPI fallback:`, e)
+        }
       }
     }
     // Fallback: call OpenAPI via HTTP
@@ -104,7 +114,7 @@ export class SwitchBotClient implements ISwitchBotClient {
       const resp = await this.fetchWithTimeoutAndRetry(url, opts)
       return resp.json()
     }
-    throw new Error('No SwitchBot client available')
+    throw new SwitchbotOperationError('No SwitchBot client available', 'no_client')
   }
 
   async getDevices(): Promise<any[]> {
@@ -149,7 +159,14 @@ export class SwitchBotClient implements ISwitchBotClient {
         try {
           const out = await this._doSetDeviceState(id, entry.body)
           for (const r of entry.resolvers) r.resolve(out)
-        } catch (e) {
+        } catch (e: any) {
+          if (e instanceof SwitchbotAuthenticationError) {
+            this.logger?.error?.(`Authentication error for setDeviceState(${id}):`, e.message)
+          } else if (e instanceof SwitchbotOperationError) {
+            this.logger?.warn?.(`Operation error for setDeviceState(${id}):`, e.message, e.code)
+          } else if (e instanceof CharacteristicMissingError) {
+            this.logger?.warn?.(`Characteristic missing for setDeviceState(${id}):`, e.characteristic)
+          }
           for (const r of entry.resolvers) r.reject(e)
         }
       }, this.writeDebounceMs)
@@ -166,8 +183,17 @@ export class SwitchBotClient implements ISwitchBotClient {
         const result = await this.client.setDeviceState(id, body)
         this.logger?.debug?.(`[${id}] client.setDeviceState() response:`, result)
         return result
-      } catch (e) {
-        this.logger?.warn?.(`Client setDeviceState failed for ${id}, trying fallback:`, e)
+      } catch (e: any) {
+        if (e instanceof SwitchbotAuthenticationError) {
+          this.logger?.error?.(`Authentication error for setDeviceState(${id}):`, e.message)
+          throw e
+        } else if (e instanceof SwitchbotOperationError) {
+          this.logger?.warn?.(`Operation error for setDeviceState(${id}):`, e.message, e.code)
+        } else if (e instanceof CharacteristicMissingError) {
+          this.logger?.warn?.(`Characteristic missing for setDeviceState(${id}):`, e.characteristic)
+        } else {
+          this.logger?.warn?.(`Client setDeviceState failed for ${id}, trying fallback:`, e)
+        }
       }
     }
 
@@ -178,8 +204,17 @@ export class SwitchBotClient implements ISwitchBotClient {
         const result = await this.client.sendCommand(id, body)
         this.logger?.debug?.(`[${id}] client.sendCommand() response:`, result)
         return result
-      } catch (e) {
-        this.logger?.warn?.(`Client sendCommand failed for ${id}, trying OpenAPI:`, e)
+      } catch (e: any) {
+        if (e instanceof SwitchbotAuthenticationError) {
+          this.logger?.error?.(`Authentication error for sendCommand(${id}):`, e.message)
+          throw e
+        } else if (e instanceof SwitchbotOperationError) {
+          this.logger?.warn?.(`Operation error for sendCommand(${id}):`, e.message, e.code)
+        } else if (e instanceof CharacteristicMissingError) {
+          this.logger?.warn?.(`Characteristic missing for sendCommand(${id}):`, e.characteristic)
+        } else {
+          this.logger?.warn?.(`Client sendCommand failed for ${id}, trying OpenAPI:`, e)
+        }
       }
     }
 
@@ -203,7 +238,7 @@ export class SwitchBotClient implements ISwitchBotClient {
       return result
     }
 
-    throw new Error('No SwitchBot client available for setDeviceState')
+    throw new SwitchbotOperationError('No SwitchBot client available for setDeviceState', 'no_client')
   }
 
   async destroy(): Promise<void> {

package/test/matter-integration.spec.ts

@@ -47,6 +47,27 @@ describe('Matter integration harness', () => {
     expect(wcType).not.toBe(4)
   })
 
+  it('registers RGBIC Neon Wire Rope Light as lightstrip with conformant ColorControl defaults', async () => {
+    const matterApi = makeFakeMatterApi()
+    const api = makeFakeApiWithMatter(matterApi)
+
+    const platform = new SwitchBotMatterPlatform(console as any, {
+      devices: [{ id: 'neon-1', type: 'RGBIC Neon Wire Rope Light', name: 'Family Room Neon Wire Rope Light' }],
+      enableMatter: true,
+      preferMatter: true,
+    } as any, api as any)
+
+    await (platform as any).registerMatterAccessories()
+
+    const regs = matterApi.getRegistered()
+    expect(regs.length).toBeGreaterThanOrEqual(1)
+    const neon = regs.find((r: any) => r?.context?.deviceId === 'neon-1')
+    expect(neon).toBeDefined()
+    expect(neon?.context?.type).toBe('lightstrip')
+    expect(neon?.clusters?.colorControl).toBeDefined()
+    expect(neon?.clusters?.colorControl?.colorMode).toBe(0)
+  })
+
   it('registers Matter accessories when Matter API available', async () => {
     // Instantiate the real Matter platform directly to test its registration path
     const matterApi = makeFakeMatterApi()