@thecloudseeker/homebridge-homekit-ble-matter 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) 2026 thecloudseeker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# homebridge-homekit-ble-matter
+
+Brings **HomeKit-only Bluetooth sensors** to **Matter** controllers such as IKEA Dirigera, Google Home, Amazon Alexa or SmartThings.
+
+Some sensors only speak HomeKit over Bluetooth (for example the Qingping Temp & RH Monitor **H version, CGG1H**), so only Apple Home can use them. This plugin pairs with such a device the way Apple Home would, reads its values, and exposes it through Homebridge's Matter bridge.
+
+> **Beta.** Tested with a Qingping CGG1H on a Raspberry Pi. Currently supports temperature and humidity sensors (with battery level).
+
+## Requirements
+
+- Homebridge **2.4.0** or later, with Matter
+- A Bluetooth adapter the Homebridge host can use (the Raspberry Pi's built-in one works)
+- Node.js 20, 22 or 24
+
+## Setup
+
+1. **Remove the device from Apple Home** (accessory → Remove Accessory). A HomeKit device can only be paired with one controller this way.
+2. Install the plugin and run it as a **child bridge**. In the child bridge settings, turn **Enable Matter** on (and HomeKit off: this plugin exposes nothing over HomeKit).
+3. Restart. The log lists nearby HomeKit Bluetooth devices:
+   ```
+   Found HomeKit Bluetooth sensor 'Qingping Temp RH H' - DeviceID 41:21:14:E5:C2:25, available to pair. Add it under 'devices' to use it.
+   ```
+4. Add it with that **DeviceID** (not the Bluetooth address) and its **HomeKit setup code**:
+   ```json
+   {
+     "platform": "HomeKitBleMatter",
+     "devices": [
+       { "deviceId": "41:21:14:E5:C2:25", "name": "Bedroom", "setupCode": "128-84-842" }
+     ]
+   }
+   ```
+5. Restart. The plugin pairs, reads the device's structure and registers one Matter device. Add the bridge to your Matter controller with the code from the child bridge's Matter settings.
+
+The pairing keys are stored in `<Homebridge storage>/homekit-ble-matter/`. Keep that folder: without it the device has to be factory-reset before it can be paired again.
+
+## Configuration
+
+| Key | Default | Description |
+|---|---|---|
+| `devices[].deviceId` | | HomeKit DeviceID from the log. Required. |
+| `devices[].name` | DeviceID | Name of the Matter device. |
+| `devices[].setupCode` | | 8-digit HomeKit code (`123-45-678`, `12345678` or `1234 5678`). Only needed for the first pairing. |
+| `pollInterval` | `10` | Minutes between reads (also per device). |
+| `timeout` | `60` | Minutes without a successful read before values are reported as unavailable (also per device). |
+
+## How it works
+
+- One Bluetooth scan listens to all HomeKit advertisements. When a device's advertised state number changes (HomeKit devices bump it when a value changes), it's read, at most once every 5 minutes. On top of that it's polled every `pollInterval` minutes.
+- Each read is a short encrypted Bluetooth connection. Connections run one at a time.
+- A device measuring both temperature and humidity becomes **one** Matter endpoint, so controllers that list every endpoint separately (IKEA Dirigera) show one device.
+- If a device is factory-reset, the plugin notices (it advertises as unpaired again) and pairs again with the configured setup code.
+
+## Known limitations
+
+- **New Matter `uniqueId` after each restart** for temperature+humidity devices, due to a Homebridge limitation ([homebridge/homebridge#4018](https://github.com/homebridge/homebridge/issues/4018)). IKEA Dirigera keeps the device, name and room across restarts; other controllers are untested.
+- **Bluetooth is shared** with any other Bluetooth plugin on the same adapter. It worked alongside a scanning plugin in testing, but busy adapters can make connections fail; failed reads are retried after a minute.
+- HomeKit's encrypted "disconnected events" aren't supported by the underlying library ([hap-controller#43](https://github.com/Apollon77/hap-controller-node/issues/43)), so change detection relies on the advertised state number plus polling.
+
+Built on [hap-controller](https://github.com/Apollon77/hap-controller-node).

package/config.schema.json

@@ -0,0 +1,83 @@
+{
+  "pluginAlias": "HomeKitBleMatter",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Pairs with HomeKit-over-Bluetooth sensors and exposes them over **Matter only**. Run this plugin as a child bridge with **Enable Matter** turned on (and HomeKit off). Nearby devices are listed in the log with their DeviceID; a device must be removed from Apple Home before this plugin can pair with it.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "devices": {
+        "title": "Devices",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "deviceId": {
+              "title": "DeviceID",
+              "type": "string",
+              "placeholder": "e.g. 41:21:14:E5:C2:25",
+              "description": "The HomeKit DeviceID, as listed in the log ('Found HomeKit Bluetooth sensor … - DeviceID …'). Not the Bluetooth address.",
+              "required": true
+            },
+            "name": {
+              "title": "Name",
+              "type": "string",
+              "placeholder": "e.g. Bedroom"
+            },
+            "setupCode": {
+              "title": "HomeKit Setup Code",
+              "type": "string",
+              "placeholder": "e.g. 123-45-678",
+              "description": "The 8-digit HomeKit code on the device or its manual. Only needed for the first pairing."
+            },
+            "pollInterval": {
+              "title": "Poll Interval (minutes)",
+              "type": "integer",
+              "minimum": 1,
+              "description": "Overrides the default below for this device."
+            },
+            "timeout": {
+              "title": "Timeout (minutes)",
+              "type": "integer",
+              "minimum": 5,
+              "description": "Overrides the default below for this device."
+            }
+          }
+        }
+      },
+      "pollInterval": {
+        "title": "Poll Interval (minutes)",
+        "type": "integer",
+        "default": 10,
+        "minimum": 1,
+        "description": "How often values are read. Devices that signal changes themselves are also read when they change (at most once every 5 minutes). Each read is a Bluetooth connection, which costs the device battery."
+      },
+      "timeout": {
+        "title": "Timeout (minutes)",
+        "type": "integer",
+        "default": 60,
+        "minimum": 5,
+        "description": "After this long without a successful read, readings are reported as unavailable."
+      }
+    }
+  },
+  "layout": [
+    {
+      "key": "devices",
+      "type": "array",
+      "items": [
+        "devices[].deviceId",
+        "devices[].name",
+        "devices[].setupCode",
+        "devices[].pollInterval",
+        "devices[].timeout"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Defaults",
+      "expandable": true,
+      "items": ["pollInterval", "timeout"]
+    }
+  ]
+}

package/index.js

@@ -0,0 +1,9 @@
+module.exports = (homebridge) => {
+  const { HomeKitBleMatterPlatform, PLUGIN_IDENTIFIER, PLATFORM_NAME } =
+    require("./lib/platform")(homebridge);
+  homebridge.registerPlatform(
+    PLUGIN_IDENTIFIER,
+    PLATFORM_NAME,
+    HomeKitBleMatterPlatform,
+  );
+};

package/lib/bleSensor.js

@@ -0,0 +1,365 @@
+const { withTimeout } = require("./connectionQueue");
+const { parseAccessoryDatabase, normalizeSetupCode } = require("./hap");
+
+const PAIR_TIMEOUT = 90 * 1000;
+const DATABASE_TIMEOUT = 90 * 1000;
+const READ_TIMEOUT = 45 * 1000;
+// Reads triggered by the sensor's own "something changed" signal are capped
+// at one per five minutes: each read is a Bluetooth connection, which costs
+// the sensor battery, and a sensor signalling every 0.1° change would
+// otherwise be connected to every minute.
+const MIN_READ_GAP = 5 * 60 * 1000;
+const RETRY_DELAY = 60 * 1000;
+
+// One HomeKit-over-Bluetooth sensor: pairs with it (once), learns where its
+// readings live (once per firmware configuration), then reads them - on a
+// poll interval, and whenever its advertisement's Global State Number (GSN)
+// changes, which HomeKit accessories bump when a value changes.
+//
+// Advertisements are fed in by the platform (one shared BLEDiscovery for all
+// sensors) via handleAdvertisement(). Connections go through the shared
+// ConnectionQueue.
+class BleSensor {
+  constructor({
+    config,
+    log,
+    hap,
+    discovery,
+    store,
+    queue,
+    onReady,
+    onReadings,
+  }) {
+    this.config = config;
+    this.deviceId = config.deviceId;
+    this.log = log;
+    this.hap = hap;
+    this.discovery = discovery;
+    this.store = store;
+    this.queue = queue;
+    this.onReady = onReady;
+    this.onReadings = onReadings;
+
+    this.state = store.load(this.deviceId) ?? {};
+    this.advertisement = null;
+    this.ready = false;
+    this.preparing = null;
+    this.reading = null;
+    this.lastReadAt = 0;
+    this.lastSuccessAt = null;
+    this.timedOut = false;
+    this.warned = new Set();
+    this.stopped = false;
+  }
+
+  get prefix() {
+    return `[${this.config.name}]`;
+  }
+
+  get pollInterval() {
+    return (this.config.pollInterval ?? 10) * 60 * 1000;
+  }
+
+  // Minutes without a successful read after which readings are reported as
+  // unavailable (null), so controllers don't show a frozen value forever.
+  get timeout() {
+    return (this.config.timeout ?? 60) * 60 * 1000;
+  }
+
+  // What's already known from a previous run, so the platform can register
+  // the Matter device before the sensor is even in range.
+  get cachedDatabase() {
+    return this.state.database ?? null;
+  }
+
+  get cachedInfo() {
+    return this.state.info ?? {};
+  }
+
+  warnOnce(key, message) {
+    if (this.warned.has(key)) {
+      return;
+    }
+    this.warned.add(key);
+    this.log.warn(`${this.prefix} ${message}`);
+  }
+
+  handleAdvertisement(service) {
+    if (this.stopped) {
+      return;
+    }
+    const previous = this.advertisement;
+    this.advertisement = service;
+    if (service.availableToPair && this.state.pairingData != null) {
+      // Advertising "not paired" although we hold keys: the sensor was
+      // factory-reset or our pairing was removed. The keys are useless now.
+      this.log.warn(
+        `${this.prefix} Sensor reports it is no longer paired (reset, or pairing removed); pairing again.`,
+      );
+      this.state.pairingData = null;
+      this.store.save(this.deviceId, this.state);
+      this.ready = false;
+    }
+    if (!this.ready) {
+      this.prepare();
+      return;
+    }
+    if (previous != null && service.CN !== previous.CN) {
+      // The accessory's configuration (e.g. after a firmware update) changed:
+      // the characteristic addressing may be stale.
+      this.log.info(`${this.prefix} Configuration changed, re-reading it.`);
+      this.ready = false;
+      this.state.database = null;
+      this.prepare();
+      return;
+    }
+    if (previous != null && service.GSN !== previous.GSN) {
+      this.requestRead("changed");
+    }
+  }
+
+  prepare() {
+    if (this.preparing == null) {
+      this.preparing = this.doPrepare()
+        .catch((error) => {
+          this.log.warn(
+            `${this.prefix} Setup failed, will retry on its next advertisement: ${error.message}`,
+          );
+        })
+        .finally(() => {
+          this.preparing = null;
+        });
+    }
+    return this.preparing;
+  }
+
+  async doPrepare() {
+    const service = this.advertisement;
+    if (this.state.pairingData == null) {
+      if (!service.availableToPair) {
+        this.warnOnce(
+          "paired-elsewhere",
+          "Already paired with another HomeKit controller (e.g. Apple Home). Remove it there (or factory-reset it) to let this plugin pair with it.",
+        );
+        return;
+      }
+      const setupCode = normalizeSetupCode(this.config.setupCode);
+      if (setupCode == null) {
+        this.warnOnce(
+          "no-setup-code",
+          "Not paired yet and no valid setupCode configured (8 digits, e.g. 123-45-678).",
+        );
+        return;
+      }
+      await this.pair(service, setupCode);
+    }
+    if (this.state.database == null || this.state.configNumber !== service.CN) {
+      await this.loadDatabase(service);
+    }
+    this.ready = true;
+    this.onReady(this.state.database, this.state.info ?? {});
+    this.requestRead("startup");
+    this.schedulePoll();
+  }
+
+  async pair(service, setupCode) {
+    this.log.info(`${this.prefix} Pairing...`);
+    await this.queue.run(async () => {
+      const pairMethod = await withTimeout(
+        this.discovery.getPairMethod(service),
+        PAIR_TIMEOUT,
+        "Reading pair method",
+      );
+      const client = new this.hap.GattClient(
+        service.DeviceID,
+        service.peripheral,
+      );
+      try {
+        await withTimeout(
+          client.pairSetup(setupCode, pairMethod),
+          PAIR_TIMEOUT,
+          "Pairing",
+        );
+        this.state.pairingData = client.getLongTermData();
+      } finally {
+        await client.close().catch(() => {});
+      }
+    });
+    this.store.save(this.deviceId, this.state);
+    this.log.info(`${this.prefix} Paired.`);
+  }
+
+  async loadDatabase(service) {
+    this.log.info(`${this.prefix} Reading accessory structure...`);
+    await this.queue.run(async () => {
+      const client = new this.hap.GattClient(
+        service.DeviceID,
+        service.peripheral,
+        this.state.pairingData,
+      );
+      try {
+        const database = parseAccessoryDatabase(
+          await withTimeout(
+            client.getAccessories(),
+            DATABASE_TIMEOUT,
+            "Reading accessory structure",
+          ),
+          this.hap,
+        );
+        const infoEntries = Object.entries(database.info);
+        const info = {};
+        if (infoEntries.length > 0) {
+          const { characteristics } = await withTimeout(
+            client.getCharacteristics(
+              infoEntries.map(([, address]) => address),
+            ),
+            READ_TIMEOUT,
+            "Reading accessory information",
+          );
+          infoEntries.forEach(([key], index) => {
+            const value = characteristics[index]?.value;
+            if (value != null && value !== "") {
+              info[key] = String(value);
+            }
+          });
+        }
+        this.state.database = database.readings;
+        this.state.info = info;
+        this.state.configNumber = service.CN;
+      } finally {
+        await client.close().catch(() => {});
+      }
+    });
+    this.store.save(this.deviceId, this.state);
+    const found = Object.keys(this.state.database);
+    this.log.info(
+      `${this.prefix} ${this.state.info.manufacturer ?? ""} ${this.state.info.model ?? ""}: found ${found.length > 0 ? found.join(", ") : "nothing this plugin can read"}.`.replace(
+        /\s+/g,
+        " ",
+      ),
+    );
+  }
+
+  requestRead(reason) {
+    if (!this.ready || this.stopped || this.reading != null) {
+      return;
+    }
+    const sinceLast = Date.now() - this.lastReadAt;
+    if (reason === "changed" && sinceLast < MIN_READ_GAP) {
+      this.log.debug(`${this.prefix} Change signalled; read deferred.`);
+      clearTimeout(this.deferTimer);
+      this.deferTimer = setTimeout(
+        () => this.requestRead("deferred"),
+        MIN_READ_GAP - sinceLast,
+      );
+      return;
+    }
+    this.reading = this.read(reason).finally(() => {
+      this.reading = null;
+    });
+  }
+
+  async read(reason) {
+    const service = this.advertisement;
+    const entries = Object.entries(this.state.database);
+    if (service == null || entries.length === 0) {
+      return;
+    }
+    this.lastReadAt = Date.now();
+    try {
+      const values = await this.queue.run(async () => {
+        const client = new this.hap.GattClient(
+          service.DeviceID,
+          service.peripheral,
+          this.state.pairingData,
+        );
+        try {
+          const { characteristics } = await withTimeout(
+            client.getCharacteristics(entries.map(([, address]) => address)),
+            READ_TIMEOUT,
+            "Reading values",
+          );
+          return Object.fromEntries(
+            entries.map(([key], index) => [key, characteristics[index]?.value]),
+          );
+        } finally {
+          await client.close().catch(() => {});
+        }
+      });
+      this.lastSuccessAt = Date.now();
+      this.timedOut = false;
+      this.warned.delete("read-failed");
+      this.log.debug(
+        `${this.prefix} Read (${reason}): ${JSON.stringify(values)}`,
+      );
+      this.onReadings(normalizeReadings(values));
+      this.scheduleTimeoutCheck();
+    } catch (error) {
+      this.warnOnce("read-failed", `Reading failed: ${error.message}`);
+      this.log.debug(`${this.prefix} Retrying in ${RETRY_DELAY / 1000}s.`);
+      clearTimeout(this.retryTimer);
+      this.retryTimer = setTimeout(
+        () => this.requestRead("retry"),
+        RETRY_DELAY,
+      );
+      this.checkTimeout();
+    }
+  }
+
+  schedulePoll() {
+    clearInterval(this.pollTimer);
+    this.pollTimer = setInterval(
+      () => this.requestRead("poll"),
+      this.pollInterval,
+    );
+  }
+
+  scheduleTimeoutCheck() {
+    clearTimeout(this.timeoutTimer);
+    this.timeoutTimer = setTimeout(() => this.checkTimeout(), this.timeout);
+  }
+
+  checkTimeout() {
+    if (
+      this.timedOut ||
+      this.lastSuccessAt == null ||
+      Date.now() - this.lastSuccessAt < this.timeout
+    ) {
+      return;
+    }
+    this.timedOut = true;
+    this.log.warn(
+      `${this.prefix} No successful read for ${this.timeout / 60000} minutes; reporting it as unavailable.`,
+    );
+    this.onReadings({
+      temperature: null,
+      humidity: null,
+      batteryLevel: null,
+      lowBattery: null,
+    });
+  }
+
+  stop() {
+    this.stopped = true;
+    clearInterval(this.pollTimer);
+    clearTimeout(this.retryTimer);
+    clearTimeout(this.deferTimer);
+    clearTimeout(this.timeoutTimer);
+  }
+}
+
+// HAP values → plain numbers/booleans. Characteristics the sensor doesn't
+// have stay undefined (MatterSensor.update skips them).
+function normalizeReadings(values) {
+  const number = (value) =>
+    value == null || Number.isNaN(Number(value)) ? undefined : Number(value);
+  return {
+    temperature: number(values.temperature),
+    humidity: number(values.humidity),
+    batteryLevel: number(values.batteryLevel),
+    lowBattery:
+      values.lowBattery == null ? undefined : Number(values.lowBattery) === 1,
+  };
+}
+
+module.exports = { BleSensor, normalizeReadings };

package/lib/connectionQueue.js

@@ -0,0 +1,30 @@
+// Runs Bluetooth connections one at a time. A single adapter handles
+// concurrent GATT connections poorly - and the Homebridge host may share it
+// with other Bluetooth plugins - so sensors take turns.
+class ConnectionQueue {
+  constructor() {
+    this.tail = Promise.resolve();
+  }
+
+  run(task) {
+    const result = this.tail.then(task, task);
+    this.tail = result.catch(() => {});
+    return result;
+  }
+}
+
+// Rejects if `promise` hasn't settled within `ms`. hap-controller has no
+// timeouts of its own for BLE operations, and a sensor that walks out of
+// range mid-read would otherwise hold the queue forever.
+function withTimeout(promise, ms, description) {
+  let timer;
+  const timeout = new Promise((resolve, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`${description} timed out after ${ms / 1000}s`)),
+      ms,
+    );
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+module.exports = { ConnectionQueue, withTimeout };

package/lib/deviceStore.js

@@ -0,0 +1,44 @@
+const fs = require("fs");
+const path = require("path");
+
+// Persists per-device state across restarts: the HomeKit pairing keys (which
+// cannot be recovered - losing them means factory-resetting the sensor), the
+// accessory database addressing, and the device's accessory information.
+// One file per device, readable by the Homebridge user only.
+class DeviceStore {
+  constructor(directory) {
+    this.directory = directory;
+  }
+
+  fileFor(deviceId) {
+    return path.join(
+      this.directory,
+      `${deviceId.replace(/[^0-9A-Za-z]/g, "")}.json`,
+    );
+  }
+
+  load(deviceId) {
+    try {
+      return JSON.parse(fs.readFileSync(this.fileFor(deviceId), "utf8"));
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  save(deviceId, data) {
+    fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+    const file = this.fileFor(deviceId);
+    // Write-then-rename so a crash mid-write can't leave a truncated file
+    // behind and lose the pairing keys.
+    const temporary = `${file}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(data, null, 2), {
+      mode: 0o600,
+    });
+    fs.renameSync(temporary, file);
+  }
+}
+
+module.exports = { DeviceStore };

package/lib/hap.js

@@ -0,0 +1,103 @@
+// Everything this plugin needs from hap-controller, loaded lazily: requiring
+// hap-controller initializes noble (Bluetooth) at module load, which must not
+// happen just because Homebridge loaded the plugin - only once discovery
+// actually starts. Tests pass their own implementation of this shape instead.
+function loadHap() {
+  const { BLEDiscovery, GattClient } = require("hap-controller");
+  const {
+    characteristicFromUuid,
+  } = require("hap-controller/lib/model/characteristic");
+  const { serviceFromUuid } = require("hap-controller/lib/model/service");
+  return { BLEDiscovery, GattClient, characteristicFromUuid, serviceFromUuid };
+}
+
+// HomeKit Accessory Protocol names (as returned by hap-controller's
+// characteristicFromUuid/serviceFromUuid) for what this plugin reads.
+const SERVICES = {
+  accessoryInformation: "public.hap.service.accessory-information",
+};
+
+const READINGS = {
+  temperature: "public.hap.characteristic.temperature.current",
+  humidity: "public.hap.characteristic.relative-humidity.current",
+  batteryLevel: "public.hap.characteristic.battery-level",
+  lowBattery: "public.hap.characteristic.status-lo-batt",
+};
+
+const INFO = {
+  manufacturer: "public.hap.characteristic.manufacturer",
+  model: "public.hap.characteristic.model",
+  serialNumber: "public.hap.characteristic.serial-number",
+  firmwareRevision: "public.hap.characteristic.firmware.revision",
+};
+
+// HomeKit accessory category advertised by sensors (HAP spec table 12-3).
+const CATEGORY_SENSOR = 10;
+
+// Reduces hap-controller's accessory database to the characteristics this
+// plugin reads, keyed by READINGS/INFO name, each with the addressing a BLE
+// read needs ({serviceUuid, characteristicUuid, iid, format}). Info fields
+// are only taken from the accessory-information service: `name` and friends
+// also appear on every other service.
+function parseAccessoryDatabase(
+  { accessories },
+  { characteristicFromUuid, serviceFromUuid },
+) {
+  const readings = {};
+  const info = {};
+  for (const accessory of accessories ?? []) {
+    for (const service of accessory.services ?? []) {
+      const serviceName = serviceFromUuid(service.type);
+      for (const characteristic of service.characteristics ?? []) {
+        const name = characteristicFromUuid(characteristic.type);
+        const address = {
+          serviceUuid: service.type,
+          characteristicUuid: characteristic.type,
+          iid: characteristic.iid,
+          format: characteristic.format,
+        };
+        for (const [key, hapName] of Object.entries(READINGS)) {
+          if (name === hapName && readings[key] == null) {
+            readings[key] = address;
+          }
+        }
+        if (serviceName === SERVICES.accessoryInformation) {
+          for (const [key, hapName] of Object.entries(INFO)) {
+            if (name === hapName) {
+              info[key] = address;
+            }
+          }
+        }
+      }
+    }
+  }
+  return { readings, info };
+}
+
+// Accepts the setup code however it's printed or typed ("12884842",
+// "1288 4842", "128-84-842") and returns HomeKit's XXX-YY-ZZZ form, or null.
+function normalizeSetupCode(code) {
+  const digits = String(code ?? "").replace(/\D/g, "");
+  if (digits.length !== 8) {
+    return null;
+  }
+  return `${digits.slice(0, 3)}-${digits.slice(3, 5)}-${digits.slice(5)}`;
+}
+
+// DeviceIDs are compared case-insensitively; hap-controller reports them in
+// whatever case the advertisement produced.
+function normalizeDeviceId(deviceId) {
+  return String(deviceId ?? "")
+    .trim()
+    .toUpperCase();
+}
+
+module.exports = {
+  loadHap,
+  parseAccessoryDatabase,
+  normalizeSetupCode,
+  normalizeDeviceId,
+  READINGS,
+  INFO,
+  CATEGORY_SENSOR,
+};

package/lib/matterSensor.js

@@ -0,0 +1,204 @@
+const { normalizeDeviceId } = require("./hap");
+
+// Matches homebridge-plugins/homebridge-matter's TemperatureSensorAccessory
+// reference bounds (-50C to 100C). Matter rejects (rather than clamps) a
+// value outside the declared range, so the range is set wide.
+const MIN_MEASURED_TEMPERATURE = -5000;
+const MAX_MEASURED_TEMPERATURE = 10000;
+
+// Matter caps these string fields at 32 characters.
+const MAX_MATTER_LABEL_LENGTH = 32;
+
+// PowerSource enum values (Matter Core spec 11.7).
+const POWER_SOURCE_STATUS_ACTIVE = 1;
+const BAT_CHARGE_LEVEL_OK = 0;
+const BAT_CHARGE_LEVEL_WARNING = 1;
+const BAT_REPLACEABILITY_UNSPECIFIED = 0;
+
+function label(value) {
+  return String(value).slice(0, MAX_MATTER_LABEL_LENGTH);
+}
+
+// The Matter counterpart of one HomeKit BLE sensor: ONE endpoint carrying
+// whatever it measures (temperature and/or humidity) plus its battery.
+//
+// A single endpoint, rather than a BridgedNode with a child endpoint per
+// reading, because some controllers (IKEA Dirigera) list every sensor
+// endpoint as its own product. For a sensor measuring both, that needs a
+// composed device type (TemperatureSensor plus the HumiditySensor's
+// relativeHumidityMeasurement behavior) and a descriptor naming both device
+// types. Known Homebridge limitation: a composed type is re-created on every
+// restart with a new uniqueId (homebridge/homebridge#4018).
+class MatterSensor {
+  static uuidFor(matter, deviceId) {
+    return matter.uuid.generate(
+      `homebridge-homekit-ble-matter:${normalizeDeviceId(deviceId)}`,
+    );
+  }
+
+  // `capabilities`: which of temperature / humidity / battery the sensor has.
+  // `info`: manufacturer/model/serialNumber/firmwareRevision read from it.
+  constructor(matter, log, { deviceId, name, capabilities, info }) {
+    this.matter = matter;
+    this.log = log;
+    this.deviceId = deviceId;
+    this.capabilities = capabilities;
+
+    // See the CGDK2 plugin: registerPlatformAccessories() is fire-and-forget,
+    // and pushes are dropped until it resolves, or for good once it rejected.
+    this.registered = false;
+    this.registrationFailed = false;
+
+    const { TemperatureSensor, HumiditySensor } = matter.deviceTypes;
+    const clusters = {};
+    let deviceType;
+    if (capabilities.temperature && capabilities.humidity) {
+      deviceType = TemperatureSensor.with(
+        HumiditySensor.behaviors.relativeHumidityMeasurement,
+      );
+      clusters.descriptor = {
+        deviceTypeList: [
+          {
+            deviceType: TemperatureSensor.deviceType,
+            revision: TemperatureSensor.deviceRevision,
+          },
+          {
+            deviceType: HumiditySensor.deviceType,
+            revision: HumiditySensor.deviceRevision,
+          },
+        ],
+      };
+    } else if (capabilities.humidity) {
+      deviceType = HumiditySensor;
+    } else {
+      deviceType = TemperatureSensor;
+    }
+    if (capabilities.temperature) {
+      clusters.temperatureMeasurement = {
+        measuredValue: null,
+        minMeasuredValue: MIN_MEASURED_TEMPERATURE,
+        maxMeasuredValue: MAX_MEASURED_TEMPERATURE,
+      };
+    }
+    if (capabilities.humidity) {
+      clusters.relativeHumidityMeasurement = {
+        measuredValue: null,
+        minMeasuredValue: 0,
+        maxMeasuredValue: 10000,
+      };
+    }
+    if (capabilities.battery) {
+      clusters.powerSource = {
+        status: POWER_SOURCE_STATUS_ACTIVE,
+        order: 0,
+        description: "Battery",
+        endpointList: [],
+        batPercentRemaining: null,
+        batChargeLevel: BAT_CHARGE_LEVEL_OK,
+        batReplacementNeeded: false,
+        batReplaceability: BAT_REPLACEABILITY_UNSPECIFIED,
+      };
+    }
+
+    this.accessory = {
+      UUID: MatterSensor.uuidFor(matter, deviceId),
+      displayName: label(name),
+      deviceType,
+      serialNumber: label(info.serialNumber || normalizeDeviceId(deviceId)),
+      manufacturer: label(info.manufacturer || "Unknown"),
+      model: label(info.model || "HomeKit BLE sensor"),
+      firmwareRevision: info.firmwareRevision || undefined,
+      context: { deviceId: normalizeDeviceId(deviceId) },
+      clusters,
+    };
+  }
+
+  toAccessories() {
+    return [this.accessory];
+  }
+
+  markRegistered() {
+    this.registered = true;
+  }
+
+  markRegistrationFailed() {
+    this.registrationFailed = true;
+  }
+
+  // Homebridge restores a cached accessory onto its existing endpoint and
+  // only swaps in new metadata, so a renamed device would never reach
+  // controllers. NodeLabel may change at runtime, so push it explicitly.
+  async syncNodeLabel() {
+    await this.pushState("bridgedDeviceBasicInformation", {
+      nodeLabel: this.accessory.displayName,
+    });
+  }
+
+  // `readings`: {temperature, humidity, batteryLevel, lowBattery}, any of
+  // them undefined when not read; null for all when the sensor timed out.
+  async update(readings) {
+    const { temperature, humidity, batteryLevel, lowBattery } = readings ?? {};
+    if (this.capabilities.temperature && temperature !== undefined) {
+      await this.pushState("temperatureMeasurement", {
+        measuredValue:
+          temperature == null ? null : Math.round(temperature * 100),
+      });
+    }
+    if (this.capabilities.humidity && humidity !== undefined) {
+      await this.pushState("relativeHumidityMeasurement", {
+        measuredValue:
+          humidity == null
+            ? null
+            : Math.round(Math.min(100, Math.max(0, humidity)) * 100),
+      });
+    }
+    if (
+      this.capabilities.battery &&
+      (batteryLevel !== undefined || lowBattery !== undefined)
+    ) {
+      const attributes = {};
+      if (batteryLevel !== undefined) {
+        // Half-percent units (0-200).
+        attributes.batPercentRemaining =
+          batteryLevel == null
+            ? null
+            : Math.round(Math.min(100, Math.max(0, batteryLevel)) * 2);
+      }
+      if (lowBattery !== undefined) {
+        attributes.batChargeLevel = lowBattery
+          ? BAT_CHARGE_LEVEL_WARNING
+          : BAT_CHARGE_LEVEL_OK;
+      }
+      await this.pushState("powerSource", attributes);
+    }
+  }
+
+  async pushState(cluster, attributes) {
+    if (!this.registered || this.registrationFailed) {
+      return;
+    }
+    try {
+      await this.matter.updateAccessoryState(
+        this.accessory.UUID,
+        cluster,
+        attributes,
+      );
+    } catch (error) {
+      this.log.error(
+        `[${this.deviceId}] Failed to update Matter ${cluster} state:`,
+        error,
+      );
+    }
+  }
+}
+
+// What a parsed accessory database (see parseAccessoryDatabase) can report.
+function capabilitiesOf(readings) {
+  return {
+    temperature: readings.temperature != null,
+    humidity: readings.humidity != null,
+    battery: readings.batteryLevel != null || readings.lowBattery != null,
+  };
+}
+
+module.exports = { MatterSensor, capabilitiesOf };

package/lib/platform.js

@@ -0,0 +1,234 @@
+const path = require("path");
+const {
+  loadHap: defaultLoadHap,
+  normalizeDeviceId,
+  CATEGORY_SENSOR,
+} = require("./hap");
+const { BleSensor } = require("./bleSensor");
+const { ConnectionQueue } = require("./connectionQueue");
+const { DeviceStore } = require("./deviceStore");
+const { MatterSensor, capabilitiesOf } = require("./matterSensor");
+
+const PLUGIN_IDENTIFIER = "@thecloudseeker/homebridge-homekit-ble-matter";
+const PLATFORM_NAME = "HomeKitBleMatter";
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+class HomeKitBleMatterPlatform {
+  constructor(log, config, api, { loadHap = defaultLoadHap } = {}) {
+    this.log = log;
+    this.config = config || {};
+    this.api = api;
+    this.loadHap = loadHap;
+    this.sensors = new Map();
+    this.matterSensors = new Map();
+    this.announced = new Set();
+
+    this.devices = new Map();
+    for (const device of asArray(this.config.devices)) {
+      const deviceId = normalizeDeviceId(device?.deviceId);
+      if (deviceId === "") {
+        this.log.warn("Ignoring a device entry without deviceId.");
+        continue;
+      }
+      this.devices.set(deviceId, {
+        ...device,
+        deviceId,
+        name: device.name || deviceId,
+        pollInterval: device.pollInterval ?? this.config.pollInterval,
+        timeout: device.timeout ?? this.config.timeout,
+      });
+    }
+
+    this.api.on("didFinishLaunching", () => {
+      try {
+        this.start();
+      } catch (error) {
+        this.log.error("Failed to start:", error);
+      }
+    });
+    this.api.on("shutdown", () => this.shutdown());
+  }
+
+  // Matter only: there is nothing to restore on the HomeKit side.
+  configureAccessory() {}
+
+  // Drops cached Matter devices whose sensor is no longer configured -
+  // Homebridge publishes every cached Matter accessory whether or not the
+  // plugin registers it again.
+  configureMatterAccessory(accessory) {
+    const deviceId = normalizeDeviceId(accessory.context?.deviceId);
+    if (this.devices.has(deviceId)) {
+      return;
+    }
+    this.log.info(
+      `Removing Matter device of a no longer configured sensor: ${accessory.displayName}`,
+    );
+    this.api.matter
+      .unregisterPlatformAccessories(PLUGIN_IDENTIFIER, PLATFORM_NAME, [
+        accessory,
+      ])
+      .catch((error) =>
+        this.log.error("Failed to remove a Matter device:", error),
+      );
+  }
+
+  // Same conditions as the CGDK2 plugin: Matter available, enabled for this
+  // bridge, and Homebridge 2.4.0+ (composed device types re-register
+  // correctly over their cached copy only from there).
+  get matterEnabled() {
+    return Boolean(
+      this.api.isMatterAvailable?.() &&
+      this.api.isMatterEnabled?.() &&
+      this.api.versionGreaterOrEqual?.("2.4.0"),
+    );
+  }
+
+  start() {
+    if (!this.matterEnabled) {
+      this.log.error(
+        "Matter is not enabled for this bridge (or Homebridge is older than 2.4.0). This plugin only exposes devices over Matter: run it as a child bridge and turn on 'Enable Matter' in its bridge settings.",
+      );
+      return;
+    }
+    if (this.devices.size === 0) {
+      this.log.info(
+        "No devices configured yet. HomeKit Bluetooth devices found nearby are listed below with their DeviceID.",
+      );
+    }
+
+    this.hap = this.loadHap();
+    this.discovery = new this.hap.BLEDiscovery();
+    const store = new DeviceStore(
+      path.join(this.api.user.storagePath(), "homekit-ble-matter"),
+    );
+    const queue = new ConnectionQueue();
+
+    for (const config of this.devices.values()) {
+      const sensor = new BleSensor({
+        config,
+        log: this.log,
+        hap: this.hap,
+        discovery: this.discovery,
+        store,
+        queue,
+        onReady: (database, info) =>
+          this.ensureMatterSensor(config, database, info),
+        onReadings: (readings) =>
+          this.matterSensors.get(config.deviceId)?.update(readings),
+      });
+      this.sensors.set(config.deviceId, sensor);
+      // Known from a previous run: register right away, so the Matter device
+      // stays published (as unavailable) even if the sensor is out of range.
+      if (sensor.cachedDatabase != null) {
+        this.ensureMatterSensor(
+          config,
+          sensor.cachedDatabase,
+          sensor.cachedInfo,
+        );
+      }
+    }
+
+    const route = (service) => {
+      const deviceId = normalizeDeviceId(service.DeviceID);
+      const sensor = this.sensors.get(deviceId);
+      if (sensor != null) {
+        sensor.handleAdvertisement(service);
+      } else {
+        this.announce(service, deviceId);
+      }
+    };
+    this.discovery.on("serviceUp", route);
+    this.discovery.on("serviceChanged", route);
+    this.discovery.start();
+    this.log.info(
+      `Scanning for HomeKit Bluetooth devices (${this.devices.size} configured).`,
+    );
+  }
+
+  // Lists each unconfigured HomeKit BLE device once, so users can find the
+  // DeviceID to put in the config.
+  announce(service, deviceId) {
+    if (this.announced.has(deviceId)) {
+      return;
+    }
+    this.announced.add(deviceId);
+    const kind =
+      service.ACID === CATEGORY_SENSOR ? "sensor" : `category ${service.ACID}`;
+    this.log.info(
+      `Found HomeKit Bluetooth ${kind} '${service.name || "unnamed"}' - DeviceID ${deviceId}, ${service.availableToPair ? "available to pair" : "paired with another controller"}. Add it under 'devices' to use it.`,
+    );
+  }
+
+  ensureMatterSensor(config, database, info) {
+    if (this.matterSensors.has(config.deviceId)) {
+      return;
+    }
+    const capabilities = capabilitiesOf(database);
+    if (!capabilities.temperature && !capabilities.humidity) {
+      this.log.warn(
+        `[${config.name}] Has no temperature or humidity reading; this plugin currently only supports temperature/humidity sensors.`,
+      );
+      return;
+    }
+    const matterSensor = new MatterSensor(this.api.matter, this.log, {
+      deviceId: config.deviceId,
+      name: config.name,
+      capabilities,
+      info,
+    });
+    this.matterSensors.set(config.deviceId, matterSensor);
+    // Fired off: registration is fire-and-forget on Homebridge's side anyway.
+    this.api.matter
+      .registerPlatformAccessories(
+        PLUGIN_IDENTIFIER,
+        PLATFORM_NAME,
+        matterSensor.toAccessories(),
+      )
+      .then(() => {
+        matterSensor.markRegistered();
+        matterSensor.syncNodeLabel();
+        const what = Object.entries(capabilities)
+          .filter(([, has]) => has)
+          .map(([key]) => key)
+          .join(", ");
+        this.log.info(`[${config.name}] Registered Matter device (${what}).`);
+      })
+      .catch((error) => {
+        matterSensor.markRegistrationFailed();
+        this.log.error(
+          `[${config.name}] Failed to register Matter device:`,
+          error,
+        );
+      });
+  }
+
+  shutdown() {
+    for (const sensor of this.sensors.values()) {
+      sensor.stop();
+    }
+    try {
+      this.discovery?.stop();
+    } catch (error) {
+      this.log.debug("Stopping Bluetooth discovery failed:", error);
+    }
+  }
+}
+
+module.exports = (homebridge, deps) => {
+  if (deps != null) {
+    // Tests: bind injected dependencies.
+    return {
+      HomeKitBleMatterPlatform: class extends HomeKitBleMatterPlatform {
+        constructor(log, config, api) {
+          super(log, config, api, deps);
+        }
+      },
+      PLUGIN_IDENTIFIER,
+      PLATFORM_NAME,
+    };
+  }
+  return { HomeKitBleMatterPlatform, PLUGIN_IDENTIFIER, PLATFORM_NAME };
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@thecloudseeker/homebridge-homekit-ble-matter",
+  "version": "0.1.0-beta.1",
+  "description": "Homebridge plugin that pairs with HomeKit-over-Bluetooth sensors and exposes them over Matter (IKEA Dirigera, Google Home, Alexa, SmartThings…)",
+  "main": "index.js",
+  "scripts": {
+    "lint": "eslint .",
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "author": {
+    "name": "thecloudseeker",
+    "url": "https://github.com/thecloudseeker"
+  },
+  "license": "MIT",
+  "keywords": [
+    "homebridge-plugin",
+    "homekit",
+    "bluetooth",
+    "ble",
+    "matter",
+    "temperature",
+    "humidity",
+    "qingping",
+    "supports-matter"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thecloudseeker/homebridge-homekit-ble-matter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thecloudseeker/homebridge-homekit-ble-matter/issues"
+  },
+  "homepage": "https://github.com/thecloudseeker/homebridge-homekit-ble-matter#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.js",
+    "config.schema.json",
+    "lib/"
+  ],
+  "engines": {
+    "homebridge": "^2.4.0",
+    "node": "^20.18.0 || ^22.10.0 || ^24.0.0"
+  },
+  "dependencies": {
+    "hap-controller": "0.10.2"
+  },
+  "devDependencies": {
+    "eslint": "^10.9.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "globals": "^17.11.0",
+    "prettier": "^3.9.6"
+  }
+}