homebridge-withings-environment-data 1.3.1 → 1.3.3

package/CHANGELOG.md

@@ -6,6 +6,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [1.3.3] - 2026-08-04
+
+### Fixed
+- Stale data now correctly shows a fault on the sensors' `StatusFault`
+  characteristic too, not just "No Response" in the Home app. A
+  successful poll always cleared the fault, even when the reading itself
+  was stale, so anything reading `StatusFault` directly instead of
+  calling the characteristic's get handler (e.g. Homebridge's own
+  accessory list) kept showing the sensors as fine
+
+## [1.3.2] - 2026-08-04
+
+### Added
+- "Retain" checkbox in the MQTT fieldset (default off) to control whether
+  published MQTT messages set the retain flag
+
+### Changed
+- "Publish to MQTT" checkbox moved into the collapsed "MQTT" fieldset,
+  as its first item
+- MQTT publishing now pauses once the newest reading is past the Stale
+  Data Warning Threshold, resuming once a fresher reading comes in —
+  previously it kept republishing the same stale reading on every poll
+
+### Fixed
+- MQTT messages are no longer published with the retain flag set by
+  default (previously always retained)
+- "Publish to MQTT" and "Retain" checkboxes now actually default to
+  unchecked in Config UI (an explicit `"default": false` wasn't being
+  applied by the schema form and rendered checked instead)
+- When Retain is off, the plugin now clears any stale retained message
+  left on the broker from before (publishing with `retain:false` doesn't
+  remove an existing retained message on its own)
+
 ## [1.3.1] - 2026-08-03
 
 ### Fixed

package/README.md

@@ -1,4 +1,4 @@
-# Withings Environment Data v1.3.1
+# Withings Environment Data v1.3.3
 
 **This Homebridge plugin has been 100% vibe coded with Claude.**
 
@@ -55,9 +55,11 @@ turned on or off in Configuration:
   plugin still polls Withings (and still publishes to MQTT, if enabled),
   but doesn't create or update any HomeKit accessory.
 - **Publish to MQTT** (default off): when on, every successful poll
-  publishes a retained message to topic `withingsenv/ws-50` on the
-  configured broker, shaped like
-  `{"temperature": 25.2, "co2_levels": 674}`.
+  publishes a message to topic `withingsenv/ws-50` on the configured
+  broker, shaped like `{"temperature": 25.2, "co2_levels": 674}`. Messages
+  aren't retained unless the Retain option is enabled. Publishing pauses
+  once the data is stale (see Stale Data Warning Threshold below) and
+  resumes once a fresh reading comes in.
 
 ### Configuration
 
@@ -85,9 +87,10 @@ Fields:
   Anything above the Inferior boundary is reported as Poor.
 - **Expose sensors as HomeKit Accessories**: see [Usage](#usage) above.
   Default on.
-- **Publish to MQTT / Host / Port / Username / Password**: see
+- **Publish to MQTT / Host / Port / Username / Password / Retain**: see
   [Usage](#usage) above. Publishing is off by default; Port defaults to
   1883. Username/Password are optional, for brokers that require auth.
+  Retain is off by default.
 - **Stale Data Warning Threshold (hours)**: if the newest reading from the
   scale itself (not the plugin's poll) is older than this many hours — e.g.
   nobody's stood on the scale in a while — a warning is logged on every

package/config.schema.json

@@ -82,7 +82,6 @@
       "publishToMqtt": {
         "title": "Publish to MQTT",
         "type": "boolean",
-        "default": false,
         "description": "Publish sensor data to configured MQTT broker. Topic name: \"withingsenv/ws-50\""
       },
       "mqttHost": {
@@ -107,6 +106,11 @@
           "type": "password"
         }
       },
+      "mqttRetain": {
+        "title": "Retain",
+        "type": "boolean",
+        "description": "Publish messages with the MQTT retain flag set, so new subscribers immediately get the last known reading."
+      },
       "noResponseAfterMissedPolls": {
         "title": "No Response After Missed Polls",
         "type": "integer",
@@ -143,17 +147,18 @@
       ]
     },
     "exposeAsHomekitAccessories",
-    "publishToMqtt",
     {
       "type": "fieldset",
       "title": "MQTT",
       "expandable": true,
       "expanded": false,
       "items": [
+        "publishToMqtt",
         "mqttHost",
         "mqttPort",
         "mqttUsername",
-        "mqttPassword"
+        "mqttPassword",
+        "mqttRetain"
       ]
     },
     {

package/index.js

@@ -239,13 +239,21 @@ class WithingsEnvironmentDataPlatform {
       password: this.config.mqttPassword || undefined,
     });
     this.mqttClient.on('error', (err) => this.log.warn(`MQTT connection error: ${err.message}`));
+    if (this.config.mqttRetain !== true) {
+      // A publish with retain:false does NOT clear a previously-retained message —
+      // the broker keeps serving the last retained one until something explicitly
+      // clears it. Do that once per connect so turning Retain off actually stops
+      // new subscribers from seeing stale data.
+      this.mqttClient.on('connect', () => this.mqttClient.publish(MQTT_TOPIC, '', { retain: true }));
+    }
     this.api.on('shutdown', () => this.mqttClient.end());
   }
 
   publishMqttReading() {
     if (!this.mqttClient) return;
+    if (this.isDataStale()) return;
     const payload = JSON.stringify({ temperature: this.lastReading.temperature, co2_levels: this.lastReading.co2 });
-    this.mqttClient.publish(MQTT_TOPIC, payload, { retain: true });
+    this.mqttClient.publish(MQTT_TOPIC, payload, { retain: this.config.mqttRetain === true });
   }
 
   setupServices(accessory) {
@@ -346,6 +354,16 @@ class WithingsEnvironmentDataPlatform {
     // quiet (no one's stood on it) while polls keep succeeding fine, so this
     // is checked every cycle against whatever the newest reading actually is.
     await this.checkStaleData();
+
+    // A successful poll above already cleared the fault via setFault(false),
+    // even though the reading it just fetched can itself be stale. Re-assert
+    // the fault in that case so anything reading StatusFault directly (e.g.
+    // Homebridge's own accessory list, which shows cached values rather than
+    // invoking the onGet handlers the way the Home app does) reflects
+    // staleness too, not just throwIfStale()'s "No Response" to HomeKit.
+    if (this.isDataStale()) {
+      this.setFault(true);
+    }
   }
 
   async sendNtfyNotification(message, title = 'Homebridge: Getting Withings Environment Data Failed!') {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-withings-environment-data",
   "displayName": "Withings Environment Data",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Homebridge plugin exposing ambient CO2/air-quality and room temperature readings from a Withings WS-50 scale as HomeKit sensors",
   "main": "index.js",
   "files": [