@switchbot/homebridge-switchbot 5.0.0 → 5.1.0-beta.1

package/src/homebridge-ui/public/index.html

@@ -11,6 +11,29 @@
 <body>
   <h1>🤖 SwitchBot Configuration</h1>
 
+  <!-- v4 config incompatibility warning – shown dynamically by app.js -->
+  <div id="v4ConfigWarning" class="v4-config-warning" style="display: none">
+    <strong>⚠️ Incompatible v4 Configuration Detected</strong>
+    <p>
+      Your config.json appears to be in the <strong>v4 format</strong> (using <code>credentials</code> and
+      <code>options.devices</code> fields). This format is <strong>not compatible with v5 or newer</strong> of the
+      SwitchBot plugin. Devices will not be recognised until the config is updated.
+    </p>
+    <p>
+      Please update your config to the v5 format:
+    </p>
+    <ul>
+      <li>Move <code>credentials.token</code> → <code>openApiToken</code> (top level)</li>
+      <li>Move <code>credentials.secret</code> → <code>openApiSecret</code> (top level)</li>
+      <li>Move <code>options.devices</code> → <code>devices</code> (top level)</li>
+      <li>Rename per-device <code>connectionType</code> → <code>connectionPreference</code></li>
+      <li>Remove the <code>credentials</code> and <code>options</code> wrapper objects</li>
+    </ul>
+    <p>
+      See the <a href="https://github.com/OpenWonderLabs/homebridge-switchbot/blob/latest/MIGRATION.md" target="_blank" rel="noopener">Migration Guide</a> for full details.
+    </p>
+  </div>
+
   <div class="card compact">
     <h2>API Credentials</h2>
     <div class="credentials-row">

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

@@ -1,5 +1,6 @@
 // Fetch the list of configured devices from the Homebridge UI API
 import { isValidDeviceType, normalizeDeviceType } from '../../../device-types.js'
+import { isV4Config } from '../../utils/v4-detection.js'
 import './types.js'
 import { uiLog } from './logger.js'
 import { toastError } from './toast.js'
@@ -22,6 +23,35 @@ export async function fetchDevices(): Promise<any[]> {
   }
 }
 
+/**
+ * Detect whether the current plugin config is in the legacy v4 format.
+ *
+ * v4 configs stored credentials under a `credentials` sub-object and devices
+ * under `options.devices`. v5+ flattened these to `openApiToken`,
+ * `openApiSecret`, and a root-level `devices` array.
+ *
+ * Returns true when a v4 config block is found, false otherwise.
+ */
+export async function detectV4Config(): Promise<boolean> {
+  try {
+    if (typeof homebridge.getPluginConfig !== 'function') {
+      return false
+    }
+    const configArr = await homebridge.getPluginConfig()
+    if (!Array.isArray(configArr)) {
+      return false
+    }
+    const config = configArr.find(isSwitchBotPlatformConfig)
+    if (!config || typeof config !== 'object') {
+      return false
+    }
+    return isV4Config(config)
+  } catch (e) {
+    uiLog.warn('Error detecting v4 config:', e)
+    return false
+  }
+}
+
 /**
  * Validate and auto-correct device types in the config array before saving.
  * Returns an array of errors for devices that cannot be fixed.
@@ -189,7 +219,19 @@ export async function addDevice(
   deviceId: string,
   name: string,
   type: string,
-  options?: { address?: string, model?: string, rssi?: number, encryptionKey?: string, keyId?: string },
+  options?: {
+    address?: string
+    model?: string
+    rssi?: number
+    connectionPreference?: string
+    externalPublishProtocol?: string
+    room?: string
+    encryptionKey?: string
+    keyId?: string
+    refreshRate?: number
+    blePollingEnabled?: boolean
+    blePollIntervalMs?: number
+  },
 ): Promise<any> {
   if (typeof homebridge.getPluginConfig !== 'function' || typeof homebridge.updatePluginConfig !== 'function') {
     throw new TypeError('Homebridge UI API not available')
@@ -224,6 +266,24 @@ export async function addDevice(
   if (options?.keyId) {
     newDevice.keyId = options.keyId
   }
+  if (options?.connectionPreference) {
+    newDevice.connectionPreference = options.connectionPreference
+  }
+  if (options?.externalPublishProtocol) {
+    newDevice.externalPublishProtocol = options.externalPublishProtocol
+  }
+  if (options?.room) {
+    newDevice.room = options.room
+  }
+  if (typeof options?.refreshRate === 'number' && Number.isFinite(options.refreshRate)) {
+    newDevice.refreshRate = options.refreshRate
+  }
+  if (typeof options?.blePollingEnabled === 'boolean') {
+    newDevice.blePollingEnabled = options.blePollingEnabled
+  }
+  if (typeof options?.blePollIntervalMs === 'number' && Number.isFinite(options.blePollIntervalMs)) {
+    newDevice.blePollIntervalMs = options.blePollIntervalMs
+  }
   config.devices.push(newDevice)
   await homebridge.updatePluginConfig(configArr)
   if (typeof homebridge.savePluginConfig === 'function') {

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

@@ -1,13 +1,31 @@
+import { detectV4Config } from './api.js'
 import { loadCredentialStatus, saveCredentials } from './credentials.js'
 import { initRemoveAllButton, loadConfiguredDevices } from './devices.js'
-import { discoverDevices, initializeDiscoverySettings } from './discovery.js';
+import { discoverDevices, initializeDiscoverySettings } from './discovery.js'
 
-(window as any).loadCredentialStatus = loadCredentialStatus;
-(window as any).saveCredentials = saveCredentials;
-(window as any).discoverDevices = discoverDevices
+;
+
+(window as any).loadCredentialStatus = loadCredentialStatus
+;(window as any).saveCredentials = saveCredentials
+;(window as any).discoverDevices = discoverDevices
+
+/**
+ * Show or hide the v4 config incompatibility warning banner.
+ */
+async function checkV4Config(): Promise<void> {
+  const banner = document.getElementById('v4ConfigWarning')
+  if (!banner) {
+    return
+  }
+  const isV4 = await detectV4Config()
+  if (isV4) {
+    banner.style.display = 'block'
+  }
+}
 
 // Initialize on page load
 async function init(): Promise<void> {
+  await checkV4Config()
   await loadCredentialStatus()
   await initializeDiscoverySettings()
   await loadConfiguredDevices()

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

@@ -26,8 +26,14 @@ export async function addDeviceToConfig(device: any, options: { refresh?: boolea
       address: importValues.address,
       model: device.model,
       rssi: device.rssi,
+      connectionPreference: importValues.connectionPreference,
+      externalPublishProtocol: importValues.externalPublishProtocol,
+      room: importValues.room,
       encryptionKey: importValues.encryptionKey,
       keyId: importValues.keyId,
+      refreshRate: importValues.refreshRate,
+      blePollingEnabled: importValues.blePollingEnabled,
+      blePollIntervalMs: importValues.blePollIntervalMs,
     })
     uiLog.info('Add device response:', resp)
 

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

@@ -6,6 +6,7 @@ export type ImportDiscoveredDeviceResult = {
   configDeviceType: string
   address?: string
   connectionPreference?: string
+  externalPublishProtocol?: string
   room?: string
   encryptionKey?: string
   keyId?: string
@@ -154,6 +155,30 @@ export async function importDiscoveredDevice(device: any): Promise<ImportDiscove
       connectionPrefSelect.appendChild(opt)
     })
 
+    // --- External Publish Protocol ---
+    const externalPublishLabel = document.createElement('label')
+    externalPublishLabel.textContent = 'Publish as External Device'
+    externalPublishLabel.style.display = 'block'
+    externalPublishLabel.style.marginBottom = '6px'
+    externalPublishLabel.style.fontWeight = '500'
+    externalPublishLabel.style.fontSize = '12px'
+    externalPublishLabel.style.color = '#6b7280'
+
+    const externalPublishSelect = document.createElement('select')
+    externalPublishSelect.style.width = '100%'
+    externalPublishSelect.style.marginBottom = '12px'
+    externalPublishSelect.style.padding = '8px 10px'
+    externalPublishSelect.style.borderRadius = '6px'
+    externalPublishSelect.style.fontSize = '14px'
+    externalPublishSelect.style.boxSizing = 'border-box'
+    ;['none', 'hap', 'matter'].forEach((val) => {
+      const opt = document.createElement('option')
+      opt.value = val
+      opt.text = val === 'none' ? 'None' : val.toUpperCase()
+      opt.selected = (device.externalPublishProtocol || 'none') === val
+      externalPublishSelect.appendChild(opt)
+    })
+
     // --- Room ---
     const roomLabel = document.createElement('label')
     roomLabel.textContent = 'Room'
@@ -308,6 +333,7 @@ export async function importDiscoveredDevice(device: any): Promise<ImportDiscove
         configDeviceType: typeSelect.value || device.type,
         address: macInput.value || undefined,
         connectionPreference: connectionPrefSelect.value || undefined,
+        externalPublishProtocol: externalPublishSelect.value || 'none',
         room: roomInput.value || undefined,
         encryptionKey: encryptionKeyInput.value || undefined,
         keyId: keyIdInput.value || undefined,
@@ -331,6 +357,8 @@ export async function importDiscoveredDevice(device: any): Promise<ImportDiscove
     contentDiv.appendChild(typeSelect)
     contentDiv.appendChild(connectionPrefLabel)
     contentDiv.appendChild(connectionPrefSelect)
+    contentDiv.appendChild(externalPublishLabel)
+    contentDiv.appendChild(externalPublishSelect)
     contentDiv.appendChild(roomLabel)
     contentDiv.appendChild(roomInput)
     contentDiv.appendChild(macLabel)
@@ -573,6 +601,30 @@ export async function editDevice(device: any): Promise<void> {
     connectionPrefSelect.appendChild(opt)
   })
 
+  // --- External Publish Protocol ---
+  const externalPublishLabel = document.createElement('label')
+  externalPublishLabel.textContent = 'Publish as External Device'
+  externalPublishLabel.style.display = 'block'
+  externalPublishLabel.style.marginBottom = '6px'
+  externalPublishLabel.style.fontWeight = '500'
+  externalPublishLabel.style.fontSize = '12px'
+  externalPublishLabel.style.color = '#6b7280'
+
+  const externalPublishSelect = document.createElement('select')
+  externalPublishSelect.style.width = '100%'
+  externalPublishSelect.style.marginBottom = '12px'
+  externalPublishSelect.style.padding = '8px 10px'
+  externalPublishSelect.style.borderRadius = '6px'
+  externalPublishSelect.style.fontSize = '14px'
+  externalPublishSelect.style.boxSizing = 'border-box'
+  ;['none', 'hap', 'matter'].forEach((val) => {
+    const opt = document.createElement('option')
+    opt.value = val
+    opt.text = val === 'none' ? 'None' : val.toUpperCase()
+    opt.selected = (device.externalPublishProtocol || 'none') === val
+    externalPublishSelect.appendChild(opt)
+  })
+
   // --- Room ---
   const roomLabel = document.createElement('label')
   roomLabel.textContent = 'Room'
@@ -674,6 +726,7 @@ export async function editDevice(device: any): Promise<void> {
         configDeviceName: nameInput.value || undefined,
         configDeviceType: typeSelect.value,
         connectionPreference: connectionPrefSelect.value,
+        externalPublishProtocol: externalPublishSelect.value,
         room: roomInput.value || undefined,
         encryptionKey: encryptionKeyInput.value || undefined,
         keyId: keyIdInput.value || undefined,
@@ -690,6 +743,9 @@ export async function editDevice(device: any): Promise<void> {
       if (params.room !== undefined) {
         options.room = params.room
       }
+      if (params.externalPublishProtocol !== undefined) {
+        options.externalPublishProtocol = params.externalPublishProtocol
+      }
       if (params.encryptionKey !== undefined) {
         options.encryptionKey = params.encryptionKey
       }
@@ -739,6 +795,8 @@ export async function editDevice(device: any): Promise<void> {
   contentDiv.appendChild(typeSelect)
   contentDiv.appendChild(connectionPrefLabel)
   contentDiv.appendChild(connectionPrefSelect)
+  contentDiv.appendChild(externalPublishLabel)
+  contentDiv.appendChild(externalPublishSelect)
   contentDiv.appendChild(roomLabel)
   contentDiv.appendChild(roomInput)
   contentDiv.appendChild(encryptionKeyLabel)

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

@@ -1011,8 +1011,9 @@ export function renderDeviceList(list: any[]): void {
 
     const typeText = d.type ? `type: ${d.type}` : ''
     const connText = d.connectionPreference ? `conn: ${d.connectionPreference}` : ''
+    const extText = d.externalPublishProtocol && d.externalPublishProtocol !== 'none' ? `external: ${d.externalPublishProtocol}` : ''
     const roomText = d.room ? `room: ${d.room}` : ''
-    meta.textContent = [typeText, connText, roomText].filter(Boolean).join(' | ')
+    meta.textContent = [typeText, connText, extText, roomText].filter(Boolean).join(' | ')
 
     info.appendChild(nameContainer)
     info.appendChild(meta)

package/src/homebridge-ui/utils/config-parser.ts

@@ -57,6 +57,15 @@ export function getAllDevices(platform: any): any[] {
   })
 }
 
+/**
+ * Detect whether a platform config block is in the legacy v4 format.
+ *
+ * v4 configs stored credentials under a `credentials` sub-object and devices
+ * under `options.devices`.  v5+ flattened these to `openApiToken`,
+ * `openApiSecret`, and a root-level `devices` array.
+ */
+export { isV4Config } from './v4-detection.js'
+
 /**
  * Get credential from platform config
  */

package/src/homebridge-ui/utils/v4-detection.ts

@@ -0,0 +1,23 @@
+/**
+ * Detect whether a platform config block is in the legacy v4 format.
+ *
+ * v4 configs stored credentials under a `credentials` sub-object and devices
+ * under `options.devices`.  v5+ flattened these to `openApiToken`,
+ * `openApiSecret`, and a root-level `devices` array.
+ *
+ * This helper has no Node.js-specific dependencies so it can be imported from
+ * both the Homebridge server-side code and the browser-side plugin UI bundle.
+ */
+export function isV4Config(platform: any): boolean {
+  if (!platform || typeof platform !== 'object') {
+    return false
+  }
+  // Presence of a `credentials` sub-object is the clearest v4 signal
+  const hasCredentials = platform.credentials !== undefined && typeof platform.credentials === 'object'
+  // Presence of `options.devices` is the other v4 signal
+  const hasOptionsDevices
+    = platform.options !== undefined
+    && typeof platform.options === 'object'
+    && Array.isArray(platform.options.devices)
+  return hasCredentials || hasOptionsDevices
+}

package/src/settings.ts

@@ -1,12 +1,24 @@
 export const PLUGIN_NAME = '@switchbot/homebridge-switchbot'
 export const PLATFORM_NAME = 'SwitchBot'
 
+export interface SwitchBotDeviceConfig {
+  deviceId?: string
+  id?: string
+  configDeviceName?: string
+  name?: string
+  configDeviceType?: string
+  type?: string
+  externalPublishProtocol?: 'none' | 'hap' | 'matter'
+  [key: string]: any
+}
+
 export interface SwitchBotPluginConfig {
   openApiToken?: string
   openApiSecret?: string
   preferMatter?: boolean
   enableMatter?: boolean
   enableBLE?: boolean // Enable or disable BLE support
+  devices?: SwitchBotDeviceConfig[]
   // other plugin-specific configuration
   [key: string]: any
 }

package/src/utils.ts

@@ -1137,6 +1137,37 @@ export function normalizeConfig(raw?: PlatformConfig): SwitchBotPluginConfig {
   return { ...(raw as any) } as SwitchBotPluginConfig
 }
 
+/**
+ * Resolve the per-device external publish protocol from raw config.
+ * Accepts canonical values (`none`, `hap`, `matter`) and common aliases.
+ */
+export function resolveExternalPublishProtocol(rawDevice: any): 'none' | 'hap' | 'matter' {
+  const raw = String(
+    rawDevice?.externalPublishProtocol
+    ?? rawDevice?.externalDeviceProtocol
+    ?? rawDevice?.publishExternal
+    ?? rawDevice?.external
+    ?? 'none',
+  ).trim().toLowerCase()
+
+  if (raw === 'true') {
+    return 'hap'
+  }
+  if (raw === 'false') {
+    return 'none'
+  }
+  if (raw === 'homekit') {
+    return 'hap'
+  }
+  if (raw === 'none' || raw === 'off' || raw === 'disabled') {
+    return 'none'
+  }
+  if (raw === 'hap' || raw === 'matter') {
+    return raw
+  }
+  return 'none'
+}
+
 // Create a Proxy constructor that instantiates the right platform implementation at runtime.
 /**
  * Creates a proxy class that instantiates the correct platform implementation (HAP or Matter) at runtime.

package/test/homebridge-ui/config-parser.spec.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+
+import { isV4Config } from '../../src/homebridge-ui/utils/v4-detection.js'
+
+describe('isV4Config', () => {
+  it('returns false for null/undefined input', () => {
+    expect(isV4Config(null)).toBe(false)
+    expect(isV4Config(undefined)).toBe(false)
+  })
+
+  it('returns false for an empty v5 config block', () => {
+    expect(isV4Config({ platform: 'SwitchBot', devices: [] })).toBe(false)
+  })
+
+  it('returns false for a v5 config with credentials omitted', () => {
+    expect(isV4Config({ platform: 'SwitchBot', openApiToken: 'tok', openApiSecret: 'sec', devices: [] })).toBe(false)
+  })
+
+  it('returns true when a credentials sub-object is present (v4 token location)', () => {
+    const v4 = {
+      platform: 'SwitchBot',
+      credentials: { token: 'tok', secret: 'sec', notice: 'Keep your token a secret!' },
+      options: { devices: [] },
+    }
+    expect(isV4Config(v4)).toBe(true)
+  })
+
+  it('returns true when options.devices array is present without credentials (partial v4)', () => {
+    const partialV4 = {
+      platform: 'SwitchBot',
+      options: {
+        devices: [{ deviceId: 'aabbcc', configDeviceName: 'Curtain', configDeviceType: 'Curtain', connectionType: 'BLE' }],
+      },
+    }
+    expect(isV4Config(partialV4)).toBe(true)
+  })
+
+  it('returns true for the exact config from the bug report', () => {
+    const bugReportConfig = {
+      name: 'SwitchBot',
+      credentials: { notice: 'Keep your token a secret!' },
+      options: {
+        devices: [
+          {
+            deviceId: 'xxxxxxxx',
+            configDeviceName: 'Curtain',
+            configDeviceType: 'Curtain',
+            connectionType: 'BLE',
+            hide_lightsensor: false,
+            set_min: 96,
+            set_max: 12,
+            maxRetry: 0,
+            logging: 'standard',
+          },
+        ],
+      },
+      platform: 'SwitchBot',
+    }
+    expect(isV4Config(bugReportConfig)).toBe(true)
+  })
+})

package/test/platform/matter-integration.spec.ts

@@ -30,4 +30,54 @@ describe('matter integration platform', () => {
     const platform = new TestMatterPlatform(logger, config, api)
     expect(platform.getDevices()).toEqual([])
   })
+
+  it('should publish per-device external Matter accessories via the Homebridge external event', async () => {
+    const pendingExternalRegistrations = new Map()
+    const apiWithMatter: any = {
+      matter: {
+        uuid: { generate: (value: string) => `m-${value}` },
+        registerPlatformAccessories: vi.fn(async () => {}),
+      },
+      hap: { uuid: { generate: (value: string) => `h-${value}` } },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: vi.fn(),
+      emit: null as any,
+      _pendingExternalRegistrations: pendingExternalRegistrations,
+    }
+    const emit = vi.fn((event: string, accessories: any[], registrationId: string) => {
+      if (event === 'publishExternalMatterAccessories') {
+        const resolve = pendingExternalRegistrations.get(registrationId)
+        resolve?.()
+      }
+      return true
+    })
+    apiWithMatter.emit = emit
+    const platform = new TestMatterPlatform(logger, config, apiWithMatter)
+    const created = {
+      createAccessory: vi.fn(async () => ({
+        name: 'Curtain3',
+        manufacturer: 'SwitchBot',
+        model: 'Curtain3',
+        serialNumber: 'serial-1',
+        deviceType: { deviceType: 514 },
+        clusters: { windowCovering: { currentPositionLiftPercent100ths: 0 } },
+        handlers: {},
+      })),
+    }
+
+    await platform.registerMatterAccessories([
+      {
+        created,
+        d: { id: 'device-1', name: 'Curtain3' },
+        type: 'curtain',
+        useMatter: true,
+        matterAvailable: true,
+        externalPublishProtocol: 'matter',
+      },
+    ])
+
+    expect(emit).toHaveBeenCalledWith('publishExternalMatterAccessories', expect.any(Array), expect.any(String))
+    expect(apiWithMatter.matter.registerPlatformAccessories).not.toHaveBeenCalled()
+  })
 })

package/test/utils/utils.spec.ts

@@ -5,6 +5,7 @@ import {
   MATTER_ATTRIBUTE_IDS,
   MATTER_CLUSTER_IDS,
   normalizeConfig,
+  resolveExternalPublishProtocol,
 } from '../../src/utils'
 
 describe('utils', () => {
@@ -50,4 +51,18 @@ describe('utils', () => {
     expect(HAP).toHaveBeenCalled()
     expect(Matter).not.toHaveBeenCalled()
   })
+
+  it('resolveExternalPublishProtocol normalizes known values and aliases', () => {
+    expect(resolveExternalPublishProtocol({ externalPublishProtocol: 'hap' })).toBe('hap')
+    expect(resolveExternalPublishProtocol({ externalPublishProtocol: 'matter' })).toBe('matter')
+    expect(resolveExternalPublishProtocol({ externalPublishProtocol: 'none' })).toBe('none')
+    expect(resolveExternalPublishProtocol({ externalPublishProtocol: 'homekit' })).toBe('hap')
+    expect(resolveExternalPublishProtocol({ publishExternal: true })).toBe('hap')
+    expect(resolveExternalPublishProtocol({ publishExternal: false })).toBe('none')
+  })
+
+  it('resolveExternalPublishProtocol defaults to none for unknown values', () => {
+    expect(resolveExternalPublishProtocol({ externalPublishProtocol: 'invalid' })).toBe('none')
+    expect(resolveExternalPublishProtocol({})).toBe('none')
+  })
 })