homebridge-withings-environment-data 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [1.4.0] - 2026-08-19
+
+### Added
+- `last_seen` field in the MQTT payload, reflecting the actual Withings
+  measurement time (not poll/publish time). Format configurable via a new
+  "Last Seen" dropdown: `ISO_8601` (default, UTC), `ISO_8601 local`,
+  `epoch` (milliseconds), or `disabled` to omit the field
+- MQTT publishing now backfills every reading the scale buffered since the
+  last publish, not just the single newest one, published oldest first
+
+### Changed
+- MQTT Retain is now on by default (previously off by default)
+
+## [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

package/README.md

@@ -1,4 +1,4 @@
-# Withings Environment Data v1.3.2
+# Withings Environment Data v1.4.0
 
 **This Homebridge plugin has been 100% vibe coded with Claude.**
 
@@ -54,12 +54,17 @@ turned on or off in Configuration:
 - **Expose sensors as HomeKit Accessories** (default on): when off, the
   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 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.
+- **Publish to MQTT** (default off): when on, publishes a message to topic
+  `withingsenv/ws-50` on the configured broker, shaped like
+  `{"temperature": 25.2, "co2_levels": 674, "last_seen":
+  "2026-08-18T20:30:00.000Z"}`, for every reading buffered by the scale
+  since the last publish, not just the newest — the WS-50 can take several
+  readings internally before it syncs, and this backfills that gap instead
+  of collapsing it into one message. Each is published in the order it was
+  actually recorded, oldest first. Messages are retained by default.
+  Publishing pauses entirely once the newest known reading is stale (see
+  Stale Data Warning Threshold below) and resumes (with any accumulated
+  backlog) once a fresh reading comes in.
 
 ### Configuration
 
@@ -87,10 +92,15 @@ 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 / 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.
+- **Publish to MQTT / Host / Port / Username / Password / Last Seen /
+  Retain**: see [Usage](#usage) above. Publishing is off by default; Port
+  defaults to 1883. Username/Password are optional, for brokers that
+  require auth. **Last Seen** controls the format of the `last_seen`
+  field, which always reflects the time the scale actually took the
+  measurement (not when the plugin polled or published it): `ISO_8601`
+  (default, UTC), `ISO_8601 local` (with UTC offset), `epoch`
+  (milliseconds), or `disabled` to omit the field entirely. Retain is on
+  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

@@ -106,6 +106,18 @@
           "type": "password"
         }
       },
+      "mqttLastSeen": {
+        "title": "Last Seen",
+        "type": "string",
+        "default": "ISO_8601",
+        "oneOf": [
+          { "title": "ISO_8601 (default)", "enum": ["ISO_8601"] },
+          { "title": "ISO_8601 local", "enum": ["ISO_8601_local"] },
+          { "title": "epoch (ms)", "enum": ["epoch"] },
+          { "title": "disabled", "enum": ["disable"] }
+        ],
+        "description": "Adds a last_seen field to the MQTT payload with the time of the newest Withings measurement (like zigbee2mqtt)."
+      },
       "mqttRetain": {
         "title": "Retain",
         "type": "boolean",
@@ -158,6 +170,7 @@
         "mqttPort",
         "mqttUsername",
         "mqttPassword",
+        "mqttLastSeen",
         "mqttRetain"
       ]
     },

package/index.js

@@ -68,9 +68,27 @@ async function fetchLatest({ cookieHeader, sessionToken, deviceId, userId }) {
     // used to detect the scale itself going quiet (e.g. nobody's stood on
     // it in a while), as opposed to the plugin failing to reach Withings.
     readingDate: co2Point?.date ?? tempPoint?.date ?? null,
+    // Full backlog within the window (getmeashf — "high frequency measure"),
+    // not just the newest point — the scale can buffer multiple readings
+    // internally between cloud syncs. Only used for MQTT backfill; HomeKit
+    // characteristics only ever reflect the single newest point above.
+    co2Series,
+    tempSeries,
   };
 }
 
+// Local-time ISO 8601 with UTC offset — Date's own toISOString() is always UTC.
+function toLocalIso8601(date) {
+  const pad = (n) => String(Math.floor(Math.abs(n))).padStart(2, '0');
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+    `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+    `${sign}${pad(offsetMinutes / 60)}:${pad(offsetMinutes % 60)}`
+  );
+}
+
 function mapCo2ToAirQuality(ppm, AirQuality, thresholds) {
   if (ppm < thresholds.excellentMaxPpm) return AirQuality.EXCELLENT;
   if (ppm < thresholds.goodMaxPpm) return AirQuality.GOOD;
@@ -122,6 +140,13 @@ class WithingsEnvironmentDataPlatform {
     // it) so a restart can't be mistaken for "no reading yet" and wrongly clear
     // an active stale-warning below.
     this.lastReadingDate = state.lastReadingDate ?? null;
+    // Unix seconds of the newest reading already published to MQTT, used to
+    // backfill any points buffered by the scale since the last publish rather
+    // than only ever sending the single newest one. Defaults to the already-
+    // known lastReadingDate (if any) on first boot after upgrading to this
+    // feature, so existing installs don't replay their entire pre-existing
+    // history — only genuinely new backlog from here on.
+    this.lastPublishedMqttDate = state.lastPublishedMqttDate ?? state.lastReadingDate ?? null;
     // The readingDate (unix seconds) we last sent a stale-data *notification* for,
     // or null if not currently in a notified state. The log warning itself repeats
     // every poll while data stays stale (like missed-poll-cycle failures do), but
@@ -152,6 +177,7 @@ class WithingsEnvironmentDataPlatform {
         JSON.stringify({
           sessionKey: this.sessionKey,
           lastReadingDate: this.lastReadingDate,
+          lastPublishedMqttDate: this.lastPublishedMqttDate,
           staleNotifiedForReadingDate: this.staleNotifiedForReadingDate,
         })
       );
@@ -239,7 +265,7 @@ 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) {
+    if (this.config.mqttRetain === false) {
       // 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
@@ -249,11 +275,67 @@ class WithingsEnvironmentDataPlatform {
     this.api.on('shutdown', () => this.mqttClient.end());
   }
 
-  publishMqttReading() {
+  // Config UI doesn't reliably apply schema defaults on boolean fields (see
+  // v1.3.2), so "on by default" is expressed here as "anything but an explicit
+  // false", not via a schema default.
+  getMqttRetain() {
+    return this.config.mqttRetain !== false;
+  }
+
+  getMqttLastSeenFormat() {
+    const valid = ['ISO_8601', 'ISO_8601_local', 'epoch', 'disable'];
+    return valid.includes(this.config.mqttLastSeen) ? this.config.mqttLastSeen : 'ISO_8601';
+  }
+
+  formatLastSeen(readingDateUnixSeconds) {
+    const format = this.getMqttLastSeenFormat();
+    if (format === 'disable' || readingDateUnixSeconds === null || readingDateUnixSeconds === undefined) {
+      return undefined;
+    }
+
+    const date = new Date(readingDateUnixSeconds * 1000);
+    if (format === 'epoch') return date.getTime();
+    if (format === 'ISO_8601_local') return toLocalIso8601(date);
+    return date.toISOString();
+  }
+
+  // Publishes every buffered point newer than the last one we published, oldest
+  // first, instead of only ever the single newest — so a gap where the scale
+  // synced a backlog of readings (e.g. after being offline) gets backfilled on
+  // the MQTT side rather than collapsed into one message. HomeKit is
+  // unaffected: it only ever shows the single newest value (see applyReading).
+  publishMqttReadings(co2Series, tempSeries) {
     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: this.config.mqttRetain === true });
+
+    const byDate = new Map();
+    for (const point of co2Series) {
+      if (!byDate.has(point.date)) byDate.set(point.date, {});
+      byDate.get(point.date).co2 = point.value;
+    }
+    for (const point of tempSeries) {
+      if (!byDate.has(point.date)) byDate.set(point.date, {});
+      byDate.get(point.date).temperature = point.value;
+    }
+
+    const unpublished = [...byDate.entries()]
+      .filter(([date]) => this.lastPublishedMqttDate === null || date > this.lastPublishedMqttDate)
+      .sort(([a], [b]) => a - b);
+
+    for (const [date, reading] of unpublished) {
+      const payload = {};
+      if (reading.co2 !== undefined) payload.co2_levels = reading.co2;
+      if (reading.temperature !== undefined) payload.temperature = reading.temperature;
+      // The actual Withings measurement time, not when this poll ran or published.
+      const lastSeen = this.formatLastSeen(date);
+      if (lastSeen !== undefined) payload.last_seen = lastSeen;
+      this.mqttClient.publish(MQTT_TOPIC, JSON.stringify(payload), { retain: this.getMqttRetain() });
+      this.lastPublishedMqttDate = date;
+    }
+
+    if (unpublished.length > 0) {
+      this.persistState();
+    }
   }
 
   setupServices(accessory) {
@@ -319,14 +401,14 @@ class WithingsEnvironmentDataPlatform {
         }
       }
 
-      const { co2, temperature, readingDate } = await fetchLatest({
+      const { co2, temperature, readingDate, co2Series, tempSeries } = await fetchLatest({
         cookieHeader,
         sessionToken,
         deviceId: this.deviceId,
         userId: this.userId,
       });
 
-      this.applyReading(co2, temperature, readingDate);
+      this.applyReading(co2, temperature, readingDate, co2Series, tempSeries);
       this.setFault(false);
       this.missedCycles = 0;
       this.hasNotifiedFailure = false;
@@ -354,6 +436,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!') {
@@ -471,7 +563,7 @@ class WithingsEnvironmentDataPlatform {
     return this.lastReading.temperature;
   }
 
-  applyReading(co2, temperature, readingDate) {
+  applyReading(co2, temperature, readingDate, co2Series = [], tempSeries = []) {
     const co2Threshold = this.getCo2Threshold();
     const hasReading = (co2 !== null && co2 !== undefined) || (temperature !== null && temperature !== undefined);
 
@@ -516,7 +608,7 @@ class WithingsEnvironmentDataPlatform {
     }
 
     if (hasReading) {
-      this.publishMqttReading();
+      this.publishMqttReadings(co2Series, tempSeries);
     }
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-withings-environment-data",
   "displayName": "Withings Environment Data",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "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": [