@rhizomatics/signalk-ble-sensors-plugin 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+# [1.0.2]
+
+- SwitchBot Meter Plus: temperature was wrong when the meter's display was set to Fahrenheit (e.g. 22.7°C published as -5.2°C). The broadcast value is always Celsius; the flag only says which unit the display shows
+- Xiaomi ATC: sensors using the `atc1441` advertising format were decoded with the pvvx layout and published nonsense temperatures. Both formats are now decoded, and BTHome payloads (not supported yet) are no longer misread as either
+- **Path change:** humidity is now published to `environment.<zone>.relativeHumidity`, the SignalK spec path (`humidity` is deprecated in the spec). Update any dashboard or alarm that reads `environment.<zone>.humidity`
+- Zone examples in the config screen and README now follow the spec's `inside.<zone>` / `outside` layout. Existing zones are unchanged
+
+# [1.0.1]
+
+No code change, re-release only for automated build.
+
 # [1.0.0]
 
 - Package moved to [Rhizomatics](https://www.rhizomatics.org.uk/sailing/)

package/README.md

@@ -1,5 +1,11 @@
 # signalk-ble-sensors-plugin
 
+[![npm version](https://img.shields.io/npm/v/@rhizomatics/signalk-ble-sensors-plugin.svg)](https://www.npmjs.com/package/@rhizomatics/signalk-ble-sensors-plugin)
+[![npm downloads](https://img.shields.io/npm/dm/@rhizomatics/signalk-ble-sensors-plugin.svg)](https://www.npmjs.com/package/@rhizomatics/signalk-ble-sensors-plugin)
+[![code style: oxfmt](https://img.shields.io/badge/code_style-oxfmt-blue.svg)](https://github.com)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/rhizomatics/signalk-ble-sensors-plugin./blob/main/LICENSE)
+[![boat tech directory](https://boat-tech-directory.rhizomatics.org.uk/images/badge.svg)](https://boat-tech-directory.rhizomatics.org.uk)
+
 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.
@@ -29,7 +35,7 @@ For boats that have IP68 RuuviTag Pro outside and RuuviTag inside, it can be han
 | 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).
+Stock Xiaomi firmware (encrypted, not the ATC/pvvx custom firmware above) isn't supported. On the custom firmware, choose the `custom` (pvvx) or `atc1441` advertising format; `BTHome` isn't decoded yet. 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
 
@@ -37,7 +43,7 @@ Stock Xiaomi firmware (encrypted, not the ATC/pvvx custom firmware above) isn't
 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**.
+5. Fill in a **Zone / location** — this becomes part of the SignalK path (`environment.<zone>.temperature`, etc.). The SignalK spec puts indoor zones under `inside`, so use e.g. `inside.mainCabin`, `inside.refrigerator` or `inside.engineRoom` (giving `environment.inside.mainCabin.temperature`), and `outside` for the outside air — 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**
@@ -47,16 +53,16 @@ sensor still needs to be added under "Registered sensors" as usual; picking it h
 
 ## 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                               |
+| Value            | Path                                  | Unit                                |
+| ---------------- | ------------------------------------- | ----------------------------------- |
+| Temperature      | `environment.<zone>.temperature`      | K                                   |
+| Humidity         | `environment.<zone>.relativeHumidity` | 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

package/index.js

@@ -140,14 +140,22 @@ function buildSchema(recognized, configured = [], outsidePressureSourceMac = nul
               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.",
+                "Used in sensors.<name>.* paths (the $source is the plugin id plus the sensor type). 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"],
+                "Used in environment.<zone>.* paths. The SignalK spec puts indoor zones under 'inside', e.g. 'inside.mainCabin' becomes environment.inside.mainCabin.*; use 'outside' for the outside air.",
+              examples: [
+                "outside",
+                "inside",
+                "inside.mainCabin",
+                "inside.galley",
+                "inside.refrigerator",
+                "inside.freezer",
+                "inside.engineRoom",
+              ],
             },
             enabled: { type: "boolean", title: "Enabled", default: true },
           },

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

@@ -19,15 +19,14 @@ function identify(adv) {
 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).
+  // Byte 4 bit 7: sign (1 = positive). Byte 4 bits 0-6: integer part (degC).
+  // Byte 3 bits 0-3: fractional decimal digit. Byte 5 bit 7 is the meter's
+  // display-unit setting (1 = shows Fahrenheit); the broadcast value is always
+  // Celsius whatever the display shows, as in pySwitchbot's decode_temp_humidity.
   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 tempC = sign * (intPart + frac);
 
   const humidity = (sd[5] & 0x7f) / 100;
   const battStrength = sd[2] / 100;

package/lib/decoders/xiaomi-atc.js

@@ -3,37 +3,49 @@
 // 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].
+// 0x181A service-data payload - no encryption key or GATT connection needed,
+// unlike stock Xiaomi firmware. Two layouts share that UUID, told apart by length:
+//
+// - pvvx "custom" (15 bytes, little-endian): mac[6] temp[i16, x0.01 degC]
+//   humidity[u16, x0.01 %] voltage[u16, mV] battery[u8, %] counter[u8] flags[u8]
+// - atc1441 (13 bytes, big-endian): mac[6] temp[i16, x0.1 degC] humidity[u8, %]
+//   battery[u8, %] voltage[u16, mV] counter[u8]
+//
+// The firmware's BTHome option (UUID 0xFCD2) is a different, TLV-encoded format
+// and isn't decoded here.
 
 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;
-}
+const SERVICE_DATA_UUID = "0000181a-0000-1000-8000-00805f9b34fb";
+const PVVX_LENGTH = 15;
+const ATC1441_LENGTH = 13;
 
 function identify(adv) {
   if (!NAME_PATTERN.test(adv.name)) return false;
-  const sd = getServiceData(adv);
-  return !!sd && sd.length >= 13;
+  const sd = adv.serviceData.get(SERVICE_DATA_UUID);
+  return !!sd && (sd.length === ATC1441_LENGTH || sd.length >= PVVX_LENGTH);
 }
 
-function decode(adv) {
-  const sd = getServiceData(adv);
+function decodePvvx(sd) {
+  return {
+    temp: 273.15 + sd.readInt16LE(6) / 100,
+    humidity: sd.readUInt16LE(8) / 10000,
+    battVoltage: sd.readUInt16LE(10) / 1000,
+    battStrength: sd.readUInt8(12) / 100,
+  };
+}
 
-  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;
+function decodeAtc1441(sd) {
+  return {
+    temp: 273.15 + sd.readInt16BE(6) / 10,
+    humidity: sd.readUInt8(8) / 100,
+    battStrength: sd.readUInt8(9) / 100,
+    battVoltage: sd.readUInt16BE(10) / 1000,
+  };
+}
 
-  return { temp, humidity, battVoltage, battStrength };
+function decode(adv) {
+  const sd = adv.serviceData.get(SERVICE_DATA_UUID);
+  return sd.length >= PVVX_LENGTH ? decodePvvx(sd) : decodeAtc1441(sd);
 }
 
 module.exports = {

package/lib/path-mapper.js

@@ -12,9 +12,9 @@ const FIELD_PATHS = {
     description: "Zone's current temperature",
   },
   humidity: {
-    path: "environment.{zone}.humidity",
+    path: "environment.{zone}.relativeHumidity",
     unit: "ratio",
-    description: "Zone's current humidity",
+    description: "Zone's current relative humidity",
   },
   pressure: {
     path: "environment.{zone}.pressure",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-ble-sensors-plugin",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Passive BLE sensor listening for SignalK (SwitchBot, RuuviTag, and others) via the SignalK BLE Manager API — no GATT connection required.",
   "keywords": [
     "ble",