@rhizomatics/signalk-ble-sensors-plugin 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# [1.0.0]
+
+- Package moved to [Rhizomatics](https://www.rhizomatics.org.uk/sailing/)
+- Choice of outdoor pressure sensors now limited to ones that have pressure (RuuviTags all have pressure in data structure, however the waterproof Pro tags send a placeholder only).
+
+# [0.1.4]
+
+Improved handling of Switchbot (Woan) thermometers with rolling codes in payload
+Fix missing devices in registration dropdown
+
+# [0.1.3]
+
+Optionally re-publish a pressure value as `environment.outside.pressure` to cope with IP68 RuuviTag Pro that doesn't capture pressure, and re-use near enough value from an indoor standard RuuviTag.
+
+# [0.1.2]
+
+Improve RuuviTag support, adding motion sensor and removing humidity/pressure where not supported, e.g. the 3in1 or 2in1 RuuviTag Pro models
+Fix for SwitchBot (Woan) thermometers that publish payloads with MAC address prefixes
+The device RSSI is added to the drop-down list, to help work out which device is which ( e.g. saloon vs deck thermometers ) or even on another boat
+
+# [0.1.1]
+
+Simplify sensor names, and make sure values published with SignalK units.
+
+# [0.1.0]
+
+First alpha release

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# signalk-ble-sensors-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This is a limited replacement for `bt-sensors-plugin-sk` that has SignalK BLE Manager support, with only a few sensors known to work and passive only BLE integration. It may work for other sensors not listed here, and PRs welcome to add or correct support.
+
+Passive BLE sensor listening for [SignalK](https://signalk.org/) — reads temperature, humidity and battery data broadcast by cheap, popular BLE sensors and republishes it to SignalK paths, without ever opening a Bluetooth connection to the device. Relies only on _BLE Manager_, so requires SignalK v2.31 or above with v2.34+ recommended.
+
+## How it works
+
+Sensors like these broadcast their readings in plain BLE advertisement packets a few times a second. This plugin listens to that broadcast stream through the SignalK server's **BLE Manager API** and decodes it — there's no pairing, no GATT connection, and no battery drain on the sensor from being connected to.
+
+Devices the plugin doesn't recognise (anything not in the supported list below — a phone, a fitness tracker, or a sensor type not yet supported) are ignored entirely; only useful advertisements from a recognised sensor type are ever surfaced, so there's noise from unknown devices reporting their Bluetooth signal strength.
+
+### Air Pressure Override
+
+For boats that have IP68 RuuviTag Pro outside and RuuviTag inside, it can be handy to republish the inside pressure value as if it were outside, for example when using the _Barometer Trend_ plugin, so there's an option now to pick a device to publish the pressure also to `environment.outside.pressure`.
+
+## Requirements
+
+- SignalK server **>= 2.31.0** with the BLE Manager enabled (Server → Bluetooth in the admin UI) and at least one BLE provider available — the server's own local Bluetooth adapter support is enough, or a BLE proxy.
+- No other dependencies. This plugin never talks to Bluetooth hardware directly.
+
+## Supported sensors
+
+| Sensor                                           | Notes                                                  |
+| ------------------------------------------------ | ------------------------------------------------------ |
+| SwitchBot Meter (WoSensorTH)                     | Actively used, well tested                             |
+| SwitchBot Meter Plus                             | Actively used, well tested                             |
+| RuuviTag (data format 5)                         | Actively used, well tested                             |
+| Xiaomi LYWSD03MMC (pvvx/atc1441 custom firmware) | Best-effort — not actively used, contributions welcome |
+| Govee H5074 / H5075                              | Best-effort — not actively used, contributions welcome |
+
+Stock Xiaomi firmware (encrypted, not the ATC/pvvx custom firmware above) isn't supported. Sensors that need a GATT connection to read (Victron, Renogy, most BMS chips, etc.) are out of scope for this plugin. Many of these already have plugins, such as [signalk-bluetti-plugin](https://github.com/rhizomatics/signalk-bluetti-plugin) or [signalk-victron-ble](https://github.com/stefanor/signalk-victron-ble).
+
+## Configuring a sensor
+
+1. Install and enable the plugin, then restart (or just start) the SignalK server.
+2. Make sure the sensor is powered on and within Bluetooth range for a minute or two.
+3. Open the plugin's configuration page and click **+ Add Item** under "Registered sensors".
+4. Pick the sensor from the **Device** dropdown — it lists every recognised sensor the plugin has seen, labelled with its advertised name, sensor type, and MAC address. If it's not there yet, close the page, wait a bit longer, and reopen it.
+5. Fill in a **Zone / location** (e.g. `cabin`, `fridge`, `engine`) — this becomes part of the SignalK path (`environment.<zone>.temperature`, etc.); dots nest into sub-paths, e.g. `inside.mainCabin` becomes `environment.inside.mainCabin.temperature` — and optionally a **Name override**.
+6. Save. Readings should start appearing within a few seconds.
+
+If a sensor measures pressure (currently RuuviTag only), it can optionally also be picked as the **Outside pressure source**
+(a plugin-level setting, above "Registered sensors") to additionally publish its reading to `environment.outside.pressure` —
+the SignalK-standard path other plugins (e.g. barometer trend) expect — alongside its own `environment.<zone>.pressure`. The
+sensor still needs to be added under "Registered sensors" as usual; picking it here doesn't register it on its own.
+
+## Published paths
+
+| Value            | Path                              | Unit                                |
+| ---------------- | --------------------------------- | ----------------------------------- |
+| Temperature      | `environment.<zone>.temperature`  | K                                   |
+| Humidity         | `environment.<zone>.humidity`     | ratio (0-1)                         |
+| Pressure         | `environment.<zone>.pressure`     | Pa                                  |
+| Battery strength | `sensors.<name>.battery.strength` | ratio (0-1), with low-battery zones |
+| Battery voltage  | `sensors.<name>.battery.voltage`  | V                                   |
+| Signal strength  | `sensors.<name>.RSSI`             | dB                                  |
+| Reachable        | `sensors.<name>.reachable`        | boolean                             |
+| Motion counter   | `sensors.<name>.motionCounter`    | count                               |
+
+`<name>` is the sensor's name, lowercased and sanitized — give each registered sensor a distinct name, since
+two sensors with the same name will collide on these paths. Not every sensor publishes every path above — only the values its
+decoder actually supports (e.g. only RuuviTag currently reports pressure and a motion counter).
+
+These path and unit conventions are reused from
+[bt-sensors-plugin-sk](https://github.com/naugehyde/bt-sensors-plugin-sk) so this plugin's output lines up with dashboards or alarms already built against that plugin's paths.
+
+## Relationship to bt-sensors-plugin-sk
+
+[bt-sensors-plugin-sk](https://github.com/naugehyde/bt-sensors-plugin-sk) is the more complete, actively maintained BLE sensor plugin for SignalK, supporting many more sensors including ones that need a GATT connection. It doesn't yet have support for the BLE Manager, so can suffer the same issues as other dedicated Bluetooth plugins. This plugin exists to cover the gap in the meantime for a narrower set of passive, advertisement-only sensors, and is expected to be retired once that support lands upstream.
+
+### Bluetooth Issues
+
+There's a long list of of advice and fixes for Bluetooth Low Energy on SignalK at the [eInk Label Bluetooth](https://signalk-einklabel.rhizomatics.org.uk/bluetooth/#ble-manager-readiness) page that covers Bluetti use too, although Bluetti isn't as tricky to work with as some eInk labels.

package/docs/assets/icon.svg

@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#0f4c5c"/>
+      <stop offset="1" stop-color="#093542"/>
+    </linearGradient>
+    <linearGradient id="body" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#f4f6f7"/>
+      <stop offset="1" stop-color="#d7dde0"/>
+    </linearGradient>
+  </defs>
+
+  <!-- app icon background -->
+  <rect x="0" y="0" width="256" height="256" rx="48" fill="url(#bg)"/>
+
+  <!-- advertisement broadcast waves -->
+  <g fill="none" stroke="#f4a340" stroke-width="9" stroke-linecap="round">
+    <path d="M182 58 A22 22 0 0 1 204 80"/>
+    <path d="M182 38 A42 42 0 0 1 224 80"/>
+  </g>
+
+  <!-- sensor body -->
+  <rect x="48" y="80" width="136" height="128" rx="18" fill="url(#body)" stroke="#093542" stroke-width="4"/>
+
+  <!-- display -->
+  <rect x="64" y="96" width="104" height="70" rx="8" fill="#0f4c5c"/>
+  <!-- thermometer glyph -->
+  <rect x="88" y="106" width="12" height="38" rx="6" fill="none" stroke="#7fd8c4" stroke-width="3"/>
+  <rect x="92" y="122" width="4" height="24" fill="#7fd8c4"/>
+  <circle cx="94" cy="150" r="8" fill="#7fd8c4"/>
+  <!-- humidity droplet glyph -->
+  <path d="M138 108 C134 116 126 126 126 136 a12 12 0 0 0 24 0 C150 126 142 116 138 108 z" fill="#7fd8c4"/>
+
+  <!-- status LED / button -->
+  <circle cx="116" cy="187" r="7" fill="none" stroke="#093542" stroke-width="4"/>
+  <circle cx="116" cy="187" r="2.5" fill="#093542"/>
+</svg>

package/index.js

@@ -0,0 +1,158 @@
+"use strict";
+
+module.exports = function (app) {
+  const plugin = {};
+  plugin.id = "signalk-ble-sensors-plugin";
+  plugin.name = "BLE Sensors (Passive)";
+  plugin.description =
+    "Passively listens to BLE advertisements from supported sensors (SwitchBot, RuuviTag, and others) via the SignalK BLE Manager API — no GATT connection required.";
+
+  // Lazy-required so a dependency load failure surfaces as a plugin error
+  // rather than crashing the server (mirrors the sibling signalk-bluetti-plugin).
+  let manager = null;
+
+  plugin.schema = function () {
+    const recognized = manager ? manager.getRecognizedDevices() : [];
+    const configured = manager ? manager.getConfiguredDevices() : [];
+    const outsidePressureSourceMac = manager ? manager.getOutsidePressureSourceMac() : null;
+    return buildSchema(recognized, configured, outsidePressureSourceMac);
+  };
+
+  plugin.start = function (options = {}) {
+    if (!app.bleApi) {
+      const msg =
+        "BLE Manager API (app.bleApi) is not available on this SignalK server — requires server >= 2.31.0 with Bluetooth enabled.";
+      app.setPluginError(msg);
+      return;
+    }
+
+    const SensorManager = require("./lib/sensor-manager");
+    manager = new SensorManager(app, plugin.id, (msg) => app.debug(msg));
+    manager.configure(options);
+
+    try {
+      manager.start();
+    } catch (err) {
+      app.setPluginError(err.message);
+      manager = null;
+      return;
+    }
+
+    const count = (options.sensors || []).filter((s) => s.enabled !== false).length;
+    app.setPluginStatus(`Listening for BLE sensor advertisements (${count} sensor${count === 1 ? "" : "s"} registered)`);
+  };
+
+  plugin.stop = function () {
+    if (manager) {
+      manager.stop();
+      manager = null;
+    }
+  };
+
+  return plugin;
+};
+
+function normalizeMac(mac) {
+  return String(mac).toLowerCase();
+}
+
+// adv.name is frequently blank for these sensors — SwitchBot and RuuviTag
+// decode entirely from manufacturer/service data and don't depend on the BLE
+// advertised name, which many providers never surface anyway (it's typically
+// only present in a scan response, not the primary advertising packet). Drop
+// the name segment rather than showing a literal placeholder. RSSI is
+// appended as a live disambiguator: with a neighboring boat's identical
+// sensor model also in range, the stronger (less negative) signal is
+// generally the one actually on this boat. sensorTypeName is only known once
+// a device's advertisement has actually been decoded — a registered MAC not
+// yet re-observed since the plugin last started (see mergeKnownWithConfigured
+// below) won't have one.
+function formatDeviceLabel(d) {
+  const namePart = d.name ? `${d.name} — ` : "";
+  const typePart = d.sensorTypeName || "not seen since restart";
+  const rssiPart = d.rssi === undefined || d.rssi === null ? "" : ` · ${d.rssi}dBm`;
+  return `${namePart}${typePart} (${d.mac})${rssiPart}`;
+}
+
+// _recognized (and therefore getRecognizedDevices()) is runtime-only and
+// resets on every plugin restart, while a MAC already saved in options.sensors
+// persists across restarts. Without this merge, a registered sensor's MAC
+// would vanish from the dropdown's enum until it happened to broadcast again,
+// making an already-saved selection look like it disappeared even though
+// it's still in the config. Merged-in entries carry no sensorTypeName (we
+// only learn that by decoding an actual advertisement) or providesPressure
+// (safe default: false, so they can't wrongly appear in the pressure-source
+// dropdown until re-observed confirms what they are).
+function mergeKnownWithConfigured(recognized, configured) {
+  const byMac = new Map(recognized.map((d) => [normalizeMac(d.mac), d]));
+  for (const c of configured) {
+    if (!c || !c.mac || byMac.has(normalizeMac(c.mac))) continue;
+    byMac.set(normalizeMac(c.mac), { mac: c.mac, name: c.name, sensorTypeName: null, providesPressure: false, rssi: undefined });
+  }
+  return [...byMac.values()];
+}
+
+function buildSchema(recognized, configured = [], outsidePressureSourceMac = null) {
+  const known = mergeKnownWithConfigured(recognized, configured).sort((a, b) => a.mac.localeCompare(b.mac));
+  const hasKnown = known.length > 0;
+
+  let pressureCapable = known.filter((d) => d.providesPressure);
+  // Same rationale as above, for the single outsidePressureSource pick: keep
+  // it selectable even if the device hasn't re-confirmed its pressure
+  // capability since the last restart.
+  if (outsidePressureSourceMac && !pressureCapable.some((d) => normalizeMac(d.mac) === normalizeMac(outsidePressureSourceMac))) {
+    pressureCapable = [...pressureCapable, { mac: outsidePressureSourceMac, name: null, sensorTypeName: null, rssi: undefined }].sort(
+      (a, b) => a.mac.localeCompare(b.mac),
+    );
+  }
+  const hasPressureCapable = pressureCapable.length > 0;
+
+  return {
+    type: "object",
+    properties: {
+      outsidePressureSource: {
+        type: "string",
+        title: "Outside pressure source",
+        description:
+          "Optional. Also publish this sensor's pressure reading to environment.outside.pressure — the SignalK-standard path other plugins (e.g. barometer trend) expect — in addition to its own environment.<zone>.pressure. Only sensors that have actually reported a pressure reading since the plugin started (e.g. a RuuviTag, but not the pressure-less RuuviTag Pro IP68) are listed here; the device must also be added as a registered sensor below to actually be read.",
+        enum: hasPressureCapable ? ["", ...pressureCapable.map((d) => d.mac)] : [""],
+        enumNames: hasPressureCapable
+          ? ["(none)", ...pressureCapable.map(formatDeviceLabel)]
+          : ["No pressure-capable sensors detected yet"],
+      },
+      sensors: {
+        type: "array",
+        title: "Registered sensors",
+        description:
+          "Sensors to publish to SignalK. Only devices already recognised as a supported sensor type appear in the dropdown below — after installing, give the plugin a minute or two to run (with the sensor in Bluetooth range) and then reopen this configuration page.",
+        items: {
+          type: "object",
+          title: "Sensor",
+          required: ["mac"],
+          properties: {
+            mac: {
+              type: "string",
+              title: "Device",
+              enum: hasKnown ? known.map((d) => d.mac) : [""],
+              enumNames: hasKnown ? known.map(formatDeviceLabel) : ["No recognised sensors detected yet"],
+            },
+            name: {
+              type: "string",
+              title: "Name override",
+              description:
+                "Used as the SignalK $source and in generated sensor paths. Defaults to the device's advertised name if it has one, otherwise its sensor type (e.g. 'SwitchBot Meter') — worth setting explicitly.",
+            },
+            zone: {
+              type: "string",
+              title: "Zone / location",
+              description:
+                "Used in environment.<zone>.* paths, e.g. 'cabin', 'engine', 'fridge'. Dots nest into sub-paths, e.g. 'inside.mainCabin' becomes environment.inside.mainCabin.*.",
+              examples: ["inside", "outside", "galley", "fridge", "cabin", "engine", "deck", "cockpit", "inside.mainCabin"],
+            },
+            enabled: { type: "boolean", title: "Enabled", default: true },
+          },
+        },
+      },
+    },
+  };
+}

package/lib/ble-advertisement.js

@@ -0,0 +1,35 @@
+"use strict";
+
+// Normalises a raw BLEAdvertisement from the SignalK server's BLE Manager API
+// (app.bleApi.onAdvertisement — see @signalk/server-api's bleapi.d.ts) into the
+// shape our sensor decoders expect. manufacturerData/serviceData arrive as
+// hex-encoded strings keyed by manufacturer ID / service UUID; decoders work
+// against decoded Buffers instead.
+function normalizeAdvertisement(adv) {
+  const manufacturerData = new Map();
+  if (adv.manufacturerData) {
+    for (const [key, hex] of Object.entries(adv.manufacturerData)) {
+      manufacturerData.set(Number(key), Buffer.from(hex, "hex"));
+    }
+  }
+
+  const serviceData = new Map();
+  if (adv.serviceData) {
+    for (const [uuid, hex] of Object.entries(adv.serviceData)) {
+      serviceData.set(uuid.toLowerCase(), Buffer.from(hex, "hex"));
+    }
+  }
+
+  const serviceUuids = (adv.serviceUuids || []).map((u) => u.toLowerCase());
+
+  return {
+    mac: adv.mac,
+    name: adv.name || "",
+    rssi: adv.rssi,
+    manufacturerData,
+    serviceData,
+    serviceUuids,
+  };
+}
+
+module.exports = { normalizeAdvertisement };

package/lib/decoders/govee.js

@@ -0,0 +1,47 @@
+"use strict";
+
+// Govee H5074/H5075 thermo-hygrometers advertise manufacturer data under
+// Govee's ID (0xEC88); the two models pack it differently, distinguished by
+// each device's advertised name. No GATT connection needed.
+
+const MANUFACTURER_ID = 0xec88;
+const H5075_NAME = /^Govee_H5075_[0-9A-Fa-f]{4}$/;
+const H5074_NAME = /^Govee_H5074_[0-9A-Fa-f]{4}$/;
+
+function identify(adv) {
+  const md = adv.manufacturerData.get(MANUFACTURER_ID);
+  if (!md) return false;
+  return (H5075_NAME.test(adv.name) && md.length >= 6) || (H5074_NAME.test(adv.name) && md.length >= 6);
+}
+
+function decodeH5075(md) {
+  // 3-byte big-endian packed value: sign bit on the top byte, then
+  // temp-in-tenths-of-a-degree * 1000 + humidity-in-hundredths-of-a-percent.
+  const negative = (md[1] & 0x80) !== 0;
+  const packed = (md.readUIntBE(1, 3) & 0xffffff) ^ (negative ? 0x800000 : 0);
+  const tempTenths = Math.trunc(packed / 1000) * (negative ? -1 : 1);
+  const temp = 273.15 + tempTenths / 10;
+  const humidity = (packed % 1000) / 1000;
+  const battStrength = md[4] / 100;
+  return { temp, humidity, battStrength };
+}
+
+function decodeH5074(md) {
+  const temp = 273.15 + md.readInt16LE(1) / 100;
+  const humidity = md.readUInt16LE(3) / 10000;
+  const battStrength = md.readUInt8(5) / 100;
+  return { temp, humidity, battStrength };
+}
+
+function decode(adv) {
+  const md = adv.manufacturerData.get(MANUFACTURER_ID);
+  return H5075_NAME.test(adv.name) ? decodeH5075(md) : decodeH5074(md);
+}
+
+module.exports = {
+  id: "govee",
+  name: "Govee H5074/H5075",
+  domain: "environmental",
+  identify,
+  decode,
+};

package/lib/decoders/ruuvitag.js

@@ -0,0 +1,74 @@
+"use strict";
+
+// RuuviTag "data format 5" — https://github.com/ruuvi/ruuvi-sensor-protocols/blob/master/dataformat_05.md
+// Manufacturer-specific advertisement data, no GATT connection needed.
+
+const MANUFACTURER_ID = 0x0499;
+const DATA_FORMAT_5 = 5;
+
+// RuuviTags run on a CR2477 coin cell; 2.0V-3.0V is the commonly used
+// "practical" range for a rough charge estimate (the ADC itself covers
+// 1.6V-3.646V per the spec, but cells are unreliable below ~2.0V).
+const BATT_EMPTY_V = 2.0;
+const BATT_FULL_V = 3.0;
+
+function clamp01(v) {
+  return Math.max(0, Math.min(1, v));
+}
+
+function identify(adv) {
+  const data = adv.manufacturerData.get(MANUFACTURER_ID);
+  return !!data && data.length >= 24 && data[0] === DATA_FORMAT_5;
+}
+
+// Sensor-less variants (e.g. the Pro IP68, which only has temperature and the
+// accelerometer-driven motion counter) fill the fields they can't measure
+// with the format's "not available" sentinel rather than omitting them:
+// largest representable value for unsigned fields, smallest for signed ones.
+// Decoding those as real numbers would publish nonsense (e.g. the invalid
+// humidity sentinel 0xffff decodes to 163.8% if not filtered out here).
+const TEMP_INVALID = -32768; // 0x8000 as int16
+const HUMIDITY_INVALID = 0xffff;
+const PRESSURE_INVALID = 0xffff;
+const BATT_VOLTAGE_11BIT_INVALID = 0x7ff;
+const MOTION_COUNTER_INVALID = 0xff;
+
+function decode(adv) {
+  const buf = adv.manufacturerData.get(MANUFACTURER_ID);
+
+  const rawTemp = buf.readInt16BE(1);
+  const temp = rawTemp === TEMP_INVALID ? undefined : 273.15 + rawTemp * 0.005;
+
+  const rawHumidity = buf.readUInt16BE(3);
+  const humidity = rawHumidity === HUMIDITY_INVALID ? undefined : (rawHumidity * 0.0025) / 100;
+
+  const rawPressure = buf.readUInt16BE(5);
+  const pressure = rawPressure === PRESSURE_INVALID ? undefined : rawPressure + 50000;
+
+  const battMillivolts11Bit = buf.readUInt16BE(13) >> 5;
+  let battVoltage;
+  let battStrength;
+  if (battMillivolts11Bit !== BATT_VOLTAGE_11BIT_INVALID) {
+    battVoltage = 1.6 + battMillivolts11Bit / 1000;
+    battStrength = clamp01((battVoltage - BATT_EMPTY_V) / (BATT_FULL_V - BATT_EMPTY_V));
+  }
+
+  const rawMotionCounter = buf.readUInt8(15);
+  const motionCounter = rawMotionCounter === MOTION_COUNTER_INVALID ? undefined : rawMotionCounter;
+
+  return { temp, humidity, pressure, battVoltage, battStrength, motionCounter };
+}
+
+module.exports = {
+  id: "ruuvitag",
+  name: "RuuviTag",
+  domain: "environmental",
+  // Sensor-less variants (e.g. the Pro IP68) never emit a pressure value —
+  // see the invalid-sentinel handling in decode() above. This flag only says
+  // the model family *can* report pressure; sensor-manager additionally
+  // requires a device to have actually decoded a pressure value before
+  // offering it as an outside-pressure source.
+  providesPressure: true,
+  identify,
+  decode,
+};

package/lib/decoders/switchbot-meter-plus.js

@@ -0,0 +1,44 @@
+"use strict";
+
+// SwitchBot Meter Plus — a newer sibling of the base Meter (switchbot-th.js)
+// with its own model byte (0x69) and its temp/humidity/battery all packed
+// into the service-data payload instead of manufacturer data. Format per
+// https://github.com/OpenWonderLabs/SwitchBotAPI-BLE (devicetypes/meter.md,
+// "(new) broadcast message"). No GATT connection needed.
+
+const MANUFACTURER_ID = 0x0969;
+const MODEL_ID = 0x69;
+const SERVICE_DATA_UUID = "0000fd3d-0000-1000-8000-00805f9b34fb";
+
+function identify(adv) {
+  const md = adv.manufacturerData.get(MANUFACTURER_ID);
+  const sd = adv.serviceData.get(SERVICE_DATA_UUID);
+  return !!md && md.length >= 1 && md[0] === MODEL_ID && !!sd && sd.length >= 6;
+}
+
+function decode(adv) {
+  const sd = adv.serviceData.get(SERVICE_DATA_UUID);
+
+  // Byte 4 bit 7: sign (1 = positive). Byte 4 bits 0-6: integer part.
+  // Byte 3 bits 0-3: fractional decimal digit. Byte 5 bit 7: unit flag
+  // (1 = the value above is in Fahrenheit rather than Celsius).
+  const sign = (sd[4] & 0x80) !== 0 ? 1 : -1;
+  const intPart = sd[4] & 0x7f;
+  const frac = (sd[3] & 0x0f) / 10;
+  const rawTemp = sign * (intPart + frac);
+  const isFahrenheit = (sd[5] & 0x80) !== 0;
+  const tempC = isFahrenheit ? (rawTemp - 32) / 1.8 : rawTemp;
+
+  const humidity = (sd[5] & 0x7f) / 100;
+  const battStrength = sd[2] / 100;
+
+  return { temp: tempC + 273.15, humidity, battStrength };
+}
+
+module.exports = {
+  id: "switchbot-meter-plus",
+  name: "SwitchBot Meter Plus",
+  domain: "environmental",
+  identify,
+  decode,
+};

package/lib/decoders/switchbot-th.js

@@ -0,0 +1,66 @@
+"use strict";
+
+// SwitchBot Meter (WoSensorTH) — manufacturer-data + service-data advertisement
+// format documented at https://github.com/OpenWonderLabs/SwitchBotAPI-BLE
+// (devicetypes/meter.md). No GATT connection needed.
+
+const MANUFACTURER_ID = 0x0969;
+const MODEL_ID = 0x77; // 'w' — distinguishes the base Meter from Meter Plus (0x69)
+// Some firmware/chip revisions prefix manufacturerData with the device's own
+// MAC address instead of putting the model byte at offset 0. Byte 6 (right
+// after the MAC) was initially assumed to be a stable device-type/mode byte
+// per OpenWonderLabs's device-type table (0x74 't' / 0x54 'T' for WoSensorTH)
+// — but a second capture from the same physical device showed it change
+// (0x74 -> 0x75) between advertisements while the sensor payload after it
+// stayed identical, so it's some kind of rolling counter, not a fixed
+// discriminator. Don't gate on its value. The MAC match alone is already a
+// ~1-in-2^48 signal, so it's sufficient on its own; the payload after it is
+// otherwise the same shape, and since the buffer is still 12 bytes total
+// either way, the temp/humidity offsets below land in the same place
+// regardless of variant.
+const BATTERY_SERVICE_UUID = "0000fd3d-0000-1000-8000-00805f9b34fb";
+
+function macBytesMatch(md, mac) {
+  if (!mac) return false;
+  return md.subarray(0, 6).toString("hex") === String(mac).replace(/:/g, "").toLowerCase();
+}
+
+function identify(adv) {
+  const md = adv.manufacturerData.get(MANUFACTURER_ID);
+  if (!md || md.length !== 12) return false;
+  return md[0] === MODEL_ID || macBytesMatch(md, adv.mac);
+}
+
+function decode(adv) {
+  const md = adv.manufacturerData.get(MANUFACTURER_ID);
+
+  // Byte 9 bit 7: sign (1 = positive). Byte 9 bits 0-6: integer part (°C).
+  // Byte 8 bits 0-3: fractional decimal digit (tenths of a degree).
+  const sign = (md[9] & 0x80) !== 0 ? 1 : -1;
+  const intPart = md[9] & 0x7f;
+  const frac = (md[8] & 0x0f) / 10;
+  const temp = 273.15 + sign * (intPart + frac);
+
+  // Byte 10 bit 7 is an alarm flag, not part of the value.
+  const humidity = (md[10] & 0x7f) / 100;
+
+  const result = { temp, humidity };
+
+  // Byte 2 bit 7 is an "update UTC" flag, not part of the value — per
+  // OpenWonderLabs's Service Data table (Byte 2: "Update UTC Flag Battery",
+  // bit[6:0] = remaining battery 0-100%).
+  const sd = adv.serviceData.get(BATTERY_SERVICE_UUID);
+  if (sd && sd.length >= 3) {
+    result.battStrength = (sd[2] & 0x7f) / 100;
+  }
+
+  return result;
+}
+
+module.exports = {
+  id: "switchbot-th",
+  name: "SwitchBot Meter",
+  domain: "environmental",
+  identify,
+  decode,
+};

package/lib/decoders/xiaomi-atc.js

@@ -0,0 +1,45 @@
+"use strict";
+
+// Xiaomi LYWSD03MMC / similar running the pvvx or atc1441 custom firmware
+// (https://github.com/pvvx/ATC_MiThermometer) advertises under its own name
+// (ATC_XXXXXX, where XXXXXX is the last 3 MAC bytes) with a fixed-format
+// service-data payload — no encryption key or GATT connection needed, unlike
+// stock Xiaomi firmware. This decodes the firmware's default little-endian
+// "custom" format: mac[6] temp[i16LE, x0.01 degC] humidity[u16LE, x0.0001]
+// voltage[u16LE, mV] battery[u8, %] counter[u8].
+
+const NAME_PATTERN = /^ATC_[A-Fa-f0-9]{6}$/;
+const SERVICE_DATA_UUIDS = ["0000181a-0000-1000-8000-00805f9b34fb", "0000fcd2-0000-1000-8000-00805f9b34fb"];
+
+function getServiceData(adv) {
+  for (const uuid of SERVICE_DATA_UUIDS) {
+    const sd = adv.serviceData.get(uuid);
+    if (sd) return sd;
+  }
+  return null;
+}
+
+function identify(adv) {
+  if (!NAME_PATTERN.test(adv.name)) return false;
+  const sd = getServiceData(adv);
+  return !!sd && sd.length >= 13;
+}
+
+function decode(adv) {
+  const sd = getServiceData(adv);
+
+  const temp = 273.15 + sd.readInt16LE(6) / 100;
+  const humidity = sd.readUInt16LE(8) / 10000;
+  const battVoltage = sd.readUInt16LE(10) / 1000;
+  const battStrength = sd.readUInt8(12) / 100;
+
+  return { temp, humidity, battVoltage, battStrength };
+}
+
+module.exports = {
+  id: "xiaomi-atc",
+  name: "Xiaomi (ATC/pvvx custom firmware)",
+  domain: "environmental",
+  identify,
+  decode,
+};

package/lib/path-mapper.js

@@ -0,0 +1,119 @@
+"use strict";
+
+// SignalK path/unit conventions reused from bt-sensors-plugin-sk's
+// plugin_defaults.json (https://github.com/naugehyde/bt-sensors-plugin-sk) —
+// path templates, units and battery-low zones only; the decoding and
+// templating code here is our own, written for this plugin's BLE-Manager-only,
+// passive-advertisement design.
+const FIELD_PATHS = {
+  temp: {
+    path: "environment.{zone}.temperature",
+    unit: "K",
+    description: "Zone's current temperature",
+  },
+  humidity: {
+    path: "environment.{zone}.humidity",
+    unit: "ratio",
+    description: "Zone's current humidity",
+  },
+  pressure: {
+    path: "environment.{zone}.pressure",
+    unit: "Pa",
+    description: "Zone's current ambient air pressure",
+  },
+  battVoltage: {
+    path: "sensors.{sensorId}.battery.voltage",
+    unit: "V",
+    description: "Sensor battery voltage",
+  },
+  battStrength: {
+    path: "sensors.{sensorId}.battery.strength",
+    unit: "ratio",
+    description: "Sensor battery strength",
+    zones: [
+      { lower: 0.3, upper: 0.5, state: "alert", message: "Battery low - change soon" },
+      { lower: 0, upper: 0.3, state: "warn", message: "Battery very low - change now" },
+    ],
+  },
+  rssi: {
+    path: "sensors.{sensorId}.RSSI",
+    unit: "dB",
+    description: "Sensor signal strength in decibels",
+  },
+  motionCounter: {
+    path: "sensors.{sensorId}.motionCounter",
+    description: "Cumulative motion-detection interrupt count from the sensor's accelerometer",
+  },
+  reachable: {
+    path: "sensors.{sensorId}.reachable",
+    description: "Whether the sensor is currently in Bluetooth contact",
+  },
+};
+
+function sanitize(str) {
+  return String(str)
+    .replace(/[^a-zA-Z0-9_-]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_|_$/g, "");
+}
+
+function sensorId(name) {
+  return sanitize(name || "sensor").toLowerCase();
+}
+
+// A zone of "inside.mainCabin" nests into environment.inside.mainCabin.* —
+// each dot-separated segment is sanitized independently so a stray invalid
+// character in one segment doesn't merge it into its neighbor.
+function sanitizeZone(zone) {
+  const segments = String(zone || "")
+    .split(".")
+    .map(sanitize)
+    .filter(Boolean);
+  return segments.length > 0 ? segments.join(".") : "unknown";
+}
+
+function resolvePath(template, { zone, name }) {
+  return template.replace("{zone}", sanitizeZone(zone)).replace("{sensorId}", sensorId(name));
+}
+
+// Builds a SignalK delta from a decoder's { tag: value } output. Unknown
+// tags and null/undefined/NaN values are dropped rather than published —
+// callers don't need to filter decoder output themselves.
+function buildDelta({ name, zone, values, source }) {
+  const deltaValues = [];
+  for (const [tag, value] of Object.entries(values)) {
+    const meta = FIELD_PATHS[tag];
+    if (!meta || value === undefined || value === null || (typeof value === "number" && Number.isNaN(value))) continue;
+    deltaValues.push({ path: resolvePath(meta.path, { zone, name }), value });
+  }
+  if (deltaValues.length === 0) return null;
+  return {
+    updates: [{ $source: source, timestamp: new Date().toISOString(), values: deltaValues }],
+  };
+}
+
+// Builds the SignalK meta delta (units, description, alarm zones) for the
+// paths a decoder's { tag: value } output maps to. Without this, the server
+// has no unit metadata for plugin-defined paths like environment.<zone>.* or
+// sensors.<sensorId>.* (unlike the fixed paths in the SignalK spec, e.g.
+// environment.outside.temperature), so webapps display raw numbers — e.g. a
+// temperature of 287.04 with no indication it's Kelvin — instead of
+// converting/labelling them.
+function buildMetaDelta({ name, zone, values, source }) {
+  const metas = [];
+  for (const tag of Object.keys(values)) {
+    const meta = FIELD_PATHS[tag];
+    if (!meta) continue;
+    const metaValue = {};
+    if (meta.unit) metaValue.units = meta.unit;
+    if (meta.description) metaValue.description = meta.description;
+    if (meta.zones) metaValue.zones = meta.zones;
+    metas.push({ path: resolvePath(meta.path, { zone, name }), value: metaValue });
+  }
+  if (metas.length === 0) return null;
+  return {
+    updates: [{ $source: source, timestamp: new Date().toISOString(), meta: metas }],
+  };
+}
+
+module.exports = { FIELD_PATHS, resolvePath, sensorId, sanitize, sanitizeZone, buildDelta, buildMetaDelta };

package/lib/sensor-manager.js

@@ -0,0 +1,224 @@
+"use strict";
+
+const { normalizeAdvertisement } = require("./ble-advertisement");
+const { identifySensorType } = require("./sensor-types");
+const { buildDelta, buildMetaDelta, sanitizeZone } = require("./path-mapper");
+
+// The SignalK-spec path other plugins (barometer trend, weather routing,
+// etc.) expect for the boat's ambient outside pressure — distinct from this
+// plugin's own environment.<zone>.pressure paths, which are keyed by
+// whatever zone name the user gave each sensor.
+const OUTSIDE_PRESSURE_PATH = "environment.outside.pressure";
+
+// If a registered sensor hasn't been heard from in this long, mark its
+// "reachable" path false. Advertisement intervals for these sensors are
+// typically a few seconds, so 5 minutes is a generous margin against a
+// couple of missed beacons.
+const NO_CONTACT_MS = 5 * 60 * 1000;
+
+function normalizeMac(mac) {
+  return String(mac).toLowerCase();
+}
+
+// Owns the live BLE Manager API subscription and all runtime state: which
+// advertised devices have been recognised as a supported sensor type (for
+// the config UI's MAC dropdown) and which of those the user has registered
+// (for actually publishing SignalK deltas). Talks to app.bleApi and
+// app.handleMessage directly, so — like lib/device.js and lib/scanner.js in
+// the sibling signalk-bluetti-plugin — it's BLE/SignalK integration glue,
+// exercised via the real server rather than unit-tested here; the decoding
+// and path-mapping it calls into are deterministic and covered separately.
+class SensorManager {
+  constructor(app, pluginId, log) {
+    this._app = app;
+    this._pluginId = pluginId;
+    this._log = log;
+    this._recognized = new Map(); // normalized mac -> { mac, name, sensorTypeId, sensorTypeName, providesPressure (actually observed), rssi, lastSeen }
+    this._configured = new Map(); // normalized mac -> config entry from options.sensors
+    this._noContactTimers = new Map(); // normalized mac -> Timeout
+    this._metaSent = new Set(); // normalized macs whose units/description meta has been published
+    this._unmatchedLogged = new Set(); // normalized macs already debug-logged as unrecognized
+    this._outsidePressureSourceMac = null; // normalized mac whose pressure also publishes to environment.outside.pressure
+    this._outsidePressureSourceMacRaw = null; // same, original casing, for the config schema
+    this._unsubscribe = null;
+  }
+
+  configure(options = {}) {
+    const sensors = options.sensors || [];
+    this._configured = new Map(sensors.filter((s) => s && s.mac).map((s) => [normalizeMac(s.mac), s]));
+    this._outsidePressureSourceMacRaw = options.outsidePressureSource || null;
+    this._outsidePressureSourceMac = options.outsidePressureSource ? normalizeMac(options.outsidePressureSource) : null;
+  }
+
+  // Devices seen so far that matched a known sensor type — used to populate
+  // the config schema's MAC dropdown. Devices with no mappable sensor data
+  // never make it into this map (see _onAdvertisement).
+  getRecognizedDevices() {
+    return [...this._recognized.values()];
+  }
+
+  // Sensors registered in the config screen, regardless of whether they've
+  // been re-observed since the plugin last started — _recognized resets on
+  // every restart (it's runtime-only), so without this a MAC the user
+  // already registered could vanish from the config dropdown's options until
+  // the sensor happens to broadcast again, making a saved selection look
+  // like it "disappeared" even though it's still there in options.sensors.
+  getConfiguredDevices() {
+    return [...this._configured.values()];
+  }
+
+  // Same rationale as getConfiguredDevices(), for the single outsidePressureSource pick.
+  getOutsidePressureSourceMac() {
+    return this._outsidePressureSourceMacRaw;
+  }
+
+  start() {
+    if (!this._app.bleApi) {
+      throw new Error("BLE Manager API (app.bleApi) is not available on this SignalK server — requires server >= 2.31.0.");
+    }
+    this._unsubscribe = this._app.bleApi.onAdvertisement(this._pluginId, (adv) => this._onAdvertisement(adv));
+  }
+
+  stop() {
+    if (this._unsubscribe) {
+      this._unsubscribe();
+      this._unsubscribe = null;
+    }
+    for (const timer of this._noContactTimers.values()) clearTimeout(timer);
+    this._noContactTimers.clear();
+  }
+
+  _onAdvertisement(rawAdv) {
+    let adv;
+    try {
+      adv = normalizeAdvertisement(rawAdv);
+    } catch (err) {
+      this._log(`Failed to parse advertisement from ${rawAdv && rawAdv.mac}: ${err.message}`);
+      return;
+    }
+
+    const sensorType = identifySensorType(adv);
+    if (!sensorType) {
+      this._logUnmatchedOnce(adv);
+      return; // no mappable sensor data (e.g. RSSI-only) — ignore
+    }
+
+    const normMac = normalizeMac(adv.mac);
+    const config = this._configured.get(normMac);
+    const isActive = !!config && config.enabled !== false;
+
+    // Decoded for every recognised device (not just registered ones) so the
+    // config screen can tell whether this particular device actually reports
+    // pressure — the decoder's providesPressure flag is only a model-family
+    // capability, and sensor-less variants (e.g. RuuviTag Pro IP68) broadcast
+    // the "not available" sentinel instead. Decoding is a few buffer reads.
+    let values;
+    let decodeError = null;
+    try {
+      values = sensorType.decode(adv);
+    } catch (err) {
+      decodeError = err;
+    }
+
+    const previous = this._recognized.get(normMac);
+    const reportsPressure =
+      !!sensorType.providesPressure &&
+      ((previous && previous.providesPressure) || (!!values && typeof values.pressure === "number" && !Number.isNaN(values.pressure)));
+    this._recognized.set(normMac, {
+      mac: adv.mac,
+      name: adv.name,
+      sensorTypeId: sensorType.id,
+      sensorTypeName: sensorType.name,
+      // Sticky once observed, so one odd advertisement can't drop a device
+      // from the pressure-source dropdown mid-session.
+      providesPressure: reportsPressure,
+      rssi: adv.rssi,
+      lastSeen: Date.now(),
+    });
+
+    if (!isActive) return;
+
+    if (decodeError) {
+      this._log(`Failed to decode ${sensorType.name} advertisement from ${adv.mac}: ${decodeError.message}`);
+      return;
+    }
+    values.rssi = adv.rssi;
+    values.reachable = true;
+
+    this._publish(adv, config, sensorType, values);
+    this._scheduleNoContactCheck(normMac, adv, config, sensorType);
+  }
+
+  // Debug aid for "my sensor isn't showing up in the dropdown": logs the raw
+  // manufacturer/service data of a device that broadcasts a payload but
+  // doesn't match any decoder's identify(), once per MAC, so a user can
+  // enable plugin debug logging and paste the output when filing an issue
+  // for an unsupported sensor/firmware variant. Devices with no payload at
+  // all (phones, fitness trackers, RSSI-only beacons) are skipped as noise.
+  _logUnmatchedOnce(adv) {
+    if (adv.manufacturerData.size === 0 && adv.serviceData.size === 0) return;
+    const normMac = normalizeMac(adv.mac);
+    if (this._unmatchedLogged.has(normMac)) return;
+    this._unmatchedLogged.add(normMac);
+
+    const mfg = [...adv.manufacturerData.entries()].map(([id, buf]) => `0x${id.toString(16)}:${buf.toString("hex")}`);
+    const svc = [...adv.serviceData.entries()].map(([uuid, buf]) => `${uuid}:${buf.toString("hex")}`);
+    this._log(
+      `No known sensor type matched ${adv.mac} (name: "${adv.name}"). manufacturerData=[${mfg.join(", ")}] serviceData=[${svc.join(", ")}]`,
+    );
+  }
+
+  _publish(adv, config, sensorType, values) {
+    const name = config.name || adv.name || sensorType.name;
+    const zone = config.zone;
+    const source = `${this._pluginId}.${sensorType.id}`;
+
+    const normMac = normalizeMac(adv.mac);
+    if (!this._metaSent.has(normMac)) {
+      const meta = buildMetaDelta({ name, zone, values, source });
+      if (meta) {
+        this._app.handleMessage(this._pluginId, meta);
+        this._metaSent.add(normMac);
+      }
+    }
+
+    const delta = buildDelta({ name, zone, values, source });
+
+    // Optionally cross-publish this sensor's pressure to the SignalK-spec
+    // environment.outside.pressure path (which already has server-provided
+    // units metadata, unlike our own environment.<zone>.* paths — no meta
+    // delta needed here) so other plugins that expect it there — barometer
+    // trend, weather routing — can use it without knowing this plugin's zone
+    // naming. Skipped when the sensor's own zone already resolves there, to
+    // avoid publishing the identical path twice in one update.
+    if (
+      this._outsidePressureSourceMac === normMac &&
+      typeof values.pressure === "number" &&
+      !Number.isNaN(values.pressure) &&
+      sanitizeZone(zone) !== "outside"
+    ) {
+      const outsidePressureDelta = {
+        updates: [
+          { $source: source, timestamp: new Date().toISOString(), values: [{ path: OUTSIDE_PRESSURE_PATH, value: values.pressure }] },
+        ],
+      };
+      this._app.handleMessage(this._pluginId, outsidePressureDelta);
+    }
+
+    if (delta) this._app.handleMessage(this._pluginId, delta);
+  }
+
+  _scheduleNoContactCheck(normMac, adv, config, sensorType) {
+    const existing = this._noContactTimers.get(normMac);
+    if (existing) clearTimeout(existing);
+
+    const timer = setTimeout(() => {
+      this._noContactTimers.delete(normMac);
+      this._publish(adv, config, sensorType, { reachable: false });
+    }, NO_CONTACT_MS);
+    timer.unref?.();
+    this._noContactTimers.set(normMac, timer);
+  }
+}
+
+module.exports = SensorManager;

package/lib/sensor-types.js

@@ -0,0 +1,29 @@
+"use strict";
+
+// Registry of supported passive-advertisement sensor decoders. Each decoder
+// is a pure { id, name, domain, identify(adv), decode(adv) } module — no BLE
+// or SignalK dependencies — so they're trivially unit-testable in isolation.
+//
+// Order matters only where two decoders could otherwise both claim the same
+// advertisement; switchbot-th and switchbot-meter-plus share a manufacturer
+// ID but are disambiguated by model byte, so ordering isn't load-bearing
+// today, but keep more specific identify() checks earlier if that changes.
+const decoders = [
+  require("./decoders/switchbot-th"),
+  require("./decoders/switchbot-meter-plus"),
+  require("./decoders/ruuvitag"),
+  require("./decoders/xiaomi-atc"),
+  require("./decoders/govee"),
+];
+
+// Returns the first decoder that claims this advertisement, or null if none
+// do — callers should treat null as "no mappable sensor data" and ignore the
+// advertisement entirely (e.g. a device only broadcasting RSSI/UUIDs).
+function identifySensorType(adv) {
+  for (const decoder of decoders) {
+    if (decoder.identify(adv)) return decoder;
+  }
+  return null;
+}
+
+module.exports = { decoders, identifySensorType };

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@rhizomatics/signalk-ble-sensors-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Passive BLE sensor listening for SignalK (SwitchBot, RuuviTag, and others) via the SignalK BLE Manager API — no GATT connection required.",
+  "keywords": [
+    "ble",
+    "bluetooth",
+    "environment",
+    "humidity",
+    "marine",
+    "ruuvitag",
+    "sensors",
+    "signalk",
+    "signalk-category-hardware",
+    "signalk-node-plugin",
+    "signalk-node-server-plugin",
+    "switchbot",
+    "temperature"
+  ],
+  "homepage": "https://github.com/rhizomatics/signalk-ble-sensors-plugin",
+  "bugs": {
+    "url": "https://github.com/rhizomatics/signalk-ble-sensors-plugin/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Jey Burrows",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rhizomatics/signalk-ble-sensors-plugin.git"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "docs/assets/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint",
+    "test": "node --test",
+    "test:coverage": "node --experimental-test-coverage --test-coverage-include=\"lib/**/*.js\" --test-coverage-exclude=\"lib/sensor-manager.js\" --test-coverage-lines=80 --test-coverage-branches=80 --test-coverage-functions=80 --test"
+  },
+  "devDependencies": {
+    "oxfmt": "^0.76.0",
+    "oxlint": "^1.91.0"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "signalk-server": ">=2.31.0"
+  },
+  "signalk": {
+    "displayName": "BLE Sensors (Passive)",
+    "appIcon": "docs/assets/icon.svg",
+    "recommends": [
+      "@rhizomatics/signalk-bluetti-plugin",
+      "@rhizomatics/signalk-einklabel-plugin"
+    ]
+  },
+  "signalk-plugin-enabled-by-default": false
+}